Glassfish example source code file (JavaEETransactionManager.java)

This example Glassfish source code file (JavaEETransactionManager.java) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - Glassfish tags/keywords

componentinvocation, componentinvocation, illegalstateexception, illegalstateexception, invocationexception, list, remoteexception, rmi, rollbackexception, string, string, systemexception, systemexception, transaction, transactionalresource, util, workexception

The Glassfish JavaEETransactionManager.java source code

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 1997-2010 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 com.sun.enterprise.transaction.api;

import java.util.List;

import javax.transaction.*;
import javax.transaction.xa.XAResource;
import javax.transaction.xa.Xid;
import java.rmi.RemoteException;
import javax.resource.spi.XATerminator;
import javax.resource.spi.work.WorkException;

import org.jvnet.hk2.annotations.Contract;

import com.sun.enterprise.transaction.spi.TransactionalResource;
import com.sun.enterprise.transaction.spi.JavaEETransactionManagerDelegate;

import org.glassfish.api.invocation.ComponentInvocation;
import org.glassfish.api.invocation.InvocationException;
import org.glassfish.api.invocation.ResourceHandler;

/**
 *
 * Manages transacations, acting as a gateway to the TM state machine.
 *
 * @author Tony Ng
 */
@Contract
public interface JavaEETransactionManager extends TransactionManager {

    /**
     * register a synchronization object with the transaction
     * associated with the current thread
     *
     * @param sync the synchronization object
     *
     * @exception IllegalStateException Thrown if the transaction in the
     *    target object is in prepared state or the transaction is inactive.
     *
     * @exception SystemException Thrown if the transaction manager
     *    encounters an unexpected error condition
     *
     */
    public void registerSynchronization(Synchronization sync)
        throws RollbackException, IllegalStateException, SystemException;


    /**
     * Enlist the resource specified with the transaction
     *
     *
     * @param tran The transaction object
     *
     * @param h The resource handle object
     *
     * @return <i>true if the resource was enlisted successfully; otherwise     *    false.
     *
     * @exception RollbackException Thrown to indicate that
     *    the transaction has been marked for rollback only.
     *
     * @exception IllegalStateException Thrown if the transaction in the
     *    target object is in prepared state or the transaction is inactive.
     *
     * @exception SystemException Thrown if the transaction manager
     *    encounters an unexpected error condition
     *
     */
    public boolean enlistResource(Transaction tran,
                                  TransactionalResource h)
        throws RollbackException,
               IllegalStateException, SystemException;

    /**
     * Delist the resource specified from the transaction
     *
     * @param tran The transaction object
     *
     * @param h The resource handle object
     *
     * @param flag One of the values of TMSUCCESS, TMSUSPEND, or TMFAIL.
     *
     * @exception IllegalStateException Thrown if the transaction in the
     *    target object is inactive.
     *
     * @exception SystemException Thrown if the transaction manager
     *    encounters an unexpected error condition
     *
     */
    public boolean delistResource(Transaction tran,
                                  TransactionalResource h,
                                  int flag)
        throws IllegalStateException, SystemException;

    /**
     * This is called by the Container to ask the Transaction
     * Manager to enlist all resources held by a component and
     * to associate the current Transaction with the current
     * Invocation
     * The TM finds the component through the InvocationManager
     */
    public void enlistComponentResources() throws RemoteException;

    /**
     * This is called by the Container to ask the Transaction
     * Manager to delist all resources held by a component
     *
     * The TM finds the component through the InvocationManager
     *
     * @param suspend true if the resources should be delisted
     * with TMSUSPEND flag; false otherwise
     *
     */
    public void delistComponentResources(boolean suspend)
        throws RemoteException;

    /**
     * This is called by Container to indicate that a component
     * is being destroyed. All resources registered in the context
     * should be released. The ComponentInvocation will be used for 
     * callback to calculate the resource table key.
     *
     * @param instance The component instance
     * @param inv The ComponentInvocation
     */
    public void componentDestroyed(Object instance, ComponentInvocation inv);

    /**
     * This is called by Container to indicate that a component
     * is being destroyed. All resources registered in the context
     * should be released
     *
     * @param instance The component instance
     */
    public void componentDestroyed(Object instance);

    /**
     * This is called by Container to indicate that a component
     * is being destroyed. All resources registered with this ResourceHandler
     * should be released. 
     *
     * @param rh The ResourceHandler
     */
    public void componentDestroyed(ResourceHandler rh);

    /**
     * Called by InvocationManager
     */

    public void preInvoke(ComponentInvocation prev)
	throws InvocationException;

    /**
     * Called by InvocationManager
     */

    public void postInvoke(ComponentInvocation curr, ComponentInvocation prev)
	throws InvocationException;

    public void setDefaultTransactionTimeout(int seconds);
    public void cleanTxnTimeout(); // clean up thread specific timeout
    /**
     * Returns a list of resource handles held by the component
     */

    public List getExistingResourceList(Object instance, ComponentInvocation inv);

    public void registerComponentResource(TransactionalResource h);

    public void unregisterComponentResource(TransactionalResource h);

    public void recover(XAResource[] resourceList);

    /**
     * Initialize recovery framework
     * @param force if true, forces initialization, otherwise relies on the TimerService 
     * configuration.
     */
    public void initRecovery(boolean force);

    public void begin(int timeout)
        throws NotSupportedException, SystemException;

    /**
     * Return true if a "null transaction context" was received
     * from the client or if the server's transaction.interoperability
     * flag is false.
     * A null tx context indicates that the client had an active
     * tx but the client container did not support tx interop.
     * See EJB2.0 spec section 18.5.2.1.
     */
    public boolean isNullTransaction();

    /**
     * Perform checks during export of a transaction on a remote call.
     */
    public void checkTransactionExport(boolean isLocal);

    /**
     * Perform checks during import of a transaction on a remote call.
     * This is called from the reply interceptors after a remote call completes.
     */
    public void checkTransactionImport();


    /**
     * Utility for the ejb container to check if the transaction is marked for
     * rollback because of timeout. This is applicable only for local transactions
     * as jts transaction will rollback instead of setting the txn for rollback
     */
    public boolean isTimedOut();

    // START IASRI 4662745

    /*
     * Returns the list of ActiveTransactions. Called by Admin framework
     *  The ArrayList contains TransactionAdminBean
     */
    public java.util.ArrayList getActiveTransactions();

    /*
     * Called by Admin Framework. Forces the given transaction to be rolled back
     */
    public void forceRollback(String txnId) throws IllegalStateException, SystemException;

    /*
     * Called by Admin Framework.
     */
    public void setMonitoringEnabled(boolean enabled);

    /*
     * Called by Admin Framework.
     */
    public void freeze();
    /*
     * Called by Admin Framework.
     */
    public void unfreeze();

    /*
     * Called by Admin Framework
     */
    public boolean isFrozen();

    // END IASRI 4662745


   /**
     * recreate a transaction based on the Xid. This call causes the calling
     * thread to be associated with the specified transaction. <p>
     * This is used by importing transactions via the Connector contract.
     *
     * @param xid the Xid object representing a transaction.
     */
    public void recreate(Xid xid, long timeout) throws WorkException ;

    /**
     * Release a transaction. This call causes the calling thread to be
     * dissociated from the specified transaction. <p>
     * This is used by importing transactions via the Connector contract.
     *
     * @param xid the Xid object representing a transaction.
     */
    public void release(Xid xid) throws WorkException ;

    /**
     * Provides a handle to a <code>XATerminator instance. The
     * <code>XATerminator instance could be used by a resource adapter
     * to flow-in transaction completion and crash recovery calls from an EIS.
     * <p>
     * This is used by importing transactions via the Connector contract.
     *
     * @return a <code>XATerminator instance.
     */
    public XATerminator getXATerminator() ;

    /**
     * Explicitly set the JavaEETransactionManagerDelegate instance
     * for implementation-specific callbacks.
     *
     * @param delegate the JavaEETransactionManagerDelegate instance.
     */
    public void setDelegate(JavaEETransactionManagerDelegate delegate);

    /**
     *
     * Return JavaEETransaction instance associated with the current thread.
     *
     * @return the JavaEETransaction associated with the current thread or null
     * if it there is none.
     */
    public JavaEETransaction getCurrentTransaction();

    /**
     *
     * Update JavaEETransaction associated with the current thread.
     *
     * @param tx the JavaEETransaction associated with the current thread or null
     * if the existing transaction had been completed.
     */
    public void setCurrentTransaction(JavaEETransaction tx);

    /**
     *
     * Return XAResourceWrapper instance specific to this datasource class name 
     * that can be used instead of the driver provided version for transaction recovery.
     *
     * @param clName the class name of a datasource.
     * @return the XAResourceWrapper instance specific to this datasource class 
     * name or null if there is no special wrapper available.
     */
    public XAResourceWrapper getXAResourceWrapper(String clName);

    /**
     * Handle configuration change. Actual change will be performed by the delegate.
     *
     * @param name the name of the configuration property.
     * @param value the ne value of the configuration.
     */
    public void handlePropertyUpdate(String name, Object value);

    /**
     * Called by the ResourceRecoveryManager to recover the populated
     * array of XAResource.
     *
     * @param delegated <code>true if the recovery process is owned by this instance.
     * @param logPath the name of the transaction logging directory
     * @param xaresArray the array of XA Resources to be recovered.
     * @return true if the recovery has been successful.
     */
    public boolean recoverIncompleteTx(boolean delegated, String logPath, 
            XAResource[] xaresArray) throws Exception;

    /**
     * get the resources being used in the calling component's invocation context
     * @param instance calling component instance
     * @param inv Calling component's invocation information
     * @return List of resources
     */
    public List getResourceList(Object instance, ComponentInvocation inv);

    /**
     * Clears the transaction associated with the caller thread
     */
    public void clearThreadTx();

    /**
     * Return location of transaction logs
     *
     * @return String location of transaction logs
     */
    public String getTxLogLocation();

    /**
     * Allows an arbitrary XAResource to register for recovery
     *
     * @param xaResource XAResource to register for recovery
     */
    public void registerRecoveryResourceHandler(XAResource xaResource);

    /**
     * Returns the value to be used to purge transaction tasks after the specified number of cancelled tasks
     */
    public int getPurgeCancelledTtransactionsAfter();

    /**
     * Allows to purge transaction tasks after the specified value of cancelled tasks
     */
    public void setPurgeCancelledTtransactionsAfter(int value);
}