org.wildfly.transaction.client.spi.SubordinateTransactionControl Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of wildfly-client-all
This artifact provides a single jar that contains all classes required to use remote EJB and JMS, including all dependencies. It is intended for use by those not using maven, maven users should just import the EJB and JMS BOM's instead (shaded JAR's cause lots of problems with maven, as it is very easy to inadvertently end up with different versions on classes on the class path).
There is a newer version: 34.0.0.Final
Show newest version
/*
 * JBoss, Home of Professional Open Source.
 * Copyright 2016 Red Hat, Inc., and individual contributors
 * as indicated by the @author tags.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.wildfly.transaction.client.spi;

import javax.transaction.xa.XAException;
import javax.transaction.xa.XAResource;

/**
 * The control interface for subordinate transactions.  This interface is used in the following cases:
 * 
 *     When a subordinate transaction is locally inflowed, an instance of this interface is used to control the
 *     lifecycle of the local transaction (the transaction's lifecycle methods are blocked in this case).
 *     The local handle for a subordinate transaction implements this interface.
 * 
 * @author David M. Lloyd
 */
public interface SubordinateTransactionControl {

    /**
     * Roll back the subordinate.  In the event of error, the following error codes are possible:
     * 
     *     {@link XAException#XAER_RMERR}
     *     {@link XAException#XAER_RMFAIL}
     *     {@link XAException#XAER_NOTA}
     *     {@link XAException#XAER_INVAL}
     *     {@link XAException#XAER_PROTO}
     *     {@link XAException#XA_HEURHAZ}
     *     {@link XAException#XA_HEURCOM}
     *     {@link XAException#XA_HEURRB}
     *     {@link XAException#XA_HEURMIX}
     * 
     *
     * @throws XAException (with one of the above error codes) if an error occurs
     */
    void rollback() throws XAException;

    /**
     * End work on behalf of a transaction branch, disassociating the subordinate from the transaction branch.  The
     * {@code flags} parameter may equal one of the following:
     * 
     *     {@link XAResource#TMFAIL} indicating that the transaction work has failed, and that the subordinate may
     *     mark the transaction as rollback-only
     *     {@link XAResource#TMSUCCESS} indicating that the work has completed successfully and that a subsequent
     *     {@link #prepare()} is likely
     * 
     * In the event of error, the following error codes are possible:
     * 
     *     {@link XAException#XAER_RMERR}
     *     {@link XAException#XAER_RMFAIL}
     *     {@link XAException#XAER_INVAL}
     *     {@link XAException#XAER_PROTO}
     *     {@link XAException#XA_RBCOMMFAIL}
     *     {@link XAException#XA_RBDEADLOCK}
     *     {@link XAException#XA_RBINTEGRITY}
     *     {@link XAException#XA_RBOTHER}
     *     {@link XAException#XA_RBPROTO}
     *     {@link XAException#XA_RBROLLBACK}
     *     {@link XAException#XA_RBTIMEOUT}
     *     {@link XAException#XA_RBTRANSIENT}
     * 
     *
     * @param flags one of the valid flag values: {@code TMSUSPEND}, {@code TMFAIL}, or {@code TMSUCCESS}
     * @throws XAException (with one of the above error codes) if an error occurs
     */
    void end(int flags) throws XAException;

    /**
     * Perform before-commit operations, including running all transaction synchronizations.  In the event of an error,
     * the following error codes are possible:
     * 
     *     {@link XAException#XAER_RMERR}
     *     {@link XAException#XAER_RMFAIL}
     *     {@link XAException#XAER_INVAL}
     *     {@link XAException#XAER_PROTO}
     *     {@link XAException#XA_RBCOMMFAIL}
     *     {@link XAException#XA_RBDEADLOCK}
     *     {@link XAException#XA_RBINTEGRITY}
     *     {@link XAException#XA_RBOTHER}
     *     {@link XAException#XA_RBPROTO}
     *     {@link XAException#XA_RBROLLBACK}
     *     {@link XAException#XA_RBTIMEOUT}
     *     {@link XAException#XA_RBTRANSIENT}
     * 
     *
     * @throws XAException (with one of the above error codes) if an error occurs
     */
    void beforeCompletion() throws XAException;

    /**
     * Prepare the transaction.  If before-commit processing was not yet run, it is run.  In the event of an error,
     * the following error codes are possible:
     * 
     *     {@link XAException#XAER_RMERR}
     *     {@link XAException#XAER_RMFAIL}
     *     {@link XAException#XAER_INVAL}
     *     {@link XAException#XAER_PROTO}
     *     {@link XAException#XA_RBCOMMFAIL}
     *     {@link XAException#XA_RBDEADLOCK}
     *     {@link XAException#XA_RBINTEGRITY}
     *     {@link XAException#XA_RBOTHER}
     *     {@link XAException#XA_RBPROTO}
     *     {@link XAException#XA_RBROLLBACK}
     *     {@link XAException#XA_RBTIMEOUT}
     *     {@link XAException#XA_RBTRANSIENT}
     * 
     *
     * @return {@link XAResource#XA_OK} or {@link XAResource#XA_RDONLY}
     * @throws XAException (with one of the above error codes) if an error occurs
     */
    int prepare() throws XAException;

    /**
     * Forget the (previously prepared) transaction.  In the event of error, the following error codes are possible:
     * 
     *     {@link XAException#XAER_RMERR}
     *     {@link XAException#XAER_RMFAIL}
     *     {@link XAException#XAER_INVAL}
     *     {@link XAException#XAER_PROTO}
     * 
     * @throws XAException (with one of the above error codes) if an error occurs
     */
    void forget() throws XAException;

    /**
     * Commit a transaction, either in a single phase or after a previous prepare.  In the event of error, the following
     * error codes are possible:
     * 
     *     {@link XAException#XAER_RMERR}
     *     {@link XAException#XAER_RMFAIL}
     *     {@link XAException#XAER_INVAL}
     *     {@link XAException#XAER_PROTO}
     *     {@link XAException#XA_HEURHAZ}
     *     {@link XAException#XA_HEURCOM}
     *     {@link XAException#XA_HEURRB}
     *     {@link XAException#XA_HEURMIX}
     * 
     * If the {@code onePhase} flag is {@code true}, one of the following error codes is also possible:
     * 
     *     {@link XAException#XA_RBCOMMFAIL}
     *     {@link XAException#XA_RBDEADLOCK}
     *     {@link XAException#XA_RBINTEGRITY}
     *     {@link XAException#XA_RBOTHER}
     *     {@link XAException#XA_RBPROTO}
     *     {@link XAException#XA_RBROLLBACK}
     *     {@link XAException#XA_RBTIMEOUT}
     *     {@link XAException#XA_RBTRANSIENT}
     * 
     * @param onePhase {@code true} to commit in a single phase, {@code false} to commit after prepare
     * @throws XAException (with one of the above error codes) if an error occurs
     */
    void commit(boolean onePhase) throws XAException;

    /**
     * An empty subordinate transaction controller.
     */
    SubordinateTransactionControl EMPTY = new SubordinateTransactionControl() {
        public void rollback() throws XAException {
        }

        public void end(final int flags) throws XAException {
        }

        public void beforeCompletion() throws XAException {
        }

        public int prepare() throws XAException {
            return XAResource.XA_RDONLY;
        }

        public void forget() throws XAException {
        }

        public void commit(final boolean onePhase) throws XAException {
        }
    };
}