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, seeSetting up the Environment.

An example implementation of a stateful application

ThePoolTesterclass provides a sample implementation and use of application module pooling inLOCALmode. 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, seeSetting up the Environment.

Line 12:Create the poolTestAMPool. SincePoolMgris a singleton object, usePoolMgr.getInstanceto get it. UsecreatePoolto create the pool. Notice thatcreatePoolrequires the name of the pool, the name of the package that contains the application module, the connect string to the database, andenv, the hashtable. ThecreatePoolmethod 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,SecondAMPoolthat 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 classesApplicationPoolImplandPoolMgrcontain other functions that you can use to traverse the pool content. Theampoolpackage also contains aPoolAdministratorWeb 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:UseremovePoolto remove the application module pool. This function callsremove()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

ThePoolTesterclass provides a sample implementation and use of application module pooling inLOCALmode. 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, seeSetting up the Environment.

Line 12:Create the poolTestAMPool. SincePoolMgris a singleton object, usePoolMgr.getInstanceto get it. UsecreatePoolto create the pool. Notice thatcreatePoolrequires the name of the pool, the name of the package that contains the application module, the connect string to the database, andenv, the hashtable. ThecreatePoolmethod 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,SecondAMPoolthat 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 classesApplicationPoolImplandPoolMgrcontain other functions that you can use to traverse the pool content. Theampoolpackage also contains aPoolAdministratorWeb 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:UseremovePoolto remove the application module pool. This function callsremove()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 Oracle8iCORBA server, the lifetime is until the client callsremoveon 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 Oracle8ias a CORBA server object

o deploying on Oracle8ias 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 theJDBC 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 toOTN'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 Oracle8ias a CORBA Server Object

The following code snippet illustrates how to set the environment for loading an Application Module deployed on Oracle8ias 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 Oracle8ias an EJB

The following code snippet illustrates how to set the environment for loading an Application Module deployed on Oracle8ias 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 theRemoteAliasis the named service which is aliased by using thestartNamingService.batfile.

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 Moduled2e.D2eModulein 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 theApplicationPoolImplclass 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 thecheckoutmethod 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 aCustomPoolclass that extendsApplicationPoolImpl.

Lines 17-23:Override thecheckoutmethod to test whether more than three instances are checked out. If more than three are checked out, throw aRuntimeException.

Using the custom application module pool Implementation

You can then use theCustomPoolclass 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 inLOCALmode. For more information about the code you need to supply to set up the environment forLOCALmode and the other platforms, seeSetting up the Environment.

Lines 12-14:Use theCustomPoolclass to create the poolCustomTestAMPool. SincePoolMgris a singleton object, usePoolMgr.getInstanceto get it. UsecreatePoolto create the pool. Notice that in this case,createPoolrequires 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 atry-catchloop to start checking out instances and to catch exceptions. Thepool.checkout()inline 20should cause an exception to be thrown.

---

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