Java EE applications use
DataSource objects when they access relational databases through the JDBC API.
DataSource has a set of properties that identify and describe the real-world data source that it represents.
These properties include information such as the location of the database server, the name of the database, and the network protocol
to use to communicate with the server. In addition, a
DataSource object works with a Java Naming and
Directory Interface (JNDI) naming service. After a
DataSource object is registered with a JNDI naming service,
an application can use the JNDI API to access that
DataSource object, which can then be used to connect to the
datasource it represents.
Prior to Java EE 6, you could create a
DataSource object using vendor-specific mechanisms, such as commands,
and use the
DataSource object in the application.
However, Java EE 6 makes datasource definition more flexible. It introduces a new datasource definition
resource that you can declare portably for database connectivity across any Java EE 6-compatible application server.
You can declare datasource definitions either through annotations or through the use of deployment descriptors.
This Tech Tip shows you how to create a datasource definition using either annotations or deployment descriptors.
It also includes a sample application that demonstrates the use of these features.
Creating Datasource Definitions Using Annotations
Java EE 6 provides two new annotations for creating datasource definitions:
@DataSourceDefinitions. Both of these annotations are in
javax.annotation.sql package. You use the
annotation to create a single datasource definition. You use the
@DataSourceDefinitions annotation to create
multiple datasource definitions.
You can use the
@DataSourceDefinition annotation to create a datasource definition. You can
specify the annotation in an application component class such as an application client, servlet, or Enterprise JavaBeans (EJB) component.
This defines a
DataSource object and registers it with JNDI. You configure the
object by setting the annotation elements with commonly used
DataSource properties. You can specify additional
standard and vendor-specific properties in the
properties element of the annotation.
For example, the following annotation creates a datasource definition for a Derby database:
The datasource definition is uniquely identified by the
name element. This is the JNDI name by which the datasource will
be registered. Notice that the name specified in the
name element begins with a namespace scope, in this case,
java:app. Java EE 6 introduces application component environment namespaces, which includes the following scopes.
java:comp. Names in this namespace have per-component visibility.
java:module. Names in this namespace are shared by all components in a module, for example, the EJB components
java:app. Names in this namespace are shared by all components and modules in an application, for example,
java:global. Names in this namespace are shared by all the applications in the server.
Depending on the namespace scope you specify in the
name element, you can make the datasource available across
a module, an application, or globally across a server. If you prefix the
name element value with:
java:comp/env/, the datasource will be available for the
java:module/env/, the datasource will be available for all the EJB components defined in its
java:app/env/, the datasource will be available for all the components and modules in the application,
You can use the
@DataSourceDefinitions annotation to create multiple datasource definitions
in a component class. You specify each datasource definition in a
value element in the annotation. Here is an example
that creates in an EJB class multiple datasource definitions for a Derby database:
Creating Datasource Definitions Using a Deployment Descriptor
You can create a datasource definition resource using a deployment descriptor in an
ejb-jar.xml file. For example, the
following deployment descriptor creates the same datasource definition as was defined in the previous
@DataSourceDefinition annotation example:
You've seen two examples that create the same datasource definition, one using an annotation and one using a
deployment descriptor. In fact, it is possible to create two datasource definitions with the same name in this way.
In that case, the values specified in the deployment descriptor take precedence over those specified in the annotation.
For example, if you create two datasource definitions with the same name, one using an annotation and one using a
deployment descriptor, and you specify a database name is each, the database name that you specified in the deployment
descriptor will be honored. However, if you specify a value for an element in an annotation and you don't specify an equivalent
element in a deployment descriptor, the value from the annotation will be merged with the deployment descriptor-based information.
A sample application accompanies this tip. The application demonstrates datasource definition using
annotations and deployment descriptors, and it does it for various types of Java EE components and for various
namespace scopes. The application includes the following Java EE components:
The application is supplied a datasource definition name. It then does a lookup of the datasource in the application client, EJB, and servlet
components. Based on the availability of the resource in the component's scope, the application either uses the provided datasource
or a default datasource,
Here are the datasource definitions that are created or exported by the application:
From the name and the namespace scope of the resource, the component in which the resource is defined can be identified.
For example, for the datasource definition named
java:app/env/HelloEJB_DD_DataSource, the namespace scope is
java:app and the resource is defined for "HelloEJB" in a deployment descriptor, "DD".
To run the application, do the following:
GF_HOMEto where you installed GlassFish v3.
PATHenvironment variable includes
PATHenvironment variable includes
sampledirectory. If your installation of GlassFish v3 requires an administration password, specify the password as the value of the
admin.passwordproperty in the
The command compiles, assembles, deploys, and runs the application. It then undeploys the application.
In response, you should see output for various datasources. Here is the output you should see for the
In the above output, DATASOURCE ACCESSIBLE in the RESULT rows indicates that the datasource named
is available across all components, that is, across the EJB, servlet, and application client components.
Similarly, here is what the output for the resource named
java:module/env/HelloEJB_DataSource should look like :
Here, the RESULT lines indicate that the datasource named
java:module/env/HelloEJB_DataSource is available only for the
EJB components defined in the
ejb-jar.xml file, that is,
Note that the sample application does a lookup to get access to a resource. However, it is also possible to inject the datasource as follows :
Also note that the sample application defines many datasources in addition to the ones named previously. To run the application for these
additional datasources, find the
build.xml file in the
sample directory. Then uncomment the commented
For more information about
DataSource resource definition in Java EE 6, see Section EE.5.17
"DataSource Resource Definition" in the Java EE 6 Specification.
About the Author
Jagadish Ramu is an engineer in the GlassFish Application Server team. He works in the areas of JDBC, connection pooling, and connectors.
He has been involved with the connectors team at Sun since mid-2005. Jagadish holds an M.Tech degree from BITS Pilani, India.