View Javadoc

1   /*
2    * Copyright 2005 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at 
7    * 
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software 
11   * distributed under the License is distributed on an "AS IS" BASIS, 
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
13   * See the License for the specific language governing permissions and 
14   * limitations under the License.
15   */
16  
17  /*
18   * Extent.java
19   *
20   */
21  
22  package javax.jdo;
23  
24  import java.util.Iterator;
25  
26  /*** Instances of the <code>Extent</code> class represent the entire collection
27   * of instances in the data store of the candidate class
28   * possibly including its subclasses.
29   * <P>The <code>Extent</code> instance has two possible uses:
30   * <ol>
31   * <li>to iterate all instances of a particular class 
32   * <li>to execute a <code>Query</code> in the data store over all instances
33   * of a particular class
34   * </ol>
35   * @version 2.0
36   */
37  public interface Extent {
38          
39      /*** Returns an iterator over all the instances in the <code>Extent</code>.
40       * The behavior of the returned iterator might depend on the setting of the
41       * <code>ignoreCache</code> flag in the owning <code>PersistenceManager</code>.
42       * @return an iterator over all instances in the <code>Extent</code>
43       */
44      Iterator iterator();
45  
46      /*** Returns whether this <code>Extent</code> was defined to contain subclasses.
47       * @return true if this <code>Extent</code> was defined to contain instances
48       * that are of a subclass type.
49       */    
50      boolean hasSubclasses();
51  
52      /*** An <code>Extent</code> contains all instances of a particular class in the data
53       * store; this method returns the <code>Class</code> of the instances.
54        * @return the <code>Class</code> of instances of this <code>Extent</code>.
55        */
56      Class getCandidateClass();
57  
58      /*** An <code>Extent</code> is managed by a <code>PersistenceManager</code>;
59       * this method gives access to the owning <code>PersistenceManager</code>.
60       * @return the owning <code>PersistenceManager</code>
61       */
62      PersistenceManager getPersistenceManager();
63      
64      /*** Close all <code>Iterator</code>s associated with this <code>Extent</code> instance.
65       * <code>Iterator</code>s closed by this method will return <code>false</code>
66       * to <code>hasNext()</code> and will throw
67       * <code>NoSuchElementException</code> on <code>next()</code>.
68       * The <code>Extent</code> instance can still be used
69       * as a parameter of <code>Query.setExtent</code>, and to get an <code>Iterator</code>.
70       */    
71      void closeAll ();
72      
73      /*** Close an <code>Iterator</code> associated with this <code>Extent</code> instance.
74       * <code>Iterator</code>s closed by this method will return <code>false</code>
75       * to <code>hasNext()</code> and will throw <code>NoSuchElementException</code>
76       * on <code>next()</code>. The <code>Extent</code> instance can still be used
77       * as a parameter of <code>Query.setExtent</code>, and to get an <code>Iterator</code>.
78       * @param it an <code>Iterator</code> obtained by the method
79       * <code>iterator()</code> on this <code>Extent</code> instance.
80       */    
81      void close (Iterator it);
82      
83      /*** Get the fetch plan associated with this Extent.
84       * @return the fetch plan
85       * @since 2.0
86       */
87      FetchPlan getFetchPlan();
88  }
89