
// 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.
 ** <BR>
 ** <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 {@link oracle.jbo.html.jsp.ConnectionInfo} documentation since it controls the key information for initializing
  **  the application pool.
  ** @param sPoolName the name of the application module pool.
  ** @param sApplicationModule name of the application module for which the pool will be created.
  ** @param sConnectString the connection string to use to connect to the database.
  ** @param env name of the hash table containing the environment variables for the selected platform.
  **/
  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.
  ** @param instance name of the application module instance to check in.
  **/
  public void checkin(ApplicationModule instance);

   /**
    * Check-in the application module as being referenced by the invoking
    * session thread.
    * <p>
    * This method should be used by pool clients that wish to maintain logical
    * application module state while still sharing an application module
    * resource across requests.  The method returns a system generated session
    * id for the check-in that should be used as the unique application module
    * identifier by the client session.</p>
    * <p>
    * The application module will be passivated immediately if failover support
    * has been requested (default).  If failover support has been disable,
    * through the jbo.DoFailover system parameter, the application module will
    * not be passivated until it is re-used by a session other than the
    * session checking in the application module.</p>
    *
    * @param appModule the application module that will be checked in
    */
   public String checkinWithSessionState(ApplicationModule appModule);

  /**
  ** Indicates whether this application module is available.
  **
  ** @param instance the application module instance that you want to
  ** test for availability.
  ** @return <tt>true</tt> if the application module is available;
  ** <tt>false</tt> otherwise.
  **/
  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;

 /**
  * Returns an application module for the specified session id.  The session
  * id must have been generated by a previous call to
  * {@link #checkinWithSessionState(ApplicationModule)}
  * against this application module pool.
  * <p>
  * The session id will be used to obtain an application module with the
  * same state as the application module that had been returned by the session
  * with checkinWithSessionState.</p>
  * <p>
  * If an unrecognized session id is specified than the implementation
  * returns an empty application module.</p>
  * @param sessionId the name of the session ID for which you want to return the
  * associated application module.
  */
  public ApplicationModule checkout(String sessionId);

  /**
  **  Causes the pool to release all the application isntances that have been created so far.
  **  The <tt>remove()</tt> 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();

  /**
  **  Creates 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
  **  {@link #checkout()} instead.
  **/
  public ApplicationModule createNewInstance() throws Exception;

  /**
  **  Returns the application instance represented by the instance index.
  ** @param nIndex the index of the application instance.
  **/
  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.
  ** @param the new hashtable to use for the environment information.
  **/
  public void setUserData(Hashtable data);

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

  /**
   * Gets the time that it will tke to create the application module
   * (in milli-secs).
   * @param instance the application module instance for which you want to
   * know how long it will take to create it.
   */
  public long getTimeToCreateMillis(ApplicationModule instance);

  /**
   * Gets the time when the app module was created (in milli-secs).
   * @param instance the application module instance for which you want to
   * know the time of creation.
   */
  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);
}
