// This Source Code is in the Public Domain per: http://litesoft.org/License.txt
package org.litesoft.orsup.transact;

import java.io.*;

import org.litesoft.db.*;
import org.litesoft.logger.*;
import org.litesoft.orsup.base.*;

public interface Transaction extends Finder
{
    public static final Logger LOGGER = LoggerFactory.getLogger( Transaction.class );

    /**
     * Add a Transaction property, pValue, (for pKey) to the Transaction properties.  The pKey can NOT be
     * null, and should be something (like your class) that would NOT collide with other users of the
     * Transaction properties
     *
     * @param pKey   !null
     * @param pValue nullable
     */
    public void addProperty( Object pKey, Object pValue );

    /**
     * Get a previously 'added' Transaction property.  The pKey can NOT be null, and should be something
     * (like your class) that would NOT collide with other users of the Transaction properties
     *
     * @param pKey !null
     */
    public Object getProperty( Object pKey );

    public String getTransactionSourceClassname();

    public Transaction setTransactionSource( Class pSourceClass );

    public Serializable getXtraData( Class pForKey );

    public Transaction setXtraData( Class pForKey, Serializable pData );

    /**
     * @throws IllegalStateException if the TransactionAugmentor created by the Factory is a DeleteAugmentor and there are already participants in the Transaction
     */
    public Transaction addTransactionAugmentor( TransactionAugmentorFactory pTransactionAugmentorFactory )
            throws IllegalStateException;

    /**
     * @throws IllegalStateException if the TransactionAugmentor is a DeleteAugmentor and there are already participants in the Transaction
     */
    public Transaction addTransactionAugmentor( TransactionAugmentor pTransactionAugmentor )
            throws IllegalStateException;

    public CommitAugmentor[] getCommitAugmentors();

    /**
     * @return true if AugmentorClass found
     */
    public boolean hasCommitAugmentor( Class<? extends CommitAugmentor> pAugmentorClass );

    public Transaction addCommitAugmentor( CommitAugmentor pCommitAugmentor );

    /**
     * @return true if AugmentorClass found & removed
     */
    public boolean removeCommitAugmentor( Class<? extends CommitAugmentor> pAugmentorClass );

    public DeleteAugmentor[] getDeleteAugmentors();

    /**
     * @return true if AugmentorClass found
     */
    public boolean hasDeleteAugmentor( Class<? extends DeleteAugmentor> pAugmentorClass );

    /**
     * @throws IllegalStateException if there are already participants in the Transaction
     */
    public Transaction addDeleteAugmentor( DeleteAugmentor pDeleteAugmentor )
            throws IllegalStateException;

    /**
     * @return true if AugmentorClass found & removed
     */
    public boolean removeDeleteAugmentor( Class<? extends DeleteAugmentor> pAugmentorClass );

    /**
     * @param pPersistedObjectRegistrationName
     *         - Persisted Object Class Name (getClass().getName())
     *
     * @return !Null
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public PersistentObject<?> create( String pPersistedObjectRegistrationName )
            throws DBException;

    /**
     * @param pPersistedObjectClass - Persisted Object Class (getClass())
     *
     * @return !Null
     *
     * @throws DBException - Exception regarding the OR layer
     */
    public <T extends PersistentObject> T create( Class<T> pPersistedObjectClass )
            throws DBException;

    public PersistentObject<?> getPersistentObjectFromIdentityMap( PersistentObjectURL pPersistentObjectURL );

    /**
     * Refresh the pPersistedObject into this transaction.
     *
     * @param pPersistedObject - Persisted Object to be freshly read
     *
     * @return Transactional copy of the latest version read via Transaction, or Null if the PO is in another Transaction and isNew() OR has been deleted
     *
     * @throws UnsupportedOperationException - if the PO is already in the Transaction
     * @throws DBException                   - Exception regarding the OR layer
     */
    public <T extends PersistentObject> T refreshInto( PersistentObject<T> pPersistedObject )
            throws UnsupportedOperationException, DBException;

    public String getState();

    /**
     * This method returns true if the PO & transaction allows modification.
     * <p/>
     * This Transaction will only return true if it is not in the LL_COMMITING state AND has not been: successfully committed or disposed.
     */
    public boolean supportsPOmodification( PersistentObject pPoToModify );

    /**
     * This method returns true if the transaction has not been: successfully committed or disposed.
     */
    public boolean isFunctional();

    public void dispose();

    /**
     * @return Unique ID for this Transaction
     */
    public long getTransactionID();

    public PersistentObject[] getAllParticipants();

    /**
     * Commit changes from a temporary transaction space to the database
     * <p/>
     * This method must be called during an active transaction
     */
    public void commit()
            throws ConcurrentPOModificationException, DBException;

    /**
     * Commit changes from a temporary transaction space to the database
     * <p/>
     * This method must be called during an active transaction
     */
    public void commit( CommitAugmentor pCommitAugmentor )
            throws ConcurrentPOModificationException, DBException;

    /**
     * Under rare circumstances, a POs Key Vvlaues are changed and the Transaction must re-index it!
     * <p/>
     *
     * @param pOrigURL !null
     * @param pNewURL  !null
     */
    public void changedURL( PersistentObjectURL pOrigURL, PersistentObjectURL pNewURL );
}