http://jta-spec.java.net: Project GlassFish Java Transaction API (GlassFish Community)
  • Stephen Felts (Oracle, Inc.) 
/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 1997-2013 Oracle and/or its affiliates. All rights reserved.
 *
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License("CDDL") (collectively, the "License").  You
 * may not use this file except in compliance with the License.  You can
 * obtain a copy of the License at
 * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
 * or packager/legal/LICENSE.txt.  See the License for the specific
 * language governing permissions and limitations under the License.
 *
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at packager/legal/LICENSE.txt.
 *
 * GPL Classpath Exception:
 * Oracle designates this particular file as subject to the "Classpath"
 * exception as provided by Oracle in the GPL Version 2 section of the License
 * file that accompanied this code.
 *
 * Modifications:
 * If applicable, add the following below the License Header, with the fields
 * enclosed by brackets [] replaced by your own identifying information:
 * "Portions Copyright [year] [name of copyright owner]"
 *
 * Contributor(s):
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright
 * holder.
 */

package javax.transaction;


This interface is intended for use by system level application server
components such as persistence managers, resource adapters, as well as
EJB and Web application components. This provides the ability to
register synchronization objects with special ordering semantics,
associate resource objects with the current transaction, get the
transaction context of the current transaction, get current transaction
status, and mark the current transaction for rollback.
This interface is implemented by the application server by a
stateless service object. The same object can be used by any number of
components with thread safety.

In standard application server environments, an instance
implementing this interface can be looked up by a standard name via JNDI.
The standard name is java:comp/TransactionSynchronizationRegistry.

Since:JTA 1.1
/**
 * This interface is intended for use by system level application server
 * components such as persistence managers, resource adapters, as well as
 * EJB and Web application components. This provides the ability to
 * register synchronization objects with special ordering semantics,
 * associate resource objects with the current transaction, get the
 * transaction context of the current transaction, get current transaction
 * status, and mark the current transaction for rollback.
 *
 * This interface is implemented by the application server by a
 * stateless service object. The same object can be used by any number of
 * components with thread safety.
 *
 * <P>In standard application server environments, an instance
 * implementing this interface can be looked up by a standard name via JNDI.
 * The standard name is java:comp/TransactionSynchronizationRegistry.
 *
 * @since JTA 1.1
 */
public interface TransactionSynchronizationRegistry {

    
Return an opaque object to represent the transaction bound to the
current thread at the time this method is called. This object
overrides hashCode and equals to allow its use as the key in a
hashMap for use by the caller. If there is no transaction currently
active, return null.

This object will return the same hashCode and compare equal to
all other objects returned by calling this method
from any component executing in the same transaction context in the
same application server.

The toString method returns a String that might be usable by a
human reader to usefully understand the transaction context. The
toString result is otherwise not defined. Specifically, there is no
forward or backward compatibility guarantee of the results of
toString.

The object is not necessarily serializable, and has no defined
behavior outside the virtual machine whence it was obtained.

Returns:an opaque object representing the transaction bound to the 
current thread at the time this method is called.
Since:JTA 1.1
/**
     * Return an opaque object to represent the transaction bound to the
     * current thread at the time this method is called. This object
     * overrides hashCode and equals to allow its use as the key in a
     * hashMap for use by the caller. If there is no transaction currently
     * active, return null.
     * 
     * <P>This object will return the same hashCode and compare equal to
     * all other objects returned by calling this method
     * from any component executing in the same transaction context in the
     * same application server.
     * 
     * <P>The toString method returns a String that might be usable by a
     * human reader to usefully understand the transaction context. The
     * toString result is otherwise not defined. Specifically, there is no
     * forward or backward compatibility guarantee of the results of
     * toString.
     * 
     * <P>The object is not necessarily serializable, and has no defined
     * behavior outside the virtual machine whence it was obtained.
     *
     * @return an opaque object representing the transaction bound to the 
     * current thread at the time this method is called.
     *
     * @since JTA 1.1
     */
    Object getTransactionKey();
    
    
Add or replace an object in the Map of resources being managed for the transaction bound to the current thread at the time this method is called. The supplied key should be of an caller- defined class so as not to conflict with other users. The class of the key must guarantee that the hashCode and equals methods are suitable for use as keys in a map. The key and value are not examined or used by the implementation. The general contract of this method is that of Map.put(Object, Object) for a Map that supports non-null keys and null values. For example, if there is already an value associated with the key, it is replaced by the value parameter. 
Params:
  • key – the key for the Map entry.
  • value – the value for the Map entry.
Throws:
Since:JTA 1.1
/**
     * Add or replace an object in the Map of resources being managed for
     * the transaction bound to the current thread at the time this 
     * method is called. The supplied key should be of an caller-
     * defined class so as not to conflict with other users. The class
     * of the key must guarantee that the hashCode and equals methods are
     * suitable for use as keys in a map. The key and value are not examined
     * or used by the implementation. The general contract of this method
     * is that of {@link java.util.Map#put(Object, Object)} for a Map that
     * supports non-null keys and null values. For example, 
     * if there is already an value associated with the key, it is replaced 
     * by the value parameter. 
     *
     * @param key the key for the Map entry.
     * @param value the value for the Map entry.
     * @exception IllegalStateException if no transaction is active.
     * @exception NullPointerException if the parameter key is null.
     *
     * @since JTA 1.1
     */
    void putResource(Object key, Object value);
    
    
Get an object from the Map of resources being managed for the transaction bound to the current thread at the time this method is called. The key should have been supplied earlier by a call to putResouce in the same transaction. If the key cannot be found in the current resource Map, null is returned. The general contract of this method is that of Map.get(Object) for a Map that supports non-null keys and null values. For example, the returned value is null if there is no entry for the parameter key or if the value associated with the key is actually null. 
Params:
  • key – the key for the Map entry.
Throws:
Returns:the value associated with the key.
Since:JTA 1.1
/**
     * Get an object from the Map of resources being managed for
     * the transaction bound to the current thread at the time this 
     * method is called. The key should have been supplied earlier
     * by a call to putResouce in the same transaction. If the key 
     * cannot be found in the current resource Map, null is returned.
     * The general contract of this method
     * is that of {@link java.util.Map#get(Object)} for a Map that
     * supports non-null keys and null values. For example, 
     * the returned value is null if there is no entry for the parameter
     * key or if the value associated with the key is actually null.
     *
     * @param key the key for the Map entry.
     * @return the value associated with the key.
     * @exception IllegalStateException if no transaction is active.
     * @exception NullPointerException if the parameter key is null.
     *
     * @since JTA 1.1
     */
    Object getResource(Object key);

    
Register a Synchronization instance with special ordering
semantics. Its beforeCompletion will be called after all 
SessionSynchronization beforeCompletion callbacks and callbacks 
registered directly with the Transaction, but before the 2-phase
commit process starts. Similarly, the afterCompletion
callback will be called after 2-phase commit completes but before
any SessionSynchronization and Transaction afterCompletion callbacks.

The beforeCompletion callback will be invoked in the transaction
context of the transaction bound to the current thread at the time 
this method is called. 
Allowable methods include access to resources,
e.g. Connectors. No access is allowed to "user components" (e.g. timer
services or bean methods), as these might change the state of data
being managed by the caller, and might change the state of data that
has already been flushed by another caller of 
registerInterposedSynchronization. 
The general context is the component
context of the caller of registerInterposedSynchronization.

The afterCompletion callback will be invoked in an undefined 
context. No access is permitted to "user components"
as defined above. Resources can be closed but no transactional
work can be performed with them.

If this method is invoked without an active transaction context, an
IllegalStateException is thrown.

If this method is invoked after the two-phase commit processing has
started, an IllegalStateException is thrown.

Params:
  • sync – the Synchronization instance.
Throws:
Since:JTA 1.1
/**
     * Register a Synchronization instance with special ordering
     * semantics. Its beforeCompletion will be called after all 
     * SessionSynchronization beforeCompletion callbacks and callbacks 
     * registered directly with the Transaction, but before the 2-phase
     * commit process starts. Similarly, the afterCompletion
     * callback will be called after 2-phase commit completes but before
     * any SessionSynchronization and Transaction afterCompletion callbacks.
     * 
     * <P>The beforeCompletion callback will be invoked in the transaction
     * context of the transaction bound to the current thread at the time 
     * this method is called. 
     * Allowable methods include access to resources,
     * e.g. Connectors. No access is allowed to "user components" (e.g. timer
     * services or bean methods), as these might change the state of data
     * being managed by the caller, and might change the state of data that
     * has already been flushed by another caller of 
     * registerInterposedSynchronization. 
     * The general context is the component
     * context of the caller of registerInterposedSynchronization.
     * 
     * <P>The afterCompletion callback will be invoked in an undefined 
     * context. No access is permitted to "user components"
     * as defined above. Resources can be closed but no transactional
     * work can be performed with them.
     * 
     * <P>If this method is invoked without an active transaction context, an
     * IllegalStateException is thrown.
     *
     * <P>If this method is invoked after the two-phase commit processing has
     * started, an IllegalStateException is thrown.
     * 
     * @param sync the Synchronization instance.
     * @exception IllegalStateException if no transaction is active.
     *
     * @since JTA 1.1
     */
    void registerInterposedSynchronization(Synchronization sync);

    
Return the status of the transaction bound to the
current thread at the time this method is called.
This is the result of executing TransactionManager.getStatus() in
the context of the transaction bound to the current thread at the time
this method is called.

Returns:the status of the transaction bound to the current thread 
at the time this method is called.
Since:JTA 1.1
/**
     * Return the status of the transaction bound to the
     * current thread at the time this method is called.
     * This is the result of executing TransactionManager.getStatus() in
     * the context of the transaction bound to the current thread at the time
     * this method is called.
     *
     * @return the status of the transaction bound to the current thread 
     * at the time this method is called.
     *
     * @since JTA 1.1
     */
    int getTransactionStatus();

    
Set the rollbackOnly status of the transaction bound to the
current thread at the time this method is called.

Throws:
  • IllegalStateException – if no transaction is active.
Since:JTA 1.1
/**
     * Set the rollbackOnly status of the transaction bound to the
     * current thread at the time this method is called.
     *
     * @exception IllegalStateException if no transaction is active.
     *
     * @since JTA 1.1
     */
    void setRollbackOnly();

    
Get the rollbackOnly status of the transaction bound to the
current thread at the time this method is called.

Throws:
Returns:the rollbackOnly status.
Since:JTA 1.1
/**
     * Get the rollbackOnly status of the transaction bound to the
     * current thread at the time this method is called.
     *
     * @return the rollbackOnly status.
     * @exception IllegalStateException if no transaction is active.
     *
     * @since JTA 1.1
     */
    boolean getRollbackOnly();
}