fine-third/fine-third-default/fine-javax-transaction/src/main/java/javax/transaction/TransactionSynchronizationRegistry.java

/*
 * 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.
 *
 * <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.
     * 
     * <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 {@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 {@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.
     * 
     * <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.
     *
     * @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.
     *
     * @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.
     *
     * @return the rollbackOnly status.
     * @exception IllegalStateException if no transaction is active.
     *
     * @since JTA 1.1
     */
    boolean getRollbackOnly();
}