/*
 * @(#)EnvInfoProvider.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;

/**
 * Invoked by {@link oracle.jbo.common.ampool.DefaultConnectionStrategy} when
 * the application pool is establishing connection to the database or when
 * the application pool is recycling an ApplicationModule.
 * <p>
 * Application developers may implement this interface to provide dynamic
 * information to {@link oracle.jbo.Transaction.connect(String, Properties)}.
 * Examples of dynamic information may include a database username or a database
 * user password.
 * <p>
 * Application developers may also implement this interface to provide dynamic
 * session information to {@link oracle.jbo.server.ApplicationModuleImpl.prepareSession(Session)}.
 * Examples of dynamic session environment may include the authenticated
 * principal name.
 * 
 */
public interface EnvInfoProvider
{
   /**
    * Invoked by the ApplicationPool to acquire dynamic application context
    * before the following ApplicationModule lifecycle events:
    * <p>
    * 1.  An ApplicationModule instance is created
    * 2.  An ApplicationModule instance is connected
    * 3.  An ApplicationModule instance is reused by an ApplicationPool
    *     session which is differnt than the session which had previously
    *     used it.  Please see {@link oracle.jbo.common.ampool.SessionCookie}
    *     for more information about ApplicationPool sessions.
    * <p>
    * An EnvInfoProvider implementation may respond to the request by providing
    * session context for the ApplicationModule instance in the environment
    * Hashtable which is passed to getInfo.
    * <p>
    * <tt>getInfo</tt> is always invoked with a Hashtable instance though
    * it may also be invoked with a <tt>java.util.Properties</tt> (extends
    * Hashtable) in some scenarios.  Any session context that is specified
    * by getInfo will also be available in the BC4J middle tier via
    * {@link oracle.jbo.Session} and during invocation of {@link oracle.jbo.server.ApplicationModuleImpl#prepareSession(Session).
    * <p>
    * <tt>getInfo</tt> may also be used to dynamically specify JDBC credentials.
    * For example, the following code snippet may be used to dynamically
    * specify the JDBC credentials for the current ApplicationModule session
    * (please see the article at http://otn.oracle.com/products/jdev/howtos/bc4j/howto_dynamic_jdbc.html for more information about dynamically specifying
    * JDBC credentials to BC4J):
    * <tt>
    *    ((Hashtable)env).put(Configuration.DB_USERNAME_PROPERTY, <username>);
    *    ((Hashtable)env).put(Configuration.DB_PASSWORD_PROPERTY, <password>);
    *    return null;
    * </tt>
    * <p>
    * Finally, <tt>getInfo</tt> may also be invoked multiple times during a
    * connect attempt, if previous connect attempts have failed.  This is
    * intended to give the EnvInfoProvider an opportunity to correct the
    * dynamic JDBC credentials before ultimately failing with an exception.
    * The connection exception, if one occurred, is available to the
    * EnvInfoProvider via the context with the
    * <tt>DefaultConnectionStrategy.LAST_EXCEPTION</tt> key.
    * <p>
    * @param info Unused.  Retained for legacy reasons.  Please note that
    *    before connecting the pooling framework may invoke getInfo multiple
    *    times with the following values for the info parameter:
    *    1.  <tt>Configuration.DB_USERNAME_PROPERTY</tt>
    *    2.  <tt>Configuration.DB_PASSWORD_PROPERTY</tt>
    *    3.  <tt>null</tt>
    * 
    *    Though it is only necessary to actually respond to the <tt>null</tt>
    *    request. 
    *
    * @param env a Hashtable object containing the environment that
    *    will be passed to:
    *       {@link oracle.jbo.Transaction.connect(String, Properties)}
    *       {@link oracle.jbo.server.ApplicationModuleImpl.prepareSession(Session)}
    *
    *
    * @return Unused.  Retained for legacy reasons.
    * @see oracle.jbo.uicli.jui.JUEnvInfoProvider for an example implementation
    *    of an EnvInfoProvider for a JClient.
    */
   public Object getInfo(String info, Object env);

   /**
    * Invoked when the application pool is creating a new application module
    * instance.  The environment hashtable may be modified by the
    * EnvInfoProvider to provide dynamic application module context.
    *
    * @deprecated {@link #getInfo(String, Object)} should be implemented
    * instead.
    * @since 9.0.2
    */
   public void modifyInitialContext(Object initialContext);

   /**
    * Returns the number times that the default connection strategy should
    * attempt to create/connect and application module instance before
    * failing.
    */
    public int getNumOfRetries();
}
