Annotation used to define a container DataSource to be registered with JNDI. The DataSource may be configured by setting the annotation elements for commonly used DataSource properties. Additional standard and vendor-specific properties may be specified using the properties element.

The data source will be registered under the name specified in the name element. It may be defined to be in any valid Jakarta EE namespace, which will determine the accessibility of the data source from other components.

A JDBC driver implementation class of the appropriate type, either DataSource, ConnectionPoolDataSource, or XADataSource, must be indicated by the className element. The availability of the driver class will be assumed at runtime.

DataSource properties should not be specified more than once. If the url annotation element contains a DataSource property that was also specified using the corresponding annotation element or was specified in the properties annotation element, the precedence order is undefined and implementation specific:

   @DataSourceDefinition(name="java:global/MyApp/MyDataSource",
      className="org.apache.derby.jdbc.ClientDataSource",
      url="jdbc:derby://localhost:1527/myDB;user=bill",
      user="lance",
      password="secret",
      databaseName="testDB",
      serverName="luckydog"
   )// DO NOT DO THIS!!!
 

In the above example, the databaseName, user and serverName properties were specified as part of the url property and using the corresponding annotation elements. This should be avoided.

If the properties annotation element is used and contains a DataSource property that was also specified using the corresponding annotation element, the annotation element value takes precedence. For example:

   @DataSourceDefinition(name="java:global/MyApp/MyDataSource",
      className="org.apache.derby.jdbc.ClientDataSource",
      user="lance",
      password="secret",
      databaseName="testDB",
      serverName="luckydog",
       properties= {"databaseName=myDB", "databaseProp=doThis"}
   )// DO NOT DO THIS!!!
 

This would result in the following values being used when configuring the DataSource:

• serverName=luckydog
• portNumber=1527
• databaseName=testDB
• user=lance
• password=secret
• databaseProp=doThis

Vendors are not required to support properties that do not normally apply to a specific data source type. For example, specifying the transactional property to be true but supplying a value for className that implements a data source class other than XADataSource may not be supported.

Vendor-specific properties may be combined with or used to override standard data source properties defined using this annotation.

DataSource properties that are specified and are not supported in a given configuration or cannot be mapped to a vendor specific configuration property may be ignored.

Examples:

   @DataSourceDefinition(name="java:global/MyApp/MyDataSource",
      className="com.foobar.MyDataSource",
      portNumber=6689,
      serverName="myserver.com",
      user="lance",
      password="secret"
   )

 

Using a URL:

  @DataSourceDefinition(name="java:global/MyApp/MyDataSource",
    className="org.apache.derby.jdbc.ClientDataSource",
    url="jdbc:derby://localhost:1527/myDB",
    user="lance",
    password="secret"
 )
 

An example lookup of the DataSource from an Jakarta Enterprise Beans:

 @Stateless
 public class MyStatelessEJB {
   @Resource(lookup="java:global/MyApp/myDataSource")
    DataSource myDB;
      ...
 }