GlassFish - World's first Java EE 7 Application Server


GlassFish 3.2 - Connectors (JavaEE Connector Architecture, Connection Pooling, JDBC-RA) Half Pager

1. Introduction

1.1. Project/Component Working Name:

Connectors, Connection Pool, JDBC features in GlassFish Server Open Source Edition 3.2

1.2. Name(s) and e-mail address of Document Author(s)/Supplier:

Jagadish Ramu: jr158900@java.net

Shalini Muthukrishnan: sm157516@java.net

1.3. Date of This Document:

04/25/11

1.4. Revision History

25-April-11 Initial document 1

2. Project Summary

2.1. Project Description:

This document describes the functionality changes and enhancements to Connectors, Connection Pooling, JDBC-RA

2.2. Risks and Assumptions:

3. Problem Summary

3.1. Problem Area:

Following enhancements can be introduced in GlassFish 3.2 to overcome or to provide :

  • Support for JDBC-4.1 and JDK-7
  • IaaS machine templates for JavaDB and MySQL
  • JavaDB Plugin and MySQL Plugin implementations
  • Installing the JDBC driver dynamically for Paas environment
  • Granular SQL Tracing
  • --target support for ping-connection-pool and flush-connection-pool
  • Support GlassFish specific pool features in @DataSourceDefinition
  • Monitoring support for @DataSourceDefinition
  • ListResources command
  • Ability to provide a Properties file as value for a connection pool property
  • Miscellaneous Enhancements

3.2. Justification:

Enhancements to existing Connectors, Pooling, JDBC-RA modules is very useful as the functionality offered by these modules are used widely among the user-base. These functionality improvements and changes would not only bring in performance improvements but also feature parity. The proposed features will enhance the user experience. There are also several specification issues and minor enhancements addressed in JDBC-4.1 MR that need to be updated in the resource adapter.

4. Technical Description:

4.1. Details:

The Connectors, Pooling, JDBC-RA modules will have the following enhancements and features in this release

4.1.1 Support for JDBC-4.1 and JDK-7

The JDBC-4.1 Maintenance release 1.1 addresses several specification issues along with minor enhancements requested by the JDBC EG and user community. It also provides support for Automatic Resource Management introduced in Java SE 7. JDBC resource-adapter will provide wrappers to these API changes (new method additions) and also provide container level support wherever applicable. This support will help users to install JDBC 4.1 compatible jdbc-driver in GlassFish and make use of the new features.

4.1.2 IaaS machine templates for JavaDB and MySQL servers

GlassFish 3.2 introduces support for PaaS styled application deployments. Applications can indicate the need for a database either directly or indirectly (eg: via <resource-ref> in standard deployment descriptors of web/ejb modules or its annotation equivalents or in persistence.xml). Such a request can be served by the GlassFish runtime either by re-using and already provisioned database or provision an application-local (fresh) database. In order to support this feature, it is necessary to have pre-bundled (pre-installed) machine templates of the database software that could be used by GlassFish runtime. These machine templates need to be created according the common guidelines/ best practices laid by IaaS team. For GlassFish 3.2, the plan is to support JavaDB and MySQL databases and hence machine templates for these databases will be made available for use. The list of cloud providers that need to be supported (machine templates for each cloud provider is needed) is based on the release criteria.

4.1.3 JavaDB Plugin and MySQL Plugin implementations

As part of PaaS runtime capability, Orchestrator need to a mechanism to provision and manage databases. Orchestrator component will define SPIs for plugin using which various service providers (eg: MySQL Database Service provider, JavaDB Database Service provider) can be plugged in the GlassFish runtime. Refer Service Orchestration sub project for Plugin SPI details.

4.1.4 Installing the JDBC driver dynamically for PaaS environment

In a PaaS environment, GlassFish clusters are provisioned on demand. Similarly, databases would also be provisioned based on the requirements of the application. JDBC drivers need to be made available to GlassFish DAS and clusters (instances) in order to enable applications to connect to databases. Current implementation of GlassFish necessitates restart whenever a JDBC driver is made available, in order to make use of the driver. We could introduce OSGi specific mechanism using which JDBC drivers could be installed and made available without restarting GlassFish. As part of OSGi JDBC RFC implementation in GlassFish 3.1, there is support to install JDBC drivers and are made available (dynamically) to all OSGi applications in the OSGi runtime. This feature could be extended to support non-OSGi applications.

4.1.5 Granular SQL Tracing

This feature extends the SQL tracing functionality to provide more granular tracing of the SQL queries. The implementation of this feature will log all the Connection related SQL traces as INFO messages.

The in-built SQL tracing logger in GlassFish by the name "javax.enterprise.resource.sqltrace" will continue to be used. When the logging level is set to INFO, only the operations done on a Connection will be traced. Existing FINE log level will continue to log operations done on Connection, Statement, PreparedStatement and CallableStatement.

4.1.6 --target support for ping-connection-pool and flush-connection-pool commands

At present, ping-connection-pool command can be executed only on DAS. However, each GlassFish instance in the domain will have separate instance of connection pools. It would be useful if user is provided an option to execute ping-connection-pool command on instances as it would help to detect any dissimilarities in the environment (eg: Network setup, database permissions to connect from a host etc.,) between DAS and instances.

Similarly, flush-connection-pool command support could be extended to support any instance as target which would help to re-initialize the connection-pool in the instances based on the need.

4.1.7 Support GlassFish specific pool features for @DataSourceDefinition

@DataSourceDefinition (or its descriptor equivalent) is a new capability introduced in Java EE 6 specification using which applications can connect to databases. This feature could be augmented with GlassFish specific connection pool features so that applications can make use of GlassFish's connection pool capabilities. For 3.2, we plan to support a sub-set of connection pool attributes for @DataSourceDefinition. Applications can specify these attributes via the properties element of DataSourceDefinition. 

eg: In order to make use of 'connection-leak-tracing' capability, user can specify :

 @DataSourceDefinition(name = "java:app/Servlet_DataSource", minPoolSize = 0,
 initialPoolSize = 0,
 className = "org.apache.derby.jdbc.ClientXADataSource",
 user = "APP",
 password = "APP",
 databaseName = "testdb",
 properties = {"connectionAttributes=;create=true","leak-timeout-in-seconds=30"}
)

List of connection pool attributes supported for @DataSourceDefinition in this release are :

  • pool-resize-quantity
  • max-wait-time-in-millis
  • validate-atmost-once-period-in-seconds
  • connection-leak-timeout-in-seconds
  • connection-leak-reclaim
  • is-connection-validation-required
  • connection-validation-method
  • validation-classname
  • validation-table-name
  • allow-non-component-callers
  • statement-cache-size

4.1.8 Monitoring support for @DataSourceDefinition

Existing implementation of @DataSourceDefinition is realized internally as a jdbc-resource and jdbc-connection-pool. It would be useful to expose monitoring statistics of @DataSourceDefinition (ie., the jdbc-connection-pool monitoring statistics) to users. Following monitoring hierarchy could be used to display the statistics according to the scope in which the @DataSourceDefinition is defined.

server.<application-name>.datasource-definition.java:global/<global-scoped-dsd>
 server.<application-name>.datasource-definition.java:app/<app-scoped-dsd>
 server.<application-name>.datasource-definition.<module-name>.java:module/<module-scoped-dsd>
 server.<application-name>.datasource-definition.<module-name>.<component-name>.java:comp/<component-scoped-dsd>

Note :
1) For component scoped @DSD in web bundle descriptors, following convention will be used
server.<application-name>.<module-name>.datasource-definition.java:comp/<component-scoped-dsd>

2) For applications that are not .ear, <module-name> will not be applicable.

4.1.9 Generic list-resources command

Existing implementation of GlassFish has list-xxx-commands for each type of resource. There is also support for Application Scoped Resources which could be listed using list-components --resources command. It would be useful to provide a generic list-resources command that could be used to list the resources for all these types ie., normal resources, application-scoped-resources as well provide ability (options) to filter the resources based on type.

ie.,

asadmin list-resources [--appname] [--modulename] [--resourcetype] [--target]

Refer Admin/Config Impact section for more information.

4.1.10 Properties file value for JDBC Connection Pool property

The JDBC resource adapter's existing implementation does not allow setting of a properties file for any Java Bean setter method for DataSource. This new capability will allow users to specify a properties file as a value for any driver vendor specific property. A typical example is to set the connectionCacheProperties property for an oracle jdbc connection pool. The Oracle JDBC driver takes in a Properties file as value for the setConnectionCacheProperties method. In the current version of GlassFish, it is not possible to provide this as a property as we do not parse the properties file and set the driver vendor property. The ability to provide a properties file value for any Java bean setter method of a JDBC driver resolves this major issue and achieves feature parity with Spring Injection.

A new property "org.glassfish.resource.properties-type:ACTUAL_SETTER_NAME=PROPERTIES_FILE_PATH" can be set on a jdbc connection pool to specify a PROPERTIES_FILE_PATH to an actual Java Bean setter name. In the above case, this property value would translate as "org.glassfish.resource.properties-type:connectionCacheProperties=/GlassFish/properties/cache.properties". The PROPERTIES_FILE_PATH could be an absolute path or one relative to the GlassFish installation directory.

org.glassfish.resource.properties-type can be set on a jdbc connection pool as follows

asadmin> set server.resources.jdbc-connection-pool.<POOL_NAME>.property.org.glassfish.resource.properties-type:connectionCacheProperties=cache.properties

4.1.11 Miscellaneous Enhancements

Depending upon the availability of time, following enhancements can be addressed.

  • Ability to specify "Properties"/"Map" in the connection-pool configuration so that the can be applied to the JDBC driver. [TBD - Raise RFE with details. Might also involve "docs" changes as the property-name-format need to be documented.]
  • Support config-property-supports-dynamic-updates attribute in ra.xml such that when a configuration of resource-adapter/connection-factory/admin-object is updated and if the config-property is found to support dynamic updates, restart or reconfiguration of various resource-adapter artifacts is not needed.
  • Support System Property token replacement for application-scoped-resources configuration.
  • Log @DataSourceDefinition configuration (configuration used for the internal jdbc-connection-pool) whenever the @DataSourceDefinition is initialized.
  • More jdbc-resource, jdbc-connection-pool templates for databases (eg: Berkeley DB, HSQLDB etc.,)

4.2. Bug/RFE Number(s):

GLASSFISH-16452 : JDK7 and JDBC4.1 Support
GLASSFISH-15732 : Ability to specify GlassFish specific pool attributes in @DataSourceDefinition
GLASSFISH-3942    : Cluster aware "Ping" feature
GLASSFISH-16469 : IaaS machine templates for JavaDB and MySQL servers
GLASSFISH-16470 : JavaDB Plugin and MySQL Plugin implementations
GLASSFISH-16471 : Granular SQL Tracing
GLASSFISH-16472 : Monitoring support for @DataSourceDefinition
GLASSFISH- 13436 : Better error/warning messages for Flush/Ping Connection failure based on warning or error.

4.3. In Scope:

1. The JDBC4.1 related API changes and clarifications will be made to the jdcb40 module of the jdbc resource adapter
2. Support JavaDB and MySQL databases and make available the machine templates for these databases
3. OSGi specific mechanism to install JDBC drivers and make them available without restarting GlassFish
4. "Connection" related SQL traces are logged as INFO messages
5. Cluster aware database "Ping" and "Flush" connection pool
6. Introduce GlassFish specific connection pool properties to @DataSourceDefinition for applications to use GlassFish's connection pool capabilities
7. Monitoring statistics of DataSourceDefinition
8. list-resources command to list all types of resources.
9. Support for specifying a properties file value to an actual java bean setter method for a jdbc connection pool.

4.4. Out of Scope:

1. Usage of org.glassfish.resource.properties-type:ACUTAL_SETTER_NAME for other types of resources.

4.5. Interfaces:

4.5.1 Public Interfaces

4.5.2 Private Interfaces

4.5.3 Deprecated/Removed Interfaces:

4.6. Doc Impact:

  1. Administration Guide
  2. Developer's Guide
  3. Administration Reference Guide
  4. Admin GUI online help
  5. Admin CLI help (man pages)

4.7. Admin/Config Impact:

  • ping-connection-pool [--target]
    • valid values for target are DAS, Standalone-Instance, Clustered-Instance
  • flush-connection-pool [--target]
    • valid values for target are DAS, Standalone-Instance, Clustered-Instance
  • Generic "list-resources" command
asadmin list-resources [--appname] [--modulename] [--resourcetype] [--target]
Samples :
asadmin list-resources
  jdbc/__TimerPool    <JdbcResource>
  jdbc/__default        <JdbcResource>
  __TimerPool            <JdbcConnectionPool>
  DerbyPool               <JdbcConnectionPool>

asadmin list-resources  --resourcetype jdbc-resource
  jdbc/__TimerPool    <JdbcResource>
  jdbc/__default        <JdbcResource>

asadmin list-resources --appname app-scoped-resourcesApp
  java:app/jdbc/app-level-ds                        <JdbcResource>
  java:app/jdbc/app-level-pool                     <JdbcConnectionPool>
  java:app/custom/my-java-bean                 <CustomResource>

asadmin list-resources --appname app-scoped-resourcesApp --type JdbcResource
  java:app/jdbc/app-level-ds                        <JdbcResource>

asadmin list-resources --appname app-scoped-resourcesApp --modulename app-scoped-resources-ejb.jar
  java:module/jdbc/ejb-level-ds       <JdbcResource>
  java:module/eis/testAdmin          <AdminObjectResource>
  java:module/jdbc/ejb-level-pool    <JdbcConnectionPool>

asadmin list-resources --appname app-scoped-resourcesApp --modulename app-scoped-resources-ejb.jar --resourcetype admin-object
  java:module/eis/testAdmin    <AdminObjectResource>
  • Monitoring hierarchy for @DataSourceDefinition defined with various scopes in an application.
server.<application-name>.datasource-definition.java:global/<global-scoped-dsd>
 server.<application-name>.datasource-definition.java:app/<app-scoped-dsd>
 server.<application-name>.datasource-definition.<module-name>.java:module/<module-scoped-dsd>
 server.<application-name>.datasource-definition.<module-name>.<component-name>.java:comp/<component-scoped-dsd>

Note :
1) For component scoped @DSD in web bundle descriptors, following convention will be used
server.<application-name>.<module-name>.datasource-definition.java:comp/<component-scoped-dsd>

2) For applications that are not .ear, <module-name> will not be applicable.
  • GUI support :
    • Support for displaying monitoring statistics of @DataSourceDefinition
    • Support for --target equivalent in GUI for ping-connection-pool and flush-connection-pool commands

4.8. HA Impact:

4.9. I18N/L10N Impact:

4.10. Packaging, Delivery & Upgrade:

4.10.1. Packaging

4.10.2. Delivery

4.10.3. Upgrade and Migration:

4.11. Security Impact:

4.12. Compatibility Impact

4.13. Dependencies:

4.13.1 Internal Dependencies

4.13.2 External Dependencies

4.14. Testing Impact:

5. Reference Documents:

6. Schedule:

6.1. Projected Availability:

  • Aligned to overall GlassFish 3.2 release schedules