View Javadoc

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