org.multiverse.stms.alpha.transactions.AlphaTransaction Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of multiverse-alpha-unborn

Contains the main Multiverse STM Implementation: the Alpha Engine. The Alpha engine supports readonly and update transactions. It also supports the retry/or else mechanism. This not the jar you want to have in your final distribution because it isn't instrumented (hence the name unborn). The jar you eventually want to have in your distribution is the multiverse-alpha jar. What this package does, is test the instrumentation for the Javaagent. The compiletime instrumentation is tested in the multiverse-alpha package (where all tests are copied and reexecuted but now with compiletime instrumentation).

The newest version!

package org.multiverse.stms.alpha.transactions;

import org.multiverse.api.Transaction;
import org.multiverse.stms.alpha.AlphaTranlocal;
import org.multiverse.stms.alpha.AlphaTransactionalObject;

/**
 * A {@link org.multiverse.api.Transaction} interface tailored for the Alpha STM.
 * 
 * Since a AlphaTransaction is a {@link org.multiverse.api.Transaction}, it isn't thread-safe.
 *
 * @author Peter Veentjer.
 */
public interface AlphaTransaction extends Transaction {

    /**
     * Opens the transactional object for reading purposes. It is not allowed to be used for writing purposes, because
     * it could be used by other transactions. If the transactional object already is opened for writing, that
     * tranlocal is returned.
     * 

     * If transactional object is null, the return value is null.
     * 

     * If a openForRead is done on a transactional object that never has been committed
     * before, a UncommittedReadConflict is thrown.
     * 

     * If the transactional object already is opened for write, that version is returned.
     * 

     * If the transactional object already was opened for a commuting operation, it is fixated
     * and returned and now can be used for direct writing purposes.
     * 

     * If the transactional object already was opened for construction, that tranlocal is returned.
     *
     * @param transactionalObject the transactional object to getClassMetadata the tranlocal for.
     * @return the opened tranlocal.
     * @throws org.multiverse.api.exceptions.ControlFlowError
     *
     * @throws IllegalThreadStateException if the transaction isn't active.
     */
    AlphaTranlocal openForRead(AlphaTransactionalObject transactionalObject);

    /**
     * Opens the transactional object for writing purposes.
     * 

     * It depends on the transaction if this operations is supported.
     * 

     * If a openForWrite is done on a transactional object that never has been committed
     * before, a UncommittedReadConflict is thrown.
     * 

     * If the transactional object already was opened for read, it is now upgraded to an
     * open for write (if it was tracked).
     * 

     * If the transactional object was opened for write, it will be fixated that tranlocal
     * can now be used for writing purposes.
     * 

     * If the transactional object already was opened for construction, that tranlocal
     * is returned.
     *
     * @param transactionalObject the transactional object to getClassMetadata the tranlocal for.
     * @return the opened tranlocal.
     * @throws NullPointerException        if transactional object is null.
     * @throws org.multiverse.api.exceptions.ControlFlowError
     *
     * @throws IllegalThreadStateException if the transaction isn't active.
     */
    AlphaTranlocal openForWrite(AlphaTransactionalObject transactionalObject);

    /**
     * Opens the transactional object for a commuting operation.
     * 

     * It depends on the transaction if this operations is supported.
     * 

     * If the transactional object has never been committed before, a UncommittedReadConflict
     * is thrown.
     * If the transactional object has been opened for read and is tracked, it will
     * be upgraded to an opened for write.
     * 

     * If the transactional object already was opened for write, that tranlocal
     * is returned and no commuting operations are possible for that tranlocal.
     * 

     * If the transactional object already was opened for construction, that tranlocal
     * is returned.
     *
     * @param transactionalObject the transactional object to open
     * @return the opened tranlocal.
     * @throws NullPointerException        if transactional object is null.
     * @throws org.multiverse.api.exceptions.ControlFlowError
     *
     * @throws IllegalThreadStateException if the transaction isn't active.
     */
    AlphaTranlocal openForCommutingWrite(AlphaTransactionalObject transactionalObject);

    /**
     * Opens the transactional object for construction (and writing) purposes.
     * 

     * It depends on the transaction if this operation is supported.
     * 

     * It is extremely important that this call is done only once for a
     * transactional objects (when it is constructed). There is no protection against
     * doing this multiple times, and when this happens it could overwrite already
     * committed changes when the transaction commits.
     * 
     * Normally this call only is made by instrumented code or by Multiverse provided
     * transactional structure.
     *
     * @param transactionalObject the transactional object to open for construction
     * @return the opened tranlocal.
     * @throws NullPointerException        if transactional object is null.
     * @throws org.multiverse.api.exceptions.ControlFlowError
     *
     * @throws IllegalThreadStateException if the transaction isn't active.
     */
    AlphaTranlocal openForConstruction(AlphaTransactionalObject transactionalObject);
}