// Copyright (c) 1999, 2000 Oracle Corporation
package oracle.jbo.common.ampool;

import java.util.Hashtable;
import oracle.jbo.*;

/**
 ** This is the ApplicationPool interface. It needs to be implemented by any class that is intended
 ** to provide a customized pool interface. Look at ApplicationPoolImpl for the default implementation.
 **
 ** <a HREF="ApplicationPool.txt">View Implementation of ApplicationPool</a>
 ** <a HREF="ApplicationPoolImpl.txt">View Implementation of ApplicationPoolImpl</a>
 ** <P>
 ** @author Juan Oropeza
 **/
public interface ApplicationPool
{
  /**
  **  This initializes the ApplicationPool. The Pool name should be unique with respect
  **  to any other pools. An exception will be thrown on any errors such as duplicate pool
  **  name or mismatched information within the connectInfo parameter. Take a close look
  **  at the ConnectInfo documentation since it controls the key information for initializing
  **  the application pool.  
  **/
  public void initialize(String sPoolName , String sApplicationModule, String sConnectString, Hashtable env) throws Exception;

  /**
  **  Return the class name of the application modules being managed by the pool. 
  **/
  public String getApplicationModuleClass();

  /**
  **  Return the connect string of the application modules being managed by the application pool.
  **/
  public String getConnectString();

  /**
  **  Returns the Hashtable that was used to initialie the Contect for the application modules.
  **/
  public Hashtable getEnvironment();
  
  /**
  **  Checks in an application instance that had previously been checked out. This makes the
  **  application instance avalable for subsequent checkout requests from this pool.
  **/
  public void checkin(ApplicationModule instance);

  /**
  **  Returns true if the application module is available
  **/
  public boolean isAvailable(ApplicationModule instance);

  /**
  **  Sets the instance to available or not
  **/
  public void setAvailable(ApplicationModule instance, boolean bSet);

  /**
  **  Checks out an application instance from the pool. If the pool doesn't have any available
  **  instances, it will create a new instance and return it to the caller. 
  **/
  public ApplicationModule checkout();

  /**
  **  Causes the pool to release all the application isntances that have been created so far.
  **  The remove() method is called on the Application Modules being represented by the application
  **  instance class
  **/
  public void releaseInstances();

  /**
  **  Returns the number of instances that the Application Pool has created.
  **/
  public int  getInstanceCount();

  /**
  **  This create a new instance of an application without looking for an available
  **  instance in the pool. This method should not be called directly, you should call
  **  checkout() .
  **/
  public ApplicationModule createNewInstance();

  /**
  **  Returns the application instance represented by the instance index.
  **/
  public ApplicationModule getInstance(int nIndex);

  /**
  **  Returns the pool's name.
  **/
  public String getPoolName();

 /**
  **  returns the User Data hashtable. This is a generic container for
  **  any settings the user would like to associate with this application pool.
  **/
  public Hashtable getUserData();

  /**
  ** Replaces the userData with the new Hashtable.
  **/
  public void setUserData(Hashtable data);
}