Java connection pooling supports five optional user-defined methods that are called automatically at specified times during the life of the pool. These methods enable you to specify that certain actions be performed at specified times during the connection’s creation and use.
To use the pooling support methods
| 1. | Write Synergy routines that perform the desired tasks. You can have several routines of the same type, if necessary (e.g., two initialization routines for two different pools), and the routines can be named anything you like. See Pooling support methods for the syntax your routine should use, a description of the purpose of each method, and when each method is called. |
| 2. | Add the routines to the SMC by attributing the Synergy code, running dbl2xml, and then importing the XML file. (Or by entering data using the MDU.) If you use the MDU, you do not need to specify an interface name, as these routines will not be included in the generated JAR file. (Because you do not call these methods directly, there is no reason to include them in the JAR file.) However, dbl2xml requires an interface name; we recommend you use a different interface name than is used for your procedural methods to avoid including the pooling support methods when you build the JAR file. |
| 3. | Include the Synergy routines when you build your ELB. You can put them in the same ELB as the other Synergy routines you prepared for remote calling, or you can put them in a separate ELB. |
| 4. | Specify the method ID—not the method name—of each routine in the pooling properties file, using the property that corresponds to the type of routine. See Specifying the pooling support methods to call. |
The methods are described below in the order in which they are called during a connection’s lifetime.
Initialization method
status = initialization_method()
status – a ^VAL value that indicates whether the initialization method was successful. Returns 0 for success or 1 for failure. If the return value is 1, the pool will not be created, xfPoolException will be thrown, and an error will be recorded in the pooling log (assuming logging is turned on).
This method is called each time a new connection is added to the pool. You can use this method to prepare the environment by opening files, initializing global data, and so forth. Because the initialization method is called when the connection is created, it gets called only once per connection, even if the connection is returned to the pool for reuse. Compare with the activation method.
Activation method
activation_method()
The activation method is called when the connection is requested by a client. This method can be used for code that should be executed when the connection is actually used.
Both the activation and the initialization methods can be used for similar purposes—preparing the environment before using the connection. The primary difference between them is that the activation method is called every time the connection is allocated to a client, whereas the initialization method is called only once when the connection is added to the pool. Consequently, to improve performance, it is recommended that you use an initialization method instead of an activation method where possible.
Deactivation method
deactivation_method()
The deactivation method is called when a connection is released. It can be used to reset the environment to a known state before a connection is returned to the pool. Because connections can be reused, this method may be called numerous times. Compare with the cleanup method.
Poolable method
status = poolable_method()
status – a ^VAL value that indicates whether the connection should be discarded or reused. Returns 0 if the connection should be discarded; returns 1 if the connection should be returned to the pool for reuse.
The poolable method is called after the deactivation method and can be used to determine at runtime if a connection should be returned to the pool or discarded. For example, if the deactivation method encounters an error, the poolable method could check how much effort is required to clean up the connection before returning it to the pool. If the effort is excessive, and it would be more efficient to discard the connection and create a new one, the poolable method would return 0. See Reusing or discarding connections for more information on when connections can be reused.
The poolable method overrides the poolReturn setting in the pooling properties file.
cleanup_method()
The cleanup method is called each time a connection is discarded from the pool. This includes when poolReturn is set to false, when the poolable method returns 0, or when any of the following methods in the SWPManager class are called: shutdown(), shutdownInPool(), resetPoolProperties(), returnToMinimum(). The cleanup method can be used to do final cleanup on the connection. If the connection is going to be reused, use the deactivation method instead to perform cleanup-type activities.
The cleanup method is also called when socket communication with the client is unexpectedly lost. When the pool is created, the cleanup method is automatically registered with the XFPL_REGCLEANUP routine on the server. (This routine must be in your SMC; see XFPL_REGCLEANUP.) Then, if there is a fatal error that causes xfServerPlus to lose socket communication with the client, xfServerPlus calls the cleanup routine before shutting down.
