Chapter 6. DB Connection Pool and JDBC

Table of Contents

6.1. Overview
6.2. Data Sources and JDBC Connection Pooling
6.2.1. JDBC Driver
6.2.2. JDBC Connection Pool
6.2.3. Data Sources
6.2.4. Cluster Data Sources and Recovery Functions
6.3. Management of Data Sources and Connection Pools
6.4. Data Source Configuration
6.4.1. Configuration Method
6.4.2. Connection Pool Configuration
6.5. Cluster Data Source Configuration
6.5.1. Cluster Data Source Configuration
6.5.2. Configuration of the Component Data Source in a Cluster Data Source
6.6. Dynamically Changing Data Source Related Configurations
6.6.1. Adding a Data Source
6.6.2. Registering a Data Source on a Server
6.6.3. Removing a Data Source from a Server
6.6.4. Registering a Data Source in a Cluster
6.6.5. Removing Data Sources from a Cluster
6.6.6. Adding a Server to a Cluster
6.6.7. Removing a Server from a Cluster
6.6.8. Removing a Cluster
6.6.9. Removing a Data Source
6.6.10. Modifying Data Source Configuration
6.6.11. Checking Data Source Configuration
6.7. Dynamically Changing Cluster Data Source Configurations
6.7.1. Adding a Cluster Data Source
6.7.2. Registering a Cluster Data Source to a Server
6.7.3. Removing a Cluster Data Source from the Server
6.7.4. Registering a Data Source to a Cluster
6.7.5. Removing a Cluster from a Cluster Data Source
6.7.6. Adding a Server to a Cluster
6.7.7. Removing a Server from a Cluster
6.7.8. Removing a Cluster
6.7.9. Removing a Cluster Data Source
6.7.10. Changing Cluster Data Source Configurations
6.7.11. Checking the Cluster Data Source Configuration
6.8. JDBC Connection Pool Monitoring
6.8.1. Checking a JDBC Connection Pool List
6.8.2. Checking Detailed JDBC Connection Pool Information
6.9. Controlling the JDBC Connection Pool
6.9.1. Creating a Connection Pool
6.9.2. Disabling a Connection Pool
6.9.3. Enabling a Connection Pool
6.9.4. Replacing a Connection in a Connection Pool
6.9.5. Minimizing the Number of Connections in a Connection Pool
6.10. JEUS JDBC Programming
6.10.1. Getting a Connection from a Data Source
6.10.2. Transaction Programming Rules
6.10.3. Getting a Connection Implementation Instance of the JDBC Driver
6.10.4. Connection Pool in a Standalone Client
6.11. Global Transaction (XA) and Connection Sharing
6.12. Connection Pooling Service Support for Various Users

This chapter describes the basic mechanism of JDBC connection pooling provided by JEUS, how to use the JDBC connection pool, and the data source management method used in the JEUS domain structure.

Web applications usually use a database (DB) to store data. Web application servers (WAS) like JEUS need to communicate with a DB in order to provide database dependent services, such as connection pooling, to applications. The Java Database Connectivity (JDBC) standard defines the interface between the DB clients and DB for an efficient and systematic communication.

The JDBC standard describes how to use DB connections in applications. It also describes how to perform SQL operations and provides related APIs. For more information about the JDBC standard, refer to Sun's JDBC web page (http://www.oracle.com/technetwork/java/javase/tech/index-jsp-136101.html).

JEUS provides connection pooling and other additional services to applications based on JDBC 4.0.

Data source is an object abstracted as a Factory that provides JDBC connections to applications. It internally constructs a JDBC connection pool and provides the connection pooling service.

JDBC connection pooling is a JDBC connection management service. JDBC connection pooling gets and stores a certain number of connections from the DB, and provides them whenever the applications need them. JDBC connection pooling service collects and reuses the connections after use.

Applications do not directly request for a connection to the DB. Instead, they use JNDI lookup to obtain a data source for the DB and requests for a connection through the data source. The data source that received the request sends a connection from its own connection pool to the application. This is how a connection request is processed.

After the application finishes using the connection, JEUS collects the connection and performs the required connection clean up operation. In order to reuse the connection, JEUS puts the connection back into the connection pool and manages it.

The following is the JDBC connection pooling mechanism used on JEUS server.


Note

Instead of creating a connection pool and initializing it at server startup, JEUS creates and initializes a connection pool when a connection request to a data source occurs for the first time in an application.

A data source is an interface between applications and connection pools, and applications view a data source object as a DB Connection Factory.

Data source connections provide more benefits than java.sql.DriverManager connections.

Performance can be enhanced by selecting a data source to use by considering the characteristics and functions of the following data source types.

Data Source Types

There are three types of data sources.

  • Default data source

    javax.sql.DataSource type. This is the default data source type and cannot be used for connection pooling.

  • Connection pool data source

    javax.sql.ConnectionPoolDataSource type. JEUS provides a connection pool for this type.

    It is usually used in the following situations.

    • When creating applications that can access a database without using XA.

    • When configuring auto-commit to "false" and manually controlling a local transaction.

      import java.sql.Connection;
      
      Connection conn = datasource.getConnection();
      conn.setAutoCommit(false);
      ...DB access code... // internally run local transaction of JDBC driver
      conn.commit();
  • XA data source

    javax.sql.XADataSource type. JEUS provides connection pool for this type. It supports connection pooling as well as integration with Global Transactions (hereafter XA).

    It's usually used in the following situations.

    • When a Java EE component logic like servlet/EJB need to access two or more DBs.

    • When related logics need to be tied as a sequence of operations even when a Java EE component accesses a single DB.

XA Emulation of Connection Pool Data Sources

The local transaction optimization function can be used to increase XA processing performance. It emulates the connections obtained from connection pool data sources so that they can participate in XA transactions. This function was provided in JEUS 6 as a separate Local Transaction Data Source. In JEUS 7, Local Transaction Data Source is not defined separately. Instead, JEUS 7 provides an option to set the XA emulation flag configuration in the connection pool data sources. It configures whether to support XA emulation of connection pool data sources.

This function is usually used in the following situations.

  • When the DB doesn't support XA, or the JDBC driver doesn't support the javax.sql.XADataSource implementation.

  • When applications need to use XA, but don't want to use an XA data source due to performance problems (basically, when local transaction optimization is needed).

Currently, DBs or JDBC drivers that do not support XA are almost never used. Therefore, this function will usually be used for transaction optimization, but only one local XA data source can participate per XA transaction. A local XA data source is used in the following situations.

  • When Java EE component logics like servlet/EJB use only one DB which does not require the use of XA data source.

  • When using one of multiple DBs used in the Java EE component to process a local transaction to enhance performance.

Note that when multiple DBs are used, transaction recovery may not be properly executed since the connection pool data source that uses the XA emulation function does not support 2-phase commit (2PC).

Note

The XA emulation of a connection pool data source is viewed as a local transaction with auto commit turned off. From the viewpoint of the DB, this is a different type of transaction than XA transaction that is managed by the JEUS transaction manager. Instead, JEUS uses emulation to allow a local transaction to participate in the XA transaction, so that the application can view the transaction as a single transaction.

A cluster data source is provided to support failover and failback between RAC instances at the JEUS level. RAC (real application cluster) is a DB clustering function provided by Oracle. For more information about RAC, refer to Oracle documentation.

A cluster data source is basically a data source instance with a single JNDI name, and it logically ties multiple individual data sources and manages them. An individual data source (hereafter component data source) that belongs to a cluster data source is also an independent data source with its own individual JNDI name and must be configured as a data source of an RAC instance. A cluster data source operates by delegating connection requests it receives from applications to one of the component data sources. A connection request is delegated only to a component data source that has been verified to process requests successfully. This allows for transparent cluster data source failover in applications.


It is recommended that JEUS cluster data sources be used instead of CTF (connect time failover) provided by Oracle's JDBC driver. Since Oracle CTF performs failover of each connection, recovering all connections in the pool may take a long time when there's a problem with an entire data source. However, JEUS cluster data sources detect problems in each data source and performs failover in data source unit which is more efficient. Furthermore, JEUS cluster data sources provide an automatic failback function.

The methods for using JEUS cluster data sources and using the properties of RAC in Oracle's JDBC drivers are different.

In the first method, since JEUS is responsible for failover, check-query and check-query-period have to be configured in order to check for component data source failure in each RAC instance. However, in the second mechanism, since the driver is responsible for failover, check-query setting is not required. For more information about the cluster data source configuration, refer to "6.5. Cluster Data Source Configuration".

Since JEUS has been expanded to a domain structure, the management structures of data source and connection pools have been partially changed. After understanding the underlying concept of the expanded domain structure, it should not be difficult to grasp the knowledge of the changed data source and connection pool management structures.

The minimum unit for running services on JEUS is the server and depending on the circumstances, services can run on multiple servers grouped into a cluster. Servers and clusters can be grouped into a single management unit called a domain. A domain includes a set of servers and clusters that need to be managed in connection to each other. It manages the servers and clusters in the domain and the Domain Administration Server (DAS) manages all services associated with the domain. Excluding DAS, all servers in the domain are called Managed Servers(MSs).

DAS can function as both DAS and MS simultaneously, but it is recommended to only use MS to provide services and only use DAS to manage the domain. For more information about JEUS domain structure, refer to "JEUS Domain Guide".

Now, let's look into how data sources and connection pools are managed in the domain structure.

By default, a data source is a resource that is exposed to a domain. This means that the servers and clusters in a domain (more accurately, servers in a cluster) reference the exposed data source configurations to create their own connection pool and provide the connection pool service. A cluster is an abstraction of a group of servers, but it isn't the actual subject that provides the services. Data sources which a cluster references are available on the servers in the cluster. Therefore, the servers in the cluster can reference the data sources that are referenced by the cluster. The servers in a cluster can also individually configure data source references. The server can reference the data sources configured both in the cluster and on itself.

In order to reference a data source on a server or cluster, the data source ID must be registered on the server or cluster. Hence, when a server or a cluster registers a data source ID, the server and servers in the cluster read the registered data source configuration and prepare the information needed to create a connection pool. The information is mapped to the JNDI name of the data source and bound to the server's JNDI repository. Once this process is completed, the application deployed on the server can create and use a connection pool by looking up the data source using its JNDI name.

Note

Data sources are bound to JNDI at the server level. The same JNDI names can be used as long as different data sources are not bound to the JNDI on the same server. This means that data sources with the same JNDI names cannot be referenced simultaneously on the same server.

Data sources are distinguished by the data source ID instead of JNDIs because different data sources can have the same JNDI names. Each data source ID must be set to a unique value at the domain level so that it can be used as an identifier.

The following shows a more detailed example of a domain that consists of DAS and three MSs.


In the previous example, MS1 is registering a cluster data source. Since the cluster data source's component data sources are DS1 and DS2, in order for MS1 to fully use the cluster data source, the component data sources (DS1 and DS2) of the cluster data source must be registered to MS1. With this configuration, after creating the connection pool with DS1 and DS2, MS1 can group them into a cluster and provide the cluster connection pool service.

MS2 and MS3 are also in the cluster. DS3 is registered to the cluster, and thus DS3 is available on both MS2 and MS3 which are in the cluster. This means that MS2 and MS3 can each create a DS3 connection pool to provide the connection pool service.

In addition, MS3 registers DS4 to itself. Now, MS3 can provide connection pool service for both DS3 registered to the cluster and DS4 registered to itself.

Each MS runs the data source and connection pool management services at the server level while DAS runs them at the domain level. DAS service is connected to each MS service. It manages all data sources and connection pools, and processes the data source and connection pool requests from the console tool or WebAdmin.

The first thing to do in using data sources and JDBC connection pools in JEUS is to check if the JDBC driver library exists in the '$JEUS_HOME/lib/datasource/' directory, and to configure the required data source settings. Data source configuration includes the basic configuration for JDBC driver and connection pool configurations.

The configurations can be configured in the console tool or WebAdmin. This section only describes the configuration method using WebAdmin. For information about the configuration method using the console tool, refer to JEUS Reference Book. "4.2.10.1. add-data-source".

The following describes how to configure a connection pool in WebAdmin. After completing the basic configuration, click [OK] to check that the data source has been added to the [Database] menu.


Click on the newly added data source ID to return to the basic configuration screen. Click [Connection Pool] tab to go to the connection pool configuration screen.


Additional configurations can be set in the Advanced Options section shown in the following screenshot.


The following describes each configuration item.

  • Pooling

    JDBC connection pool size and related settings.

    ItemDescription
    MinMinimum number of connections in the connection pool.
    MaxMaximum number of connections in the connection pool.
    StepNumber of DB connections to get, if connections are insufficient and the number of connections in the connection pool is smaller than the maximum value.
    PeriodInterval for adjusting the connection pool size based on the minimum value. If the connection pool size is bigger than the minimum value, unused connections are closed. If the size is smaller than the minimum value, new DB connections are added. (Unit: ms)
  • Wait free connection

    Method for handling a connection request when all connections in the connection pool are occupied.

    ItemDescription
    Enable Wait

    Method for handling connection requests, when there are no available connections in the pool and no more connections can be added.

    • true : Wait for an available connection.

    • false : Create a new connection, but it will be discarded without entering the pool after use. This type of connection is called a disposable connection.

    Wait TimeTimeout to wait for a connection if "enable-wait" is "true". If a connection cannot be obtained within the time period, JEUS generates a timeout exception. (Unit: ms)
  • Connection pool

    Add-on functions of the connection pool.

    ItemDescription
    Delegation Datasource

    When a request does not involve a transaction, it is better to get a connection through a connection pool data source instead of an XA data source.

    This is because the XA connection, which involves transaction-related functions, gives more burden on the system, and in this case, the two provide the same functionality. When using the XA data source, specify the connection pool data source to delegate connection requests that are not related to transactions.

    This setting can be used to prevent unexplained exceptions that may occur when Oracle and DB2 use XA connections for both with or without transactions.

    Max Use Count

    Maximum number of times a connection can be used. If a connection is used more than the specified number, the connection will be replaced by a new connection.

    The default value is 0, meaning connections are not replaced.

    Delegation Dba

    JNDI name of the data source (hereafter DBA delegation data source) that has the permission to forcibly terminate database sessions (DBA permission). If there is a delay in handling a query through the connection received from the data source, a query to forcibly terminate the DB session is sent to the DB through the DBA delegation data source. After the application handles exceptions that occurred due to the disabled connection, it closes the connection. Then JEUS deletes the connection and gets a new connection from the DB and puts it in the connection pool.

    Currently, this function is supported for Tibero, Oracle, and Sybase. This function is used to suspend queries that take too long to process for JDBC driver version 2.0 or earlier. For JDBC driver version 3.0 or later, it is recommended to use java.sql.Statement#setQueryTimeout instead of forcibly terminating DB sessions.

    Especially for XA data sources, if DB sessions are terminated while XA is normally processing, the XA operation can generate an error. In this case, the statement query timeout and transaction timeout properties should be used instead.

    Dba TimeoutTimeout for the delegation DBA data source to wait for a query to finish using a connection. If the time expires, it sends a query to the DB to forcibly terminate the DB session. This only applies when the Delegation Dba is set. (Unit: ms)
    Stmt Caching Size

    JDBC driver parses the SQL statements sent as parameters whenever an application requests for a PreparedStatement. Since this can affect the system performance, JEUS provides a function that internally caches the prepared statements. This configuration sets the number of prepared statements to be cached.

    Stmt Fetch SizeFetch size of a JDBC driver statement.
    Use Sql TraceOption to display SQL queries running on each connection. If the jeus.jdbc.sql logger level is set to FINE, the SQL query history can be checked in the server logs. If set, the statement implementation class of the JDBC driver will be wrapped by JEUS class. Therefore, the applications that cast and use the statement objects of the JDBC driver cannot use this function.
    Keep Connection Handle Open

    Option to always keep the connection handle (or logical connection) open when the connection pooling is used.

    [Note]

    1. It is recommended to use this setting when the Universal Driver (JCC) type 4 provided by IBM DB2 is using the XA data source. This is because "hang up" occurs when threads open and close connection handles that are physically different from each other.

      Since the threads internally use and share the same vector (java.util.Vector), when a thread occupies a vector lock and falls into an infinite loop, then other threads are also put in an infinite wait for the lock. The root cause of the hang up is unknown, not the internal logic of DB2. However, according to the test result, no error occurred when the connection handle is always left open. When the connection handle is always left open, the thread only accesses the internal share vector when the connection handle is created for the first time and when the physical connection is closed.

    2. This bug has been fixed for DB2 driver 3.53.95 and later. IBM's official bug report number is 'APAR IZ41181' and can be found in the DB2 9.5 Fixpak 4 document.

    [Caution]

    If set, the connection handle cannot be closed which means that the driver does not clear the task when the connection is closed. For example, when using this setting with Oracle's JDBC driver and auto-commit set to false, if the connection is closed without executing a commit or rollback, then commit, which normally executes automatically, does not execute.

    Init SqlSQL query that is processed first after a connection has been created.
  • Connection trace

    Option to use additional connection-related settings.

    ItemDescription
    EnabledOption to use additional connection-related settings. If this configuration is set to "false", then both 'Get Connection Trace' and 'Auto Commit Trace' settings are invalid.
    Get Connection TraceOption to display the stack trace when the application calls java.sql.DataSource#getConnection.
    Auto Commit TraceOption to record the logs and stack trace to the server log when java.sql.Connection#setAutoCommit is called. The log level of the jeus.jdbc.connection-trace logger must be set to FINE.

This chapter describes how to configure a cluster data source.

The configuration can be set by using the console tool or WebAdmin. This section only describes the configuration method using WebAdmin. For information about the configuration method using the console tool, refer to JEUS Reference Book. "4.2.10.6. add-cluster-data-source".

From the left menu of the WebAdmin home screen, select [Resources] > [Data Source] and click the [Lock & Edit] button to get the lock. Go to the basic cluster data source configuration screen by clicking [Add] from the Cluster DS list.


Additional configurations can be set in the Advanced Options section shown in the following screenshot.


The following describes each configuration item.

  • Basic information

    ItemDescription
    Data Source IdCluster data source ID. It must be unique within the domain.
    Export NameCluster data source JNDI name. If two data sources are guaranteed to be bound to different JNDIs on different servers, they can have the same JNDI name. This means that data sources with the same JNDI names are not allowed on the same server. If not set, the cluster data source ID is used as the JNDI name.
    Data Source Selector

    When getting a connection from a cluster data source, users or developers can define the policy for selecting a component data source.

    Implements the jeus.jdbc.helper.DataSourceSelector interface, and includes the implementation class package name in the class name. If set, the load balance configuration is ignored. The policy should be defined taking synchronization into consideration.

    Load BalanceOption to use load balancing. If set to true, the 'Is Pre Conn' and 'Use Failback' settings are ignored.
    Component Data SourcesData source IDs of the component data sources in the cluster data source.
  • Advanced options

    ItemDescription
    Is Pre ConnOption to create connection pool of component data sources in the cluster data source in advance. Creating the connection pool in advance can be beneficial for performance, but is not a good use of resources.
    Use FailbackSince only failover is supported in the earlier versions of JEUS, this option is provided for backward compatibility. This determines whether to failback using the main data source after failing over by using the assistant data source. By default, failback is used. To use failback, the 'Check Query' and 'Check Query Period' settings must be set for the main data source.

The following is the jeus.jdbc.helper.DataSourceSelector interface specification mentioned in the Data Source Selector configuration. The user can define a policy for selecting a component data source by implementing this interface and configuring the implementation class as a Data Source Selector.


MethodDescription
setComponentDataSourceList()Gets the list of component data source IDs that belong to the cluster data source.
selectDataSourceDefines the policy for selecting a component data source in a cluster data source. The return value is the ID of the data source selected through the defined policy. In most environments, multiple request threads can simultaneously access a connection obtained from a cluster data source. Hence, synchronization should usually be considered when implementing the policy.

The following DataSourceSelector interface can be implemented based on these specifications. This DataSourceSelector implementation has a 2:1 selection ratio for the two data sources in the cluster data source.


A cluster data source delegates the connection request processing to one of its component data sources. If load balancing is not configured, then the cluster data source always delegates connection request processing to the main component data source. However, if an error is detected in the main component data source, then a new component data source is used as the main component data source in order to guarantee uninterrupted processing of connection requests. This is called the cluster data source failover.

To failback after a failover, it must be checked to see if the previous main component data source has been recovered. The check is done using the check queries that are periodically sent to the component data source. In order to use failback in the cluster data source, the 'Check Query' and 'Check Query Period' settings must be configured for each component data source in the cluster. To only use failover, set 'Use Failback' to 'false'. Failover commands can be executed manually. For more information, refer to JEUS Reference Book. "4.2.11.8. control-cluster-data-source".

Note

It is beneficial to set the 'Destroy Policy On Check Query' configuration of the component data source to 'ALL_CONNECTIONS'. Otherwise, inaccessible connections can remain in the connection pool of the faulty component data source for some time after the failover. Although they are cleaned up during periodic connection checks, it is preferable that they are destroyed when failover occurs.

One of the main features of JEUS 7 is that some configurations can be dynamically changed. Dynamically changing a configuration means that changed configurations are immediately applied during runtime without the need to reboot JEUS. For more information about changing configurations dynamically, refer toJEUS Domain Guide. "Chapter 3. Configuring a Domain".

This section shows how to dynamically change data source related configurations through examples. Knowledge about JEUS domain structure and data source management structure in the domain are needed for better understanding. Knowledge about using each configuration item of the data source is also required. For information about JEUS domain configuration, refer to JEUS Domain Guide. "1.3. Composition". For information about the data source management structure in the domain and how to use each configuration item, refer to"6.3. Management of Data Sources and Connection Pools" and "6.4. Data Source Configuration".

Dynamic changes can be applied in the console tool or WebAdmin. Both methods are described in this section. Abbreviated commands and option names are used for describing the console tool method. For more information about how to use abbreviated commands and option names, execute 'help' in the console tool or refer to JEUS Reference Book. "4.2.10. Data Source Commands" and JEUS Reference Book. "4.2.11. Connection Pool Controlling and Monitoring Commands".

First perform some preparation tasks to help with the explanation. Create a domain named domain1 and a DAS named adminServer. After starting DAS, add three MSs named server1, server2, and server3 to domain1 and start them. Then, group server2 and server3 to a cluster named cluster1. For information about configuration methods related to the domain, cluster, and server, refer to JEUS Domain Guide. "Chapter 2. Creating a Domain", JEUS Domain Guide. "Chapter 5. JEUS Clustering", and "Chapter 2. JEUS Configuration". From here on, it is assumed that the aforementioned preparation tasks have been completed.

Note

Since all examples are related to each other, the contents of this section should be read in order.

It is possible to add dynamic data sources. Adding a data source involves registering the data source configuration to the domain so that it can be referenced by the server and cluster in the domain.

Using WebAdmin

The following describes how to add a data source in WebAdmin.

Using the Console Tool

The add-data-source command is used to dynamically add a data source to the domain. Adding a data source by executing add-data-source requires the configuration of each detailed data source properties. For more information about using add-data-source, refer to JEUS Reference Book. "4.2.10.1. add-data-source".

The following is an example of executing add-data-source to enter some required configurations and add a data source with ID ds1 to domain1.

[DAS]domain1.adminServer>addds -id ds1 -dst ConnectionPoolDataSource -dscn
oracle.jdbc.pool.OracleConnectionPoolDataSource -sn 192.168.1.165 -pn 1521 -dn ora10g
-user jeustest1 -password jeustest1 -property driverType;java.lang.String;thin
Successfully performed the ADD operation for data source [ds1] to domain.
Check the results using "add-data-source"

As shown in the previous result message, the result of adding ds1 can be checked by executing add-data-source.

[DAS]domain1.adminServer>addds
Shows the current configuration
Data sources in domain
====================================================================
+------+-----------------------------------------------------------+
| ds1  | common data source                                        |
+------+-----------------------------------------------------------+
====================================================================

For later examples, add two more data sources whose ID are ds2 and ds3 by using the previous method. From here on, it is assumed that ds2 and ds3 have been added to domain1.

Although data sources are added to domains, to actually reference and use data sources on a server, they must be registered on the server. Data sources must be registered on the server to bind their information to the JNDI repository to allow applications deployed on the server to look them up. Data sources can be registered dynamically.

Using WebAdmin

The following describes how to register a data source to a server in WebAdmin.

Using the Console Tool

The add-data-sources-to-server command is used to dynamically add data sources to a server. For more information about using add-data-sources-to-server, refer toJEUS Reference Book. "4.2.3.2. add-data-sources-to-server".

The following is an example of registering ds1 and ds2 on server1 by executing add-data-sources-to-server.

[DAS]domain1.adminServer>adddstosvr -server server1 -ids ds1,ds2
Successfully performed the ADD operation for data sources to the server [server1].
Check the results using "add-data-sources-to-server -server server1"

As shown in the previous result message, the result of registering ds1 and ds2 can be checked by executing 'add-data-sources-to-server -server server1'.

[DAS]domain1.adminServer>adddstosvr -server server1
Shows the current configuration.
Data sources registered in the server [server1].
=========================================================
+--------------------------------------------+----------+
| data sources                               | ds1, ds2 |
+--------------------------------------------+----------+
=========================================================

Execute jndilist to verify that ds1 and ds2 are bound to the JNDI repository of server1. Since a separate JNDI name has been entered for each data source, each data source ID is also used as the JNDI name.

[DAS]domain1.adminServer>jndilist -server server1
The JNDI list on the server1
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| ds1         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| ds2         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                           | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

A data source registered on a server can be removed dynamically. If a data source is removed from a server, the data source information is unbound from JNDI and connection pool, if exists, is destroyed.

Using WebAdmin

The following describes how to remove a data source from a server in WebAdmin.

Using the Console Tool

The remove-data-sources-from-server command is used to dynamically remove a data source from a server. For more information about using remove-data-sources-from-server, refer toJEUS Reference Book. "4.2.3.34. remove-data-sources-from-server".

The following is an example of removing ds2 from server1 by executing remove-data-sources-from-server.

[DAS]domain1.adminServer>rmdsfromsvr -server server1 -ids ds2
Successfully performed the REMOVE operation for data sources from the server [server1].
Check the results using "remove-data-sources-from-server -server server1"

Execute remove-data-sources-from-server -server server1 to verify that ds2 has been removed from server1 and only ds1 remains.

[DAS]domain1.adminServer>rmdsfromsvr -server server1
Shows the current configuration.
Data sources registered in the server [server1].
=============================================================
+---------------------------------------------------+-------+
| data sources                                      | ds1   |
+---------------------------------------------------+-------+
=============================================================

Execute jndilist to verify that ds2 is removed from the JNDI repository of server1 and only ds1 is still bound to JNDI.

[DAS]domain1.adminServer>jndilist -server server1
The JNDI list on the server1
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| ds1         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                           | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

Like registering a data source on a server, a data source can be registered in a cluster. A data source registered in a cluster is valid on all servers in the cluster. Hence, a server in a cluster can use a data source registered in the cluster as if it is registered on the server. As a data source can be registered dynamically on the server, it can also be dynamically registered in a cluster.

Using WebAdmin

The following describes how to register data sources in a cluster in WebAdmin.

Using the Console Tool

The add-data-sources-to-cluster command is used to dynamically add data sources to a cluster. For detailed information about how to use add-data-sources-to-cluster, refer toJEUS Reference Book. "4.2.4.4. add-data-sources-to-cluster".

The following is an example of registering ds2 and ds3 to cluster1 by executing add-data-sources-to-cluster.

[DAS]domain1.adminServer>adddstocluster -cluster cluster1 -ids ds2,ds3
Successfully performed the ADD operation for data sources to the cluster [cluster1].
Check the results using "add-data-sources-to-cluster -cluster cluster1"

As shown in the previous result message, the result of registering ds2 and ds3 to cluster1 can be checked by executing 'add-data-sources-to-cluster -cluster cluster1'.

[DAS]domain1.adminServer>adddstocluster -cluster cluster1
Shows the current configuration.
The data sources registered in the cluster [cluster1].
=========================================================
+--------------------------------------------+----------+
| data sources                               | ds2, ds3 |
+--------------------------------------------+----------+
=========================================================

Now that data sources ds2 and ds3 are registered in cluster1, server2 and server3 in cluster1 can use ds2 and ds3. This means that ds2 and ds3 are JNDI bound to the JNDI repository of server2 and server3. Execute jndilist to verify that ds2 and ds3 are bound to the JNDI repository of server2.

[DAS]domain1.adminServer>jndilist -server server2
The JNDI list on the server2
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| ds2         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| ds3         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                           | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

Execute jndilist again to verify that ds2 and ds3 are bound to the JNDI repository of server3.

[DAS]domain1.adminServer>jndilist -server server3
The JNDI list on the server3
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| ds2         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| ds3         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                           | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

As data sources can be dynamically removed from a server, they can also be dynamically removed from a cluster. If all data sources registered in a cluster are removed, then all servers in the cluster that were using those data sources cannot use them anymore. If a data source is removed from a cluster, the data source information is unbound from JNDI and connection pool, if exists, is also destroyed on each server.

Using WebAdmin

The following describes how to remove a data source from a cluster in WebAdmin.

Using the Console Tool

The remove-data-sources-from-cluster command is used to dynamically remove a data source from a cluster. For more information about how to use remove-data-sources-from-cluster, refer toJEUS Reference Book. "4.2.4.23. remove-data-sources-from-cluster".

The following is an example of removing ds2 from cluster1 by executing remove-data-sources-from-cluster.

[DAS]domain1.adminServer>rmdsfromcluster -cluster cluster1 -ids ds2
Successfully performed the REMOVE operation for data sources from the cluster [cluster1].
Check the results using "remove-data-sources-from-cluster -cluster cluster1"

Execute 'remove-data-sources-from-cluster -cluster cluster1' to verify that ds2 has been removed from cluster1 and only ds3 remains.

[DAS]domain1.adminServer>rmdsfromcluster -cluster cluster1
Shows the current configuration.
The data sources registered in the cluster [cluster1].
=============================================================
+---------------------------------------------------+-------+
| data sources                                      | ds3   |
+---------------------------------------------------+-------+
=============================================================

Now that ds2 is removed from cluster1, server2 and server3 in cluster1 can no longer use ds2. This means that ds2 is unbound from the repository of server2 and server3 and the connection pool for ds2, if exists, is also destroyed.

Execute jndilist to verify that ds2 is removed from the JNDI repository of server2.

[DAS]domain1.adminServer>jndilist -server server2
The JNDI list on the server2
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| ds3         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                           | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

Execute jndilist to verify that ds2 is removed from the JNDI repository of server3.

[DAS]domain1.adminServer>jndilist -server server3
The JNDI list on the server3
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| ds3         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                           | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

A server can be dynamically added to a cluster. This involves modifying both the cluster and server configuration, and data source configuration can also be affected by this.

When a server is dynamically added to a cluster, data sources registered on the cluster is available to the newly added server.

However, any data sources previously registered on the newly added server are unbound from JNDI and their connection pool, if exists, is also destroyed.

Using WebAdmin

The following describes how to add a server to a cluster in WebAdmin.

Using the Console Tool

The add-servers-to-cluster command is used to dynamically add a server to a cluster. For more information about how to use add-servers-to-cluster, refer toJEUS Reference Book. "4.2.4.8. add-servers-to-cluster".

The following is an example of adding server1 to cluster1 by executing add-servers-to-cluster.

[DAS]domain1.adminServer>add-servers-to-cluster cluster1 -servers server1
Successfully performed the ADD operation for The server list for cluster(cluster1)..
Check the results using "list-clusters cluster1 or add-servers-to-cluster cluster1"

As shown in the previous result message, the result of adding server1 to cluser1 can be checked by executing 'list-clusters cluster1' or 'add-servers-to-cluster cluster1'.

[DAS]domain1.adminServer>add-servers-to-cluster cluster1
Shows the current configuration.
The server list for cluster(cluster1).
===================================================================
+-----------------+-----------------------------------------------+
| List of Servers | server2, server3, server1                     |
+-----------------+-----------------------------------------------+
===================================================================

Now that server1 is added to cluster1, server1 can use ds3 registered in cluster1. This means that ds3 is JNDI bound to the JNDI repository of server1. Also, ds1, which was registered on server1, is still valid on server1.

When the JNDI monitoring information for server1 is checked, it can be seen that ds3 and ds1 are JNDI bound.

[DAS]domain1.adminServer>jndilist -server server1
The JNDI list on the server1
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| ds1         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| ds3         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                            | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

A server can be dynamically removed from a cluster. Same as in dynamically adding a server to a cluster, dynamically removing a server from a cluster also involves modifying both the cluster and server configurations. This may also affect data source configurations.

When a server is dynamically removed from a cluster, the data source registered to the cluster is no longer valid on the server that is deleted from the cluster. The server removed from the cluster unbinds all data source information registered to the cluster and connection pool, if exists, is also destroyed.

However, any data sources that were previously registered on the server are JNDI bound and their connection pool, if exists, is recreated.

Using WebAdmin

The following describes how to remove a server from a cluster in WebAdmin.

Using the Console Tool

The remove-servers-from-cluster command is used to dynamically remove a server from a cluster. For more information about how to use remove-servers-from-cluster, refer toJEUS Reference Book. "4.2.4.27. remove-servers-from-cluster".

The following is an example of removing server3 from cluster1 by executing remove-servers-from-cluster.

[DAS]domain1.adminServer>remove-servers-from-cluster cluster1 -servers server3
Successfully performed the REMOVE operation for The server list for cluster(cluster1)..
Check the results using "list-clusters cluster1 or remove-servers-from-cluster cluster1"

As shown in the previous result message, execute 'list-clusters cluster1' or 'remove-servers-from-cluster cluster1'. To verify that server3 has been removed from cluster1.

[DAS]domain1.adminServer>remove-servers-from-cluster cluster1
Shows the current configuration.
The server list for cluster(cluster1).
===========================================================
+-----------------+---------------------------------------+
| List of Servers | server2, server1                      |
+-----------------+---------------------------------------+
===========================================================

Now that server3 is removed from cluster1, server3 can no longer use ds3 registered to cluster1. This means that ds3 is unbound from the JNDI repository of server3 and the connection pool of ds3, if exists, is also destroyed.

Execute jndilist to verify that ds3 is removed from the JNDI repository of server3.

[DAS]domain1.adminServer>jndilist -server server3
The JNDI list on the server3
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                           | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

A cluster can be removed from a domain. This involves modifying both the domain and cluster configuration, and data source configuration can also be affected by this.

When a cluster is removed from the domain, all data sources registered to the cluster are no longer valid on the servers in the cluster. The servers in the removed cluster unbinds all the data source information registered to the cluster and their connection pool, if exists, is also destroyed.

However, any data sources that were previously registered on the servers in the removed cluster are JNDI bound and their connection pool, if exists, is recreated.

Using WebAdmin

The following describes how to remove a cluster in WebAdmin.

Using the Console Tool

The remove-cluster command is used to dynamically remove a cluster from the domain. For more information about how to use remove-cluster, refer toJEUS Reference Book. "4.2.4.20. remove-cluster".

The following is an example of removing cluster1 from domain1 by executing remove-cluster.

[DAS]domain1.adminServer>remove-cluster cluster1
Successfully performed the REMOVE operation for cluster (cluster1).
Check the results using "list-clusters or remove-cluster"

As shown in the previous result message, execute 'list-clusters' or 'remove-cluster' to verify that cluster1 has been removed from domain1.

[DAS]domain1.adminServer>remove-cluster
Shows the current configuration
cluster list
=================================================================
+-------------------------------------------------------+-------+
| List of Clusters                                      | empty |
+-------------------------------------------------------+-------+
=================================================================

Now that cluster1 is removed from domain1, server1 and server2 in cluster1 can no longer use ds3 registered in cluster1. This means that ds3 is unbound from the JNDI repository of server1 and server2 and the connection pool of ds3, if exists, is also destroyed.

Execute jndilist to verify that ds3 is unbound from the JNDI repository of server1 only ds1 remains bound.

[DAS]domain1.adminServer>jndilist -server server1
The JNDI list on the server1
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| ds1         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                           | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

Execute jndilist to verify that no data source is bound to the JNDI repository of server2.

[DAS]domain1.adminServer>jndilist -server server2
The JNDI list on the server2
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                           | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

A data source can be dynamically removed from a domain. When a data source is removed from a domain, the deleted data source is no longer valid on the servers and cluster that were using it. The servers that were using the removed data source unbinds the data source and its connection pool, if exists, is also destroyed.

Using WebAdmin

Since ds1 is currently registered on server1, to remove ds1 from the domain, first the check box for Delete Reference in the WebAdmin configuration menu must be checked. For information about how to adjust the environment configuration menu in WebAdmin, refer toJEUS WebAdmin Guide. "2.3.1. Header".

The following describes how to remove a data source in WebAdmin.

Using the Console Tool

The remove-data-source command is used to dynamically remove a data source from the domain. For more information about remove-data-source refer toJEUS Reference Book. "4.2.10.2. remove-data-source".

The following is an example of removing ds1 from domain1 by executing remove-data-source.

[DAS]domain1.adminServer>rmds -id ds1
Successfully performed the REMOVE operation for data source [ds1] from the domain.
================================================================================
+---------------------------------------------------------+--------+-----------+
| resources.dataSource.database                           | MODIFY | ACTIVATED |
| servers.server.{? name == 'server1' }.dataSources       | MODIFY | ACTIVATED |
+---------------------------------------------------------+--------+-----------+
================================================================================
Check the results using "remove-data-source"

The previous result message shows that executing remove-data-source to delete ds1 has also modified server1 to which ds1 was registered. The result shows that ds1 as well as ds1 information on server1 have been removed from domain1. When a dynamic configuration command is executed in this way, the result shows all related configuration changes that have occurred at runtime due to the command execution. For more information about how to use dynamic configuration commands, refer toJEUS Domain Guide. "Chapter 3. Configuring a Domain".

As shown in the previous result message, the result can be checked by executing remove-data-source without any options.

[DAS]domain1.adminServer>rmds
Shows the current configuration.
Data sources in domain
====================================================================
+------+-----------------------------------------------------------+
| ds2  | common data source                                        |
| ds3  | common data source                                        |
+------+-----------------------------------------------------------+
====================================================================

Now that ds1 is removed from domain1, server1 can no longer use ds1. This means that ds1 is unbound from the JNDI repository of server1 and the connection pool of ds1, if exists, is also destroyed.

Execute jndilist and verify that ds1 is unbound from the JNDI repository of server1.

[DAS]domain1.adminServer>jndilist -server server1
The JNDI list on the server1
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                           | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

So far, we saw how data sources are managed when a data source, server, or cluster is added or removed. This section describes how to modify the data source configuration.

As discussed in"6.4. Data Source Configuration", the data source configuration largely consists of the basic configurations needed for driver set up and the connection pool configuration. The driver set up configurations cannot be changed dynamically, but some basic configurations and most of the connection pool configurations can be changed dynamically. When static configurations are changed they are recorded in the configuration file but not applied to runtime. The server must be restarted to apply the changes to runtime. The dynamic configuration changes are also recorded in the configuration file, and they are applied immediately to runtime.

There are various dynamic data source configurations, and we will look into examples of the minimum and maximum connection value of the connection pool which are expected to change dynamically frequently. The configurations are changed and verified using the data source ds2, and ds2 is registered on server1 and its connection pool is created. The method for registering data sources on the server have already been described. From here on, the method for creating the actual ds2 connection pool on server1 is described.

Using WebAdmin

The following describes how to create a connection pool in WebAdmin.

The minimum connection value is set to 2 and the maximum connection value is set to 30 for the runtime connection pool of ds2. This is the default value when ds2 is initially added to the domain. The following describes the process of changing the minimum and maximum connection values of ds2.

Using the Console Tool

The create-connection-pool command is used to create a connection pool. For more information about create-connection-pool, refer toJEUS Reference Book. "4.2.11.1. create-connection-pool".

The following is an example of creating a connection pool for ds2 by executing create-connection-pool. The result message shows that the connection pool for ds2 has been created on server1.

[DAS]domain1.adminServer>createcp -id ds2
Servers that successfully created a connection pool : server1
Servers that failed to create a connection pool : none.

Execute connection-pool-info to check the minimum and maximum connection values of the runtime connection pool. For more information about this command, refer to JEUS Reference Book. "4.2.11.7. connection-pool-info".

The following is an example of checking the minimum and maximum connection values of the ds2 runtime connection pool created on server1 by executing connection-pool-info.

[DAS]domain1.adminServer>cpinfo -server server1
The connection pool information on the server [server1].
================================================================================
+---------------+-----+-----+--------+------+----------+-------+-------+-------+
|   Connection  | Min | Max | Active | Idle |Disposable| Total |  Wait |Enabled|
|    Pool ID    |     |     |        |      |          |       |       |       |
+---------------+-----+-----+--------+------+----------+-------+-------+-------+
| ds2           |   2 |  30 |      0 |    2 |        0 |     2 | false | true  |
+---------------+-----+-----+--------+------+----------+-------+-------+-------+
* : has not been created, total = active + idle + disposable
================================================================================

As shown in the previous example, the minimum and maximum connection values of the ds2 runtime connection pool are configured to 2 and 30 respectively. These are the default values set when ds2 is initially added to the domain.

The following describes how to change the minimum and maximum connection values of ds2.

Execute modify-data-source to dynamically change the data source configurations. All configurations that can be changed with modify-data-source can be checked by executing 'help' or referring to JEUS Reference Book. "4.2.10.3. modify-data-source". Dynamic configurations and related options are tagged to show which ones are dynamic configurations.

The following is an example of changing ds2's minimum and maximum connection values to 10 and 50 by executing modify-data-source.

[DAS]domain1.adminServer>modifyds -id ds2 -min 10 -max 50
Successfully performed the MODIFY operation for configuration of the data source [ds2].
Check the results using "modify-data-source -id ds2"

As shown in the previous result message, the result can be checked by executing 'modify-data-source -id ds2'.

[DAS]domain1.adminServer>modifyds -id ds2
Shows the current configuration.
configuration of the data source [ds2]
================================================================================
+----------------------------+-------------------------------------------------+
| id                         | ds2                                             |
| export-name                | ds2                                             |
| data-source-class-name     | oracle.jdbc.pool.OracleConnectionPoolDataSource |
| data-source-type           | ConnectionPoolDataSource                        |
| server-name                | 192.168.1.165                                   |
| port-number                | 1521                                            |
| database-name              | ora10g                                          |
| user                       | jeustest1                                       |
| password                   | jeustest1                                       |
| login-timeout              | 0                                               |
| auto-commit                | DRIVER                                          |
| stmt-query-timeout         | 0                                               |
| pool-destroy-timeout       | 10000                                           |
| property                   | driverType;java.lang.String;thin                |
| support-xa-emulation       | false                                           |
| min                        | 10                                              |
| max                        | 50                                              |
| step                       | 1                                               |
| period                     | 3600000                                         |
| enable-wait                | false                                           |
| wait-time                  | 10000                                           |
| max-use-count              | 0                                               |
| dbaTimeout                 | -1                                              |
| stmt-caching-size          | -1                                              |
| stmt-fetch-size            | -1                                              |
| connection-trace           | false                                           |
| get-connection-trace       | true                                            |
| auto-commit-trace          | false                                           |
| use-sql-trace              | false                                           |
| keep-connection-handle-open| false                                           |
+----------------------------+-------------------------------------------------+
================================================================================

The following is an example of checking the minimum and maximum connection values of the ds2 runtime connection pool created on server1 by executing connection-pool-info. The minimum and maximum connection values of ds2 runtime have been changed to 10 and 50 respectively.

[DAS]domain1.adminServer>cpinfo -server server1
The connection pool information on the server [server1].
================================================================================
+---------------+-----+-----+--------+------+----------+-------+-------+-------+
|   Connection  | Min | Max | Active | Idle |Disposable| Total |  Wait |Enabled|
|    Pool ID    |     |     |        |      |          |       |       |       |
+---------------+-----+-----+--------+------+----------+-------+-------+-------+
| ds2           |  10 |  50 |      0 |   10 |        0 |    10 | false | true  |
+---------------+-----+-----+--------+------+----------+-------+-------+-------+

* : has not been created, total = active + idle + disposable
================================================================================

Starting from JEUS 7, JEUS is no longer responsible for any direct modifications to the configuration file made by the user. Opening the configuration file and checking the configuration is not relevant to this, but it is recommended that the configuration file is not accessed by the user. Instead, use the command that is provided for checking the data source configurations.

Using WebAdmin

The following describes how to check the data source configurations in WebAdmin.

Using the Console Tool

The list-data-sources command is used to check the list of all data sources that exist in the domain.

The following is an example of checking the data sources in the domain by executing list-data-sources.

[DAS]domain1.adminServer>lsds
The list of data sources
================================================================================
+----------------+----------------------+--------------------------------------+
| Data Source ID |   JNDI Export Name   |           Data Source Type           |
+----------------+----------------------+--------------------------------------+
| ds2            | ds2                  | ConnectionPoolDataSource             |
| ds3            | ds3                  | ConnectionPoolDataSource             |
+----------------+----------------------+--------------------------------------+
================================================================================

If a data source ID is given as an option, data source configuration details are displayed.

The following is an example of checking the detailed configuration of ds2 by executing list-data-sources.

[DAS]domain1.adminServer>lsds -id ds2
The configuration of the data source [ds2]
================================================================================
+----------------------------+-------------------------------------------------+
|     Configuration name     |               Configuration value               |
+----------------------------+-------------------------------------------------+
| id                         | ds2                                             |
| export-name                | ds2                                             |
| data-source-class-name     | oracle.jdbc.pool.OracleConnectionPoolDataSource |
| data-source-type           | ConnectionPoolDataSource                        |
| server-name                | 192.168.1.165                                   |
| port-number                |                                            1521 |
| database-name              | ora10g                                          |
| user                       | jeustest1                                       |
| password                   | jeustest1                                       |
| login-timeout              |                                               0 |
| auto-commit                | DRIVER                                          |
| stmt-query-timeout         |                                               0 |
| pool-destroy-timeout       |                                           10000 |
| property                   | [driverType;java.lang.String;thin]              |
| support-xa-emulation       | false                                           |
| min                        |                                              10 |
| max                        |                                              50 |
| step                       |                                               1 |
| period                     |                                         3600000 |
| enable-wait                | false                                           |
| wait-time                  |                                           10000 |
| max-use-count              |                                               0 |
| dbaTimeout                 |                                              -1 |
| stmt-caching-size          |                                              -1 |
| stmt-fetch-size            |                                              -1 |
| connection-trace           | false                                           |
| get-connection-trace       | true                                            |
| auto-commit-trace          | false                                           |
| use-sql-trace              | false                                           |
| keep-connection-handle-open| false                                           |
+----------------------------+-------------------------------------------------+
================================================================================

By using examples, this section describes how to dynamically change the configurations related to cluster data sources. For better understanding, knowledge about JEUS domain structure and data source management structure in the domain are required. Knowledge about using each configuration item of the cluster data source is also required.

For information about JEUS domain structure, refer to JEUS Domain Guide. "1.3. Composition". For information about the data source management structure in the domain and how to use each configuration item, refer to "6.3. Management of Data Sources and Connection Pools" and "6.5. Cluster Data Source Configuration".

Dynamic changes can be applied in the console tool or WebAdmin. Both methods are described in this section. Abbreviated commands and option names are used for describing the console tool method. For more information about how to use abbreviated commands and option names, execute 'help' in the console tool or refer to JEUS Reference Book. "4.2.11. Connection Pool Controlling and Monitoring Commands".

First perform some preparation tasks to help with the explanation. Create a domain named domain1 and a DAS named adminServer. After starting DAS, add three MSs named server1, server2, and server3 to domain1 and start them. Then, group server2 and server3 to a cluster named cluster1. For information about configuration methods related to the domain, cluster, and server, refer to JEUS Domain Guide. "Chapter 2. Creating a Domain", JEUS Domain Guide. "Chapter 5. JEUS Clustering", and "Chapter 2. JEUS Configuration". From here on, it is assumed that the aforementioned preparation tasks have been completed.

Note

Since all examples are related to each other, the contents of this section should be read in order.

Like other data sources, a cluster data source can also be added dynamically. Always keep in mind that when a cluster data source is added, the component data sources in the cluster data source must also be added.

This section describes an example of adding a cluster data source made up of data sources ds1 and ds2 to domain1. The cluster data source ID is cds1.

Using WebAdmin

The data sources ds1 and ds2 which are the component data sources of cds1 have to be added to domain1. For information about how to add a data source to the domain in WebAdmin, refer to "6.6.1. Adding a Data Source". From here on, it is assumed that ds1 and ds2 have been added to domain1.

Using the Console Tool

The data sources ds1 and ds2 that are the component data source of cds1 must be added to domain1.

The following is an example of adding ds1 and ds2 to domain1 by executing add-data-source. For more information about using add-data-source, refer to JEUS Reference Book. "4.2.10.1. add-data-source".

[DAS]domain1.adminServer>addds -id ds1 -dst ConnectionPoolDataSource -dscn oracle.jdbc.pool.OracleConnectionPoolDataSource -sn 192.168.1.165 -pn 1521 -dn ora10g -user jeustest1 -password jeustest1 -property driverType;java.lang.String;thin
Successfully performed the ADD operation for data source [ds1] to domain.
Check the results using "add-data-source"

[DAS]domain1.adminServer>addds -id ds2 -dst ConnectionPoolDataSource -dscn oracle.jdbc.pool.OracleConnectionPoolDataSource -sn 192.168.1.165 -pn 1521 -dn ora10g -user jeustest1 -password jeustest1 -property driverType;java.lang.String;thin
Successfully performed the ADD operation for data source [ds2] to domain.
Check the results using "add-data-source"

After adding ds1 and ds2 to domain1, add cds1 to domain1.

Execute add-cluster-data-source to dynamically add a cluster data source. For more information about using add-cluster-data-source, refer to JEUS Reference Book. "4.2.10.6. add-cluster-data-source". Option values corresponding to each cluster data source configuration items must be given with the command.

The following is an example of entering some required configurations by executing add-cluster-data-source and adding the cluster data source cds1 to domain1.

[DAS]domain1.adminServer>addcds -id cds1 -cds ds1,ds2
Successfully performed the ADD operation for cluster data source [cds1] to domain.
Check the results using "add-cluster-data-source"

As shown in the previous result message, the result of adding cds1 can be checked by executing add-cluster-data-source without any options.

[DAS]domain1.adminServer>addcds
Shows the current configuration.
Data sources in domain
====================================================================
+------+-----------------------------------------------------------+
| ds1  | common data source                                        |
| ds2  | common data source                                        |
| cds1 | cluster data source                                       |
+------+-----------------------------------------------------------+
====================================================================

To use a cluster data source, it must be registered to a server like other data sources. Only when a cluster data source is registered on a server, the cluster data source information is bound to the JNDI repository of the server. After this, deployed applications can look up the cluster data source, but the component data sources grouped into the cluster data source must be registered on the server.

Each component data source provides the connection pool service, and their connection pool is created on the server. To use the cluster data sources as desired, the component data sources in the cluster data source must be registered on the server where the cluster data source is registered on.

This section describes how to register cds1 to server1.

Using WebAdmin

The component data sources ds1 and ds2 of cds1 must also be registered on server1. For information on registering a data source to a server in WebAdmin, refer to"6.6.2. Registering a Data Source on a Server". Hereafter, it is assumed that ds1 and ds2 are registered on server1.

Using the Console Tool

The component data sources ds1 and ds2 of cds1 must also be registered on server1.

The following is an example of registering ds1, ds2, and cds1 on server1 by executing add-data-sources-to-server. For more information about how to use add-data-sources-to-server, refer to JEUS Reference Book. "4.2.3.2. add-data-sources-to-server".

[DAS]domain1.adminServer>adddstosvr -server server1 -ids ds1,ds2,cds1
Successfully performed the ADD operation for data sources to the server [server1].
Check the results using "add-data-sources-to-server -server server1"

As shown in the previous result message, the result of registering ds1,ds2, and cds2 can be checked by executing 'add-data-sources-to-server -server server1'.

[DAS]domain1.adminServer>adddstosvr -server server1
Shows the current configuration.
Data sources registered in the server [server1].
==========================================================
+--------------+-----------------------------------------+
| data sources | ds1, ds2, cds1                          |
+--------------+-----------------------------------------+
==========================================================

Execute jndilist to verify that ds1, ds2, and cds1 are bound to the JNDI repository of server1.

[DAS]domain1.adminServer>jndilist -server server1
The JNDI list on the server1
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| cds1        | jeus.jdbc.info.JDBCBindInfo                    | true          |
| ds1         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| ds2         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                           | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

Cluster data sources registered on the server can also be dynamically removed from the server like other data sources.

Like other data sources, when a cluster data source is removed from the server, the cluster data source information is unbound from JNDI. Cluster data source does not have its own connection pool, and the actual connection pool is created in the component data sources in the cluster data source. Therefore, when a cluster data source is removed from a server, unlike other data sources, the 'destroy' command does not execute for the connection pool. Although it may be assumed that the connection pool of the component data sources in the cluster data source will be destroyed, since each component data source can function as an independent data source, it is neither unbound from JNDI nor destroyed.

Using WebAdmin

The following describes how to remove a cluster data source from a server in WebAdmin.

Using the Console Tool

The remove-data-sources-from-server command is used to dynamically remove a cluster data source from the server. For more information about how to use remove-data-sources-from-server, refer to JEUS Reference Book. "4.2.3.34. remove-data-sources-from-server".

The following is an example of removing cds1 from server1 by executing remove-data-sources-from-server.

[DAS]domain1.adminServer>rmdsfromsvr -server server1 -ids cds1
Successfully performed the REMOVE operation for data sources from the server [server1].
Check the results using "remove-data-sources-from-server -server server1"

As shown in the previous result message, the result of removing cds1 from server1 can be checked by executing 'remove-data-sources-from-server -server server1'.

[DAS]domain1.adminServer>rmdsfromsvr -server server1
Shows the current configuration.
Data sources registered in the server [server1].
=========================================================
+--------------------------------------------+----------+
| data sources                               | ds1, ds2 |
+--------------------------------------------+----------+
=========================================================

It shows that cds1 has been removed, and ds1 and ds2 still remain registered.

Execute jndilist to verify that cds1 has been unbound from the JNDI repository of server1.

[DAS]domain1.adminServer>jndilist -server server1
The JNDI list on the server1
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| ds1         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| ds2         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                           | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

Cluster data sources can be dynamically registered to a cluster like other data sources. Cluster data sources registered to a cluster are valid on all servers in the cluster. Therefore, servers in a cluster can use the cluster data source registered on the cluster as if it was registered on each server. Like registering a cluster data source to a server, the component data sources in the cluster data source must be registered with the cluster data source to a cluster.

This section describes the process of registering cds1 to cluster1.

Using WebAdmin

The component data sources ds1 and ds2 of cds1 must also be registered to cluster1. For more information about how to register a data source to a cluster in WebAdmin, refer to "6.6.4. Registering a Data Source in a Cluster". From here on, it is assumed that ds1 and ds2 are registered to cluster1.

The following describes how to register a cluster data source in WebAdmin.

Using the Console Tool

The component data sources ds1 and ds2 of cds1 must also be registered to cluster1.

The following is an example of registering ds1, ds2, and cds1 to cluster1 by executing add-data-sources-to-cluster in the console tool. For more information about how to use add-data-sources-to-cluster, refer toJEUS Reference Book. "4.2.4.4. add-data-sources-to-cluster".

[DAS]domain1.adminServer>adddstocluster -cluster cluster1 -ids ds1,ds2,cds1
Successfully performed the ADD operation for data sources to the cluster [cluster1].
Check the results using "add-data-sources-to-cluster -cluster cluster1"

As shown in the previous result message, the result of registering ds1,ds2, and cds2 can be checked by executing 'add-data-sources-to-cluster -cluster cluster1'.

[DAS]domain1.adminServer>adddstocluster -cluster cluster1
Shows the current configuration.
The data sources registered in the cluster [cluster1].
==========================================================
+--------------+-----------------------------------------+
| data sources | ds1, ds2, cds1                          |
+--------------+-----------------------------------------+
==========================================================

Now that ds1, ds2, and cds1 are registered to cluster1, they can be used by server1 and server2 in cluster1.

Execute jndilist to verify that ds1, ds2, and cds1 are bound to the JNDI repository of server2.

[DAS]domain1.adminServer>jndilist -server server2
The JNDI list on the server2
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| cds1        | jeus.jdbc.info.JDBCBindInfo                    | true          |
| ds1         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| ds2         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                           | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

Cluster data sources registered to a cluster can also be dynamically removed from the cluster like other data sources. When a cluster data source registered to a cluster is removed, all the servers in the cluster that were using it cannot use the cluster data source anymore. Therefore, when a cluster data source is removed from the cluster, the servers in the cluster unbind the cluster data source information from JNDI. However, as when cluster data sources are removed from the server, "connection pool destroy" does execute on the component data sources.

Using WebAdmin

The following describes how to remove a cluster data source from a cluster in WebAdmin.

Using the Console Tool

The remove-data-sources-from-cluster command is used to dynamically remove a cluster data source from a cluster. For more information about how to use remove-data-sources-from-cluster, refer to JEUS Reference Book. "4.2.4.23. remove-data-sources-from-cluster".

The following is an example of removing cds1 from cluster1 by executing remove-data-sources-from-cluster.

[DAS]domain1.adminServer>rmdsfromcluster -cluster cluster1 -ids cds1
Successfully performed the REMOVE operation for data sources from the cluster [cluster1].
Check the results using "remove-data-sources-from-cluster -cluster cluster1"

As shown in the previous result message, the result of removing cds1 from cluster1 can be checked by executing 'remove-data-sources-from-cluster -cluster cluster1'. The result also shows that ds1 and ds2 still bound to cluster1.

[DAS]domain1.adminServer>rmdsfromcluster -cluster cluster1
Shows the current configuration.
The data sources registered in the cluster [cluster1].
=========================================================
+--------------------------------------------+----------+
| data sources                               | ds1, ds2 |
+--------------------------------------------+----------+
=========================================================

Now that cluster data source cds1 is removed from cluster1, server2 and server3 in cluster1 can no longer use cds1. This means that cds1 is unbound from the JNDI repository of server2 and server3.

Execute jndilist to verify that cds1 has been unbound from the JNDI repository of server2.

[DAS]domain1.adminServer>jndilist -server server2
The JNDI list on the server2
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| ds1         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| ds2         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                           | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

Cluster data sources can be dynamically deleted from the domain like other data sources. When a cluster data source is deleted from the domain, it is no longer valid on the server and cluster that were using it. Hence, the servers that were using the deleted cluster data source unbind the cluster data source information from JNDI.

To check how the cluster data source registered on the server and cluster is processed when removing a cluster data source, cds1 is registered on server1 and cluster1. From here on, it is assumed that cds1 is registered on server1 and cluster1.

This section describes the process of removing cds1 from domain1.

Using WebAdmin

Since cds1 is registered on cluster1 and server2, to delete cds1 from a domain, go to the environment configuration menu of WebAdmin and check the Delete Reference check box. For information about using the environment configuration menu, refer to JEUS WebAdmin Guide. "2.3.1. Header".

The following describes how to delete a cluster data source in WebAdmin. This is an example of removing cds1 from the domain.

Using the Console Tool

The remove-cluster-data-source command is used to dynamically delete a cluster data source from the domain. For more information about remove-cluster-data-source, refer to JEUS Reference Book. "4.2.10.7. remove-cluster-data-source".

The following is an example of removing cds1 from domain1 by executing remove-cluster-data-source.

[DAS]domain1.adminServer>rmcds -id cds1
Successfully performed the REMOVE operation for cluster data source [cds1] from domain.
================================================================================
+---------------------------------------------------------+--------+-----------+
| resources.dataSource.clusterDs                          | MODIFY | ACTIVATED |
| servers.server.{? name == 'server1' }.dataSources       | MODIFY | ACTIVATED |
| clusters.cluster.{? name == 'cluster1' }.dataSources    | MODIFY | ACTIVATED |
+---------------------------------------------------------+--------+-----------+
================================================================================
Check the results using "remove-cluster-data-source"

As shown in the previous result message, removing cds1 by executing remove-cluster-data-source also affects server1 and cluster1 where cds1 is registered to. The result displays that when cds1 is removed from domain1, the cds1 information registered on server1 and cluster1 are also deleted.

When executing a dynamic configuration command, you can check for all other runtime configuration changes that occurred from it. For more information about how to use the dynamic configuration command, refer to JEUS Domain Guide. "Chapter 3. Configuring a Domain".

As shown in the previous result message, execute remove-cluster-data-source to verify that cds1 has been removed.

[DAS]domain1.adminServer>rmcds
Shows the current configuration.
Data sources in domain
====================================================================
+------+-----------------------------------------------------------+
| ds1  | common data source                                        |
| ds2  | common data source                                        |
+------+-----------------------------------------------------------+
====================================================================

Now that cds1 is deleted from domain1, server1, where cds1 is registered and used, and server2 and server3, which were able to use cds1 that is registered to cluster1, cannot use cds1 anymore. This means that cds1 is unbound from the repository of server1, server2, and server3. Execute jndilist to verify that cd1 is unbound from the JNDI repository of server1.

[DAS]domain1.adminServer>jndilist -server server1
The JNDI list on the server1
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| ds1         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| ds2         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                           | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

Execute jndilist to verify that cds is unbound from JNDI repository of server2.

[DAS]domain1.adminServer>jndilist -server server2
The JNDI list on the server2
List of the context /
================================================================================
+-------------+------------------------------------------------+---------------+
|     Name    |                      Value                     | Local Binding |
+-------------+------------------------------------------------+---------------+
| ds1         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| ds2         | jeus.jdbc.info.JDBCBindInfo                    | true          |
| JEUSMQ_DLQ  | jeus.jms.common.destination.JeusQueue          | false         |
| mgmt        | jeus.jndi.JNSContext                           | false         |
+-------------+------------------------------------------------+---------------+
================================================================================

Up to this point, we examined how data sources are managed when cluster data sources, servers, and clusters are added/deleted. This section will show how to change the configuration of a cluster data source. It is possible to dynamically change the configurations of a cluster data source. We will look into an example of changing the component data source of a cluster data source.

Since currently there is no cluster data source in the domain, first add cds1 with ds1 and ds2 as the component data source1 to domain1 by executing add-cluster-data-source. From here on, it is assumed that cds1, which has ds1 and ds2 as its component data sources, has been added to domain1.

This section describes the process of removing ds2 from cds1.

Using WebAdmin

The following describes how to change the cluster data source configuration in WebAdmin.

Using the Console Tool

The modify-cluster-data-source command is used to change the cluster data source configuration.

Use the 'help' command or refer to JEUS Reference Book. "4.2.10.8. modify-cluster-data-source" to look up all configurations that can be modified with the modify-cluster-data-source command by using the option name. Dynamic configurations and related options are tagged to show which ones are dynamic configurations.

The following is an example of removing ds2 from the component data source list of cds1 by executing modify-cluster-data-source.

[DAS]domain1.adminServer>modifycds -id cds1 -cds ds1
Successfully performed the MODIFY operation for configuration of the cluster data source [cds1].
Check the results using "modify-cluster-data-source -id cds1"

The result of removing ds2 from the cds1 component data source list can be verified by executing 'modify-cluster-data-source-id cds1' with other option values.

[DAS]domain1.adminServer>modifycds -id cds1
Shows the current configuration.
configuration of the cluster data source [cds1]
=====================================================================
+-----------------------------------------------------------+-------+
| id                                                        | cds1  |
| export-name                                               | cds1  |
| load-balance                                              | false |
| is-pre-conn                                               | false |
| use-failback                                              | true  |
| component-data-sources                                    | ds1   |
+-----------------------------------------------------------+-------+
=====================================================================

Starting from JEUS 7, JEUS is no longer responsible for any direct modifications to the configuration file made by the user. Opening the configuration file and checking the configuration is not relevant to this, but it is recommended that the configuration file is not accessed by the user. Instead, a command is provided to use for checking the cluster data source configurations.

Using WebAdmin

The following describes how to check the cluster data source configuration in WebAdmin.

Using the Console Tool

The list-cluster-data-sources command is used to view the list of all cluster data sources in the domain.

The following is an example of checking the list of all cluster data sources in the domain by executing list-cluster-data-sources.

[DAS]domain1.adminServer>lscds
The list of cluster data sources
================================================================================
+--------------------+-----------------------+---------------------------------+
|   Data Source ID   |    JNDI Export Name   |      Component Data Sources     |
+--------------------+-----------------------+---------------------------------+
| cds1               | cds1                  | [ds1]                           |
+--------------------+-----------------------+---------------------------------+
================================================================================

If a cluster data source ID is given as an option, cluster data source configuration details are displayed. The following is an example of checking the configuration details of cds1 by executing list-cluster-data-sources.

[DAS]domain1.adminServer>lscds -id cds1
The configuration of cluster data source [cds1]
================================================================================
+------------------------------------------+-----------------------------------+
|            Configuration Name            |        Configuration Value        |
+------------------------------------------+-----------------------------------+
| id                                       | cds1                              |
| export-name                              | cds1                              |
| load-balance                             | false                             |
| is-pre-conn                              | false                             |
| use-failback                             | true                              |
| component-data-sources                   | [ds1]                             |
+------------------------------------------+-----------------------------------+
================================================================================

This section describes how to monitor connection pools on a server by using examples. For better understanding, knowledge about JEUS domain structure, and data source and connection pool management structure in the domain are required. For information about JEUS domain structure, refer to JEUS Domain Guide. "1.3. Composition", and for information about the management structure of data sources and connection pool, refer to "6.3. Management of Data Sources and Connection Pools".

The JDBC connection pool can be monitored by using the console tool or WebAdmin. Both methods are described in this section. Abbreviated commands and option names are used for describing the console tool method. For information about abbreviated commands, option names, and command usage descriptions, execute 'help' with the command name as an argument, or refer to JEUS Reference Book. "4.2.11. Connection Pool Controlling and Monitoring Commands".

First perform some preparation tasks to help with the explanation. Create a domain named domain1 and a DAS named adminServer. After starting DAS, add two MSs named server1 and server2 to domain1 and start them. Then, add the data sources ds1 and ds2 to domain1. Register both ds1 and ds2 on server1, and only ds1 on server2. Lastly, create a connection pool for ds1 on both server1 and server2.

For information about domain and server related configurations, refer to JEUS Domain Guide. "Chapter 2. Creating a Domain" and "Chapter 2. JEUS Configuration", and for the data source related configurations, refer to "6.6. Dynamically Changing Data Source Related Configurations". For description about how to create a connection pool, refer to "6.9. Controlling the JDBC Connection Pool". From here on, it is assumed that the aforementioned preparation tasks have been completed.

Note

The server is the final target where data sources are registered on. The data sources registered to the cluster as well as directly on the server affect the server. A cluster is just a logical group of servers, and the server is the one that actually uses a data source to create and use a connection pool. For this reason, the server is the monitoring unit for the connection pool.

This section describes how to check the JDBC connection pool list by using the console tool and WebAdmin.

Using WebAdmin

The following is an example of checking the connection pool of server1 in WebAdmin.

Since only ds1 is registered on server2, only the connection pool for ds1 exists.

Using the Console Tool

The connection-pool-info command is used to check for the list of all connection pools on a server. Since the connection-pool-info command provides the same function for JDBC connection pools as well as JCA connection pools, the JDBC option must be provided when using a JDBC connection pool. For more information about using connection-pool-info, refer to JEUS Reference Book. "4.2.11.7. connection-pool-info". The method for creating a connection pool can be found in the reference.

The following is an example of checking the list of all JDBC connection pools on server1 by executing connection-pool-info.

[DAS]domain1.adminServer>cpinfo -server server1 -jdbc
The connection pool information on the server [server1].
================================================================================
+---------------+-----+-----+--------+------+----------+-------+-------+-------+
|   Connection  | Min | Max | Active | Idle |Disposable| Total |  Wait |Enabled|
|    Pool ID    |     |     |        |      |          |       |       |       |
+---------------+-----+-----+--------+------+----------+-------+-------+-------+
| ds1           |   2 |  30 |      0 |    2 |        0 |     2 | false | true  |
+---------------+-----+-----+--------+------+----------+-------+-------+-------+
| ds2 *         |   2 |  30 |      0 |    0 |        0 |     0 | false | false |
+---------------+-----+-----+--------+------+----------+-------+-------+-------+

* : has not been created, total = active + idle + disposable
================================================================================

Since both ds1 and ds2 are registered on Server1, the connection pool information for both ds1 and ds2 exist. The connection pool for ds1 has already been created as a preparation task, but ds2 connection pool has not been created yet. The columns consist of the connection pool ID, minimum number of connections, maximum number of connections, active connection count, idle connection count, disposable connection count, total number of connections, whether to wait when there are no available connections, and whether the connection pool has been enabled.

To only check for the currently created connection pools, use the 'active' option as in the following.

[DAS]domain1.adminServer>cpinfo -server server1 -active -jdbc
The connection pool information on the server [server1].
================================================================================
+---------------+-----+-----+--------+------+----------+-------+-------+-------+
|   Connection  | Min | Max | Active | Idle |Disposable| Total |  Wait |Enabled|
|    Pool ID    |     |     |        |      |          |       |       |       |
+---------------+-----+-----+--------+------+----------+-------+-------+-------+
| ds1           |   2 |  30 |      0 |    2 |        0 |     2 | false | true  |
+---------------+-----+-----+--------+------+----------+-------+-------+-------+

* : has not been created, total = active + idle + disposable
================================================================================

Use the JNDI option to also display the JNDI name of the data source.

[DAS]domain1.adminServer>cpinfo -server server1 -jndi -jdbc
The connection pool information on the server [server1].
================================================================================
+------------+------------+-----+-----+-----+------+--------+-----+-----+------+
| Connection | JNDI export| Min | Max | Acti| Idle | Disposa|Total| Wait| Enabl|
|  Pool ID   |    name    |     |     | ve  |      |  ble   |     |     |  ed  |
+------------+------------+-----+-----+-----+------+--------+-----+-----+------+
| ds1        | ds1        |   2 |  30 |   0 |    2 |      0 |   2 |false| true |
+------------+------------+-----+-----+-----+------+--------+-----+-----+------+
| ds2 *      | ds2        |   2 |  30 |   0 |    0 |      0 |   0 |false| false|
+------------+------------+-----+-----+-----+------+--------+-----+-----+------+

* : has not been created, total = active + idle + disposable
================================================================================

The following shows the list of all connection pools that exist on server2.

[DAS]domain1.adminServer>cpinfo -server server2 -jdbc
The connection pool information on the server [server2].
================================================================================
+---------------+-----+-----+--------+------+----------+-------+-------+-------+
|   Connection  | Min | Max | Active | Idle |Disposable| Total |  Wait |Enabled|
|    Pool ID    |     |     |        |      |          |       |       |       |
+---------------+-----+-----+--------+------+----------+-------+-------+-------+
| ds1 *         |   2 |  30 |      0 |    0 |        0 |     0 | false | false |
+---------------+-----+-----+--------+------+----------+-------+-------+-------+

* : has not been created, total = active + idle + disposable
================================================================================

Since only ds1 is registered on server2, only the connection pool for ds1 exists.

This section describes how to check detailed information of a specific JDBC connection pool by using the console tool and WebAdmin.

Using WebAdmin

The following describes how to check the details of a specific connection pool in WebAdmin.

Using the Console Tool

The connection-pool-info command is used to check for the details of a connection pool on the server. Since the connection-pool-info command provides the same function for JDBC connection pools as well as JCA connection pools, the JDBC option must be provided when using a JDBC connection pool. For more information about using connection-pool-info, refer to JEUS Reference Book. "4.2.11.7. connection-pool-info".

The following is an example of checking details of connection pool for ds1 on server1 by executing connection-pool-info.

[DAS]domain1.adminServer>cpinfo -server server1 -id ds1 -jdbc
Information about connections in the server [server1]'s connection pool [ds1].
================================================================================
+------------------+-------+------------------------------+-----------+--------+
|   Connection ID  | State |       State Time(sec)        | Use Count |  Type  |
+------------------+-------+------------------------------+-----------+--------+
| ds1-1            | idle  |                      965.837 |         0 | pooled |
| ds1-2            | idle  |                      965.806 |         0 | pooled |
+------------------+-------+------------------------------+-----------+--------+
================================================================================

It shows two unused connections that have been idle for about 965 seconds, and both are not disposable connections.

Use the '-t' option as in the following example to check for the name of the thread that owns the connection.

[DAS]domain1.adminServer>cpinfo -server server1 -id ds1 -t -jdbc
Information about connections in the server [server1]'s connection pool [ds1].
================================================================================
+---------------+-------+-------------------+-----------+--------+-------------+
| Connection ID | State |  State Time(sec)  | Use Count |  Type  | Thread name |
+---------------+-------+-------------------+-----------+--------+-------------+
| ds1-1         | active|          1105.954 |         1 | pooled | http-w1     |
| ds1-2         | idle  |          1105.923 |         0 | pooled |             |
+---------------+-------+-------------------+-----------+--------+-------------+
================================================================================

This section describes how to control a connection pool on the server by using examples.

Knowledge about JEUS domain structure, and data source and connection pool management structure in the domain are needed for better understanding. For information about the JEUS domain structure, refer to JEUS Domain Guide. "1.3. Composition". For information about the data source and connection pool management structure, refer to "6.3. Management of Data Sources and Connection Pools".

The JDBC connection pool can be controlled by using WebAdmin or the console tool. This section describes both methods.

First perform some preparation tasks to help with the explanation. Create a domain named domain1 and a DAS named adminServer. After starting DAS, add two MSs named server1 and server2 to domain1 and start them. Then, add the data sources ds1 and ds2 to domain1. Register both ds1 and ds2 on server1 and server2. For information about domain and server related configurations, refer to JEUS Domain Guide. "Chapter 2. Creating a Domain" and "Chapter 2. JEUS Configuration". For information about data source related configurations, refer to "6.6. Dynamically Changing Data Source Related Configurations".

Note

For examples that show the result of controlling a connection pool, refer to "6.8. JDBC Connection Pool Monitoring".

This section describes the method for creating a connection pool by using the console tool and WebAdmin.

Using WebAdmin

The following describes how to create a connection pool in WebAdmin.

Using the Console Tool

The create-connection-pool command is used to create a connection pool for the data source on the server. For more information about using create-connection-pool, refer to JEUS Reference Book. "4.2.11.1. create-connection-pool".

The following is an example of creating connection pool for ds1 on server1 by executing create-connection-pool.

[DAS]domain1.adminServer>createcp -server server1 -id ds1
Servers that successfully created a connection pool : server1
Servers that failed to create a connection pool : none.

If the server option value is not provided, then a connection pool is created for all the servers where the data source is registered on.

The following is an example of executing create-connection-pool to create connection pool for ds1 on server1 and server2 where ds2 is registered on.

[DAS]domain1.adminServer>createcp -id ds2 
Servers that successfully created a connection pool : server1, server2
Servers that failed to create a connection pool : none.

A JDBC connection pool can be created even if control-connection-pool is used. For more information about using control-connection-pool, refer toJEUS Reference Book. "4.2.11.6. control-connection-pool".

The following is an example of creating a connection pool for ds1 on server1 by executing control-connection-pool.

[DAS]domain1.adminServer>ctrlcp -server server1 -id ds1 -create
Servers that successfully created a connection pool : server1
Servers that failed to create a connection pool : none.

This section describes how to disable a connection pool by using the console tool and WebAdmin.

Using WebAdmin

The following describes how to disable a connection pool in WebAdmin.

Using the Console Tool

The disable-connection-pool command is used to disable the connection pool on the server. For more information about how to use disable-connection-pool, refer to JEUS Reference Book. "4.2.11.3. disable-connection-pool".

The following is an example of disabling the connection pool for ds1 on server1 by executing disable-connection-pool.

[DAS]domain1.adminServer>disablecp -server server1 -id ds1
Servers that successfully disabled a connection pool : server1
Servers that failed to disable a connection pool : none.

If the server option is not provided, then the connection pool will be disabled for all servers where the data source is registered on.

The following is an example of disabling the connection pool for ds2 on server1 and server2 where ds2 is registered on by executing disable-connection-pool.

[DAS]domain1.adminServer>disablecp -id ds2
Servers that successfully disabled a connection pool : server1, server2
Servers that failed to disable a connection pool : none.

JDBC connection pool can also be disabled by executing control-connection-pool. For more information about using control-connection-pool, refer toJEUS Reference Book. "4.2.11.6. control-connection-pool".

The following is an example of disabling ds1 connection pool on server1 by executing control-connection-pool.

[DAS]domain1.adminServer>ctrlcp -server server1 -id ds1 -disable
Servers that successfully disabled a connection pool : server1
Servers that failed to disable a connection pool : none.

This section describes how to enable a connection pool by using the console tool and WebAdmin.

Using WebAdmin

The following describes how to enable a connection pool in WebAdmin.

Using the Console Tool

The enable-connection-pool command is used to enable the connection pool on the server. For more information about using enable-connection-pool, refer to JEUS Reference Book. "4.2.11.2. enable-connection-pool".

The following is an example of enabling the connection pool for ds1 created on server1 by executing enable-connection-pool.

[DAS]domain1.adminServer>enablecp -server server1 -id ds1
Servers that successfully enabled a connection pool : server1
Servers that failed to enable a connection pool : none.

If the server option is not provided, then the connection pool will be disabled for all servers where the data source is registered on.

The following is an example of enabling the connection pool for ds2 on server1 and server2 where ds2 is registered on by executing enable-connection-pool.

[DAS]domain1.adminServer>enablecp -id ds2
Servers that successfully enabled a connection pool : server1, server2
Servers that failed to enable a connection pool : none.

The control-connection-pool command can also be used to enable a JDBC connection pool. For more information about using control-connection-pool, refer to JEUS Reference Book. "4.2.11.6. control-connection-pool".

The following is an example of enabling the ds1 connection pool created on server1 by executing control-connection-pool.

[DAS]domain1.adminServer>ctrlcp -server server1 -id ds1 -enable
Servers that successfully enabled a connection pool : server1
Servers that failed to enable a connection pool : none.

This section describes how to replace a connection of a connection pool by using the console tool and WebAdmin.

Using WebAdmin

The following describes how to replace a connection in a connection pool in WebAdmin.

Using the Console Tool

The refresh-connection-pool command is used to replace the connections in the connection pool of the server with new connections. For more information about how to use refresh-connection-pool, refer to JEUS Reference Book. "4.2.11.4. refresh-connection-pool".

The following is an example of replacing the connections in the connection pool for ds1 on server1 with new connections by executing refresh-connection-pool.

[DAS]domain1.adminServer>refreshcp -server server1 -id ds1
Servers that successfully refreshed a connection pool : server1
Servers that failed to refresh a connection pool : none.

If the server option value is not provided, then a connection pool is created for all the servers where the data source is registered on.

The following is an example of refreshing the newly added connections in the connection pool on server1 and server2, where ds2 is registered, by executing refresh-connection-pool.

[DAS]domain1.adminServer>refreshcp -id ds2
Servers that successfully refreshed a connection pool : server1, server2
Servers that failed to refresh a connection pool : none.

JDBC connection pool's connections can also be refreshed by executing control-connection- pool. For more information about using control-connection-pool, refer toJEUS Reference Book. "4.2.11.6. control-connection-pool".

The following is an example of refreshing the connections in the connection pool for ds1 on server1 by executing control-connection-pool.

[DAS]domain1.adminServer>ctrlcp -server server1 -id ds1 -refresh
Servers that successfully refreshed a connection pool : server1
Servers that failed to refresh a connection pool : none.

This section describes how to minimize the number of connections in the connection pool by using the console tool and WebAdmin.

Using WebAdmin

The following describes how to minimize the number of connections in a connection pool in WebAdmin.

Using the Console Tool

The shrink-connection-pool command is used to adjust the number of connections in the connection pool on the server to the set minimum connection value. For more information about using shrink-connection-pool, refer to JEUS Reference Book. "4.2.11.5. shrink-connection-pool".

The following is an example of adjusting the number of connections in the connection pool for ds1 on server1 to the set minimum connection value by executing shrink-connection-pool.

[DAS]domain1.adminServer>shrinkcp -server server1 -id ds1
Servers that successfully shrank a connection pool : server1
Servers that failed to shrink a connection pool : none.

If the server option is not provided, then the connection pool will be disabled for all servers where the data source is registered on.

The following is an example of adjusting the number of connections in the connection pool for ds2 on server1 and server2, where ds2 is registered on, to the set minimum connection value by executing shrink-connection-pool.

[DAS]domain1.adminServer>shrinkcp -id ds2
Servers that successfully shrank a connection pool : server1, server2
Servers that failed to shrink a connection pool : none.

The number of connections in the JDBC connection pool can also be adjusted to the set minimum value by executing control-connection-pool. For more information about using control-connection-pool, refer to JEUS Reference Book. "4.2.11.6. control-connection-pool".

The following is an example of adjusting the number of connections in the connection pool for ds1 on server1 to the set minimum value by executing control-connection-pool.

[DAS]domain1.adminServer>ctrlcp -server server1 -id ds1 -shrink
Servers that successfully shrank a connection pool : server1
Servers that failed to shrink a connection pool : none.

This section briefly describes the JDBC application programming rules.

In the JCA standard, Connection Sharing is defined to guarantee that only one connection is always used for each resource in a transaction. Most of the resources from the JDBC viewpoint are databases or data sources. Without additional configuration, by default JEUS provides connection sharing to connection pool data sources that use the XA data source and emulation functions.

In application frameworks like ProFrame, since multiple connection requests are made within the same transaction, it is preferable to use connection sharing. Otherwise, multiple number of connections can participate in the transaction by using a single data source. This puts a lot of burden on the DB in managing the transaction lock which can reduce the overall performance of the transaction.

When it is not desirable to use connection sharing, compose the Java EE component configuration file (web.xml, ejb-jar.xml, etc) that uses XA data source as in the following. For <res-ref-name>, enter the JNDI name of the data source.

<resource-ref>
<res-ref-name>jdbc/xads</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-sharing-scope>Unshareable</res-sharing-scope>
</resource-ref>

If no configuration is made, then by default the <res-sharing-scope> element is set to shareable, and a servlet or EJB always uses connection sharing. However, since the connection pool data source that uses the XA emulation function must always share the connection, a java.sql.SQLException error occurs when it is configured to Unshareable.

JEUS has been only supporting connection pooling service for default users specified in the data source configuration. When connection was requested with a different user information, the connection was always handled as a disposable connection. Disposable connection is created whenever there is a connection request and it is removed from the connection pool after use. Hence, when there are a lot of requests for disposable connections, it can be a considerable burden on connection pooling.

For this reason, starting from JEUS 7.0 Fix#1, connection pooling service is supported for various users. This means that a single connection pool is transparently divided and managed per user, and the client can use the connection pooling service same as before without noticing any changes to the previous configuration. In the connection pool, the connections with different user information still all follow the overall configuration and policy of the connection pool. This way, even if multiple user-specific connections are used frequently, the connection pooling service can be used efficiently without having the burden of creating disposable connections.