The Extent Interface

The Extent interface specifies a group whose membership is managed by JDO and the datastore. Unless explicitly turned off in the JDO metadata, all application data classes are associated with an extent. An extent holds information and resources related to the class of objects in the datastore. Extents are used primarily to specify the objects in the datastore to examine when executing a query, but extents can also iterate the entire class of persistent application data objects. When a query uses an extent, the JDO implementation usually translates the query into the datastore's query language and sends it to the datastore service. The persistence manager is the factory that creates Extent objects.

An extent acts like a read-only collection but does not implement the Java Collection interface. Like a Collection, it can be iterated, but it does not have a size method, and it has no mutating methods. There are two ways to determine if a particular object is a member of an extent. The extent can be iterated, or a query can be executed that uses the extent. The application cannot add objects to, nor can it delete objects from, an extent directly. Instead, the application accomplishes these tasks indirectly by calling the persistence manager's makePersistent and deletePersistent methods.

Extents and the Persistence Manager's IgnoreCache Property

Extents are always up-to-date with regard to the effects of committed transactions. If a committed transaction added an object to the extent by the makePersistent method or removed it from the extent by the deletePersistent method, a new iteration of the extent will always include the addition and exclude the deletion. These committed transactions might be previous transactions for the current persistence manager from which the extent was obtained, or they may be transactions committed by other persistence managers. It depends on the implementation whether an open iterator on an extent reflects the committed transactions that have occurred since the iterator was opened.

On the other hand, it is possible that an extent will not include the additions or exclude the deletions made within the current, uncommitted transaction. Whether the effects of calling makePersistent or deletePersistent are visible to a new iterator depends on the setting of the IgnoreCache flag in the persistence manager that produced the extent at the time that the iterator is obtained. If the flag is set to false, then the extent's iterator will include the additions and exclude the deletions made within the current transaction. In other words, when the IgnoreCache flag is false, uncommitted changes in the current transaction are treated the same as committed changes in previous or other transactions. If the flag is set to true, then the iterator may exclude the changes made within the current transaction. In this case, the setting is a hint which the implementation may, or may not, follow.

The Factory Method That Produces Extent Objects

Although Chapter 3 describes the PersistenceManager interface, this is the appropriate place to look at its factory method that produces Extent objects.

 public Extent getExtent(Class adClass, boolean getSubclasses) 

This method is the only way to obtain an Extent object. The adClass parameter is the Class object for any application data class. The getSubclasses flag determines whether the extent includes objects in the subclasses, if any, of the adClass. As long as the persistence manager remains open, an Extent object can be used and reused.

An application data class does not have an extent if the JDO metadata turns off this feature for the class. In this case, getExtent throws a JDOUserException. Chapter 5 describes the JDO metadata.

Starting with JDO 1.0.1, an application can obtain an extent regardless of the value of the transaction's Active property or its NontransactionalRead property. Chapter 4 discusses the Transaction interface.

Figure 2-1 shows the UML class diagram of the Extent interface. Six methods define the four operations and two read-only properties shown in Figure 2-1.

Figure 2-1: The class diagram of the Extent interface

The Read-Only CandidateClass Property

The Extent interface provides a getter method that returns the read-only CandidateClass property.

 public Class getCandidateClass() 

This method returns the Class object for the application data class used to obtained the extent. Every persistent object returned by iterating the extent is assignment compatible with the CandidateClass.

The Read-Only PersistenceManager Property

The Extent interface provides a getter method that returns the read-only PersistenceManager property.

 public PersistenceManager getPersistenceManager() 

This method returns the persistence manager that produced the extent.

Determining Whether the Extent Includes Subclasses

The Extent interface provides one method to determine whether the extent includes objects of subclasses of the CandidateClass.

 public boolean hasSubclasses() 

The value returned by the hasSubclasses method is the value of the flag passed to the getExtent method. When true, iterators return objects in the CandidateClass and all of its subclasses, if any. When false, iterators do not return objects in the subclasses of the CandidateClass.

Obtaining an Iterator over the Extent

The Extent interface provides a factory method that returns iterators.

 public java.util.Iterator iterator() 

The iterators obtained from the extent iterate the objects of the extent. Iterators obtained from an extent do not support the mutating methods in the Iterator interface. Calling a mutating method in the iterator results in an java.lang.UnsupportedOperationException. To obtain an iterator, either the transaction's NontransactionalRead property must be true or the transaction must be active. If these conditions are not met, then this method throws a JDOUserException. Chapter 4 describes the Transaction interface.

Closing Extent Iterators

The Extent interface provides two methods to close an iterator.

 public void close(java.util.Iterator iter) public void closeAll() 

The close method closes an iterator. Because the iterators are likely tied to resource usage in the datastore, they should be closed when no longer needed. After an iterator is closed, its hasNext method returns false and its next method throws a java.util.NoSuchElementException. Closing an iterator has no effect on new or other existing iterators for the extent.

The closeAll method closes all open iterators on the extent.