About Application Module Pooling

A client can use application module instances from a pool, called application module pooling. It has these advantages:

For example, in the case of a web application, you may have 1,000 users but you know that only 100 will be using a certain application module at one time. So you use an application module pool. When a client needs an application module instance, it takes a free one from the pool and releases it to the pool after either committing or rolling back the transaction. Because the instance is precreated, end users are saved the time it takes to instantiate the application module when they want to perform a task. Typically, web-based JSP clients use pools. If you want to make sure that the application module pool has a maximum of 100 application module instances, you can customize the default application module pool.

One pool manager per Java VM

The framework provides a pool manager to manage the application module pools. There is one pool manager for each web server's Java VM. Application module instances remain in the pool until the Java VM stops running. There is no way to specify maximum number of instances, except in a custom application module pool. The pool manager is defined in the framework class PoolMgr.

One application module pool per application module definition

There is one application module pool per application module definition. For example, for a web server, there is one pool for each type of application module that clients can access.

The following illustration shows how three deployed application modules, TaskApp, StatusApp, and MTBFApp, use application module pooling. TaskApp, StatusApp, and MTBFApp each have their own application module pools. These pools are managed by the pool manager. Each pool manages application module instances. The instances are connected to a database server.

How application module instances are created, assigned, and released

In general terms, the application module pooling feature is implemented as follows:

  1. A client sends an HTTP request to a web server.

  2. If the request requires an application module instance, the web application on the web server first checks if a pool manager has been created. If not, it creates one.

  3. The web application requests an application module pool from the pool manager. If one has not already been created, it is created.

  4. The web application checks out an application module instance from the application module pool.

  5. The web application uses the application module instance to perform the requested service.

  6. The web application releases the application module instance. There are three types of release modes, described later.

    After it is released to the pool, the instance can be reused by other web applications.

Three release modes are provided by the business components framework

The web application framework (including Data Web Beans and JSP tags), provided with Business Components for Java, supports three release modes for application module instances obtained from a pool. You can decide how instances are allocated, whether their state is preserved, and whether there is failover support.

Note that the stateful mode of previous releases is now reserved mode. However, old code should be backward compatible.

The state of application module instances can be preserved

When you use stateful mode, the state of an application module instance is maintained between requests. Your program can maintain a user's data without tying up an application module instance. The state includes the currencies of view objects in the application module, all modified attributes and new rows, and other view-object–specific states that are required to resurrect a view object, including queries, the Where clause, Where clause parameters, and so on.

When using the web application framework, the framework can persist information about the state of the application module by placing a state identifier in a browser cookie. So, a client can still retrieve the state of the application module even after is is checked in. (However, if you want to retrieve the state if the web server's JVM crashes, you need to enable failover support, described later.) For each browser, you can have one state per application module class. You can specify how long a cookie is a valid through a JBO parameter.

For stateful application module check-ins, if failover support has been specified (the default), then the application module state is persisted to a datastore (a file, database, or memory) when the application module is checked into the application module pool. If failover support has not been specified, then application module state is persisted when the application module pool detects that it must recycle that application module instance. The application module pool recycles application module instances when an application module is requested, the application module pool size is greater than the recycle threshold, and there are not any available application module instances in the pool. Unstateful application module check-ins do not cause the application module state to be persisted. The cookie is used to store a unique identifier for the AM state in the client browser. The cookie is only generated if failover support has been specified. The cookie is generated upon stateful application module check-in.

For Java servlets, you use the checkout method. Later, you use the checkinWithSessionState method and the method returns a session ID, which you pass between requests with a browser cookie or URL, for example. When you call checkout again, you supply the session ID, and the state is returned. These methods are always called on the client. See the Javadoc for more information.

When using stateful mode, your program must meet the following conditions:

Note: When your application module state is saved, the data in the cache is saved. If there are changes in the database, there is no guarantee that they will be reflected in your saved data when you check the application module state back out. For example, if the application module was not recycled, the data stays the same. However, if the application module was recycled and then activated through failover, the activation logic reexecutes the view objects, so it may bring in more or less rows than originally seen by the clients due to any database updates that have occurred.


What happens if a user leaves a browser open for a long period of time, such as to get some coffee? Does the the Pool Manager release the application module to the pool?

If the release mode is reserved, the application module is checked into the pool after the HttpSession is timed out by the Web Server. The application module state is not persisted if the session is timed out.

If the release mode is stateful, the application module is released after the page is displayed and the state is persisted immediately, if failover support has been requested.

Application module instances can be failover protected

In case the business logic tier or database becomes inoperable, such as from a power failure, you may want to preserve application module states in the database. To do so, you can enable failover support, which is the default. The disadvantage is that storing data in a database makes business logic tier operation somewhat slower.