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   * Transaction.java
    20   *
    21   */
    22
    23  package javax.jdo;
    24  import javax.transaction.Synchronization;
    25
    26  /** The JDO <code>Transaction</code> interface provides for initiation and
    27   * completion of transactions under user control.
    28   * It is a sub-interface of the {@link PersistenceManager}
    29   * that deals with options and transaction demarcation.
    30   * <P>Transaction options include whether optimistic concurrency
    31   * control should be used for the current transaction, whether instances
    32   * may hold values in the cache outside transactions, and whether
    33   * values should be retained in the cache after transaction completion.  These
    34   * options are valid for both managed and non-managed transactions.
    35   *
    36   * <P>Transaction initiation and completion methods have similar semantics to
    37   * <code>javax.transaction.UserTransaction</code> when used outside a managed
    38   * environment. When used in a managed environment, transaction initiation
    39   * and completion methods may only be used with bean-managed transaction
    40   * semantics.
    41   * @version 3.0
    42   */
    43  public interface Transaction
    44  {
    45      /** Begin a transaction.  The type of transaction is determined by the
    46       * setting of the Optimistic flag.
    47       * @see #setOptimistic
    48       * @see #getOptimistic
    49       * @throws JDOUserException if transactions are managed by a container
    50       * in the managed environment, or if the transaction is already active.
    51       */
    52      void begin();
    53
    54      /** Commit the current transaction.
    55       * @throws JDOUserException if transactions are managed by a container
    56       * in the managed environment, or if the transaction is not active.
    57       */
    58      void commit();
    59
    60      /** Roll back the current transaction.
    61       * @throws JDOUserException if transactions are managed by a container
    62       * in the managed environment, or if the transaction is not active.
    63       */
    64      void rollback();
    65
    66      /** Returns whether there is a transaction currently active.
    67       * @return <code>true</code> if the transaction is active.
    68       */
    69      boolean isActive();
    70
    71      /**
    72       * Returns the rollback-only status of the transaction. When
    73       * begun, the rollback-only status is false. Either the
    74       * application or the JDO implementation may set this flag
    75       * using setRollbackOnly.
    76       * @return <code>true</code> if the transaction has been
    77       * marked for rollback.
    78       * @since 2.0
    79       */
    80      boolean getRollbackOnly();
    81
    82      /**
    83       * Sets the rollback-only status of the transaction to <code>true</code>.
    84       * After this flag is set to <code>true</code>, the transaction
    85       * can no longer be committed, and any attempt to commit the
    86       * transaction will throw <code>JDOFatalDataStoreException<code>.
    87       * @since 2.0
    88       */
    89      void setRollbackOnly();
    90
    91      /** If <code>true</code>, allow persistent instances to be read without
    92       * a transaction active.
    93       * If an implementation does not support this option, a
    94       * <code>JDOUnsupportedOptionException</code> is thrown.
    95       * @param nontransactionalRead the value of the nontransactionalRead
    96       * property
    97       */
    98      void setNontransactionalRead (boolean nontransactionalRead);
    99
    100     /** If <code>true</code>, allows persistent instances to be read without
    101      * a transaction active.
    102      * @return the value of the nontransactionalRead property
    103      */
    104     boolean getNontransactionalRead ();
    105
    106     /** If <code>true</code>, allow persistent instances to be written without
    107      * a transaction active.
    108      * If an implementation does not support this option, a
    109      * <code>JDOUnsupportedOptionException</code> is thrown.
    110      * @param nontransactionalWrite the value of the nontransactionalRead
    111      * property
    112      */
    113     void setNontransactionalWrite (boolean nontransactionalWrite);
    114
    115     /** If <code>true</code>, allows persistent instances to be written without
    116      * a transaction active.
    117      * @return the value of the nontransactionalWrite property
    118      */
    119     boolean getNontransactionalWrite ();
    120
    121     /** If <code>true</code>, at commit instances retain their values and the
    122      * instances transition to persistent-nontransactional.
    123      * If an implementation does not support this option, a
    124      * <code>JDOUnsupportedOptionException</code> is thrown.
    125      * @param retainValues the value of the retainValues property
    126      */
    127     void setRetainValues(boolean retainValues);
    128
    129     /** If <code>true</code>, at commit time instances retain their field
    130      * values.
    131      * @return the value of the retainValues property
    132      */
    133     boolean getRetainValues();
    134
    135     /** If <code>true</code>, at rollback, fields of newly persistent instances
    136      * are restored to
    137      * their values as of the beginning of the transaction, and the instances
    138      * revert to transient.  Additionally, fields of modified
    139      * instances of primitive types and immutable reference types
    140      * are restored to their values as of the beginning of the
    141      * transaction.
    142      * <P>If <code>false</code>, at rollback, the values of fields of
    143      * newly persistent instances are unchanged and the instances revert to
    144      * transient.  Additionally, dirty instances transition to hollow.
    145      * If an implementation does not support this option, a
    146      * <code>JDOUnsupportedOptionException</code> is thrown.
    147      * @param restoreValues the value of the restoreValues property
    148      */
    149     void setRestoreValues(boolean restoreValues);
    150
    151     /** Return the current value of the restoreValues property.
    152      * @return the value of the restoreValues property
    153      */
    154     boolean getRestoreValues();
    155
    156     /** Optimistic transactions do not hold data store locks until commit time.
    157      * If an implementation does not support this option, a
    158      * <code>JDOUnsupportedOptionException</code> is thrown.
    159      * @param optimistic the value of the Optimistic flag.
    160      */
    161     void setOptimistic(boolean optimistic);
    162
    163     /** Optimistic transactions do not hold data store locks until commit time.
    164      * @return the value of the Optimistic property.
    165      */
    166     boolean getOptimistic();
    167
    168     /** Get the value for transaction isolation level for this transaction.
    169      * @return the transaction isolation level
    170      * @see #setIsolationLevel(String)
    171      * @since 2.2
    172      */
    173     String getIsolationLevel();
    174
    175     /** Set the value for transaction isolation level for this transaction.
    176      * Transaction isolation levels are defined in javax.jdo.Constants.
    177      * If the requested level is not available, but a higher level is
    178      * available, the higher level is silently used.
    179      * If the requested level is not available, and no higher level is
    180      * available, then JDOUnsupportedOptionException is thrown.
    181      * Five standard isolation levels are defined. Other isolation levels
    182      * might be supported by an implementation but are not standard.
    183      * <p>Standard values in order of low to high are:
    184      * <ul><li>read-uncommitted
    185      * </li><li>read-committed
    186      * </li><li>repeatable-read
    187      * </li><li>snapshot
    188      * </li><li>serializable
    189      * </li></ul>
    190      * @param level the transaction isolation level
    191      * @see #getIsolationLevel()
    192      * @see Constants#TX_READ_UNCOMMITTED
    193      * @see Constants#TX_READ_COMMITTED
    194      * @see Constants#TX_REPEATABLE_READ
    195      * @see Constants#TX_SNAPSHOT
    196      * @see Constants#TX_SERIALIZABLE
    197      * @since 2.2
    198      */
    199     void setIsolationLevel(String level);
    200
    201     /** The user can specify a <code>Synchronization</code> instance to be
    202      * notified on transaction completions.  The <code>beforeCompletion</code>
    203      * method is called prior to flushing instances to the data store.
    204      *
    205      * <P>The <code>afterCompletion</code> method is called after performing
    206      * state transitions of persistent and transactional instances, following
    207      * the data store commit or rollback operation.
    208      * <P>Only one <code>Synchronization</code> instance can be registered with
    209      * the  <code>Transaction</code>. If the application requires more than one
    210      * instance to receive synchronization callbacks, then the single
    211      * application instance is responsible for managing them, and forwarding
    212      * callbacks to them.
    213      * @param sync the <code>Synchronization</code> instance to be notified;
    214      * <code>null</code> for none
    215      */
    216     void setSynchronization(Synchronization sync);
    217
    218     /** The user-specified <code>Synchronization</code> instance for this
    219      * <code>Transaction</code> instance.
    220      * @return the user-specified <code>Synchronization</code> instance.
    221      */
    222     Synchronization getSynchronization();
    223
    224     /** The <code>Transaction</code> instance is always associated with exactly
    225      * one <code>PersistenceManager</code>.
    226      *
    227      * @return the <code>PersistenceManager</code> for this
    228      * <code>Transaction</code> instance
    229      */
    230     PersistenceManager getPersistenceManager();
    231
    232     /**
    233      * If <code>true</code>, a lock will be applied to all objects read in this
    234      * transaction.
    235      * <P>If <code>false</code> then retrieved objects will not be locked.
    236      * If null will fallback to the value for metadata for the class in question.
    237      * @param serialize the value of the serializeRead property
    238      * @since 3.0
    239      */
    240     void setSerializeRead(Boolean serialize);
    241
    242     /**
    243      * Return the current value of the serializeRead property.
    244      * @return the value of the serializeRead property
    245      * @since 3.0
    246      */
    247     Boolean getSerializeRead();
    248 }