001: /**********************************************************************
002: Copyright (c) 2007 Erik Bengtson 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: ...
017: **********************************************************************/package org.jpox;
018:
019: /**
020: * UserTransaction is the interface exposed by JPOX to User Applications.
021: * It allows proprietary JPOX extensions to be used by user applications.
022: * To exemplify the usage of this interface, the below is a JDO snippet:
023: * <code>
024: * Transaction tx = pm.currentTransaction();
025: * ((UserTransaction)tx).setUseUpdateLock(true);
026: * </code>
027: *
028: * This interface does not make any distinction between user APIs, such as
029: * JDO or JPA, neither the datastores, such as RDBMS or DB4O. Unsupported
030: * operations will throw {@link UnsupportedOperationException}.
031: *
032: * User applications must be aware that the behaviour of this interface and
033: * effects caused by invoking these operations may not be portable between
034: * different datastores kinds (RBDMS, DB4O, LDAP, etc )or datastores of same
035: * kind (RDBMS Oracle, RDBMS DB2, RDBMS MySQL, RDBMS Derby, etc).
036: */
037: public interface UserTransaction {
038: /**
039: * Turn on serialized access to data fetch from datastore.
040: * Calling this in the middle of a transaction will only affect data read after it.
041: * Some datastores do not support Update Lock feature, and for such datastores
042: * this setting is silently ignored.
043: */
044: void useUpdateLockOnFetch();
045:
046: /**
047: * Turn on/off serialized access to data fetch from datastore.
048: * Calling this in the middle of a transaction will only affect data read after it.
049: * Some datastores do not support Update Lock feature, and for such datastores
050: * this setting is silently ignored.
051: * @param lock whether to lock data or not
052: */
053: void setUseUpdateLock(boolean lock);
054:
055: /**
056: * Configure isolation level for the transaction
057: * Some datastores do not support Isolation Level feature, and for such datastores
058: * this setting is silently ignored.
059: * Calling this in the middle of a transaction has behaviour undetermined
060: * @param isolation level
061: */
062: void setTransactionIsolation(int isolation);
063:
064: /**
065: * A constant indicating that transactions are not supported.
066: */
067: int TRANSACTION_NONE = 0;
068:
069: /**
070: * A constant indicating that
071: * dirty reads, non-repeatable reads and phantom reads can occur.
072: * This level allows a row changed by one transaction to be read
073: * by another transaction before any changes in that row have been
074: * committed (a "dirty read"). If any of the changes are rolled back,
075: * the second transaction will have retrieved an invalid row.
076: */
077: int TRANSACTION_READ_UNCOMMITTED = 1;
078:
079: /**
080: * A constant indicating that
081: * dirty reads are prevented; non-repeatable reads and phantom
082: * reads can occur. This level only prohibits a transaction
083: * from reading a row with uncommitted changes in it.
084: */
085: int TRANSACTION_READ_COMMITTED = 2;
086:
087: /**
088: * A constant indicating that
089: * dirty reads and non-repeatable reads are prevented; phantom
090: * reads can occur. This level prohibits a transaction from
091: * reading a row with uncommitted changes in it, and it also
092: * prohibits the situation where one transaction reads a row,
093: * a second transaction alters the row, and the first transaction
094: * rereads the row, getting different values the second time
095: * (a "non-repeatable read").
096: */
097: int TRANSACTION_REPEATABLE_READ = 4;
098:
099: /**
100: * A constant indicating that
101: * dirty reads, non-repeatable reads and phantom reads are prevented.
102: * This level includes the prohibitions in
103: * <code>TRANSACTION_REPEATABLE_READ</code> and further prohibits the
104: * situation where one transaction reads all rows that satisfy
105: * a <code>WHERE</code> condition, a second transaction inserts a row that
106: * satisfies that <code>WHERE</code> condition, and the first transaction
107: * rereads for the same condition, retrieving the additional
108: * "phantom" row in the second read.
109: */
110: int TRANSACTION_SERIALIZABLE = 8;
111:
112: }
|