This topic includes the following sections:
Using your JAR file with connection pooling
This section contains information that the person using your JAR file for development needs to know. The machine used by the Java developer must be properly configured. (See Setting up your environment for development for details.) The code examples in this section use JSP, since that is the primary use for Java connection pooling.
| 1. | Associate the component with your project |
Before using your JAR file, you’ll need to associate it with your project in your development environment. The method for doing this depends on the environment. See step 1 in Using your JAR file: The basics for details.
| 2. | Import the necessary packages |
The import statement enables you to more easily access the classes in the imported package.
We recommend that you import the Synergex.util package to make it easier to access methods of the SWPManager() class, which are required for pooling. (The example code in this section assumes this package is imported.)
For example:
<%@ page import="Synergex.util.*" %>
| 3. | Create the pool |
The SWPManager.getInstance() method is used to instantiate an instance of the pool at application level. The SWPManager class uses a singleton pattern. This means that there can be only a single instance of the class and that it is global by nature. Consequently, the first time your application calls getInstance(), it will instantiate an instance of the pool. Subsequent calls to getInstance() will get an instance of the pool for use on a particular JSP page.
The getInstance() method uses the settings in the pooling properties file and the xfNetLink Java properties file to instantiate the pool(s) of connections. For JSP, you should put the initial call to getInstance() in your application’s start-up page because the pool creation process may take a few moments. (The minimum number of connections must be created, initialization methods run, cleanup methods registered, etc.)
You can also pass the pooling properties file to use with the getInstance() method. See Synergex.util.SWPManager for an example.
For example:
SWPManager poolMgr = SWPManager.getInstance();
| 4. | Get an instance of the pool |
Once the pool is created, you must get an instance of it in each JSP page that uses connection pooling. As explained above, after the initial call to getInstance(), subsequent calls will get an instance of the pool to use in a particular page.
For example:
SWPManager poolMgr = SWPManager.getInstance();
| 5. | Instantiate an instance of a procedural class |
Use the default constructor to instantiate a new instance of a procedural class in your generated JAR file. (Do not use the “ini file” constructor with pooling.)
For example:
<jsp:useBean id="appLog" scope="session" class="ConsultIt.AppLogin">
| 6. | Indicate that pooling will be used |
Call the usePool() method on your object to indicate that this object will use a connection from the pool. Pass as parameters the ID of the pool that you want to get a connection from and the instance of the pool manager. The pool ID (“custPool” in our example) is defined in the pooling properties file. (See Setting up a pooling properties file.) The usePool() method is one of the public utility methods that is included when you build your JAR file. (See the Method reference.)
For example:
appLog.usePool("custPool", poolMgr);
| 7. | Get a connection, invoke methods in the component, disconnect |
Call the connect() method to get a connection from the pool. You can then make calls to your Synergy methods, and call disconnect() when you are done. This part of your application is coded the same whether you are using pooling or not. You can also use an implied connection or share connections when you are using pooling. See step 5 in Using your JAR file: The basics for more information about the different ways to connect.
For example:
appLog.connect();
String id = new String("MFranklin");
String password = new String("123abc");
appLog.login(id, password);
.
.
.
appLog.disconnect();
Setting up a pooling properties file
The pooling properties file defines settings, such as the size of the pool, used by Java connection pooling. This file is required. If the file is named xfPool.properties and placed in either the Java application directory or in the directory required by your web server and servlet container, you can use the getInstance() method that doesn’t take any parameters; it will use this default file. However, you can choose to name the pooling properties file differently and place it elsewhere and then use one of the getInstance() methods that passes the properties file. See Synergex.util.SWPManager for details on these methods.
There is a sample pooling properties file included in the Examples directory that is part of the xfNetLink Java distribution. You can copy the sample file to the correct location and modify it, or you can create your own text file with the necessary settings to use as a properties file.
The pooling properties file supports multiple pools, each of which is identified by a pool ID. The file must identify at least one, named pool using the syntax
poolID.pool
where poolID is the name of the pool. For example:
orderPool.pool
The pool ID must precede each pool-specific setting in the file. Logging level and log filename are not pool-specific; all pools use a single log file. See Sample pooling properties file.
Why use multiple pools?
By using multiple pools, you can specify that different pooling support methods be called for different objects. You may even have some objects that require no pooling support methods. For example, you might have a customer object and an order object, which require different initialization methods. You can create two pools, custPool and orderPool, and reference the appropriate initialization method ID for each pool. Then, when calling the usePool() method on the customer object, pass the custPool ID; and when calling the usePool() method on the order object, pass the orderPool ID. If you need to retrieve the pool ID, use the getPoolName() method. (See the Method reference.)
Using multiple pools also enables you to have multiple xfNetLink Java properties files with different settings in each file. This will enable you to, for example, run xfServerPlus on more than one port or on different machines.
|
To include comments in the pooling properties file, precede the comment with a number sign (#). |
The table below shows the settings that can be included in the pooling properties file. Each is discussed in more detail in the following pages. With the exception of the two logging settings, each setting in the pooling properties file must be preceded by the pool ID. There is an example in Sample pooling properties file.
|
Setting |
Description |
For more information see |
|---|---|---|
|
minPool |
(required) The minimum number of connections to be maintained in the pool. |
|
|
maxPool |
(required) The maximum number of connections to be maintained in the pool. |
|
|
propertiesFile |
(required) The path and filename of the xfNetLink Java properties file to use. |
|
|
poolReturn |
Boolean value that indicates whether the connection should be discarded or returned to the pool for reuse. |
Specifying whether connections should be returned to the pool |
|
poolLogFile |
Filename that logging information will be written to. |
|
|
poolLogLevel |
Level of logging desired. Possible values are none, error, and all. If poolLogFile is specified and poolLogLevel is not specified, error level logging will take place. |
|
|
connectWaitTimeout |
Number of seconds that the getConnection( ) method will continue checking for a connection from the pool. |
|
|
poolMethodTimeout |
Number of seconds that xfNetLink will wait for a return from a remote call to xfServerPlus when any of the five pooling support methods are called. |
|
|
initializationTimeout |
(Deprecated in 10.1.1c; superseded by poolMethodTimeout) Number of seconds that xfNetLink will wait for a return from a remote call when the pool is being started. This value controls a special call time-out that applies only to the method specified with initializationMethodID. |
|
|
initializationMethodID |
Method ID of the Synergy method that will be called each time a new connection is added to the pool. |
|
|
activationMethodID |
Method ID of the Synergy method that will be called each time getConnection() is called. |
|
|
deactivationMethodID |
Method ID of the Synergy method that will be called each time a connection is freed. |
|
|
poolableMethodID |
Method ID of the Synergy method that will be called after the method specified by deactivationMethodID is called. |
|
|
cleanupMethodID |
Method ID of the Synergy method that will be called each time a connection is discarded (i.e., not returned to the pool for reuse). |
|
You must specify the minimum and maximum size of each pool defined in the pooling properties file. The minPool and maxPool settings are required.
Use minPool to indicate the number of connections you want created at pool start-up. The minimum value for minPool is 1, but we recommend you set it to at least 3 to improve the responsive of your application.
Use maxPool to indicate the maximum number of connections that you want in the pool at any one time. When deciding how large to make the pool, keep in mind how many xfServerPlus licenses you have available and the number of connections in all the pools. The maximum size of all connection pools should not exceed the number of available licenses.
Remember to precede minPool and maxPool with the pool ID. For example:
poolID.minPool=5 poolID.maxPool=20
Specifying the xfNetLink Java properties file to use
When using Java connection pooling, you must use an xfNetLink Java properties file to specify information such as the host name and port. Using the “set” methods that were included when you built your JAR file will have no effect. Use the propertiesFile setting in the pooling properties file to specify the filename and location of the xfNetLink Java properties file you will be using. This setting is required.
When you are using pooling, you can name the properties file anything you like and place it anywhere on the xfNetLink Java machine because the setting in the pooling properties file enables xfNetLink to find it. In addition, you can have more than one properties file (one per pool, if desired), even for a JSP application.
For example:
poolID.propertiesFile=c:\\tomcat\\conf\\poolxfnj.properties
Specifying whether connections should be returned to the pool
When a connection is released, it can be either returned to the pool for reuse or discarded. We recommend returning connections to the pool whenever possible for improved performance. See Reusing or discarding connections for more information on when connections can be reused. Set poolReturn to true to indicate that connections should be returned to the pool. Set poolReturn to false to indicate that they should be discarded.
For example:
poolID.poolReturn=true
If poolReturn is not set, connections will be discarded.
You can also control whether connections are returned to the pool at runtime by writing a “poolable” method and specifying it with the poolableMethodID property. See Specifying the pooling support methods to call and Pooling support methods.
Specifying pool logging options
You can specify that errors and actions related to the creation and maintenance of the pool be logged. All pools use a single log file, so you don’t need to specify the pool ID.
For additional information on pooling logging, including sample log files, see Using pooling logging.
To turn logging on
| 1. | Specify a log filename with the poolLogFile property. For example: |
poolLogFile=c:\\work\\Myfile.log
Myfile.log is created if it does not exist; if the file already exists, additional material is appended to the end. To place the file in a specific location, specify the full path name, using double slashes as shown in the example above. If you do not specify a path, the file is created in the current working directory. Note that a filename is required to turn on pooling logging.
| 2. | Specify a logging level with the poolLogLevel property. The available options are as follows: |
- error. Only errors and exceptions will be logged. This setting is recommended in production environments.
- all. Informational messages, such as those generated when the pool is started, will be logged in addition to errors and exceptions. InUse and inPool counts are also included. This setting is recommended only during development.
- none. No logging will take place. Use this option to turn logging off without removing the logging settings from the pooling properties file.
For example:
poolLogLevel=error
If poolLogFile is specified and poolLogLevel is not specified, error level logging will take place.
Specifying pool time-out values
There are two time-out values that can be specified in the pooling properties file, connectWaitTimeout and poolMethodTimeout.
- The connectWaitTimeout value determines how long the SWPManager.getConnection() method will continue to check for a connection from the pool. If a connection is available, it will return immediately. If no connection is available, getConnection() will check for a free connection every one-tenth of a second for the number of seconds that connectWaitTimeout is set to before returning null. (For example, if connectWaitTimeout is set to 20, getConnection will check every one-tenth of a second for up to 20 seconds.) If connectWaitTimeout is not specified, getConnection() will not wait, and will immediately return null if no connection is available. We recommend you set connectWaitTimeout as there is no default value for this time-out.
- The poolMethodTimeout value determines the call time-out for the five pooling support methods (initialize, activate, deactivate, poolable, cleanup). The default is 60 seconds. We recommend that the poolMethodTimeout value be smaller than connectWaitTimeout (if set). If poolMethodTimeout is larger, the connectWaitTimeout value is used instead.
Note: The poolMethodTimeout setting replaces the deprecated initializationTimeout as of version 10.1.1c. If initializationTimeout is set and poolMethodTimeout is not set, initializationTimeout will be used. If both are set, poolMethodTimeout will be used instead.
To specify time-out values
Specify a value in seconds for connectWaitTimeout and poolMethodTimeout.
For example:
poolID.connectWaitTimeout=60 poolID.poolMethodTimeout=30
Specifying the pooling support methods to call
Java connection pooling supports the use of five pooling support methods. These are Synergy methods that you write, which are then called automatically at certain points during the lifetime of the connection pool. Using the pooling support methods is optional. (See Using the pooling support methodsfor more information on writing the methods.)
To use the pooling support methods, you must specify them by method ID—not method name—in the pooling properties file.
For example:
poolID.initializationMethodID=poolInit poolID.activationMethodID=poolActivate poolID.deactivationMethodID=poolDeactivate poolID.cleanupMethodID=poolClean poolID.poolableMethodID=poolReuse
Sample pooling properties file
The sample pooling properties file below includes logging settings that will be applied to all pools, along with settings for two pools. For “orderPool”, we specified all settings. For “custPool”, we specified only the required settings; default values will be used for all unspecified settings.
# Property settings for all pools poolLogLevel=error poolLogFile=c:\\tomcat\\logs\\Myfile.log # Property settings for order pool orderPool.pool orderPool.minPool=3 orderPool.maxPool=6 orderPool.poolReturn=true orderPool.connectWaitTimeout=45 orderPool.poolMethodTimeout=30 orderPool.propertiesFile=c:\\tomcat\\conf\\poolxfnj.properties orderPool.initializationMethodID=poolInit orderPool.activationMethodID=poolActivate orderPool.deactivationMethodID=poolDeactivate orderPool.cleanupMethodID=poolClean orderPool.poolableMethodID=poolReuse # Property settings for customer pool custPool.pool custPool.minPool=5 custPool.maxPool=10 custPool.propertiesFile=c:\\tomcat\\conf\\poolxfnj.properties
Pool maintenance
The SWPManager class includes several methods that you can use to change the pool configuration: resetPoolProperties(), returnToMinimum(), shutdown(), and shutdownInPool(). We recommend that you write a separate utility method or JSP page that calls these methods and can be accessed by the system administrator.
Updating the properties files
You may need to change settings in the pooling properties file or the xfNetLink Java properties file after the application has been started. Once you have updated the properties file(s), call the resetPoolProperties() method from your administrative page, passing the ID of the pool to update. This method closes down all of the free connections in the specified pool and then restarts the pool with the minimum number of connections. (Connections that are in use will be discarded when they are released, even if poolReturn is set to true.) The new settings in the pooling properties file are read when the pool is restarted, as are the settings in the xfNetLink Java properties file used by that pool. For more information about resetPoolProperties(), see Synergex.util.SWPManager.
Alternatively, you can stop and restart the application to update the properties files. To do this, you have to shut down your web server or servlet container. The new pool will be created using the new values.
Returning the pool to the minimum size
You can call the returnToMinimum() method to return a specific pool to the size specified with minPool, thereby freeing up xfServerPlus licenses so that they can be used by other pools. For example, when poolReturn is set to true, the pool may grow to the maximum size and then, because all connections are being returned to the pool, remain at the maximum. (When poolReturn is set to false, the pool will always be maintained at the minimum size, so calling returnToMinimum() will have no effect.) Rather than including returnToMinimum() in a JSP page that can be accessed by the system administrator, you may want to call it periodically in your application.
For more information about returnToMinimum(), see Synergex.util.SWPManager.
Shutting down the pool
There are two methods that shut down the pool, shutdown() and shutdownInPool(). Call one of these methods when closing down your application.
When the shutdown() method is called, all connections in all pools, as well as all in-use connections, are closed and the pools are destroyed. Deactivation and cleanup methods are called if implemented. You can shut down all pools or you can choose to shut down a specific pool by passing a pool ID as the parameter. The next call to getInstance() will restart the pool(s).
When the shutdownInPool() method is called, all connections in all pools are shut down, but connections that are in use are not terminated until they are released, at which point they are discarded (even if poolReturn is set to true). Deactivation and cleanup methods are called if implemented. You can shut down all pools or you can choose to shut down a specific pool by passing a pool ID as the parameter. The next call to getInstance() will restart the pool(s).
