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   * StateInterrogation.java
    20   *
    21   */
    22
    23  package javax.jdo.spi;
    24
    25  import javax.jdo.PersistenceManager;
    26
    27  /**
    28   * This interface is implemented by a non-binary-compatible JDO implementation
    29   * to provide state interrogation for non-enhanced persistent classes.
    30   *
    31   * <P>A call to JDOHelper to get the status of an instance is handled
    32   * internally if the parameter instance implements PersistenceCapable.
    33   * For non-binary-compatible implementations, there is no requirement
    34   * that persistent instances implement PersistenceCapable. Therefore,
    35   * if the parameter does not implement PersistenceCapable, JDOHelper
    36   * delegates to all registered instances of StateInterrogation until
    37   * an instance can handle the request.
    38   * <P>For JDOHelper isXXX methods, which return boolean, the
    39   * corresponding method in StateInterrogation returns Boolean. If the
    40   * return value is <code>null</code> then the StateInterrogation does
    41   * not recognize the parameter as being handled by it. A non-null return
    42   * value indicates that the implementation has determined the answer.
    43   * <P>For JDOHelper getXXX methods, which return an Object, each
    44   * registered StateInterrogation is given the parameter until one of
    45   * them returns a non-null value, which is passed to the caller.
    46   * <P>For JDOHelper makeDirty, each
    47   * registered StateInterrogation is given the parameter until one of
    48   * them returns true, indicating that it has handled the call.
    49   * An instance that implements this interface must be registered with the
    50   * {@link JDOImplHelper}.
    51   * @version 2.0
    52   * @since 2.0
    53   */
    54  public interface StateInterrogation {
    55
    56
    57      /** Tests whether the parameter instance is persistent.
    58       *
    59       * Instances that represent persistent objects in the data store
    60       * return <code>Boolean.TRUE</code>.
    61       *
    62       * <P>Instances known by the implementation to be non-persistent
    63       * return <code>Boolean.FALSE</code>.
    64       *
    65       * <P>Instances not recognized by the implementation return
    66       * <code>null</code>.
    67       *
    68       * @see PersistenceManager#makePersistent(Object pc)
    69       * @see PersistenceCapable#jdoIsPersistent()
    70       * @param pc the instance.
    71       * @return <code>Boolean.TRUE</code> if the parameter instance is persistent.
    72       */
    73      Boolean isPersistent (Object pc);
    74
    75      /** Tests whether the parameter instance is transactional.
    76       *
    77       * Instances whose state is associated with the current transaction
    78       * return <code>Boolean.TRUE</code>.
    79       *
    80       * <P>Instances known by the implementation to be non-transactional
    81       * return <code>Boolean.FALSE</code>.
    82       *
    83       * <P>Instances not recognized by the implementation return
    84       * <code>null</code>.
    85       *
    86       * @see PersistenceCapable#jdoIsTransactional()
    87       * @param pc the instance.
    88       * @return <code>Boolean.TRUE</code> if the parameter instance is transactional.
    89       */
    90      Boolean isTransactional (Object pc);
    91
    92      /** Tests whether the parameter instance is dirty.
    93       *
    94       * Instances that have been modified, deleted, newly
    95       * made persistent in the current transaction,
    96       * or modified while detached return <code>Boolean.TRUE</code>.
    97       *
    98       * <P>Instances known by the implementation to be non-dirty
    99       * return <code>Boolean.FALSE</code>.
    100      *
    101      * <P>Instances not recognized by the implementation return
    102      * <code>null</code>.
    103      *
    104      * @see StateManager#makeDirty(PersistenceCapable pc, String fieldName)
    105      * @see PersistenceCapable#jdoIsDirty()
    106      * @param pc the instance.
    107      * @return <code>Boolean.TRUE</code> if the parameter instance has been modified
    108      * in the current transaction, or while detached.
    109      */
    110     Boolean isDirty (Object pc);
    111
    112     /** Tests whether the parameter instance has been newly made persistent.
    113      *
    114      * Instances that have been made persistent in the current transaction
    115      * return <code>Boolean.TRUE</code>.
    116      *
    117      * <P>Instances known by the implementation to be non-new
    118      * return <code>Boolean.FALSE</code>.
    119      *
    120      * <P>Instances not recognized by the implementation return
    121      * <code>null</code>.
    122      *
    123      * @see PersistenceManager#makePersistent(Object pc)
    124      * @see PersistenceCapable#jdoIsNew()
    125      * @param pc the instance.
    126      * @return <code>Boolean.TRUE</code> if the parameter instance was made persistent
    127      * in the current transaction.
    128      */
    129     Boolean isNew (Object pc);
    130
    131     /** Tests whether the parameter instance has been deleted.
    132      *
    133      * Instances that have been deleted in the current transaction
    134      * return <code>Boolean.TRUE</code>.
    135      *
    136      * <P>Instances known by the implementation to be non-deleted
    137      * return <code>Boolean.FALSE</code>.
    138      *
    139      * <P>Instances not recognized by the implementation return
    140      * <code>null</code>.
    141      *
    142      * @see PersistenceManager#deletePersistent(Object pc)
    143      * @see PersistenceCapable#jdoIsDeleted()
    144      * @param pc the instance.
    145      * @return <code>Boolean.TRUE</code> if the parameter instance was deleted
    146      * in the current transaction.
    147      */
    148     Boolean isDeleted (Object pc);
    149
    150     /** Tests whether the parameter instance is detached.
    151      *
    152      * Instances that are detached return <code>Boolean.TRUE</code>.
    153      *
    154      * <P>Instances known by the implementation to be non-detached
    155      * return <code>Boolean.FALSE</code>.
    156      *
    157      * <P>Instances not recognized by the implementation return
    158      * <code>null</code>.
    159      *
    160      * @see PersistenceManager#detachCopy(Object pc)
    161      * @see PersistenceCapable#jdoIsDeleted()
    162      * @param pc the instance.
    163      * @return <code>Boolean.TRUE</code> if the parameter instance is detached.
    164      */
    165     Boolean isDetached (Object pc);
    166
    167     /** Return the associated <code>PersistenceManager</code> if there is one.
    168      * Transactional and persistent instances return the associated
    169      * <code>PersistenceManager</code>.
    170      *
    171      * <P>Transient non-transactional instances return <code>null</code>.
    172      * <P>Instances unknown by the implementation return <code>null</code>.
    173      * @see PersistenceCapable#jdoGetPersistenceManager()
    174      * @param pc the instance.
    175      * @return the <code>PersistenceManager</code> associated with the
    176      * parameter instance.
    177      */
    178     PersistenceManager getPersistenceManager (Object pc);
    179
    180     /** Return a copy of the JDO identity associated with the parameter
    181      * instance.
    182      *
    183      * <P>Persistent instances of <code>PersistenceCapable</code> classes
    184      * have a JDO identity
    185      * managed by the <code>PersistenceManager</code>.  This method returns
    186      * a copy of the
    187      * ObjectId that represents the JDO identity.
    188      *
    189      * <P>Instances unknown by the implementation return <code>null</code>.
    190      * <P>The ObjectId may be serialized
    191      * and later restored, and used with a <code>PersistenceManager</code>
    192      * from the same JDO
    193      * implementation to locate a persistent instance with the same data store
    194      * identity.
    195      *
    196      * <P>If the JDO identity is managed by the application, then the ObjectId
    197      * may be used with a <code>PersistenceManager</code> from any JDO
    198      * implementation that supports
    199      * the <code>PersistenceCapable</code> class.
    200      *
    201      * <P>If the JDO identity is not managed by the application or the data
    202      * store, then the ObjectId returned is only valid within the current
    203      * transaction.
    204      *<P>
    205      * @see PersistenceManager#getObjectId(Object pc)
    206      * @see PersistenceCapable#jdoGetObjectId()
    207      * @see PersistenceManager#getObjectById(Object oid, boolean validate)
    208      * @param pc the instance.
    209      * @return a copy of the ObjectId of the parameter instance as of the
    210      * beginning of the transaction.
    211      */
    212     Object getObjectId (Object pc);
    213
    214     /** Return a copy of the JDO identity associated with the parameter
    215      * instance.
    216      *
    217      * <P>Instances unknown by the implementation return <code>null</code>.
    218      * @see PersistenceCapable#jdoGetTransactionalObjectId()
    219      * @see PersistenceManager#getObjectById(Object oid, boolean validate)
    220      * @param pc the instance.
    221      * @return a copy of the ObjectId of the parameter instance as modified
    222      * in this transaction.
    223      */
    224     Object getTransactionalObjectId (Object pc);
    225
    226     /** Return the version of the parameter instance.
    227      *
    228      * <P>Instances unknown by the implementation return <code>null</code>.
    229      * @see PersistenceCapable#jdoGetVersion()
    230      * @param pc the instance.
    231      * @return a copy of the ObjectId of the parameter instance as modified
    232      * in this transaction.
    233      */
    234     Object getVersion (Object pc);
    235
    236     /** Explicitly mark the parameter instance and field dirty.
    237      * Normally, <code>PersistenceCapable</code> classes are able to detect
    238      * changes made
    239      * to their fields.  However, if a reference to an array is given to a
    240      * method outside the class, and the array is modified, then the
    241      * persistent instance is not aware of the change.  This API allows the
    242      * application to notify the instance that a change was made to a field.
    243      *
    244      * <P>Instances unknown by the implementation are unaffected.
    245      * @see PersistenceCapable#jdoMakeDirty(String fieldName)
    246      * @param pc the instance.
    247      * @param fieldName the name of the field to be marked dirty.
    248      */
    249     boolean makeDirty (Object pc, String fieldName);
    250
    251 }