| /* |
| * Copyright 2005 The Apache Software Foundation. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| /* |
| * Transaction.java |
| * |
| */ |
| |
| package javax.jdo; |
| import javax.transaction.Synchronization; |
| |
| /** The JDO <code>Transaction</code> interface provides for initiation and completion |
| * of transactions under user control. |
| * It is a sub-interface of the {@link PersistenceManager} |
| * that deals with options and transaction demarcation. |
| * <P>Transaction options include whether optimistic concurrency |
| * control should be used for the current transaction, whether instances |
| * may hold values in the cache outside transactions, and whether |
| * values should be retained in the cache after transaction completion. These |
| * options are valid for both managed and non-managed transactions. |
| * |
| * <P>Transaction initiation and completion methods have similar semantics to |
| * <code>javax.transaction.UserTransaction</code> when used outside a managed |
| * environment. When used in a managed environment, transaction initiation |
| * and completion methods may only be used with bean-managed transaction semantics. |
| * @version 2.0 |
| */ |
| |
| public interface Transaction |
| { |
| /** Begin a transaction. The type of transaction is determined by the |
| * setting of the Optimistic flag. |
| * @see #setOptimistic |
| * @see #getOptimistic |
| * @throws JDOUserException if transactions are managed by a container |
| * in the managed environment, or if the transaction is already active. |
| */ |
| void begin(); |
| |
| /** Commit the current transaction. |
| * @throws JDOUserException if transactions are managed by a container |
| * in the managed environment, or if the transaction is not active. |
| */ |
| void commit(); |
| |
| /** Roll back the current transaction. |
| * @throws JDOUserException if transactions are managed by a container |
| * in the managed environment, or if the transaction is not active. |
| */ |
| void rollback(); |
| |
| /** Returns whether there is a transaction currently active. |
| * @return <code>true</code> if the transaction is active. |
| */ |
| boolean isActive(); |
| |
| /** |
| * Returns the rollback-only status of the transaction. When |
| * begun, the rollback-only status is false. Either the |
| * application or the JDO implementation may set this flag |
| * using setRollbackOnly. |
| * @return <code>true</code> if the transaction has been |
| * marked for rollback. |
| * @since 2.0 |
| */ |
| boolean getRollbackOnly(); |
| |
| /** |
| * Sets the rollback-only status of the transaction to <code>true</code>. |
| * After this flag is set to <code>true</code>, the transaction |
| * can no longer be committed, and any attempt to commit the |
| * transaction will throw <code>JDOUserException<code>. |
| * @since 2.0 |
| */ |
| void setRollbackOnly(); |
| |
| /** If <code>true</code>, allow persistent instances to be read without |
| * a transaction active. |
| * If an implementation does not support this option, a |
| * <code>JDOUnsupportedOptionException</code> is thrown. |
| * @param nontransactionalRead the value of the nontransactionalRead property |
| */ |
| void setNontransactionalRead (boolean nontransactionalRead); |
| |
| /** If <code>true</code>, allows persistent instances to be read without |
| * a transaction active. |
| * @return the value of the nontransactionalRead property |
| */ |
| boolean getNontransactionalRead (); |
| |
| /** If <code>true</code>, allow persistent instances to be written without |
| * a transaction active. |
| * If an implementation does not support this option, a |
| * <code>JDOUnsupportedOptionException</code> is thrown. |
| * @param nontransactionalWrite the value of the nontransactionalRead property |
| */ |
| void setNontransactionalWrite (boolean nontransactionalWrite); |
| |
| /** If <code>true</code>, allows persistent instances to be written without |
| * a transaction active. |
| * @return the value of the nontransactionalWrite property |
| */ |
| boolean getNontransactionalWrite (); |
| |
| /** If <code>true</code>, at commit instances retain their values and the instances |
| * transition to persistent-nontransactional. |
| * If an implementation does not support this option, a |
| * <code>JDOUnsupportedOptionException</code> is thrown. |
| * @param retainValues the value of the retainValues property |
| */ |
| void setRetainValues(boolean retainValues); |
| |
| /** If <code>true</code>, at commit time instances retain their field values. |
| * @return the value of the retainValues property |
| */ |
| boolean getRetainValues(); |
| |
| /** If <code>true</code>, at rollback, fields of newly persistent instances |
| * are restored to |
| * their values as of the beginning of the transaction, and the instances |
| * revert to transient. Additionally, fields of modified |
| * instances of primitive types and immutable reference types |
| * are restored to their values as of the beginning of the |
| * transaction. |
| * <P>If <code>false</code>, at rollback, the values of fields of |
| * newly persistent instances are unchanged and the instances revert to |
| * transient. Additionally, dirty instances transition to hollow. |
| * If an implementation does not support this option, a |
| * <code>JDOUnsupportedOptionException</code> is thrown. |
| * @param restoreValues the value of the restoreValues property |
| */ |
| void setRestoreValues(boolean restoreValues); |
| |
| /** Return the current value of the restoreValues property. |
| * @return the value of the restoreValues property |
| */ |
| boolean getRestoreValues(); |
| |
| /** Optimistic transactions do not hold data store locks until commit time. |
| * If an implementation does not support this option, a |
| * <code>JDOUnsupportedOptionException</code> is thrown. |
| * @param optimistic the value of the Optimistic flag. |
| */ |
| void setOptimistic(boolean optimistic); |
| |
| /** Optimistic transactions do not hold data store locks until commit time. |
| * @return the value of the Optimistic property. |
| */ |
| boolean getOptimistic(); |
| |
| /** The user can specify a <code>Synchronization</code> instance to be notified on |
| * transaction completions. The <code>beforeCompletion</code> method is called prior |
| * to flushing instances to the data store. |
| * |
| * <P>The <code>afterCompletion</code> method is called after performing state |
| * transitions of persistent and transactional instances, following |
| * the data store commit or rollback operation. |
| * <P>Only one <code>Synchronization</code> instance can be registered with the |
| * <code>Transaction</code>. If the application requires more than one instance to |
| * receive synchronization callbacks, then the single application instance |
| * is responsible for managing them, and forwarding callbacks to them. |
| * @param sync the <code>Synchronization</code> instance to be notified; <code>null</code> for none |
| */ |
| void setSynchronization(Synchronization sync); |
| |
| /** The user-specified <code>Synchronization</code> instance for this <code>Transaction</code> instance. |
| * @return the user-specified <code>Synchronization</code> instance. |
| */ |
| Synchronization getSynchronization(); |
| |
| /** The <code>Transaction</code> instance is always associated with exactly one |
| * <code>PersistenceManager</code>. |
| * |
| * @return the <code>PersistenceManager</code> for this <code>Transaction</code> instance |
| */ |
| PersistenceManager getPersistenceManager(); |
| } |