// 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() throws Exception;

  /**
  **  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() throws Exception;

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

  public ApplicationModule getInstanceByCookie(Object cookie, boolean checkout);
  
  public Object getCookie(ApplicationModule instance);
  
  /**
  **  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);

  /**
    * Gets the snapshot of available number of pools
    * returns number of available pools
  */
  public int getAvailableNumPools();

  /**
   * Get the time when the app module was created (in milli-secs).
   */
  public long getTimeToCreateMillis(ApplicationModule instance);

  /**
   * Get the time when the app module was created (in milli-secs).
   */
  public long getCreationTimeMillis(ApplicationModule instance);

  /**
   * Returns the user name
   */
  public String getUserName();

  /**
   * Returns the password
   */
  public String getPassword();

  public void setUserName(String sUser);

  public void setPassword(String sPassword);

  /**
  * Given an intitial Application Module instance, synchronizes the caches of all
  * Application Module instances in the pool.
  * <p>
  * This method commits the transaction for <tt>instance</tt>.
  * Then, it loops through all other instances of the
  * Application Module
  * in the pool and synchronizes their caches with the
  * changes committed by <tt>instance</tt>.
  * For example:
  * <p>
  * <pre>
  *  // Insert a new row
  *     row = voEmp1.createRow();
  *
  *     row.setAttribute("EmpNum", new Integer(9999));
  *     row.setAttribute("EmpName", "NewPers");
  *     row.setAttribute("EmpJob", "JOBX");
  *
  *     voEmp1.insertRow(row);
  *
  *  // Commit the changes for the specified instance, then sync 
  *  // them with the rest of the Application Module instances.
  *     pool1.commitAndSyncCache(am1);
  * </pre>
  * <p>
  * @param instance an instance of an Application Module in the pool.
  */
  public void commitAndSyncCache(ApplicationModule instance);
}