001: /**********************************************************************
002: Copyright (c) 2002 Kelly Grizzle and others. All rights reserved.
003: Licensed under the Apache License, Version 2.0 (the "License");
004: you may not use this file except in compliance with the License.
005: You may obtain a copy of the License at
006:
007: http://www.apache.org/licenses/LICENSE-2.0
008:
009: Unless required by applicable law or agreed to in writing, software
010: distributed under the License is distributed on an "AS IS" BASIS,
011: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012: See the License for the specific language governing permissions and
013: limitations under the License.
014:
015: Contributors:
016: 2003 Andy Jefferson - commented
017: 2006 Andy Jefferson - rewritten to be independent of JDO
018: ...
019: **********************************************************************/package org.jpox;
020:
021: import java.util.Map;
022:
023: import javax.transaction.Synchronization;
024:
025: import org.jpox.exceptions.JPOXUserException;
026:
027: /**
028: * Representation of a transaction within JPOX. This interface is not
029: * user application visible.
030: *
031: * Handling of transactions in JPOX is split in 4 layers:
032: * <li>
033: * <ul>API - The User Visible Transaction API</ul>
034: * <ul>ObjectManager Transaction - The Transaction assigned to a ObjectManager</ul>
035: * <ul>X/Open/JTA - The Transaction Manager associated to the underlying datastore transaction</ul>
036: * <ul>Resource - The Transaction handled by the datastore</ul>
037: * </li>
038: *
039: * In the the API layer, there are interfaces provided to the user application, as such:
040: * <li>
041: * <ul>{@link javax.jdo.Transaction} - the JDO API interface</ul>
042: * <ul>javax.persistence.EntityTransaction - the JPA API interface</ul>
043: * <ul>{@link javax.transaction.UserTransaction} - the JTA API interface</ul>
044: * <ul>{@link org.jpox.UserTransaction} - JPOX API proprietary API</ul>
045: * </li>
046: *
047: * In the ObjectManager layer, the {@link org.jpox.Transaction} interface defines the contract
048: * for handling transactions for the ObjectManager.
049: *
050: * In the X/Open/JTA layer the handling of XA resources is done. It means, XAResources are
051: * obtained and enlisted to a TransactionManager. The TransactionManager will commit or rollback the resources
052: * at the end of the transactions. There are two kinds of TransactionManager: JPOX and JTA. A
053: * JTA TransactionManager is external to JPOX, while the JPOX TransactionManager is implemented
054: * by JPOX as {@link org.jpox.transaction}. The JPOX TransactionManager is used when the DataSource used
055: * to obtain connections to the underlying database is not enlisted in an external JTA TransactionManager.
056: * The JTA TransactionManager is usually found when running in J2EE application servers, however
057: * nowadays there are many JTA containers that can be used in J2SE.
058: *
059: * The scenarios where a JTA TransactionManager is used is:
060: * When an JTA TransactionManager exists, and the connections to the underlying databases
061: * are acquired via transactional DataSources. That means, when you ask a connection to the DataSource,
062: * it will automatically enlist it in a JTA TransactionManager.
063: *
064: * The Resource layer is handled by the datastore. For example, with RDBMS databases,
065: * the javax.sql.Connection is the API used to demarcate the database transactions. In The RBDMS database,
066: * the resource layer, it is handling the database transaction.
067: *
068: * @version $Revision: 1.27 $
069: **/
070: public interface Transaction {
071: /**
072: * Begin a transaction.
073: * The type of transaction (datastore/optimistic) is determined by the setting of the Optimistic flag.
074: * @throws JPOXUserException if transactions are managed by a container
075: * in the managed environment, or if the transaction is already active.
076: */
077: void begin();
078:
079: /**
080: * Commit the current transaction. The commit will trigger flushing the transaction, will
081: * invoke the preCommit, commit the resources and invoke postCommit listeners.
082: *
083: * If during flush or preCommit phases a JPOXUserException is raised, then the transaction will not
084: * complete and the transaction remains active. The JPOXUserException is cascaded to the caller.
085: *
086: * @throws JPOXUserException if transactions are managed by a container
087: * in the managed environment, or if the transaction is not active.
088: */
089: void commit();
090:
091: /**
092: * Rollback the current transaction. The commit will trigger flushing the transaction, will
093: * invoke the preRollback, rollback the resources and invoke postRollback listeners.
094: *
095: * If during flush or preRollback phases a JPOXUserException is raised, then the transaction will not
096: * complete and the transaction remains active. The JPOXUserException is cascaded to the caller.
097: *
098: * @throws JPOXUserException if transactions are managed by a container
099: * in the managed environment, or if the transaction is not active.
100: */
101: void rollback();
102:
103: /**
104: * Returns whether there is a transaction currently active.
105: * @return Whether the transaction is active.
106: */
107: boolean isActive();
108:
109: /**
110: * Method to allow the transaction to flush any resources.
111: */
112: void flush();
113:
114: /**
115: * Method to allow the transaction to flush any resources.
116: */
117: void end();
118:
119: /**
120: * Returns the rollback-only status of the transaction.
121: * When begun, the rollback-only status is false. Either the
122: * application or the JDO implementation may set this flag
123: * using setRollbackOnly.
124: * @return Whether the transaction has been marked for rollback.
125: */
126: boolean getRollbackOnly();
127:
128: /**
129: * Sets the rollback-only status of the transaction to <code>true</code>.
130: * After this flag is set to <code>true</code>, the transaction
131: * can no longer be committed.
132: * @throws JPOXUserException if the flag is true and an attempt is made
133: * to commit the txn
134: */
135: void setRollbackOnly();
136:
137: /**
138: * If <code>true</code>, allow persistent instances to be read without
139: * a transaction active.
140: * If an implementation does not support this option, a
141: * @param nontransactionalRead Whether to have non-tx reads
142: * @throws JPOXUserException if not supported (supported by JPOX)
143: */
144: void setNontransactionalRead(boolean nontransactionalRead);
145:
146: /**
147: * If <code>true</code>, allows persistent instances to be read without
148: * a transaction active.
149: * @return Whether we are allowing non-tx reads
150: */
151: boolean getNontransactionalRead();
152:
153: /**
154: * If <code>true</code>, allow persistent instances to be written without
155: * a transaction active.
156: * @param nontransactionalWrite Whether requiring non-tx writes
157: * @throws JPOXUserException if not supported (JPOX doesnt support it!)
158: */
159: void setNontransactionalWrite(boolean nontransactionalWrite);
160:
161: /**
162: * If <code>true</code>, allows persistent instances to be written without
163: * a transaction active.
164: * @return Whether we are allowing non-tx writes
165: */
166: boolean getNontransactionalWrite();
167:
168: /**
169: * If <code>true</code>, at commit instances retain their values and the
170: * instances transition to persistent-nontransactional.
171: * @param retainValues the value of the retainValues property
172: * @throws JPOXUserException if not supported (JPOX supports it)
173: */
174: void setRetainValues(boolean retainValues);
175:
176: /**
177: * If <code>true</code>, at commit time instances retain their field values.
178: * @return the value of the retainValues property
179: */
180: boolean getRetainValues();
181:
182: /**
183: * If <code>true</code>, at rollback, fields of newly persistent instances
184: * are restored to their values as of the beginning of the transaction, and
185: * the instances revert to transient. Additionally, fields of modified
186: * instances of primitive types and immutable reference types
187: * are restored to their values as of the beginning of the
188: * transaction.
189: * <P>If <code>false</code>, at rollback, the values of fields of
190: * newly persistent instances are unchanged and the instances revert to
191: * transient. Additionally, dirty instances transition to hollow.
192: * @param restoreValues the value of the restoreValues property
193: * @throws JPOXUserException if not supported (JPOX supports it)
194: */
195: void setRestoreValues(boolean restoreValues);
196:
197: /**
198: * Return the current value of the restoreValues property.
199: * @return the value of the restoreValues property
200: */
201: boolean getRestoreValues();
202:
203: /**
204: * Optimistic transactions do not hold data store locks until commit time.
205: * @param optimistic the value of the Optimistic flag.
206: * @throws JPOXUserException if not supported (JPOX supports it)
207: */
208: void setOptimistic(boolean optimistic);
209:
210: /**
211: * Optimistic transactions do not hold data store locks until commit time.
212: * @return the value of the Optimistic property.
213: */
214: boolean getOptimistic();
215:
216: /**
217: * The user can specify a <code>Synchronization</code> instance to be
218: * notified on transaction completions. The <code>beforeCompletion</code>
219: * method is called prior to flushing instances to the data store.
220: *
221: * <P>The <code>afterCompletion</code> method is called after performing
222: * state transitions of persistent and transactional instances, following
223: * the data store commit or rollback operation.
224: * <P>Only one <code>Synchronization</code> instance can be registered with
225: * the <code>Transaction</code>. If the application requires more than one
226: * instance to receive synchronization callbacks, then the single
227: * application instance is responsible for managing them, and forwarding
228: * callbacks to them.
229: * @param sync the <code>Synchronization</code> instance to be notified;
230: * <code>null</code> for none
231: */
232: void setSynchronization(Synchronization sync);
233:
234: /** The user-specified <code>Synchronization</code> instance for this
235: * <code>Transaction</code> instance.
236: * @return the user-specified <code>Synchronization</code> instance.
237: */
238: Synchronization getSynchronization();
239:
240: /**
241: * Checks whether a transaction is committing.
242: * @return Whether the transaction is committing
243: */
244: boolean isCommitting();
245:
246: void addTransactionEventListener(TransactionEventListener listener);
247:
248: void removeTransactionEventListener(
249: TransactionEventListener listener);
250:
251: /**
252: * Obtain all settings for this Transaction
253: * @return a map with settings
254: */
255: Map getOptions();
256:
257: void setOption(String option, int value);
258:
259: void setOption(String option, boolean value);
260:
261: void setOption(String option, String value);
262: }
|