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  package javax.jdo.spi;
    19
    20  import javax.jdo.PersistenceManager;
    21
    22  /** This interface is the point of contact between managed instances of
    23   * <code>PersistenceCapable</code> classes and the JDO implementation.  It
    24   * contains the methods used by <code>PersistenceCapable</code> instances to
    25   * delegate behavior to the JDO implementation.
    26   *<P>Each managed <code>PersistenceCapable</code> instance contains a reference
    27   * to a <code>StateManager</code>.  A <code>StateManager</code> might manage one
    28   * or multiple instances of <code>PersistenceCapable</code> instances, at the
    29   * choice of the implementation.
    30   *
    31   * @version 2.0
    32   *
    33   */
    34  public interface StateManager {
    35
    36      /** The owning <code>StateManager</code> uses this method to supply the
    37       * value of the flags to the <code>PersistenceCapable</code> instance.
    38       * @param pc the calling <code>PersistenceCapable</code> instance
    39       * @return the value of <code>jdoFlags</code> to be stored in the
    40       * <code>PersistenceCapable</code> instance
    41       */
    42      byte replacingFlags(PersistenceCapable pc);
    43
    44      /** Replace the current value of <code>jdoStateManager</code>.
    45       * <P>
    46       * This method is called by the <code>PersistenceCapable</code> whenever
    47       * <code>jdoReplaceStateManager</code> is called and there is already
    48       * an owning <code>StateManager</code>.  This is a security precaution
    49       * to ensure that the owning <code>StateManager</code> is the only
    50       * source of any change to its reference in the
    51       * <code>PersistenceCapable</code>.
    52       * @return the new value for the <code>jdoStateManager</code>
    53       * @param pc the calling <code>PersistenceCapable</code> instance
    54       * @param sm the proposed new value for the <code>jdoStateManager</code>
    55       */
    56      StateManager replacingStateManager (PersistenceCapable pc, StateManager sm);
    57
    58      /** Tests whether this object is dirty.
    59       *
    60       * Instances that have been modified, deleted, or newly
    61       * made persistent in the current transaction return <code>true</code>.
    62       *
    63       *<P>Transient nontransactional instances return <code>false</code>.
    64       *<P>
    65       * @see PersistenceCapable#jdoMakeDirty(String fieldName)
    66       * @param pc the calling <code>PersistenceCapable</code> instance
    67       * @return <code>true</code> if this instance has been modified in the
    68       * current transaction.
    69       */
    70      boolean isDirty(PersistenceCapable pc);
    71
    72      /** Tests whether this object is transactional.
    73       *
    74       * Instances that respect transaction boundaries return <code>true</code>.
    75       * These instances include transient instances made transactional as a
    76       * result of being the target of a <code>makeTransactional</code> method
    77       * call; newly made persistent or deleted persistent instances; persistent
    78       * instances read in data store transactions; and persistent instances
    79       * modified in optimistic transactions.
    80       *
    81       *<P>Transient nontransactional instances return <code>false</code>.
    82       *<P>
    83       * @param pc the calling <code>PersistenceCapable</code> instance
    84       * @return <code>true</code> if this instance is transactional.
    85       */
    86      boolean isTransactional(PersistenceCapable pc);
    87
    88      /** Tests whether this object is persistent.
    89       *
    90       * Instances whose state is stored in the data store return
    91       * <code>true</code>.
    92       *
    93       *<P>Transient instances return <code>false</code>.
    94       *<P>
    95       * @see PersistenceManager#makePersistent(Object pc)
    96       * @param pc the calling <code>PersistenceCapable</code> instance
    97       * @return <code>true</code> if this instance is persistent.
    98       */
    99      boolean isPersistent(PersistenceCapable pc);
    100
    101     /** Tests whether this object has been newly made persistent.
    102      *
    103      * Instances that have been made persistent in the current transaction
    104      * return <code>true</code>.
    105      *
    106      * <P>Transient instances return <code>false</code>.
    107      * <P>
    108      * @see PersistenceManager#makePersistent(Object pc)
    109      * @param pc the calling <code>PersistenceCapable</code> instance
    110      * @return <code>true</code> if this instance was made persistent
    111      * in the current transaction.
    112      */
    113     boolean isNew(PersistenceCapable pc);
    114
    115     /** Tests whether this object has been deleted.
    116      *
    117      * Instances that have been deleted in the current transaction return
    118      * <code>true</code>.
    119      *
    120      *<P>Transient instances return <code>false</code>.
    121      *<P>
    122      * @see PersistenceManager#deletePersistent(Object pc)
    123      * @param pc the calling <code>PersistenceCapable</code> instance
    124      * @return <code>true</code> if this instance was deleted
    125      * in the current transaction.
    126      */
    127     boolean isDeleted(PersistenceCapable pc);
    128
    129     /** Return the <code>PersistenceManager</code> that owns this instance.
    130      * @param pc the calling <code>PersistenceCapable</code> instance
    131      * @return the <code>PersistenceManager</code> that owns this instance
    132      */
    133     PersistenceManager getPersistenceManager (PersistenceCapable pc);
    134
    135     /** Mark the associated <code>PersistenceCapable</code> field dirty.
    136      * <P>The <code>StateManager</code> will make a copy of the field
    137      * so it can be restored if needed later, and then mark
    138      * the field as modified in the current transaction.
    139      * @param pc the calling <code>PersistenceCapable</code> instance
    140      * @param fieldName the name of the field
    141      */
    142     void makeDirty (PersistenceCapable pc, String fieldName);
    143
    144     /** Return the object representing the JDO identity
    145      * of the calling instance.  If the JDO identity is being changed in
    146      * the current transaction, this method returns the identity as of
    147      * the beginning of the transaction.
    148      * @param pc the calling <code>PersistenceCapable</code> instance
    149      * @return the object representing the JDO identity of the calling instance
    150      */
    151     Object getObjectId (PersistenceCapable pc);
    152
    153     /** Return the object representing the JDO identity
    154      * of the calling instance.  If the JDO identity is being changed in
    155      * the current transaction, this method returns the current identity as
    156      * changed in the transaction.
    157      * @param pc the calling <code>PersistenceCapable</code> instance
    158      * @return the object representing the JDO identity of the calling instance
    159      */
    160     Object getTransactionalObjectId (PersistenceCapable pc);
    161
    162     /** Return the object representing the version
    163      * of the calling instance.
    164      * @param pc the calling <code>PersistenceCapable</code> instance
    165      * @return the object representing the version of the calling instance
    166      * @since 2.0
    167      */
    168     Object getVersion (PersistenceCapable pc);
    169
    170     /** Return <code>true</code> if the field is cached in the calling
    171      * instance.
    172      * @param pc the calling <code>PersistenceCapable</code> instance
    173      * @param field the field number
    174      * @return whether the field is cached in the calling instance
    175      */
    176     boolean isLoaded (PersistenceCapable pc, int field);
    177
    178     /** Guarantee that the serializable transactional and persistent fields
    179      * are loaded into the instance.  This method is called by the generated
    180      * <code>jdoPreSerialize</code> method prior to serialization of the
    181      * instance.
    182      * @param pc the calling <code>PersistenceCapable</code> instance
    183      */
    184     void preSerialize (PersistenceCapable pc);
    185
    186     /** Return the value for the field.
    187      * @param pc the calling <code>PersistenceCapable</code> instance
    188      * @param field the field number
    189      * @param currentValue the current value of the field
    190      * @return the new value for the field
    191      */
    192     boolean getBooleanField (
    193             PersistenceCapable pc, int field, boolean currentValue);
    194
    195     /** Return the value for the field.
    196      * @param pc the calling <code>PersistenceCapable</code> instance
    197      * @param field the field number
    198      * @param currentValue the current value of the field
    199      * @return the new value for the field
    200      */
    201     char getCharField (PersistenceCapable pc, int field, char currentValue);
    202
    203     /** Return the value for the field.
    204      * @param pc the calling <code>PersistenceCapable</code> instance
    205      * @param field the field number
    206      * @param currentValue the current value of the field
    207      * @return the new value for the field
    208      */
    209     byte getByteField (PersistenceCapable pc, int field, byte currentValue);
    210
    211     /** Return the value for the field.
    212      * @param pc the calling <code>PersistenceCapable</code> instance
    213      * @param field the field number
    214      * @param currentValue the current value of the field
    215      * @return the new value for the field
    216      */
    217     short getShortField (PersistenceCapable pc, int field, short currentValue);
    218
    219     /** Return the value for the field.
    220      * @param pc the calling <code>PersistenceCapable</code> instance
    221      * @param field the field number
    222      * @param currentValue the current value of the field
    223      * @return the new value for the field
    224      */
    225     int getIntField (PersistenceCapable pc, int field, int currentValue);
    226
    227     /** Return the value for the field.
    228      * @param pc the calling <code>PersistenceCapable</code> instance
    229      * @param field the field number
    230      * @param currentValue the current value of the field
    231      * @return the new value for the field
    232      */
    233     long getLongField (PersistenceCapable pc, int field, long currentValue);
    234
    235     /** Return the value for the field.
    236      * @param pc the calling <code>PersistenceCapable</code> instance
    237      * @param field the field number
    238      * @param currentValue the current value of the field
    239      * @return the new value for the field
    240      */
    241     float getFloatField (PersistenceCapable pc, int field, float currentValue);
    242
    243     /** Return the value for the field.
    244      * @param pc the calling <code>PersistenceCapable</code> instance
    245      * @param field the field number
    246      * @param currentValue the current value of the field
    247      * @return the new value for the field
    248      */
    249     double getDoubleField (PersistenceCapable pc, int field,
    250                            double currentValue);
    251
    252     /** Return the value for the field.
    253      * @param pc the calling <code>PersistenceCapable</code> instance
    254      * @param field the field number
    255      * @param currentValue the current value of the field
    256      * @return the new value for the field
    257      */
    258     String getStringField (PersistenceCapable pc, int field,
    259                            String currentValue);
    260
    261     /** Return the value for the field.
    262      * @param pc the calling <code>PersistenceCapable</code> instance
    263      * @param field the field number
    264      * @param currentValue the current value of the field
    265      * @return the new value for the field
    266      */
    267     Object getObjectField (PersistenceCapable pc, int field,
    268                            Object currentValue);
    269
    270     /** Mark the field as modified by the user.
    271      * @param pc the calling <code>PersistenceCapable</code> instance
    272      * @param field the field number
    273      * @param currentValue the current value of the field
    274      * @param newValue the proposed new value of the field */
    275     void setBooleanField (PersistenceCapable pc, int field,
    276                           boolean currentValue, boolean newValue);
    277
    278     /** Mark the field as modified by the user.
    279      * @param pc the calling <code>PersistenceCapable</code> instance
    280      * @param field the field number
    281      * @param currentValue the current value of the field
    282      * @param newValue the proposed new value of the field */
    283     void setCharField (PersistenceCapable pc, int field,
    284                        char currentValue, char newValue);
    285
    286     /** Mark the field as modified by the user.
    287      * @param pc the calling <code>PersistenceCapable</code> instance
    288      * @param field the field number
    289      * @param currentValue the current value of the field
    290      * @param newValue the proposed new value of the field */
    291     void setByteField (PersistenceCapable pc, int field,
    292                        byte currentValue, byte newValue);
    293
    294     /** Mark the field as modified by the user.
    295      * @param pc the calling <code>PersistenceCapable</code> instance
    296      * @param field the field number
    297      * @param currentValue the current value of the field
    298      * @param newValue the proposed new value of the field */
    299     void setShortField (PersistenceCapable pc, int field,
    300                         short currentValue, short newValue);
    301
    302     /** Mark the field as modified by the user.
    303      * @param pc the calling <code>PersistenceCapable</code> instance
    304      * @param field the field number
    305      * @param currentValue the current value of the field
    306      * @param newValue the proposed new value of the field */
    307     void setIntField (PersistenceCapable pc, int field,
    308                       int currentValue, int newValue);
    309
    310     /** Mark the field as modified by the user.
    311      * @param pc the calling <code>PersistenceCapable</code> instance
    312      * @param field the field number
    313      * @param currentValue the current value of the field
    314      * @param newValue the proposed new value of the field */
    315     void setLongField (PersistenceCapable pc, int field,
    316                        long currentValue, long newValue);
    317
    318     /** Mark the field as modified by the user.
    319      * @param pc the calling <code>PersistenceCapable</code> instance
    320      * @param field the field number
    321      * @param currentValue the current value of the field
    322      * @param newValue the proposed new value of the field */
    323     void setFloatField (PersistenceCapable pc, int field,
    324                         float currentValue, float newValue);
    325
    326     /** Mark the field as modified by the user.
    327      * @param pc the calling <code>PersistenceCapable</code> instance
    328      * @param field the field number
    329      * @param currentValue the current value of the field
    330      * @param newValue the proposed new value of the field */
    331     void setDoubleField (PersistenceCapable pc, int field,
    332                          double currentValue, double newValue);
    333
    334     /** Mark the field as modified by the user.
    335      * @param pc the calling <code>PersistenceCapable</code> instance
    336      * @param field the field number
    337      * @param currentValue the current value of the field
    338      * @param newValue the proposed new value of the field */
    339     void setStringField (PersistenceCapable pc, int field,
    340                          String currentValue, String newValue);
    341
    342     /** Mark the field as modified by the user.
    343      * @param pc the calling <code>PersistenceCapable</code> instance
    344      * @param field the field number
    345      * @param currentValue the current value of the field
    346      * @param newValue the proposed new value of the field */
    347     void setObjectField (PersistenceCapable pc, int field,
    348                          Object currentValue, Object newValue);
    349
    350     /** The value of the field requested to be provided to the
    351      * <code>StateManager</code>.
    352      * @param pc the calling <code>PersistenceCapable</code> instance
    353      * @param field the field number
    354      * @param currentValue the current value of the field
    355      */
    356     void providedBooleanField (PersistenceCapable pc, int field,
    357                                boolean currentValue);
    358
    359     /** The value of the field requested to be provided to the
    360      * <code>StateManager</code>.
    361      * @param pc the calling <code>PersistenceCapable</code> instance
    362      * @param field the field number
    363      * @param currentValue the current value of the field
    364      */
    365     void providedCharField (PersistenceCapable pc, int field,
    366                             char currentValue);
    367
    368     /** The value of the field requested to be provided to the
    369      * <code>StateManager</code>.
    370      * @param pc the calling <code>PersistenceCapable</code> instance
    371      * @param field the field number
    372      * @param currentValue the current value of the field
    373      */
    374     void providedByteField (PersistenceCapable pc, int field,
    375                             byte currentValue);
    376
    377     /** The value of the field requested to be provided to the
    378      * <code>StateManager</code>.
    379      * @param pc the calling <code>PersistenceCapable</code> instance
    380      * @param field the field number
    381      * @param currentValue the current value of the field
    382      */
    383     void providedShortField (PersistenceCapable pc, int field,
    384                              short currentValue);
    385
    386     /** The value of the field requested to be provided to the
    387      * <code>StateManager</code>.
    388      * @param pc the calling <code>PersistenceCapable</code> instance
    389      * @param field the field number
    390      * @param currentValue the current value of the field
    391      */
    392     void providedIntField (PersistenceCapable pc, int field, int currentValue);
    393
    394     /** The value of the field requested to be provided to the
    395      * <code>StateManager</code>.
    396      * @param pc the calling <code>PersistenceCapable</code> instance
    397      * @param field the field number
    398      * @param currentValue the current value of the field
    399      */
    400     void providedLongField (PersistenceCapable pc, int field,
    401                             long currentValue);
    402
    403     /** The value of the field requested to be provided to the
    404      * <code>StateManager</code>.
    405      * @param pc the calling <code>PersistenceCapable</code> instance
    406      * @param field the field number
    407      * @param currentValue the current value of the field
    408      */
    409     void providedFloatField (PersistenceCapable pc, int field,
    410                              float currentValue);
    411
    412     /** The value of the field requested to be provided to the
    413      * <code>StateManager</code>.
    414      * @param pc the calling <code>PersistenceCapable</code> instance
    415      * @param field the field number
    416      * @param currentValue the current value of the field
    417      */
    418     void providedDoubleField (PersistenceCapable pc, int field,
    419                               double currentValue);
    420
    421     /** The value of the field requested to be provided to the
    422      * <code>StateManager</code>.
    423      * @param pc the calling <code>PersistenceCapable</code> instance
    424      * @param field the field number
    425      * @param currentValue the current value of the field
    426      */
    427     void providedStringField (PersistenceCapable pc, int field,
    428                               String currentValue);
    429
    430     /** The value of the field requested to be provided to the
    431      * <code>StateManager</code>.
    432      * @param pc the calling <code>PersistenceCapable</code> instance
    433      * @param field the field number
    434      * @param currentValue the current value of the field
    435      */
    436     void providedObjectField (PersistenceCapable pc, int field,
    437                               Object currentValue);
    438
    439     /** The replacement value of the field in the calling instance.
    440      * @param pc the calling <code>PersistenceCapable</code> instance
    441      * @param field the field number
    442      * @return the new value for the field
    443      */
    444     boolean replacingBooleanField (PersistenceCapable pc, int field);
    445
    446     /** The replacement value of the field in the calling instance.
    447      * @param pc the calling <code>PersistenceCapable</code> instance
    448      * @param field the field number
    449      * @return the new value for the field
    450      */
    451     char replacingCharField (PersistenceCapable pc, int field);
    452
    453     /** The replacement value of the field in the calling instance.
    454      * @param pc the calling <code>PersistenceCapable</code> instance
    455      * @param field the field number
    456      * @return the new value for the field
    457      */
    458     byte replacingByteField (PersistenceCapable pc, int field);
    459
    460     /** The replacement value of the field in the calling instance.
    461      * @param pc the calling <code>PersistenceCapable</code> instance
    462      * @param field the field number
    463      * @return the new value for the field
    464      */
    465     short replacingShortField (PersistenceCapable pc, int field);
    466
    467     /** The replacement value of the field in the calling instance.
    468      * @param pc the calling <code>PersistenceCapable</code> instance
    469      * @param field the field number
    470      * @return the new value for the field
    471      */
    472     int replacingIntField (PersistenceCapable pc, int field);
    473
    474     /** The replacement value of the field in the calling instance.
    475      * @param pc the calling <code>PersistenceCapable</code> instance
    476      * @param field the field number
    477      * @return the new value for the field
    478      */
    479     long replacingLongField (PersistenceCapable pc, int field);
    480
    481     /** The replacement value of the field in the calling instance.
    482      * @param pc the calling <code>PersistenceCapable</code> instance
    483      * @param field the field number
    484      * @return the new value for the field
    485      */
    486     float replacingFloatField (PersistenceCapable pc, int field);
    487
    488     /** The replacement value of the field in the calling instance.
    489      * @param pc the calling <code>PersistenceCapable</code> instance
    490      * @param field the field number
    491      * @return the new value for the field
    492      */
    493     double replacingDoubleField (PersistenceCapable pc, int field);
    494
    495     /** The replacement value of the field in the calling instance.
    496      * @param pc the calling <code>PersistenceCapable</code> instance
    497      * @param field the field number
    498      * @return the new value for the field
    499      */
    500     String replacingStringField (PersistenceCapable pc, int field);
    501
    502     /** The replacement value of the field in the calling instance.
    503      * @param pc the calling <code>PersistenceCapable</code> instance
    504      * @param field the field number
    505      * @return the new value for the field
    506      */
    507     Object replacingObjectField (PersistenceCapable pc, int field);
    508
    509     /** The replacement value of the detached state in the calling instance.
    510      * @param pc the calling <code>Detachable</code> instance
    511      * @param state the current value of the detached state
    512      * @return the replacement value for the detached state
    513      * @since 2.0
    514      */
    515     Object[] replacingDetachedState (Detachable pc, Object[] state);
    516 }