Introduction
Bean creation is turned off by default. To enable bean creation,
you have to generate your object model with the property
torque.om.generateBeans set to true.
Creating beans from Torque objects creates a bridge between an environment which knows Torque and has access to a database, and another environment which does not know anything about Torque and databases.
For example, you might have a server using Torque, and a java client without database access where you want to use data supplied by Torque, but do not want to include Torque in any way.
If this is the case, you can create simple beans from Torque objects in the server, send them over the network to your client, manipulate them there, send them back over the network, create Torque objects from the beans, and save the objects generated from the beans.
However, a similar situation can also be achieved
by generating the save methods not to the data objects but to the
Peer classes by setting the generator switch
torque.om.saveMethodsInDbObjects to false.
This approach does not have the same separation between objects
and Torque as the beans approach, but it has the advantage that no mapping
between data objects and beans (which can be cumbersome) is needed.
Decide for yourself which is your favorite approach.
Creation of beans from Torque objects and vice versa
Created bean classes
If bean creation is turned on, the beans are automatically created by torque in the bean subpackage of your target package. E.g. in the bookstore example in the tutorial, the classes are generated in the com.kazmier.om package, so the beans will be generated in the package com.kazmier.om.bean. Each bean has getters and setters for all the properties defined in the schema.xml.
Also, getters and setters for two boolean values, namely isNew(), setNew(), isModified() and setModified() are generated, which keep track of which changes have already made it into the database. You should not normally need to use these.
Additional methods in the Torque objects
If bean creation is enabled, every Torque object gets some additional methods. E.g, the author class from the bookstore example in the tutorial gets the additional methods
public AuthorBean createBean(); public static Author createAuthor(AuthorBean bean);
These methods are used to create an AuthorBean from an Author or vice versa.
Beans and database state
If a bean is created from an object, the beans gets knowledge about whether the object it was created from already exists in the database, or whether it was changed after reading it from the database (that is what the isNew() and isModified() methods are for). So assuming we have at least one author stored in the database, the following code works as expected
List authors = AuthorPeer.doSelect(new Criteria());
Author author = (Author) authors.get(0);
AuthorBean authorBean = author.getBean();
// e.g. send the authorBean over the network
authorBean.setFirstName("Joshua");
// e.g. send the authorBean back over the network
Author authorFromBean = Author.createAuthor(authorBean);
authorFromBean.save();
This reads an author from the database, creates a bean from the author, manipulates the bean, and saves the manipulated data back into the database.
Object relations
The bean creation process preserves object relations. Consider again the bookstore example from the tutorial: Each book has an author, and an author can have serveral books. So if you have created an author-book relation, e.g. by
Author author = new Author(); // fill author data here Book book = new Book(); // fill book data here(); author.addBook(book); AuthorBean authorBean = author.getBean();
then the related bookBean is automatically created, and can be retrieved by
BookBean bookBean = (BookBean) authorBean.getBookBeans().get(0);
This is also true in the reverse direction. If you create an author from this authorBean, the corresponding book can also be retrieved:
Author authorFromBean = Author.createAuthor(authorBean); Book bookFromBean = (Book) author.getBooks().get(0);
Note that only newly created or cached related objects are considered in bean creation. To elaborate that, consider the case where one author which is related to several books is stored in the database.
The following code will NOT transfer the related books into the bean:
List authorList = AuthorPeer.doSelect(new Criteria()); Author author = (Author) authorList.get(0); AuthorBean authorBean = author.getBean();
This is because the related books are never read from the database, and thus are not included in bean conversion. To include the related books into the author bean, you have to assure that the related books are read into memory. This can be done as follows if lazy loading for related collections is turned on (the default):
List authorList = AuthorPeer.doSelect(new Criteria()); Author author = (Author) authorList.get(0); // the following reads all books related to the author into memory author.getBooks(); AuthorBean authorBean = author.getBean();