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
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.
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.
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.
In general terms, the application module pooling feature is implemented as follows:
A client sends an HTTP request to a web server.
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.
The web application requests an application module pool from the pool manager. If one has not already been created, it is created.
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.
The web application uses the application module instance to perform the requested service.
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.
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. <<You can use reserved mode to hold pessimistic locks between HTTP requests.>>
Note that the stateful mode of previous releases is now reserved mode. However, old code should be backward compatible.
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-objectspecific 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:
Pessimistic locking is not permitted.
There should not be any uncommitted, posted changes. All changes are preserved, whether they were committed or not. For example, if you called the postChanges method to cause a database trigger to fire but you didn't commit, you could get conflicts when a row is restored because the trigger fires more than once.
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.
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.