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   * FetchGroup.java
    20   *
    21   */
    22
    23  package javax.jdo;
    24
    25  import java.util.Set;
    26
    27  /**
    28   * FetchGroup represents a named fetch group for a specific class or
    29   * interface. A fetch group instance identifies the name of the class or
    30   * interface, the list of members (fields or properties) to be fetched when
    31   * the fetch group is active, and the recursion depth for each member.
    32   * <p>
    33   * Fetch groups are updated using methods on this interface. An instance of
    34   * a class implementing this interface can be obtained from
    35   * {@link PersistenceManager#getFetchGroup} or
    36   * {@link PersistenceManagerFactory#getFetchGroup}.
    37   * <p>
    38   * A FetchGroup can be unscoped or can be in one of two scopes (the
    39   * {@link PersistenceManager} or the {@link PersistenceManagerFactory} scope).
    40   * Unscoped FetchGroups do not affect any behavior.
    41   * A FetchGroup in PersistenceManager scope hides the corresponding
    42   * FetchGroup in the PersistenceManagerFactory scope.
    43   * <ul><li>When a FetchGroup is obtained via
    44   * {@link PersistenceManager#getFetchGroup},
    45   * it is immediately in scope of its <code>PersistenceManager</code>.
    46   * Subsequent modifications of the FetchGroup
    47   * immediately affect <code>FetchPlan</code>s that contain the
    48   * <code>FetchGroup</code>.
    49   * </li><li>When a FetchGroup is obtained via
    50   * {@link PersistenceManagerFactory#getFetchGroup}, it is unscoped.
    51   * </li><li>When a FetchGroup is added to the set of active FetchGroups via
    52   * {@link PersistenceManagerFactory#addFetchGroups}, it is put in scope of the
    53   * <code>PersistenceManagerFactory</code>.
    54   * </li><li>When a FetchGroup is removed from the set of active FetchGroups via
    55   * {@link PersistenceManagerFactory#removeFetchGroups},
    56   * {@link PersistenceManagerFactory#removeAllFetchGroups}, or replaced via
    57   * {@link PersistenceManagerFactory#addFetchGroups}, it is unscoped.
    58   * </li></ul>
    59   * @version 2.2
    60   * @since 2.2
    61   */
    62  public interface FetchGroup {
    63
    64      /**
    65       * For use with {@link #addCategory} and {@link #removeCategory} calls.
    66       * This category includes members defined in the default fetch group
    67       * in xml or annotations. Redefining the default fetch group via the API
    68       * does not affect the members defined by this category.
    69       * <p>
    70       * Using this category also sets the fetch-depth for the members in the
    71       * default fetch group.</p>
    72       * @since 2.2
    73       */
    74      public static final String DEFAULT = "default";
    75
    76      /**
    77       * For use with {@link #addCategory} and {@link #removeCategory} calls.
    78       * This category includes members of all relationship types.
    79       * @since 2.2
    80       */
    81      public static final String RELATIONSHIP = "relationship";
    82
    83      /**
    84       * For use with {@link #addCategory} and {@link #removeCategory} calls.
    85       * This category includes members of all multi-valued types, including
    86       * Collection, array, and Map types of basic and relationship types.
    87       * @since 2.2
    88       */
    89      public static final String MULTIVALUED = "multivalued";
    90
    91      /**
    92       * For use with {@link #addCategory} and {@link #removeCategory} calls.
    93       * This category includes members of all primitive and immutable
    94       * object class types as defined in section 6.4 of the specification,
    95       * including String, Locale, Currency, BigDecimal, and BigInteger;
    96       * as well as Date and its jdbc subtypes and Enum types.
    97       * @since 2.2
    98       */
    99      public static final String BASIC = "basic";
    100
    101     /**
    102      * For use with {@link #addCategory} and {@link #removeCategory} calls.
    103      * This category includes all members in the persistent type.
    104      * <p>
    105      * Using this category also sets the fetch-depth for the members in the
    106      * default fetch group.</p>
    107      * @since 2.2
    108      */
    109     public static final String ALL = "all";
    110
    111     /**
    112      * Return the hashCode for this instance. The hash code should combine both
    113      * the class and fetch group name. The hash codes for two equal instances
    114      * must be identical.
    115      * @return the hash code
    116      * @since 2.2
    117      */
    118     int hashCode();
    119
    120     /**
    121      * Return whether this instance is equal to the other. The equals method
    122      * must compare the class for identity and the fetch group name for
    123      * equality.
    124      * @return whether this instance is equal to the other
    125      * @since 2.2
    126      */
    127     boolean equals(Object other);
    128
    129     /**
    130      * Get the name of this FetchGroup. The name is set only in the
    131      * factory method.
    132      * @return the name
    133      * @since 2.2
    134      */
    135     String getName();
    136
    137     /**
    138      * Get the persistent type (class or interface) of this FetchGroup.
    139      * The persistent type is set only in the factory method(s).
    140      * @return the persistent type
    141      * @since 2.2
    142      */
    143     Class getType();
    144
    145     /**
    146      * Get the post-load property of this FetchGroup.
    147      * @return the post-load property
    148      * @since 2.2
    149      */
    150     boolean getPostLoad();
    151
    152     /**
    153      * Set the post-load property of this FetchGroup.
    154      * @return the FetchGroup
    155      * @throws JDOUserException if the FetchGroup is unmodifiable
    156      * @since 2.2
    157      */
    158     FetchGroup setPostLoad(boolean postLoad);
    159
    160     /**
    161      * Add the member (field or property) to the set of members in this
    162      * FetchGroup.
    163      * @param memberName the name of a member to add to the FetchGroup
    164      * @return the FetchGroup
    165      * @throws JDOUserException if the parameter is not a member of the
    166      * persistent type
    167      * @throws JDOUserException if the FetchGroup is unmodifiable
    168      * @since 2.2
    169      */
    170     FetchGroup addMember(String memberName);
    171
    172     /**
    173      * Add the member (field or property) to the set of members in this
    174      * FetchGroup. Duplicates are ignored.
    175      * @param memberNames the names of members to add to the FetchGroup
    176      * @return the FetchGroup
    177      * @throws JDOUserException if any parameter is not a member of the
    178      * persistent type
    179      * @throws JDOUserException if the FetchGroup is unmodifiable
    180      * @since 2.2
    181      */
    182     FetchGroup addMembers(String... memberNames);
    183
    184     /**
    185      * Remove the member (field or property) from the set of members in this
    186      * FetchGroup.
    187      * @return the FetchGroup
    188      * @throws JDOUserException if the parameter is not a member of the
    189      * persistent type
    190      * @throws JDOUserException if the FetchGroup is unmodifiable
    191      * @since 2.2
    192      */
    193     FetchGroup removeMember(String memberName);
    194
    195     /**
    196      * Remove the member (field or property) from the set of members in this
    197      * FetchGroup. Duplicates in the parameter list are eliminated before
    198      * removing them from the membership.
    199      * @return the FetchGroup
    200      * @throws JDOUserException if any parameter is not a member of the
    201      * persistent type
    202      * @throws JDOUserException if the FetchGroup is unmodifiable
    203      * @since 2.2
    204      */
    205     FetchGroup removeMembers(String... memberNames);
    206
    207     /**
    208      * Add the members (fields or properties) of the named category
    209      * to the set of members in this FetchGroup. This method first
    210      * resolves the category name to a set of members and then adds
    211      * the members as if {@link #addMembers} was called. After this
    212      * method executes, the category is not remembered.
    213      * @return the FetchGroup
    214      * @throws JDOUserException if the FetchGroup is unmodifiable
    215      * @since 2.2
    216      */
    217     FetchGroup addCategory(String categoryName);
    218
    219     /**
    220      * Remove the members (fields or properties) of the named category
    221      * from the set of members in this FetchGroup. This method first
    222      * resolves the category name to a set of members and then removes
    223      * the members as if {@link #removeMembers} was called. After this
    224      * method executes, the category is not remembered.
    225      * @return the FetchGroup
    226      * @throws JDOUserException if the FetchGroup is unmodifiable
    227      * @since 2.2
    228      */
    229     FetchGroup removeCategory(String categoryName);
    230
    231     /**
    232      * Set the recursion-depth for this member. The default is 1. A value of 0
    233      * means don't fetch the member (as if the member were omitted entirely).
    234      * A value of -1 means fetch all instances reachable via this member.
    235      * @return the FetchGroup
    236      * @param memberName the name of the field or property
    237      * @param recursionDepth the value for the recursion-depth property
    238      * @throws JDOUserException if the member does not exist
    239      * @throws JDOUserException if the FetchGroup is unmodifiable
    240      * @since 2.2
    241      */
    242     FetchGroup setRecursionDepth(String memberName, int recursionDepth);
    243
    244     /**
    245      * Get the recursion-depth for this member.
    246      * @param memberName the name of the field or property
    247      * @return the recursion-depth for this member
    248      * @throws JDOUserException if the member is not in the FetchGroup
    249      * @since 2.2
    250      */
    251     int getRecursionDepth(String memberName);
    252
    253     /**
    254      * Return an immutable Set of String containing the names of all members.
    255      * The Set is a copy of the currently defined members and will not change
    256      * based on subsequent changes to the membership in the FetchGroup.
    257      * @return an immutable Set containing the names of all members
    258      * in the FetchGroup
    259      * @since 2.2
    260      */
    261     Set getMembers();
    262
    263     /**
    264      * Make this FetchGroup unmodifiable. If already unmodifiable, this method
    265      * has no effect.
    266      * @return the FetchGroup
    267      * @since 2.2
    268      */
    269     FetchGroup setUnmodifiable();
    270
    271     /**
    272      * Return whether this FetchGroup is unmodifiable. If so, methods
    273      * {@link #setPostLoad}, {@link #addMember}, {@link #removeMember},
    274      * {@link #addMembers}, {@link #removeMembers},
    275      * {@link #addCategory}, and {@link #removeCategory}
    276      * will throw {@link JDOUserException}.
    277      * @return whether the FetchGroup is unmodifiable
    278      * @since 2.2
    279      */
    280     boolean isUnmodifiable();
    281 }