Package jakarta.annotation.sql

Annotation Interface DataSourceDefinition

@Target(TYPE) @Retention(RUNTIME) @Repeatable(DataSourceDefinitions.class) public @interface DataSourceDefinition
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;
      ...
 }

Since:
Common Annotations 1.1
See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    className
    Name of a DataSource class that implements javax.sql.DataSource or javax.sql.XADataSource or javax.sql.ConnectionPoolDataSource.
    String
    name
    JNDI name by which the data source will be registered.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    databaseName
    Name of a database on a server.
    String
    description
    Description of this data source
    int
    initialPoolSize
    Number of connections that should be created when a connection pool is initialized.
    int
    isolationLevel
    Isolation level for connections.
    int
    loginTimeout
    Sets the maximum time in seconds that this data source will wait while attempting to connect to a database.
    int
    maxIdleTime
    The number of seconds that a physical connection should remain unused in the pool before the connection is closed for a connection pool.
    int
    maxPoolSize
    Maximum number of connections that should be concurrently allocated for a connection pool.
    int
    maxStatements
    The total number of statements that a connection pool should keep open.
    int
    minPoolSize
    Minimum number of connections that should be allocated for a connection pool.
    String
    password
    Password to use for connection authentication.
    int
    portNumber
    Port number where a server is listening for requests.
    String[]
    properties
    Used to specify vendor-specific properties and less commonly used DataSource properties such as:
    String
    serverName
    Database server name.
    boolean
    transactional
    Set to false if connections should not participate in transactions.
    String
    url
    A JDBC URL.
    String
    user
    User name to use for connection authentication.

  • Element Details

    • name

      String name
      JNDI name by which the data source will be registered.
      Since:
      1.1

    • className

      String className
      Name of a DataSource class that implements javax.sql.DataSource or javax.sql.XADataSource or javax.sql.ConnectionPoolDataSource.
      Since:
      1.1

    • description

      String description
      Description of this data source
      Since:
      1.1
      Default:
      ""

    • url

      String url
      A JDBC URL. If the url annotation element contains a DataSource property that was also specified using the corresponding annotation element, the precedence order is undefined and implementation specific.
      Since:
      1.1
      Default:
      ""

    • user

      String user
      User name to use for connection authentication.
      Since:
      1.1
      Default:
      ""

    • password

      String password
      Password to use for connection authentication.
      Since:
      1.1
      Default:
      ""

    • databaseName

      String databaseName
      Name of a database on a server.
      Since:
      1.1
      Default:
      ""

    • portNumber

      int portNumber
      Port number where a server is listening for requests.
      Since:
      1.1
      Default:
      -1

    • serverName

      String serverName
      Database server name.
      Since:
      1.1
      Default:
      "localhost"

    • isolationLevel

      int isolationLevel
      Isolation level for connections. The Isolation level must be one of the following:

      • Connection.TRANSACTION_NONE,
      • Connection.TRANSACTION_READ_ UNCOMMITTED,
      • Connection.TRANSACTION_READ_COMMITTED,
      • Connection.TRANSACTION_REPEATABLE_READ,
      • Connection.TRANSACTION_SERIALIZABLE

      Default is vendor-specific.

      Since:
      1.1
      Default:
      -1

    • transactional

      boolean transactional
      Set to false if connections should not participate in transactions.

      Default is to enlist in a transaction when one is active or becomes active.

      Since:
      1.1
      Default:
      true

    • initialPoolSize

      int initialPoolSize
      Number of connections that should be created when a connection pool is initialized.

      Default is vendor-specific

      Since:
      1.1
      Default:
      -1

    • maxPoolSize

      int maxPoolSize
      Maximum number of connections that should be concurrently allocated for a connection pool.

      Default is vendor-specific.

      Since:
      1.1
      Default:
      -1

    • minPoolSize

      int minPoolSize
      Minimum number of connections that should be allocated for a connection pool.

      Default is vendor-specific.

      Since:
      1.1
      Default:
      -1

    • maxIdleTime

      int maxIdleTime
      The number of seconds that a physical connection should remain unused in the pool before the connection is closed for a connection pool.

      Default is vendor-specific

      Since:
      1.1
      Default:
      -1

    • maxStatements

      int maxStatements
      The total number of statements that a connection pool should keep open. A value of 0 indicates that the caching of statements is disabled for a connection pool.

      Default is vendor-specific

      Since:
      1.1
      Default:
      -1

    • properties

      String[] properties
      Used to specify vendor-specific properties and less commonly used DataSource properties such as:

      • dataSourceName
      • networkProtocol
      • propertyCycle
      • roleName

      Properties are specified using the format: propertyName=propertyValue with one property per array element.

      If a DataSource property is specified in the properties element and the annotation element for the property is also specified, the annotation element value takes precedence.

      Since:
      1.1
      Default:
      {}

    • loginTimeout

      int loginTimeout
      Sets the maximum time in seconds that this data source will wait while attempting to connect to a database. A value of zero specifies that the timeout is the default system timeout if there is one; otherwise, it specifies that there is no timeout.

      Default is vendor-specific.

      Since:
      1.1
      Default:
      0