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