/*

  * Licensed to the Apache Software Foundation (ASF) under one or more

  * contributor license agreements.  See the NOTICE file distributed with

  * this work for additional information regarding copyright ownership.

  * The ASF licenses this file to You 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.apache.commons.transaction.file;

 import java.io.InputStream;

 import java.io.OutputStream;

 import javax.transaction.Status;

 /**

  * Interface for resource managers.

  * 

  * A resource manager is an entity

  * that manages the processing and administration of resources.

  * 

  * What is specified here are methods

  * <ul> 

  * <li>for tasks related to starting and stopping of the resource manager

  * <li>for transaction management, like

  * starting, rolling back and committing of transactions  

  * <li>to set and get transaction timeouts

  * <li>to set the isolation level of a transaction

  * <li>for the general administration of resources

  * <li>for reading and writing of resources

  * </ul> 

  *  

  * @version $Id: ResourceManager.java 513490 2007-03-01 20:46:28Z ozeigermann $

  */

 public interface ResourceManager extends Status {

     /**

      * Isolation level <b>read uncommitted</b>: data written by other transactions can be read even before they commit  

      */

     public final static int ISOLATION_LEVEL_READ_UNCOMMITTED = 0;

     /**

      * Isolation level <b>read committed</b>: data written by other transactions can be read after they commit

      */

     public final static int ISOLATION_LEVEL_READ_COMMITTED = 10;

     /**

      * Isolation level <b>repeatable read</b>: data written by other transactions can be read after they commit if this transaction has not read this data before  

      */

     public final static int ISOLATION_LEVEL_REPEATABLE_READ = 50;

     /**

      * Isolation level <b>serializable</b>: result of other transactions will not influence the result of this transaction in any way

      */

     public final static int ISOLATION_LEVEL_SERIALIZABLE = 100;

     /**

      * Shutdown mode: Wait for all transactions to complete

      */

     public final static int SHUTDOWN_MODE_NORMAL = 0;

     /**

      * Shutdown mode: Try to roll back all active transactions

      */

     public final static int SHUTDOWN_MODE_ROLLBACK = 1;

     /**

      * Shutdown mode: Try to stop active transaction <em>NOW</em>, do no rollbacks

      */

     public final static int SHUTDOWN_MODE_KILL = 2;

     /**

      * Prepare result: resource manager guarantees a successful commit

      */

     public final static int PREPARE_SUCCESS = 1;

     /**

      * Prepare result: resource manager guarantees a successful commit as there is nothing to commit

      */

     public final static int PREPARE_SUCCESS_READONLY = 2;

     /**

      * Prepare result: transaction can not commit

      */

     public final static int PREPARE_FAILURE = -1;

     /**

      * Starts this resource manager. A resource manager must be started before transactions

      * can be started or any operations on transactions can be executed.

      * 

      * @throws ResourceManagerSystemException if start failed due to internal problems

      */

     public void start() throws ResourceManagerSystemException;

     /**

      * Tries to stop this resource manager within the given timeout.

      * 

      * @param mode one of {@link #SHUTDOWN_MODE_NORMAL}, {@link #SHUTDOWN_MODE_ROLLBACK}  or {@link #SHUTDOWN_MODE_KILL}

      * @param timeoutMSecs timeout for shutdown in milliseconds

      * @return <code>true</code> if resource manager stopped within given timeout

      * @throws ResourceManagerSystemException if something fatal hapened during shutdown

      */

     public boolean stop(int mode, long timeoutMSecs) throws ResourceManagerSystemException;

     /**

      * Tries to stop this resource manager within a default timeout.

      * 

      * @param mode one of predefined shutdown modes {@link #SHUTDOWN_MODE_NORMAL}, {@link #SHUTDOWN_MODE_ROLLBACK}  or {@link #SHUTDOWN_MODE_KILL}

      * or any other int representing a shutdown mode

      * @return <code>true</code> if resource manager stopped within given timeout

      * @throws ResourceManagerSystemException if anything fatal hapened during shutdown

      */

     public boolean stop(int mode) throws ResourceManagerSystemException;

     /**

      * Tries to bring this resource manager back to a consistent state. 

      * Might be called after system failure. An administrator might be forced

      * to fix system errors outside this resource manager to actually make

      * recovery possible. E.g. there may be a need for more disk space or

      * a network connection must be reestablished.

      * 

      * @return <code>true</code> upon successful recovery of the resource manager

      * @throws ResourceManagerSystemException if anything fatal hapened during recovery

      */

     public boolean recover() throws ResourceManagerSystemException;

     /**

      * Gets the default isolation level as an integer. 

      * The higher the value the higher the isolation.

      *  

      * @return one of the predefined isolation levels {@link #ISOLATION_LEVEL_READ_UNCOMMITTED}, 

      * {@link #ISOLATION_LEVEL_READ_COMMITTED}, {@link #ISOLATION_LEVEL_REPEATABLE_READ} or {@link #ISOLATION_LEVEL_SERIALIZABLE} 

      * or any other int representing an isolation level

      * @throws ResourceManagerException if an error occured

      */

     public int getDefaultIsolationLevel() throws ResourceManagerException;

     /**

      * Gets an array of all isolation levels supported by this resource manager.

      * This array must not be <code>null</code> or empty as every resource manager has some sort of isolation level.

      * 

      * @return array of the predefined isolation levels {@link #ISOLATION_LEVEL_READ_UNCOMMITTED}, 

      * {@link #ISOLATION_LEVEL_READ_COMMITTED}, {@link #ISOLATION_LEVEL_REPEATABLE_READ} or {@link #ISOLATION_LEVEL_SERIALIZABLE} 

      * or any other int representing an isolation level

      * @throws ResourceManagerException if an error occured

      * @see #getDefaultIsolationLevel

      */

     public int[] getSupportedIsolationLevels() throws ResourceManagerException;

     /**

      * Tests if the specified isolation level is supported by this resource manager.

      * 

      * @param level isolation level whose support is to be tested 

      * @return <code>true</code> if the isolation level is supported

      * @throws ResourceManagerException if an error occured

      * @see #getDefaultIsolationLevel

      */

     public boolean isIsolationLevelSupported(int level) throws ResourceManagerException;

     /**

      * Gets the isolation level for the specified transaction. 

      * 

      * @param txId identifier for the concerned transaction

      * @return one of the predefined isolation levels {@link #ISOLATION_LEVEL_READ_UNCOMMITTED}, 

      * {@link #ISOLATION_LEVEL_READ_COMMITTED}, {@link #ISOLATION_LEVEL_REPEATABLE_READ} or {@link #ISOLATION_LEVEL_SERIALIZABLE} 

      * or any other int representing an isolation level

      * @throws ResourceManagerException if an error occured

      * @see #getDefaultIsolationLevel

      */

     public int getIsolationLevel(Object txId) throws ResourceManagerException;

     /**

      * Sets the isolation level for the specified transaction.

      * <br>

      * <em>Caution</em>: Implementations are likely to forbid changing the isolation level after any operations

      * have been executed inside the specified transaction.  

      * 

      * @param txId identifier for the concerned transaction

      * @param level one of the predefined isolation levels {@link #ISOLATION_LEVEL_READ_UNCOMMITTED}, 

      * {@link #ISOLATION_LEVEL_READ_COMMITTED}, {@link #ISOLATION_LEVEL_REPEATABLE_READ} or {@link #ISOLATION_LEVEL_SERIALIZABLE} 

      * or any other int representing an isolation level

      * @throws ResourceManagerException if an error occured

      * @see #getDefaultIsolationLevel

      */

     public void setIsolationLevel(Object txId, int level) throws ResourceManagerException;

     /**

      * Gets the default transaction timeout in milliseconds.

      * After this time expires and the concerned transaction has not finished

      * - either rolled back or committed - the resource manager is allowed and

      * also encouraged - but not required - to abort the transaction and to roll it back.

      * 

      * @return default transaction timeout in milliseconds

      * @throws ResourceManagerException if an error occured

      */

     public long getDefaultTransactionTimeout() throws ResourceManagerException;

     /**

      * Gets the transaction timeout of the specified transaction in milliseconds.

      * 

      * @param txId identifier for the concerned transaction

      * @return transaction timeout of the specified transaction in milliseconds

      * @throws ResourceManagerException if an error occured

      * @see #getDefaultTransactionTimeout

      */

     public long getTransactionTimeout(Object txId) throws ResourceManagerException;

     /**

      * Sets the transaction timeout of the specified transaction in milliseconds.

      * 

      * @param txId identifier for the concerned transaction

      * @param mSecs transaction timeout of the specified transaction in milliseconds

      * @throws ResourceManagerException if an error occured

      * @see #getDefaultTransactionTimeout

      */

     public void setTransactionTimeout(Object txId, long mSecs) throws ResourceManagerException;

     /**

      * Creates and starts a transaction using the specified transaction identifier.

      * The identifier needs to be unique to this resource manager.

      * As there is no transaction object returned all access to the transaction

      * needs to be addressed to this resource manager.

      * 

      * @param txId identifier for the transaction to be started

      * @throws ResourceManagerException if an error occured

      */

     public void startTransaction(Object txId) throws ResourceManagerException;

     /**

      * Prepares the transaction specified by the given transaction identifier for commit.

      * The preparation may either succeed ({@link #PREPARE_SUCCESS}), 

      * succeed as there is nothing to commit ({@link #PREPARE_SUCCESS_READONLY})

      * or fail ({@link #PREPARE_FAILURE}). If the preparation fails, commit will

      * fail as well and the transaction should be marked for rollback. However, if it 

      * succeeds the resource manager must guarantee that a following commit will succeed as well.

      * 

      * <br><br>

      * An alternative way to singal a <em>failed</em> status is to throw an exception.

      * 

      * @param txId identifier for the transaction to be prepared

      * @return result of the preparation effort, either {@link #PREPARE_SUCCESS}, {@link #PREPARE_SUCCESS_READONLY} or {@link #PREPARE_FAILURE}   

      * @throws ResourceManagerException alternative way to signal prepare failed

      */

     public int prepareTransaction(Object txId) throws ResourceManagerException;

     /**

      * Marks the transaction specified by the given transaction identifier for rollback.

      * This means, even though the transaction is not actually finished, no other operation

      * than <code>rollback</code> is permitted.

      * 

      * @param txId identifier for the transaction to be marked for rollback

      * @throws ResourceManagerException if an error occured

      */

     public void markTransactionForRollback(Object txId) throws ResourceManagerException;

     /**

      * Rolls back the transaction specified by the given transaction identifier. 

      * After roll back the resource manager is allowed to forget about

      * the associated transaction.

      * 

      * @param txId identifier for the transaction to be rolled back

      * @throws ResourceManagerException if an error occured

      */

     public void rollbackTransaction(Object txId) throws ResourceManagerException;

     /**

      * Commis the transaction specified by the given transaction identifier. 

      * After commit the resource manager is allowed to forget about

      * the associated transaction.

      * 

      * @param txId identifier for the transaction to be committed

      * @throws ResourceManagerException if an error occured

      */

     public void commitTransaction(Object txId) throws ResourceManagerException;

     /**

      * Gets the state of the transaction specified by the given transaction identifier.

      * The state will be expressed by an <code>int</code> code as defined 

      * in the {@link javax.transaction.Status} interface. 

      * 

      * @param txId identifier for the transaction for which the state is returned

      * @return state of the transaction as defined in {@link javax.transaction.Status}

      * @throws ResourceManagerException if an error occured

      */

     public int getTransactionState(Object txId) throws ResourceManagerException;

     /**

      * Explicitly locks a resource. Although locking must be done implicitly by methods 

      * creating, reading or modifying resources, there may be cases when you want to do this

      * explicitly.<br>

      * 

      *<br>

      * <em>Note</em>: By intention the order of parameters (<code>txId</code> does not come first) is different than in other methods of this interface. 

      * This is done to make clear locking affects all transactions, not only the locking one. 

      * This should be clear anyhow, but seems to be worth noting.

      * 

      * @param resourceId identifier for the resource to be locked 

      * @param txId identifier for the transaction that tries to acquire a lock

      * @param shared <code>true</code> if this lock may be shared by other <em>shared</em> locks

      * @param wait <code>true</code> if the method shall block when lock can not be acquired now

      * @param timeoutMSecs timeout in milliseconds

      * @param reentrant <code>true</code> if the lock should be acquired even when the <em>requesting transaction and no other</em> holds an incompatible lock

      * @return <code>true</code> when the lock has been acquired

      * @throws ResourceManagerException if an error occured

      */

     public boolean lockResource(

         Object resourceId,

         Object txId,

         boolean shared,

         boolean wait,

         long timeoutMSecs,

         boolean reentrant)

         throws ResourceManagerException;

     /**

      * Explicitly locks a resource in reentrant style. This method blocks until the lock

      * actually can be acquired or the transaction times out. 

      * 

      * @param resourceId identifier for the resource to be locked 

      * @param txId identifier for the transaction that tries to acquire a lock

      * @param shared <code>true</code> if this lock may be shared by other <em>shared</em> locks

      * @throws ResourceManagerException if an error occured

      * @see #lockResource(Object, Object, boolean, boolean, long, boolean)

      */

     public boolean lockResource(Object resourceId, Object txId, boolean shared) throws ResourceManagerException;

     /**

      * Explicitly locks a resource exclusively, i.e. for writing, in reentrant style. This method blocks until the lock

      * actually can be acquired or the transaction times out. 

      * 

      * @param resourceId identifier for the resource to be locked 

      * @param txId identifier for the transaction that tries to acquire a lock

      * @throws ResourceManagerException if an error occured

      * @see #lockResource(Object, Object, boolean)

      * @see #lockResource(Object, Object, boolean, boolean, long, boolean)

      */

     public boolean lockResource(Object resourceId, Object txId) throws ResourceManagerException;

     /**

      * Checks if a resource exists. 

      * 

      * @param txId identifier for the transaction in which the resource is to be checked for

      * @param resourceId identifier for the resource to check for 

      * @return <code>true</code> if the resource exists

      * @throws ResourceManagerException if an error occured

      */

     public boolean resourceExists(Object txId, Object resourceId) throws ResourceManagerException;

     /**

      * Checks if a resource exists wihtout being in a transaction. This means only take

      * into account resources already globally commited.

      * 

      * @param resourceId identifier for the resource to check for 

      * @return <code>true</code> if the resource exists

      * @throws ResourceManagerException if an error occured

      */

     public boolean resourceExists(Object resourceId) throws ResourceManagerException;

     /**

      * Deletes a resource.

      * 

      * @param txId identifier for the transaction in which the resource is to be deleted

      * @param resourceId identifier for the resource to be deleted

      * @throws ResourceManagerException if the resource does not exist or any other error occured

      */

     public void deleteResource(Object txId, Object resourceId) throws ResourceManagerException;

     /**

      * Deletes a resource.

      * 

      * @param txId identifier for the transaction in which the resource is to be deleted

      * @param resourceId identifier for the resource to be deleted

      * @param assureOnly if set to <code>true</code> this method will not throw an exception when the resource does not exist

      * @throws ResourceManagerException if the resource does not exist and <code>assureOnly</code> was not set to <code>true</code> or any other error occured

      */

     public void deleteResource(Object txId, Object resourceId, boolean assureOnly) throws ResourceManagerException;

     /**

      * Creates a resource.

      * 

      * @param txId identifier for the transaction in which the resource is to be created

      * @param resourceId identifier for the resource to be created

      * @throws ResourceManagerException if the resource already exist or any other error occured

      */

     public void createResource(Object txId, Object resourceId) throws ResourceManagerException;

     /**

      * Creates a resource.

      * 

      * @param txId identifier for the transaction in which the resource is to be created

      * @param resourceId identifier for the resource to be created

      * @param assureOnly if set to <code>true</code> this method will not throw an exception when the resource already exists

      * @throws ResourceManagerException if the resource already exists and <code>assureOnly</code> was not set to <code>true</code> or any other error occured

      */

     public void createResource(Object txId, Object resourceId, boolean assureOnly) throws ResourceManagerException;

         /**

          * Opens a streamable resource for reading.

          * 

          * <br><br>

          * <em>Important</em>: By contract, the application is responsible for closing the stream after its work is finished.

          * 

          * @param txId identifier for the transaction in which the streamable resource is to be openend

          * @param resourceId identifier for the streamable resource to be opened

          * @return stream to read from 

          * @throws ResourceManagerException if the resource does not exist or any other error occured

          */

         public InputStream readResource(Object txId, Object resourceId) throws ResourceManagerException;

         /**

          * Opens a streamable resource for a single reading request not inside the scope of a transaction.

          *  

          * <br><br>

          * <em>Important</em>: By contract, the application is responsible for closing the stream after its work is finished.

          * 

          * @param resourceId identifier for the streamable resource to be opened

          * @return stream to read from 

          * @throws ResourceManagerException if the resource does not exist or any other error occured

          */

         public InputStream readResource(Object resourceId) throws ResourceManagerException;

         /**

          * Opens a resource for writing. 

          * 

          * <br><br>

          * <em>Important</em>: By contract, the application is responsible for closing the stream after its work is finished.

          * 

          * @param txId identifier for the transaction in which the streamable resource is to be openend

          * @param resourceId identifier for the streamable resource to be opened

          * @return stream to write to 

          * @throws ResourceManagerException if the resource does not exist or any other error occured

          */

         public OutputStream writeResource(Object txId, Object resourceId) throws ResourceManagerException;

 }