Acquiring a DataSource connection to a database

Using the DataSource interface, the connection to the database is obtained with a Java™ Naming and Directory Interface (JNDI) DataSource name lookup. JDBC DataSource implementation is provided by either the cicsts:jdbc-1.0, the Liberty jdbc-4.1 or jdbc-4.2 feature.

About this task

The term data source can be used in two different contexts, careful attention is needed, as they are distinguished by capitalization:
  • A data source is a source of data such as a database.
  • A DataSource is the Java EE way of encapsulating a set of properties that identify and describe the real world data source that it represents. A DataSource object can be thought of as a factory for connections to the particular data source that it represents.
  • If 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 data source it represents.
  • A DataSource object can choose to implement a connection pool (a set of temporary logical representations of a physical connection). When the application closes such a connection, the temporary connection (also known as a JDBC connection) is not closed, but returned to a pool for re-use.

If you are using JDBC type 4 connectivity, and want to coordinate database updates with the updates made in the CICS® unit of work, use the CICS JTA integration support and perform your updates within the scope of a UserTransaction. See Java Transaction API (JTA) for more information. Additionally you should ensure that your DataSource is an XADataSource (specified by adding the element type="javax.sql.XADataSource " to your definition). If you use the Liberty default DataSource <dataSource id="DefaultDataSource"> it is an XADataSource by default.

After the DataSource is configured, the application can use the use the value of the jndiName specified in either the cicsts_dataSource element, or the dataSource element, respectively, in the Liberty server configuration to obtain an instance of that DataSource class from the JNDI naming service. The getConnection() method can then be called on that DataSource object to get a connection. For example: 
Context context = new InitialContext();
DataSource dataSource = (DataSource)
context.lookup("jdbc/defaultCICSDataSource");

Connection connection = dataSource.getConnection();