User's Manual

68 Chapter 9. Persistence Tutorial
• PersistenceException — http://rhea.redhat.com/doc/waf/6.0/api/com/arsdigita/persistence/\
PersistenceException.html
This is an unchecked exception that is thrown whenever there is an error within the persistence
system. It typically contains an error message as well as some debugging information.
9.2.5. Creating and Retrieving Objects in Java
Now that you have written your PDL files and your database is loaded, the next step is to create Data
Objects to access the information in the database. The main access point to Data Objects is through
the Session class. Session objects allow you to instantiate data objects that are part of a logical
client session. Specifically, there are three methods that allow you to create and retrieve objects as
well as a method allowing you to delete an object.
Suppose you have defined a Publication and want to create a new DataObject so that you can store
information about it. The first step is to use the Session.create(String typeName) method. You
can pass in the fully qualified name of the Object Type and get a Data Object back that corresponds
to the defined events. For instance, to create a new Publication, you can do the following (remove the
"\" and make it all one line):
DataObject publication = SessionManager.getSession().create\
("tutorial.Publication");
If you want to retrieve an object that already exists (and you have the OID), you can use the Ses-
sion.retrieve(OID oid) method. This is similar to the creation method, except that you are
accessing a row that already exists in the database instead of creating a new row (or rows).
If you have an OID and you want to delete the object from the database, Session provides a
delete(OID oid) method that allows you to perform the deletion. For most cases, however, you
will have the DataObject and can just call the local delete() method.
The above methods show how to retrieve or create a single object within the system. The system also
provides the ability to retrieve all objects of a given object type. This capability is provided through
the method retrieve(String typeName), located in the Session class.
Suppose you want to print out the names of all of the Publications in the system whose ID is less than
100. One way to do this would be to loop from 1 to 100, create the corresponding OID, and look up
each Publication. Another way would be to use a Data Query. However, the simplest way is to take
advantage of the retrieve all event that is generated for the Magazine object type. The following
example demonstrates this (remove the "\" and make it all one line):
// get all of the Publications in the system. Calling "retrieve" triggers
// the "retrieve all" event defined in the PDL file. Note that
// the string passed in to the method is the model name (tutorial)
// followed by the object type name (Publication) separated by a dot (.).
DataCollection pub = SessionManager.getSession().retrieve\
("tutorial.Publication");
// now we want to filter on the ID of the publication
pub.addFilter(pub.getFilterFactory().addLessThan("id", new Integer(100), \
false));
// finally, we can loop through the publications and print out its name
//
// the query to get the information out of the database is executed
// when next() is called for the first time
while (pub.next()) {
System.out.println(pub.get("name"));
}