Module jakarta.annotation

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:

• invalid reference

  javax.sql.DataSource

• invalid reference

  javax.sql.XADataSource

• invalid reference

  javax.sql.ConnectionPoolDataSource

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: dataSourceName networkProtocol propertyCycle roleName Properties are specified using the format: propertyName=propertyValue with one property per array element.
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