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   * FetchPlan.java
    20   *
    21   */
    22
    23  package javax.jdo;
    24
    25  import java.util.Collection;
    26  import java.util.Set;
    27
    28  /**
    29   * Fetch groups are activated using methods on this interface. An
    30   * instance of this interface can be obtained from {@link
    31   * PersistenceManager#getFetchPlan}, {@link Extent#getFetchPlan}, and
    32   * {@link Query#getFetchPlan}. When a <code>Query</code> or
    33   * <code>Extent</code> is retrieved from a
    34   * <code>PersistenceManager</code>, its <code>FetchPlan</code> is
    35   * initialized to the same settings as that of the
    36   * <code>PersistenceManager</code>. Subsequent modifications of the
    37   * <code>Query</code> or <code>Extent</code>'s <code>FetchPlan</code>
    38   * are not reflected in the <code>FetchPlan</code> of the
    39   * <code>PersistenceManager</code>.
    40   * @version 2.0
    41   * @since 2.0
    42   */
    43  public interface FetchPlan {
    44
    45      /**
    46       * For use with {@link #addGroup}, {@link #removeGroup}, and the
    47       * various {@link #setGroups} calls. Value: <code>default</code>.
    48       * @since 2.0
    49       */
    50      public static final String DEFAULT = "default";
    51
    52      /**
    53       * For use with {@link #addGroup}, {@link #removeGroup}, and the
    54       * various {@link #setGroups} calls. Value: <code>all</code>.
    55       * @since 2.0
    56       */
    57      public static final String ALL = "all";
    58
    59      /**
    60       * For use with {@link PersistenceManager#detachCopy} and
    61       * {@link #setDetachmentOptions}. Specifies that
    62       * fields that are loaded but not in the current fetch plan should
    63       * be unloaded prior to detachment.
    64       * @since 2.0
    65       */
    66      public static final int DETACH_UNLOAD_FIELDS = 2;
    67
    68      /**
    69       * For use with {@link PersistenceManager#detachCopy} and
    70       * {@link #setDetachmentOptions}. Specifies that
    71       * fields that are not loaded but are in the current fetch plan should
    72       * be loaded prior to detachment.
    73       * @since 2.0
    74       */
    75      public static final int DETACH_LOAD_FIELDS = 1;
    76
    77      /**
    78       * For use with {@link #setFetchSize}. Value: -1.
    79       * @since 2.0
    80       */
    81      public static final int FETCH_SIZE_GREEDY = -1;
    82
    83      /**
    84       * For use with {@link #setFetchSize}. Value: 0.
    85       * @since 2.0
    86       */
    87      public static final int FETCH_SIZE_OPTIMAL = 0;
    88
    89      /**
    90       * Add the fetch group to the set of active fetch groups.
    91       * @return the FetchPlan
    92       * @since 2.0
    93       */
    94      FetchPlan addGroup(String fetchGroupName);
    95
    96      /**
    97       * Remove the fetch group from the set active fetch groups.
    98       * @return the FetchPlan
    99       * @since 2.0
    100      */
    101     FetchPlan removeGroup(String fetchGroupName);
    102
    103     /**
    104      * Remove all active groups leaving no active fetch group.
    105      * @return the FetchPlan
    106      * @since 2.0
    107      */
    108     FetchPlan clearGroups();
    109
    110     /**
    111      * Return an immutable Set containing the names
    112      * of all active fetch groups. The Set is a copy of
    113      * the currently active groups and will not change
    114      * based on subsequent changes to the groups.
    115      * @return an immutable Set containing the names
    116      * of all currently active fetch groups
    117      * @since 2.0
    118      */
    119     Set getGroups();
    120
    121     /**
    122      * Set a collection of groups.
    123      * @param fetchGroupNames a collection of names of fetch groups
    124      * @return the FetchPlan
    125      * @since 2.0
    126      */
    127     FetchPlan setGroups(Collection fetchGroupNames);
    128
    129     /**
    130      * Set a collection of groups.
    131      * @param fetchGroupNames a String array of names of fetch groups
    132      * @return the FetchPlan
    133      * @since 2.0
    134      */
    135     FetchPlan setGroups(String... fetchGroupNames);
    136
    137     /**
    138      * Set the active fetch groups to the single named fetch group.
    139      * @param fetchGroupName the single fetch group
    140      * @return the FetchPlan
    141      * @since 2.0
    142      */
    143     FetchPlan setGroup(String fetchGroupName);
    144
    145     /**
    146      * Set the maximum fetch depth when fetching.
    147      * A value of 0 has no meaning and will throw a JDOUserException.
    148      * A value of -1 means that no limit is placed on fetching.
    149      * A positive integer will result in that number of references from the
    150      * initial object to be fetched.
    151      * @param fetchDepth the depth
    152      * @return the FetchPlan
    153      * @since 2.0
    154      */
    155     FetchPlan setMaxFetchDepth(int fetchDepth);
    156
    157     /**
    158      * Return the maximum fetch depth used when fetching instances.
    159      * @return the maximum fetch depth
    160      * @since 2.0
    161      */
    162     int getMaxFetchDepth();
    163
    164     /**
    165      * Set the roots for DetachAllOnCommit.
    166      * @param roots Collection of the detachment roots.
    167      * @since 2.0
    168      */
    169     FetchPlan setDetachmentRoots(Collection roots);
    170
    171     /**
    172      * Get the roots for DetachAllOnCommit.
    173      * @return Collection of detachment roots.
    174      * @since 2.0
    175      */
    176     Collection getDetachmentRoots();
    177
    178     /**
    179      * Set the root classes for DetachAllOnCommit.
    180      * @param rootClasses The root classes.
    181      * @since 2.0
    182      */
    183     FetchPlan setDetachmentRootClasses(Class... rootClasses);
    184
    185     /**
    186      * Get the root classes for DetachAllOnCommit.
    187      * @return The detachment root classes
    188      * @since 2.0
    189      */
    190     Class[] getDetachmentRootClasses();
    191
    192     /**
    193      * Set the fetch size for large result set support. Use
    194      * {@link #FETCH_SIZE_OPTIMAL} to unset, and {@link #FETCH_SIZE_GREEDY}
    195      * to force loading of everything.
    196      * @param fetchSize the fetch size
    197      * @return the FetchPlan
    198      * @since 2.0
    199      */
    200     FetchPlan setFetchSize(int fetchSize);
    201
    202     /**
    203      * Return the fetch size, or {@link #FETCH_SIZE_OPTIMAL} if not set,
    204      * or {@link #FETCH_SIZE_GREEDY} to fetch all.
    205      * @return the fetch size
    206      * @since 2.0
    207      */
    208     int getFetchSize();
    209
    210     /**
    211      * Set options to be used during detachment. Options are {@link
    212      * #DETACH_LOAD_FIELDS} and {@link #DETACH_UNLOAD_FIELDS}.
    213      */
    214     FetchPlan setDetachmentOptions(int options);
    215
    216     /**
    217      * Get options used during detachment.
    218      */
    219     int getDetachmentOptions();
    220
    221 }
    222