Chapter 10. Extent
Prev | Part 3. Java Data Objects | Next

## Chapter 10. Extent

An `Extent` is a logical view of all persistent instances of a given persistence-capable class, possibly including subclasses. `Extent`s are obtained from `PersistenceManager`s, and are usually used to specify the candidate objects to a `Query`.

| Note
Kodo extends the standard `Extent` with the `KodoExtent` interface to provide additional functionality. You can cast any `Extent` in Kodo to a `KodoExtent`.

    public Class getCandidateClass ();
    public boolean hasSubclasses ();

The `getCandidateClass` method returns the persistence-capable class of the `Extent`'s instances. The `hasSubclasses` method indicates whether instances of subclasses are part of the `Extent` as well.

    public FetchPlan getFetchPlan ();

Before iterating an `Extent`, you may want to use the `FetchPlan` to optimize which fields and relations of the returned objects will be loaded, and to configure result scrolling. See Chapter 12, FetchPlan for details on the `FetchPlan` interface.

When you create an `Extent` with `PersistenceManager.getExtent`, the `Extent`'s `FetchPlan` is initialized to the same values as the plan of its owning `PersistenceManager`. Subsequent changes to the `Extent`'s `FetchPlan`, however, will not affect the `PersistenceManager`'s plan.

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

You can obtain an iterator over every object in an `Extent` using the `iterator` method. The iterators used by some implementations might consume datastore resources; therefore, you should always close an `Extent`'s iterators as soon as you are done with them. You can close an individual iterator by passing it to the `close` method, or all open iterators at once with `closeAll`.

| Note
Kodo may use scrollable JDBC `ResultSet`s when large data sets are being iterated. Combined with Kodo's memory-sensitive data structures, this allows you to efficiently iterate over huge data sets - even when the entire data set could not possibly fit into memory at once. These scrollable results consume database resources, however, so you are strongly encouraged to close your iterators when you are through with them. If they are not closed immediately, they will be closed when they are garbage collected by the JVM.

Example 10.1. Iterating an Extent

    PersistenceManager pm = ...;

    Extent mags = pm.getExtent (Magazine.class, true);
    Iterator itr = employees.iterator ();
    while (itr.hasNext ())
        processMagazine ((Magazine) itr.next ());
    mags.close (itr);

Prev | Up | Next
9.2. The JDO Transaction Interface | Home | Chapter 11. Query