# About Application Module Pooling

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

- reduces the amount of time to obtain server-side resources

- allows a small number of instances to serve a much larger number of requests

- addresses the requirements of web applications that must handle thousands of incoming requests

- lets you preserve session state and provides failover support (new in version 3.2 of Business Components for Java)

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.

Some additional features have been added in version 3.2 of Business Components for Java, as described here.

## 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.

   - If the pool contains an idle instance, the application module pool reuses the instance.

   - If there isn't an idle instance, the application module pool creates one.

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.

- Stateful — In a stateful JSP application, the data tags or data web beans of a JSP application also do not access the same application module instance each time they are invoked. However, unlike stateless applications, Business Components for Java saves the application module state to the database when the application module is released, and allows a view object's rowset to remain the same from one invocation to the next. Stateful mode is the preferred choice because it provides failover support from the database and still allows application modules to be recycled. However, you may need to use the stateless mode when you expect many users to access your JSP application simultaneously. The stateless option may allow more users to access a JSP application simultaneously at the cost of requiring the user to reconnect to a new application module instance every time a JSP page is invoked (or re-invoked).

- Stateless — When you select the stateless option for individual JSP pages or the entire JSP application, the data tags or data web beans do not necessarily access the same application module instance each time a new page is invoked during a specific HTTP session and, therefore, cannot depend on a view object's rowset remaining the same from one invocation to the next. Each HTTP session does not get its own instance for each application module; instead, all HTTP sessions share a limited pool of instances of each application module.

- Reserved — When you select reserved mode for individual JSP pages or the entire JSP application, once a data tag or data web bean has connected to an application module, all subsequent connections to that application module from any data tag or data web bean during the same HTTP session involve the same instance of the application module. This holds true whether a subsequent connection is from another JSP page or from a new invocation of the same JSP page. This mode is similar to the stateful application, but it does not provide failover support nor does it permit application modules to be recycled. Reserved mode is provided primarily for compatibility with application modules that use non-standard JDBC connections.

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.

When using the web application framework, the framework persists information about the state of the application module 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 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:

- Pessimistic locking is not permitted.

- There must not be any uncommitted, posted changes.

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.

## 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.

Related topics
Pooling Application Modules
About Application Module Pooling Classes
About Configuration Properties for a JSP Project