3.6 Reading an Object

After an instance has been made persistent and its fields stored in the datastore, it can be retrieved again, either within the same application or by a different application.

There are three primary ways of finding an instance in the datastore with JDO ”by navigation, via an Extent , or by a Query .

3.6.1 Reading by navigation

Retrieving an instance by navigation is simple. Extending the previous example, this code snippet taken from ReadByNavigationExample.java shows how the Author instance can be retrieved again in the next transaction simply by using it:

 tx.begin(); String name =  author.getName()  ; System.out.println("Author's name is '" + name + "'."); tx.commit(); 

Underneath the covers, the JDO implementation retrieves the fields for the Author instance from the datastore. The output would be as follows :

 Author's name is 'Keiron McCammon'. 

Using navigation to retrieve persistent objects from the datastore also applies when one persistent object is referenced from another. Essentially , anytime a persistent object is referenced, the JDO implementation retrieves the instance's fields from the datastore, if it has not already done so within the current transaction.

A common question often arises from the previous example: Why do the fields of the Author instance have to be retrieved from the datastore again after it was initially created?

The answer has to do with transactions. After each transaction ends (either by a commit or rollback), all in-memory persistent objects become hollow. This is because the representation of a persistent object in the datastore could be updated by another application after the transaction ends, making any in-memory values out of sync. For this reason, JDO's default behavior is to clear the fields of each persistent object and retrieve them again if used within the next transaction, thereby ensuring that the in-memory instance remains consistent with the datastore.

JDO has some advanced options that change this default behavior and allow instances to be retained over transaction boundaries or even accessed outside of a transaction altogether. See Chapter 5 for more details.

3.6.2 Reading using an extent

What happens if another application wants to access the new Author instance? Obviously, this application won't have a reference to which it can navigate. In this case, the application can use an Extent to find all Author instances.

Extents

An Extent represents a collection of all instances in the datastore of a particular persistence-capable class and can consist of just instances of the class or instances of all subclasses. An application can get an Extent for a class from a PersistenceManager and then use an Iterator to iterate through all instances, or it can use the Extent as input to a query.

By default, it is possible to get an Extent for any persistence-capable class. If an Extent is not required, then as a potential optimization, it is possible to specify explicitly that an extent is not required in the JDO metadata for the class. Depending on the underlying datastore, this may or may not make any difference.

An application can get an Extent using the getExtent() method on PersistenceManager :

 public Extent getExtent(Class pc, boolean subclasses) 

The subclasses flag determines whether the returned Extent represents instances of the specified class only or includes instances of subclasses as well. If true, then it includes instances of all subclasses as well.

The iterator() method on Extent can be used to get an Iterator that iterates through all the instances in the Extent :

 public Iterator iterator() 

The following code snippet taken from ReadByExtentExample.java shows how an Extent can be used to iterate through the instances of the Author class:

 tx.begin();  Extent extent = pm.getExtent(Author.class, true);  Iterator authors = extent.iterator(); while (authors.hasNext()) {   Author author = (Author) authors.next();   String name = author.getName();   System.out.println("Author's name is '" + name + "'."); } extent.close(authors); tx.commit(); 

It is a good practice to use the close() or closeAll() method on Extent when an iterator has been used. The close() method closes an individual iterator, whereas closeAll() closes all iterators retrieved from the Extent :

 public void close(Iterator iterator) public void closeAll() 

Depending on the underlying datastore, this may free resources that were allocated when the Iterator was created (a cursor, for example).

3.6.3 Reading using a query

An Extent is useful if an application wants to retrieve all instances of a class in no particular order. However, if an application is looking for a particular instance that has certain field values, an Extent is not very useful. In this case, a query is needed to find an instance based on the values of its fields.

JDO defines a query language called JDOQL (JDO Query Language). JDOQL is essentially a simplified version of the Java syntax for an "if" statement. The PersistenceManager is used to create a Query instance, and once created, a Query can be executed to return a collection of matching persistent objects. There are approximately nine methods on PersistenceManager to create a Query instance; the most straightforward requires only a Java class and a filter:

 public Query newQuery(Class cln, String filter) 

The class specifies the persistence-capable class that the query is for, and the filter, which is just a string, specifies which instances of the class should be returned.

A Query can also be created using an Extent . A query created using a Java class is equivalent to a Query created using an Extent whose subclasses property is true. This means that a Query created from a Java class may include instances of the specified class and subclass (which is generally the desired behavior).

If an application specifically wants to restrict the query to instances of a given class only, then it can create an Extent whose subclasses property is false and use the Extent to create the Query . When executed, the Query includes only instances of the class itself and ignores subclasses.

The basic syntax for a filter is as follows:

 <field> <operator> <constant> 

where <field> is the name of the field as declared in the Java class, <operator> is one of the standard Java comparison operators (==, !=, <, >, and so on), and <constant> is the value to be compared against. Much more sophisticated queries than this can be defined; see Chapter 6 for details.

The following code snippet taken from ReadByQueryExample.java shows how to use a query to find a previously created Author by name. For simplicity, it assumes that at least one author with the given name is in the datastore:

 tx.begin();  Query query =   pm.newQuery(Author.class, "name == \"Keiron McCammon\"");  Collection result = (Collection) query.execute(); Author author = (Author) result.iterator().next(); query.close(result); String name = author.getName(); System.out.println("Author's name is '" + name + "'."); tx.commit(); 

The output would be as follows:

 Author's name is 'Keiron McCammon'. 

The execute() method on Query is used to execute the query and return the result. A half dozen ways of executing a query exist. The simplest is this:

 public Object execute() 

The execute() methods all return java.lang.Object , which must be cast to a java.util.Collection type for JDOQL queries. This collection is the set of instances that matched the specified filter. It can be iterated through in the normal manner to retrieve the persistent objects themselves .

The execute() methods on Query return java.lang.Object rather than java.util.Collection directly to allow for implementation-specific extensions. JDO requires that JDOQL be supported; however, an implementation can optionally support alternative query languages (maybe SQL, OQL, or something proprietary). In this case, the result of executing a query may not be a java.util.Collection ; instead, it needs to be cast to something specific to the query language being used.

It is a good practice to use the close() method on Query to release the result returned from a call to execute() :

 public Object close(Object result) 

Depending on the underlying datastore, this may free resources that were allocated during the execution of the query (a database cursor, for example).