Application-Scoped Resources

You can define an application-scoped JDBC resource or other resource for an enterprise application, web module, EJB module, connector module, or application client module. This allows single-step deployment for resource-dependent modules and applications. An application-scoped resource has the following characteristics:

• It is available only to the module or application that defines it.

• It cannot be referenced or looked up by other modules or applications.

• It is created during deployment, destroyed during undeployment, and recreated during redeployment.

• It is free from unexpected resource starvation or delay in acquiring connections because no other application or module competes for accesses to it.

The following resource types can be application-scoped:

• JDBC connection pools

• JDBC resources

• Connector connection pools

• Connector resources

• Resource adapters

• External JNDI resources

• Custom resources

• Admin object resources

• JavaMail resources

Deployment Descriptor. An application-scoped resource is defined in the glassfish-resources.xml deployment descriptor file. This file is placed in the META-INF directory of the module or application archive. For web applications or modules, this file is placed in the WEB-INF directory. If any submodule archives of an enterprise application archive have their own glassfish-resources.xml files, the resource definitions are scoped to those modules only. For more information about the glassfish-resources.xml file, see Appendix B, GlassFish Server Deployment Descriptor Files and Appendix C, Elements of the GlassFish Server Deployment Descriptors.

Naming. Application-scoped resource JNDI names begin with java:app or java:module. If one of these prefixes is not specified in the JNDI name, it is added. For example, application-scoped databases have JNDI names in the following format: java:app/jdbc/DataSourceName or java:module/jdbc/DataSourceName. This is in accordance with the naming scopes introduced in the Java EE 6 Specification.

Errors. Application-scoped resource definitions with same resource name, resource type, attributes, and properties are duplicates. These generate WARNING level log messages and deployment continues. Definitions with the same resource name and type but different attributes or properties are conflicts and cause deployment failure. When an application or module tries to look up a scoped resource that does not belong to it, a naming exception is thrown.

Redeployment. When an application or module is undeployed, its scoped resources are deleted. During redeployment, resources are destroyed and recreated based on changes in the glassfish-resources.xml file. To preserve old resource definitions during redeployment, use the preserveAppScopedResources property of the redeploy (or deploy --force=true) subcommand. For example:

asadmin> redeploy --property preserveAppScopedResources=true MyApp.ear

asadmin> deploy --force=true --property preserveAppScopedResources=true MyApp.ear

For more information, see redeploy(1) and deploy(1).

Listing. Use the --resources option of the list-applications subcommand to list application-scoped resources. Use the --subcomponents option in addition to list scoped resources for enterprise application modules or for module subcomponents. To list scoped resources for subcomponents only, use the --resources option of the list-subcomponents subcommand

For more information, see list-applications(1) and list-sub-components(1).

Restrictions. Use of application-scoped resources is subject to the following restrictions:

• resource-adapter-config and connector-work-security-map — These can only be specified in the glassfish-resources.xml file of the corresponding connector module. In an enterprise application, the resource-adapter-config or connector-work-security-map for an embedded connector module must be specified in the glassfish-resources.xml file of the connector module. You cannot specify a resource-adapter-config or connector-work-security-map in an application for a connector module that is not part of the application.

• Resource to connection pool cross references — A module-level jdbc-resource cannot reference an application-level jdbc-connection-pool. Likewise, a module-level connector-resource cannot reference an application-level connector-connection-pool.

• Global resources — Defining java:global JNDI names is not supported.

• Cross definitions — Defining java:app JNDI names at the module level is not supported.