/*
 * @(#)ApplicationModuleRef.java
 *
 * Copyright 2001-2002 by Oracle Corporation,
 * 500 Oracle Parkway, Redwood Shores, California, 94065, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Oracle Corporation.
 */

package oracle.jbo.common.ampool;

import oracle.jbo.ApplicationModule;
import oracle.jbo.ApplicationModuleHandle;

public interface ApplicationModuleRef extends ApplicationModuleHandle
{
   public static final boolean SHARED = true;
   public static final boolean UNSHARED = false;
   public static final boolean STATE_MANAGED = true;
   public static final boolean STATE_UNMANAGED = false;

   /**
    * Tests if the application module that is referenced by this session cookie
    * has been reserved for exclusive access by this session cookie.
    *
    * @return boolean true if the referenced instance is reserved
    */
   public boolean isApplicationModuleReserved();

   /**
    * Returns an application module instance without acquiring a session
    * cookie lock.
    *
    * @see #useApplicationModule(boolean, long)
    */
   public ApplicationModule useApplicationModule();

   /**
    * Returns an application module instance for the current thread.
    * Uses the default waitTimeout specified by the cookie.
    * <p>
    * @see #useApplicationModule(boolean, long)
    * @param lock specify whether a session lock should be acquired for the
    *    shared application module resource
    */
   public ApplicationModule useApplicationModule(boolean lock);

   /**
    * Returns an application module instance for the current thread.
    * <p>
    * If the application session cookie references application state the
    * application state should be activated in the returned application module.
    * <p>
    * The lock parameter may be specified to acquire a lock for the shared
    * application module resource.  If a lock is acquired the application
    * should be careful to release that lock after it is done using the
    * application module resource.   Application thread starvation may occur if
    * the lock is held indefinitely.
    * <p>
    * If another thread is holding the lock associated with the session cookie
    * then the current thread will wait for the period specified by the waitTimeout
    * parameter.
    * <p>
    * Best practice would be to invoke {@link #useApplicationModule(boolean)}
    * in a try...finally block that invokes {@link #releaseApplicationModule(boolean, boolean}
    * during finally.
    * <p>
    * @param lock specify whether a session lock should be acquired for the
    *    shared application module resource
    * @param waitTimeout specifies the amount of time in milliseconds that the 
    *    thread should wait for the session cookie lock
    */
   public ApplicationModule useApplicationModule(boolean lock, long waitTimeout);

   /**
    * Release an application module for reuse.
    * <p>
    * This method should be invoked at the end of each session request.
    * <p>
    * If another thread is holding the lock associated with the session cookie
    * then the current thread will wait indefinitely.  Please see {@link #releaseApplicationModule(boolean, boolean, long)}
    * if a wait timeout is desired.
    * <p>
    * The checkin parameter may be used to indicate that the session application
    * module instance should be checked in for reuse by other sessions.
    * <p>
    * The manageState parameter may be used to indicate that the session
    * application state should be managed between requests by the pooling
    * framework.
    * <p>
    * @param checkin <tt>SHARED</tt> or <tt>UNSHARED</tt>
    * @param manageState manage the session application state between requests
    */
   public void releaseApplicationModule(boolean checkin, boolean manageState);

   /**
    * Release an application module for reuse.
    * <p>
    * This method should be invoked at the end of each session request.
    * <p>
    * If another thread is holding the lock associated with the session cookie
    * then the current thread will wait for the period specified by the waitTimeout
    * parameter.  The current thread may be blocked upon invoking releaseApplicationModule
    * if it did not acquire a session cookie lock when it dereferenced the 
    * application module with {@link #useApplicationModule(boolean).
    * <p>
    * The checkin parameter may be used to indicate that the session application
    * module instance should be checked in for reuse by other sessions.
    * <p>
    * The manageState parameter may be used to indicate that the session
    * application state should be managed between requests by the pooling
    * framework.
    * <p>
    * I
    * @param checkin <tt>SHARED</tt> or <tt>UNSHARED</tt>
    * @param manageState <tt>STATE_MANAGED</tt> or <tt>STATE_UNMANAGED</tt>
    * @param waitTimeout specifies the amount of time in milliseconds that the 
    *    thread should wait for the session cookie lock
    */
   public void releaseApplicationModule(boolean checkin, boolean manageState, long waitTimeout);

   /**
    * Reset the ApplicationModule state associated with this 
    * ApplicationModuleRef.   
    * <p>
    * Invoking this method after an ApplicationModule has been released
    * with state management specified will result in the affinity between
    * the ApplicationModuleRef and the ApplicationModule state being lost. 
    * Consequently, the next time invocation of <tt>useApplicationModule</tt>
    * on this ApplicationModuleRef will return a stateless Applicationmodule.
    * <p>
    * Invoking this method on an ApplicationModuleRef which is not referencing
    * any ApplicationModule state will have no effect.  Invoking this method
    * on an ApplicationModuleRef which is currently reserving an
    * ApplicationModule will result in an ApplicationPoolException.
    */ 
   public void resetState();
}
