GlassFish - World's first Java EE 7 Application Server


Connectors (JavaEE Connector Architecture, Connection Pooling, JDBC-RA) Documentation Plan for GlassFish Server Open Source Edition 3.1

People and Roles

Name Role Location Time Zone Email
Scott Fordin Documentation Feature Owner Burlington, MA, USA US/Eastern sfordin@dev.java.net
Rebecca Parks Owner of Deployment Feature Santa Clara, CA, USA US/Pacific junesm@dev.java.net
Jagadish Ramu Project Lead Bangalore, India IST jr158900@dev.java.net
Shalini Muthukrishnan Project Lead Bangalore, India IST sm157516@dev.java.net
Sivakumar Thyagarajan Software Engineer Bangalore, India IST sivakumart@dev.java.net
Roberto Chinnici Software Engineer Menlo Park, CA, US US/Pacific rchinnici@dev.java.net
Alex Pineda Quality Engineer Santa Clara, CA, US US/Pacific pineda@dev.java.net
Paul Davies Peer Reviewer Santa Clara, CA, USA US/Pacific pauldavies@dev.java.net

Audience

This feature is aimed at system administrators and application developers.

Summary of the Feature From a User's Perspective

Enhancements to existing Connectors, Pooling, JDBC-RA modules will include:

  • Statement leak detection and reclaim support for JDBC applications
  • Clustering support for all types of resources
  • Application scoped resources to enable single click deployment of archive with resource definitions
  • Reconfiguration support for datasource-definition
  • Monitoring support to display:
    • Connections usage in a pool grouped by different applications
    • Frequently executed SQL queries by applications
    • Statement cache hit/miss statistics
    • Statement leaks
  • Ease of use and configurability features
  • Transparent reconfiguration of jdbc-connection-pool

Availability

This feature is available in all GlassFish Server distributions.

Statement of Work

This section describes in detail for each document the work that is required by the introduction of the feature, such as changes, addition of new material, relocation of existing material, and removal of existing material.

Documentation Impact:

  • None
  • Minor
  • Moderate
  • Major
  • New

Note - If a document is task based (as opposed to reference), the changes should be determined from the user task analysis for the feature.

Changes to Books

Administration Guide Changes

Item Number Section Documentation Impact Writer Reviewers Description of Change
1 Chapter 14, Administering Database Connectivity
Configuring Access to the Database 		New Scott Jagadish, Shalini, Alex Statement leak detection and reclaim; new statement-leak-timeout-in-seconds and statement-leak-reclaim options.
2 Chapter 14, Administering Database Connectivity
Configuring Access to the Database 		New Scott Jagadish, Shalini, Alex Application scoped resources: preserve-app-scoped-resources
list-application-scoped-resources --target
3 Chapter 14, Administering Database Connectivity
Configuring Access to the Database 		New Scott Jagadish, Shalini, Alex Dynamic reconfiguration: new dynamic-reconfiguration-wait-timeout-in-seconds properties.
4 Chapter 14, Administering Database Connectivity
Configuring Access to the Database 		New Scott Jagadish, Shalini, Alex New options:
preserve-app-scoped-resources
list-application-scoped-resources --target
5 Chapter 14, Administering Database Connectivity
Configuring Access to the Database 		New Scott Jagadish, Shalini, Alex New introspection behavior returns list of class names when prompting user for datasource or driver name.
6 Chapter 14, Administering Database Connectivity
Configuring Access to the Database 		New Scott Jagadish, Shalini, Alex New support for datasource-definition.
7 Chapter 14, Administering Database Connectivity
Configuring Access to the Database 		New Scott Jagadish, Shalini, Alex Monitoring support for various Connection Pool and JDBC artifacts.
8 Chapter 14, Administering Database Connectivity
Configuring Access to the Database 		Minor Scott Roberto, Sivakumar Add new --target option to relevant subcommands:
add-resources
create-admin-object
delete-admin-object
create-connector-resource
delete-connector-resource
create-javamail-resource
delete-javamail-resource
create-jdbc-resource
delete-jdbc-resource
create-custom-resource
delete-custom-resource
create-jndi-resource
delete-jndi-resource
list-admin-objects
list-connector-resources
list-javamail-resources
list-jdbc-resources
list-custom-resources
list-jndi-resources
create-resource-ref
delete-resource-ref
list-resource-refs
9 Chapter 14, Administering Database Connectivity
Administering JDBC Resources 		New Scott Jagadish, Shalini, Alex New SQL tracing properties:
sql-trace-listeners
time-to-keep-queries
10 Chapter 14, Administering Database Connectivity
Administering JDBC Resources 		New Scott Jagadish, Shalini, Alex New statement cache hit/miss monitoring probe; statement-cache-size property.
11 Chapter 14, Administering Database Connectivity
Administering JDBC Resources 		New Scott Jagadish, Shalini, Alex New statement leak monitoring feature; statement-leak-timeout-in-seconds property.
12 Chapter 14, Administering Database Connectivity
Administering JDBC Resources 		New Scott Jagadish, Shalini, Alex New transparent dynamic redeployment features: transparent-jdbc-connection-pool-redeployment
transparent-jdbc-connection-pool-redeployment
dynamic-reconfiguration-wait-timeout-in-seconds
13 Chapter 14, Administering Database Connectivity
Administering JDBC Resources 		New Scott Jagadish, Shalini, Alex New restrictions related to scoped resources.

Application Development Guide Changes

Item Number Section Documentation Impact Writer Reviewers Description of Change
1 Chapter 12, Developing Connectors
2 Connector Support in the GlassFish Server Moderate Scott Roberto, Sivakumar Add information about scoped resources, clustering, leak detection and reclaiming, transparent reconfiguration.
3 Advanced Connector Configuration Options, Thread Associations Moderate Scott Roberto, Sivakumar Scoped resources.
4 Advanced Connector Configuration Options, Work Security Maps Moderate Scott Roberto, Sivakumar connector-work-security-map concepts.
5 Advanced Connector Configuration Options, Transparent Reconfiguration New Scott Jagadish, Shalini, Alex Transparent reconfiguration features.
6 Advanced Connector Configuration Options, Flushing a Connector Connection Pool Minor Scott Roberto, Sivakumar flush-connection-pool concepts.
7 Advanced Connector Configuration Options, Handling Invalid Connections Moderate Scott Roberto, Sivakumar Leak detection and reclaiming.
8 Advanced Connector Configuration Options, Leak Detection New Scott Jagadish, Shalini, Alex More about leak detection and reclaiming.
9 Advanced Connector Configuration Options, OSGi Support New Scott Jagadish, Shalini, Alex OSGi support information.
10 Chapter 14, Using the JDBC API for Database Access        
11 Statements, Statement Tracing, Statement Caching Moderate Scott   SQL caching, tracing, monitoring options.
12 Connections, Scoped Resources New Scott Jagadish, Shalini, Alex Scoped resource instructions.
13 Connections, Marking Bad Connections Minor Scott Roberto, Sivakumar Reference to new Leak Detection section, below.
14 Connections, Leak Detection and Reclaiming New Scott Jagadish, Shalini, Alex New Leak and reclaiming topics.
15 Connections, Transparent Reconfiguration New Scott Jagadish, Shalini, Alex New transparent reconfiguration tasks.

Application Deployment Guide Changes

Item Number Section Documentation Impact Writer Reviewers Description of Change
1 Chapter 1, Overview, Module-Based Deployment Major Rebecca Jagadish, Shalini, Alex Rework Figure 1-1 and 1-2 to accommodate scoped resources. This is an RFE.
2 Chapter 2, Deploying Applications New Rebecca Roberto, Sivakumar Explain scoped resources, transparent reconfiguration in general. Show set subcommand for dynamic-reconfiguration-wait-timeout-in-seconds property.
3 Chapter 2, Deploying Applications New Rebecca Roberto, Sivakumar Add new redeploy property preserve-app-scoped-resources, new list-applications options --subcomponents and --resources
4 Chapter 2, Deploying Applications, Deploying a Connector Module New Rebecca Jagadish, Shalini, Alex Explain scoped resources relative to connectors.
5 Appendix C, Elements of the GlassFish Server Deployment Descriptors, glassfish-resources.xml, jdbc-connection-pool New Rebecca Jagadish, Shalini, Alex New attributes:
statement-leak-timeout-in-seconds
statement-leak-reclaim
New properties:
dynamic-reconfiguration-wait-timeout-in-seconds
number-of-top-queries-to-report
time-to-keep-queries-in-minutes

Domain File Format Reference Changes

Item Number Section Documentation Impact Writer Reviewers Description of Change
1 jdbc-connection-pool entry New Scott Jagadish, Shalini, Alex New properties:
statement-leak-timeout-in-seconds
statement-leak-reclaim
dynamic-reconfiguration-wait-timeout-in-seconds
preserve-app-scoped-resources
statement-cache-size
transparent-jdbc-connection-pool-redeployment
2 resource-adapter-config New Scott Jagadish, Shalini, Alex New options:
connector-work-security-map
sql-trace-listeners
time-to-keep-queries
statement-cache-size
datasource-definition
3 jdbc-connection-pool entry Minor Scott Roberto, Sivakumar Add --target option.
4 jdbc-resource entry Minor Scott Roberto, Sivakumar Add --target option.

Changes to man Pages

asadmin man Page Changes

Item Number Topic Title Documentation Impact Writer Reviewers Description of Change
1 create-jdbc-connection-pool New Scott Jagadish, Shalini, Alex New subcommand options:
statement-leak-timeout-in-seconds
statement-leak-reclaim
2 add-resources
create-admin-object
delete-admin-object
create-connector-resource
delete-connector-resource
create-javamail-resource
delete-javamail-resource
create-jdbc-resource
delete-jdbc-resource
create-custom-resource
delete-custom-resource
create-jndi-resource
delete-jndi-resource
list-admin-objects
list-connector-resources
list-javamail-resources
list-jdbc-resources
list-custom-resources
list-jndi-resources
create-resource-ref
delete-resource-ref
list-resource-refs 		Moderate Scott Roberto, Sivakumar Add new --target option to subcommands.
3 ping-connection-pool
flush-connection-pool 		Minor Scott Roberto, Sivakumar Add new --appname option to subcommand.
4 create-jdbc-connection-pool New Scott Jagadish, Shalini, Alex New dynamic-reconfiguration-wait-timeout-in-seconds property.
5 deploy New Scott Jagadish, Shalini, Alex New options:
preserve-app-scoped-resources
list-application-scoped-resources --target
5 create-jdbc-connection-pool New Scott Jagadish, Shalini, Alex New introspection behavior returns list of class names when prompting user for datasource or driver name.
6 jdbc-connection-pool New Scott Jagadish, Shalini, Alex New SQL tracing properties:
sql-trace-listeners
time-to-keep-queries
7 jdbc-connection-pool New Scott Jagadish, Shalini, Alex New statement cache hit/miss monitoring probe; statement-cache-size property.
8 jdbc-connection-pool New Scott Jagadish, Shalini, Alex New statement leak monitoring feature; statement-leak-timeout-in-seconds property.
9 jdbc-connection-pool New Scott Jagadish, Shalini, Alex New transparent dynamic redeployment features: transparent-jdbc-connection-pool-redeployment
transparent-jdbc-connection-pool-redeployment
dynamic-reconfiguration-wait-timeout-in-seconds
10 resource-adapter-config
connector-work-security-map 		New Scott Jagadish, Shalini, Alex New restrictions related to scoped resources.
11 jdbc-connection-pool New Scott Jagadish, Shalini, Alex New support for datasource-definition.

Changes to Online Help

Admin Console Online Help Changes

See the GlassFish 3.1 Admin Console Doc Plan for a list of Admin Console online help changes.

Review Schedule

The review schedule for the documentation items that are affected by this feature is provided in the following table.

Item Review Start Date Review End Date
Administration Guide changes    
Application Development Guide changes    
Application Deployment Guide changes    
Admin Console Online Help changes    
asadmin man Page changes    
Domain File Format Reference    

Reviewers are listed in the Statement of Work.

Related Information

Email aliases:

Comments:

1. Under Administration Guide changes : item 5 : Not clear on whether the description is about GUI or CLI or both. If this means both, appropriate explanations should be included for GUI and CLI separately.
2. Under Administration Guide changes : item 9 : sql-trace-listeners is not a new attribute for this release. The new properties for monitoring sql traces are "TIME-TO-KEEP-QUERIES-IN-MINUTES" and "NUMBER-OF-TOP-QUERIES-TO-REPORT". (One pager will be updated soon with the latest changes). Please refer one pager for the dotted names.
3. Under Administration Guide changes : item 10 : statement-cache-size is an attribute introduced in the last release to enable statement caching. Only when this is enabled, number of hits/misses can be monitored. Please refer one pager for the dotted names.
4. Under Administration Guide changes : item 11 : Only when statement-leak-timeout-in-seconds attribute (being introduced in this release) is set, statement leaks can be monitored. Please refer one pager for the dotted names.
5. Please add the new feature : "Connections usage in a pool by applications" (as in the one pager) to the admin guide.

6. Under Application Development Guide changes : item 11 : the changes are sql trace monitoring, statement cache hit/miss monitoring, statement leak detection & reclaim, statement leak monitoring.

7. Under Application Deployment Guide changes : last item : sql-trace-listeners, statement-cache-size are not new attributes for this release. They were introduced in 3.0. The time-to-keep-queries-in-minutes and number-of-top-queries-to-report are properties being introduced for this release for sql trace monitoring.

8. Under Reference Manual changes : item 6 : GUI and CLI introspection behavior should be described appropriately.
9. Under Reference Manual changes : item 7 : new sql trace monitoring properties are time-to-keep-queries-in-minutes and number-of-top-queries-to-report.

10. Under Domain File format reference changes : item 1 : Should be New attributes instead of properties. statement-cache-size was introduced in 3.0 and hence is not a new attribute for this release. New properties for jdbc connection pool are (only when sql-trace-listeners attribute is set), time-to-keep-queries-in-minutes and number-of-top-queries-to-report.
11. Under Domain File format reference changes : item 2 : Changes to be made according to (10).

12. Under asadmin man page changes : item 7, 8, 9 should be addressed based on comments above.
Posted by mchondria at Jul 28, 2010 05:06

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Administration Guide Changes :

CHAPTER 14 :
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Item 2 :

Application scoped resources: preserve-app-scoped-resources
list-application-scoped-resources --target

COMMENT :
We need not specify about app-scoped-resources in the above section.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Item 4 :

New options:
preserve-app-scoped-resources
list-application-scoped-resources --target

COMMENT :
We need not specify about app-scoped-resources in the above section.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Item 12 :
New transparent dynamic redeployment features: transparent-jdbc-connection-pool-redeployment
transparent-jdbc-connection-pool-redeployment
dynamic-reconfiguration-wait-timeout-in-seconds

COMMENT :
This seems to be already covered in Item 3.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Item 13 :
New restrictions related to scoped resources.

COMMENT :
We need not specify this in the above section.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Application Development Guide changes :
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
CHAPTER 12 :

Item 2 :

Add information about scoped resources, clustering, leak detection and reclaiming, transparent reconfiguration.

COMMENT :
This is not applicable for connectors.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Item 4 :
connector-work-security-map concepts.

COMMENT :
This was introduced in 3.0
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Item 3 & 5 :
COMMENT :
Application scoped resources include non-connector / non-jdbc resources also.
Instead of listing them under "connectors" section, we might have to introduce a new section named "application-scoped-resources" and provide feature description.
"Application Development Guide > Using Services and APIs > Application Scoped Resources" would be an option.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Item 9 :
It is not clear about the support of OSGi as of today. We shall revisit this during MS-5.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
CHAPTER 14 :
Item 12 :
"Scoped resource instructions. "

COMMENT :
No need to specify here.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Application Deployment Guide Changes :
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Item 1 :
"Clustering support, application scoped resources, transparent reconfiguration, support for OSGi RFCs for JDBC (OSGi RFC 122) and Resource-Adapters (OSGi RFC 146)."
can be
"Clustering support, application scoped resources" for now.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Item 3 :
"Add information about transparent reconfiguration. "

COMMENT :
Not applicable in application deployment section.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Item 5:
"Explain scoped resources, transparent reconfiguration. "
can be
"Explain scoped resources"

Reference Manual Changes :
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Item 5 :
"New options:
preserve-app-scoped-resources
list-application-scoped-resources --target"

can be

"New options:
preserve-app-scoped-resources"
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Domain File Format Reference Changes

Item 1 :
"dynamic-reconfiguration-wait-timeout-in-seconds" is a property and hence it has no DTD impact.
"transparent-jdbc-connection-pool-redeployment" is same as "dynamic-reconfiguration-wait-timeout-in-seconds"
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Item 2 :
"New options:
connector-work-security-map
sql-trace-listeners
time-to-keep-queries
statement-cache-size
datasource-definition"

can be

New options:
connector-work-security-map
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------

asadmin Man Pages :

Item 5 :
list-application-scoped-resources --target
need not be specified under "deploy" command section.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Posted by jagadish at Jul 28, 2010 09:54
Comment ID
Section Comment
PMD-001 Application Development Guide Changes Most of the information in Chapter 12, Developing Connectors is about administration, despite the title of the chapter. Plan on migrating that information to the Administration Guide and consolidating it with the information about connectors and so forth already there. That way, you might avoid having to make the same changes in 2 different places.

Any information about writing or editing deployment descriptors can be moved to the Application Deployment Guide.
PMD-002 Reference Manual Changes Delete this section. The changes to man pages are propagated automatically to the Reference Manual without further intervention from the writer, so they do not need to be listed twice.
PMD-003 Domain File Format Changes, Item 2
Clarify whether these items are properties or attributes of the element. domain.xml has no concept of options.
PMD-004 Domain File Format Changes, Items 3,4
Delete these items. Support for the --target option does not affect the content of these elements in domain.xml
PMD-005 Man Page Changes, Items 6-11
I think you need to prefix the name of each item in the topic column with "create-".
PMD-006 Man Page Changes Ensure that all additions to man pages are consistent with all additions to Domain File Format Reference. As a general rule, an option in a create command corresponds to an attribute of the element that represents the created item in domain.xml and a property of an element in domain.xml corresponds to a property that can be specified through --property in the command.
Posted by pauldavies at Jul 29, 2010 19:34