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.lang.Iterable;
26  import java.util.Iterator;
27  
28  /** Instances of the <code>Extent</code> class represent the entire collection
29   * of instances in the data store of the candidate class or interface
30   * possibly including its subclasses or subinterfaces.
31   * <P>The <code>Extent</code> instance has two possible uses:
32   * <ol>
33   * <li>to iterate all instances of a particular class or interface
34   * <li>to execute a <code>Query</code> in the data store over all instances
35   * of a particular class or interface
36   * </ol>
37   * @version 2.1
38   */
39  public interface Extent<E> extends Iterable<E> {
40          
41      /** Returns an iterator over all the instances in the <code>Extent</code>.
42       * The behavior of the returned iterator might depend on the setting of the
43       * <code>ignoreCache</code> flag in the owning <code>PersistenceManager</code>.
44       * @return an iterator over all instances in the <code>Extent</code>
45       */
46      Iterator<E> iterator();
47  
48      /** Returns whether this <code>Extent</code> was defined to contain subclasses.
49       * @return true if this <code>Extent</code> was defined to contain instances
50       * that are of a subclass type.
51       */    
52      boolean hasSubclasses();
53  
54      /** An <code>Extent</code> contains all instances of a particular class 
55       * or interface in the data
56       * store; this method returns the <code>Class</code> of the instances
57       * represented by this Extent.
58        * @return the <code>Class</code> of instances of this <code>Extent</code>.
59        */
60      Class<E> getCandidateClass();
61  
62      /** An <code>Extent</code> is managed by a <code>PersistenceManager</code>;
63       * this method gives access to the owning <code>PersistenceManager</code>.
64       * @return the owning <code>PersistenceManager</code>
65       */
66      PersistenceManager getPersistenceManager();
67      
68      /** Close all <code>Iterator</code>s associated with this <code>Extent</code> instance.
69       * <code>Iterator</code>s closed by this method will return <code>false</code>
70       * to <code>hasNext()</code> and will throw
71       * <code>NoSuchElementException</code> on <code>next()</code>.
72       * The <code>Extent</code> instance can still be used
73       * as a parameter of <code>Query.setExtent</code>, and to get an <code>Iterator</code>.
74       */    
75      void closeAll ();
76      
77      /** Close an <code>Iterator</code> associated with this <code>Extent</code> instance.
78       * <code>Iterator</code>s closed by this method will return <code>false</code>
79       * to <code>hasNext()</code> and will throw <code>NoSuchElementException</code>
80       * on <code>next()</code>. The <code>Extent</code> instance can still be used
81       * as a parameter of <code>Query.setExtent</code>, and to get an <code>Iterator</code>.
82       * @param it an <code>Iterator</code> obtained by the method
83       * <code>iterator()</code> on this <code>Extent</code> instance.
84       */    
85      void close (Iterator<E> it);
86      
87      /** Get the fetch plan associated with this Extent.
88       * @return the fetch plan
89       * @since 2.0
90       */
91      FetchPlan getFetchPlan();
92  }
93