Implementing Pooling in Application Module Code

Implementing Pooling in Application Module Code

One of the tasks you must perform to enable application module pooling is to set up the environment information needed to connect to the application module. The information you supply will depend on the platform on which the application module resides. To find out more about the code you need to supply to set up the environment for the various platforms, see Setting up the Environment.

An example implementation of a stateful application

The PoolTester class provides a sample implementation and use of application module pooling in LOCAL mode. This example uses the default implementation of application module pooling.

 1 public class PoolTester extends Object {

 2 /**
 3    * Constructor
 4  */
 5 public PoolTester() {
 6 }

 7 public void doTest() throws Exception
 8 {

 9   Hashtable env = new Hashtable(10);
 
10   env.put(JboContext.INITIAL_CONTEXT_FACTORY, JboContext.JBO_CONTEXT_FACTORY);
11   env.put(JboContext.DEPLOY_PLATFORM, JboContext.PLATFORM_LOCAL);

12   PoolMgr.getInstance().createPool("TestAMPool", "Package1.MyAppMod",
          "jdbc:oracle:thin:scott/tiger@localhost:1521:orcl", env); 

13   PoolMgr.getInstance().createPool("SecondAMPool", "Package2.MyAppMod",
          "jdbc:oracle:thin:scott/tiger@localhost:1521:orcl", env); 

14   ApplicationPool pool = PoolMgr.getInstance().getPool("TestAMPool");

15   ApplicationModule instance = pool.checkout();

16   ApplicationModule instance2 = pool.checkout();

17   ApplicationModule instance3 = pool.checkout();

18   ApplicationPool pool2 = PoolMgr.getInstance().getPool("SecondAMPool");

19   ApplicationModule instance22 = pool2.checkout();

20   ApplicationModule instance23 = pool2.checkout();

21   String sessionId = pool2.checkinWithSessionState(instance22);

22   instance22 = pool2.checkout(sessionId);

23   PoolMgr.getInstance().removePool("TestAMPool");   

24 }

Lines 9-11: Define the environment settings. This can be done directly (as is demonstrated here) or from a property file. In this example, the hashtable contains the properties to set up the environment to connect in LOCAL mode. For more information about the code you need to supply to set up the environment for LOCAL mode and the other platforms, see Setting up the Environment.

Line 12: Create the pool TestAMPool. Since PoolMgr is a singleton object, use PoolMgr.getInstance to get it. Use createPool to create the pool. Notice that createPool requires the name of the pool, the name of the package that contains the application module, the connect string to the database, and env, the hashtable. The createPool method is overloaded—an alternative version takes an additional parameter that lets you override the default implementation of application module pooling and specify your own.

Line 13: Create a second pool, SecondAMPool that connects with the same environment variables, but to an application module in a different package.

Line 14: PoolMgr.getInstance().getPool("TestAMPool") gets a handle to the pool to work with it.

Lines 15-17: Checkout three instances. Note that the classes ApplicationPoolImpl and PoolMgr contain other functions that you can use to traverse the pool content. The ampool package also contains a PoolAdministrator Web Bean that you can use to dump the contents of the pool.

Lines 18-20: Get a handle to the second pool, check out two instances.

Lines 21-22: Check in an application module instance in a stateful fashion, stroring the session ID in a local String. Check out an application module with the same state that was checked in.

Line 23: Use removePool to remove the application module pool. This function calls remove() on all of the application module instances, including ones that are currently checked out and in use, and causes them to disconnect from the database and remove all of their view objects.

An example implementation of a stateless application

The PoolTester class provides a sample implementation and use of application module pooling in LOCAL mode. This example uses the default implementation of application module pooling.

 1 public class PoolTester extends Object {

 2 /**
 3    * Constructor
 4  */
 5 public PoolTester() {
 6 }

 7 public void doTest() throws Exception
 8 {

 9   Hashtable env = new Hashtable(10);
 
10   env.put(JboContext.INITIAL_CONTEXT_FACTORY, JboContext.JBO_CONTEXT_FACTORY);
11   env.put(JboContext.DEPLOY_PLATFORM, JboContext.PLATFORM_LOCAL);

12   PoolMgr.getInstance().createPool("TestAMPool", "Package1.MyAppMod",
          "jdbc:oracle:thin:scott/tiger@localhost:1521:orcl", env); 

13   PoolMgr.getInstance().createPool("SecondAMPool", "Package2.MyAppMod",
          "jdbc:oracle:thin:scott/tiger@localhost:1521:orcl", env); 

14   ApplicationPool pool = PoolMgr.getInstance().getPool("TestAMPool");

15   ApplicationModule instance = pool.checkout();

16   ApplicationModule instance2 = pool.checkout();

17   ApplicationModule instance3 = pool.checkout();

18   ApplicationPool pool2 = PoolMgr.getInstance().getPool("SecondAMPool");

19   ApplicationModule instance22 = pool2.checkout();

20   ApplicationModule instance23 = pool2.checkout();

21   pool2.checkin(instance22);

22   PoolMgr.getInstance().removePool("TestAMPool");  

23 }

Lines 9-11: Define the environment settings. This can be done directly (as is demonstrated here) or from a property file. In this example, the hashtable contains the properties to set up the environment to connect in LOCAL mode. For more information about the code you need to supply to set up the environment for LOCAL mode and the other platforms, see Setting up the Environment.

Line 12: Create the pool TestAMPool. Since PoolMgr is a singleton object, use PoolMgr.getInstance to get it. Use createPool to create the pool. Notice that createPool requires the name of the pool, the name of the package that contains the application module, the connect string to the database, and env, the hashtable. The createPool method is overloaded—an alternative version takes an additional parameter that lets you override the default implementation of application module pooling and specify your own.

Line 13: Create a second pool, SecondAMPool that connects with the same environment variables, but to an application module in a different package.

Line 14: PoolMgr.getInstance().getPool("TestAMPool") gets a handle to the pool to work with it.

Lines 15-17: Checkout three instances. Note that the classes ApplicationPoolImpl and PoolMgr contain other functions that you can use to traverse the pool content. The ampool package also contains a PoolAdministrator Web Bean that you can use to dump the contents of the pool.

Lines 18-21: Get a handle to the second pool, check out two instances, then check in one.

Line 22: Use removePool to remove the application module pool. This function calls remove() on all of the application module instances, including ones that are currently checked out and in use, and causes them to disconnect from the database and remove all of their view objects.

---

Related topics
Pooling Application Modules
About Application Module Pooling
About Application Module Pooling Classes

 

 

Loading an Application Module Instance in Code

The following example illustrates code snippets for setting up an environment, loading an application module, and creating a platform-independent application module. The example assumes that connection parameters, including user name and password would probably be provided by a user.

An Application Module's lifetime depends on the deployment platform. When deployed to the Visibroker platform or Oracle8i CORBA server, the lifetime is until the client calls remove on the Application Module. When running locally, an Application Module lasts as long as the local variable that represents it.

This topic provides code examples for:

·         Setting up the environment

·         Setting platform-dependent environment variables for deploying the Application Module. You use different environment variables depending on whether you are:

o    deploying locally

o    deploying on Oracle8i as a CORBA server object

o    deploying on Oracle8i as an EJB

o    deploying on the Visibroker platform as a CORBA server object

·         Loading an Application Module

Setting up the Environment

Your set up code, in addition to importing the appropriate files for your application, must include a hash table to hold the values of environment variables.

  static Hashtable env = new Hashtable(10);

Your code must also include a definition of the Application Module home:

  static ApplicationModuleHome mHome ;

You must include code to connect to the database. For information on how to connect to a database, see the JDBC Developer's Guide and Reference. To access this book you must be registered with the Oracle Technical Network (OTN). To use this free resource, go to OTN's registration page.

Setting Environment Variables for Deploying Locally

The following code snippet illustrates how to set the environment variables to run an Application Module deployed locally.

// Component running locally

     {

     public static void setLocalEnv()  {

     env.put(JboContext.INITIAL_CONTEXT_FACTORY, JboContext.JBO_CONTEXT_FACTORY);

     env.put(JboContext.DEPLOY_PLATFORM, JboContext.PLATFORM_LOCAL);

     }

    }

Setting Environment Variables for Deploying on Oracle8i as a CORBA Server Object

The following code snippet illustrates how to set the environment for loading an Application Module deployed on Oracle8i as a CORBA object.

     // Component deployed to Oracle8i CORBA Server.

     // Set up the 8i environment

      public static void set8iEnv()  {

      env.put(JboContext.INITIAL_CONTEXT_FACTORY, 

              JboContext.JBO_CONTEXT_FACTORY);

      env.put(JboContext.DEPLOY_PLATFORM, JboContext.PLATFORM_ORACLE8I);

      env.put(JboContext.SECURITY_PRINCIPAL, "scott");

      env.put(JboContext.SECURITY_CREDENTIALS, "tiger");

      env.put(JboContext.HOST_NAME, "localhost");

      env.put(JboContext.CONNECTION_PORT, "2481");

      env.put(JboContext.ORACLE_SID, "ORA815");

      env.put(JboContext.APPLICATION_PATH, "test");

    }

Setting Environment Variables for Deploying on Oracle8i as an EJB

The following code snippet illustrates how to set the environment for loading an Application Module deployed on Oracle8i as an EJB.

     // Component deployed to Oracle8i as EJB.

     // Set up the 8i environment

      public static void set8iEnv()  {

      env.put(JboContext.INITIAL_CONTEXT_FACTORY, 

              JboContext.JBO_CONTEXT_FACTORY);

      env.put(JboContext.DEPLOY_PLATFORM, JboContext.PLATFORM_EJB);

      env.put(JboContext.SECURITY_PRINCIPAL, "scott");

      env.put(JboContext.SECURITY_CREDENTIALS, "tiger");

      env.put(JboContext.HOST_NAME, "localhost");

      env.put(JboContext.CONNECTION_PORT, "2481");

      env.put(JboContext.ORACLE_SID, "ORA815");

      env.put(JboContext.APPLICATION_PATH, "test");

    }

Setting Environment Variables for Deploying on the Visibroker Platform as a CORBA Server Object

The following code snippet illustrates how to set the environment for loading an Application Module on the Visibroker platform. You provide different values for the connection parameter, depending on whether you are connecting in naming service (remote), use binding, or colocate mode.

Setting the Environment for the Naming Service Mode

  // Component deployed to Visibroker connecting in Naming Service mode

            public static void setRemoteVbEnv()  {

            env.put(JboContext.INITIAL_CONTEXT_FACTORY, 

                     JboContext.JBO_CONTEXT_FACTORY);

            env.put(JboContext.DEPLOY_PLATFORM, JboContext.PLATFORM_VB);

            env.put(JboContext.CONNECTION_MODE,

                     new Integer(ConnectionModeConstants.REMOTE));

            env.put(JboContext.APPLICATION_PATH, "RemoteAlias");

  }

where the RemoteAlias is the named service which is aliased by using the startNamingService.bat file.

Setting the Environment for the Use Binding Mode

// Component deployed to Visibroker connecting in Use Binding mode

             public static void setBindVbEnv()  {

            env.put(JboContext.INITIAL_CONTEXT_FACTORY, 

                    JboContext.JBO_CONTEXT_FACTORY);

            env.put(JboContext.DEPLOY_PLATFORM, JboContext.PLATFORM_VB);

            env.put(JboContext.CONNECTION_MODE,

                    new Integer(ConnectionModeConstants.USE_BIND));

           env.put(JboContext.HOST_NAME, hostName);

  } 

Setting the Environment for the Colocate Mode

// Component deployed to Visibroker connecting  Colocate mode

          public static void setColocatedVbEnv()  {

          env.put(JboContext.INITIAL_CONTEXT_FACTORY, 

                     JboContext.JBO_CONTEXT_FACTORY);

          env.put(JboContext.DEPLOY_PLATFORM, JboContext.PLATFORM_VB);

          env.put(JboContext.CONNECTION_MODE,

                   new Integer(ConnectionModeConstants.COLOCATE));

  }

Loading the Application Module

The following code snippet illustrates creating an initial context for the environment and creating the Application Module d2e.D2eModule in the database. This Application Module was created at design time.

 // Load the Application Module

   ApplicationModule appMod = null;

   try

      {

            Context ic = new InitialContext(env);

            String theAMDefName = "d2e.D2eModule";

            ApplicationModuleHome home = (ApplicationModuleHome)ic.lookup(theAMDefName);

            ApplicationModule appMod = home.create();

            appMod.getTransaction().connect("jdbc:oracle:thin:scott/tiger@pc3:1521:ORCL");

            return appMod;

      }

      catch(Exception e) {

    e.printStackTrace();

   }

 

/

Implementing a Custom Application Module Pool

You can create your own custom implementations of application module pooling by extending the ApplicationPoolImpl class and overriding the methods you need. For example, you can define a class, CustomPool, that ensures that no more than three instances are checked out of the pool at any time. In this case, the definition of the checkout method is overridden to check that no more than three instances are checked out. If more than three are checked out, an exception is thrown.

 1  /**
 2   **  This is a simple application pool class that allows checkout
 3   **  of only three instances.
 4   **/
 5  class CustomPool extends ApplicationPoolImpl 
 6  {
 7  public CustomPool()
 8  {
 9  }

10  /**
11   * Ensures that only three instances are
12   * checked out of the pool. Otherwise, a
13   * RuntimeException is thrown.
14   *
15   * @return oracle.jbo.ApplicationModule
16   */
17  public synchronized ApplicationModule createNewInstance()
18  {
19    // if the instance count > 3 throw an exception
20    int nCount = getInstanceCount();
21    if(nCount > 3)
22    {
23      throw new RuntimeException("You have exceeded the number of
             instances for this pool");
24    }
25    return super.checkout();
26  }

27 }

Line 5: Create a CustomPool class that extends ApplicationPoolImpl.

Lines 17-23: Override the checkout method to test whether more than three instances are checked out. If more than three are checked out, throw a RuntimeException.

Using the custom application module pool Implementation

You can then use the CustomPool class in your programs.

 1 public class PoolTester extends Object {

 2   /**
 3    * Constructor
 4    */
 5   public PoolTester() {
 6   }
 7   public void doTest() throws Exception
 8   {
 9     Hashtable info = new Hashtable();  

10    info.put(JboContext.INITIAL_CONTEXT_FACTORY, JboContext.JBO_CONTEXT_FACTORY);
11    info.put(JboContext.DEPLOY_PLATFORM, "LOCAL");

12    // create a pool with a custom application pool class
13    PoolMgr.getInstance().createPool("CustomTestAMPool", 
       "oracle.jbo.common.ampool.CustomPool" , "package2.Package2Module" ,
       "jdbc:oracle:thin:scott/tiger@localhost:1521:orcl", info);
14    pool = PoolMgr.getInstance().getPool("CustomTestAMPool");

15    try   
16    {
17      instance = pool.checkout();
18      instance = pool.checkout();
19      instance = pool.checkout();

20      instance = pool.checkout();
21      instance = pool.checkout();
22    }
23    catch(Exception ex)  
24     {
25       ex.printStackTrace();       
26     }    
27  }

Lines 9-11: Define the environment settings. This can be done directly (as is demonstrated here) or from a property file. In this example, the hashtable contains the properties to set up the environment to connect in LOCAL mode. For more information about the code you need to supply to set up the environment for LOCAL mode and the other platforms, see Setting up the Environment.

Lines 12-14: Use the CustomPool class to create the pool CustomTestAMPool. Since PoolMgr is a singleton object, use PoolMgr.getInstance to get it. Use createPool to create the pool. Notice that in this case, createPool requires the name of the pool, the name of the class that overrides the default implementation of application module pooling, the name of the package that contains the application module, the connect string to the database, and the name of the hashtable.

Lines 15-25: Set up a try-catch loop to start checking out instances and to catch exceptions. The pool.checkout() in line 20 should cause an exception to be thrown.

---

Related topics
Pooling Application Modules
About Application Module Pooling
About Application Module Pooling Classes