If you want to create a batch application, we recommend using DB Connector for connecting to resources. DB Connector is a resource adapter provided on Application Server used for connecting to a database. The following subsection describes how to connect to resources by using DB Connector.

1. Set DB Connector on batch server.
   You assign an optional name to an object of DB Connector by using the user-specified name space functionality and register the object in JNDI name space. Make sure to use the user-specified namespace functionality, when connecting to a database from a batch application.
   You deploy DB Connector on a batch server, and then set up the optional name in the HITACHI Connector Property file. As shown in the following example, you add the <optional name> tag in the <resource-external-property> tag of the HITACHI Connector Property file and set up an optional name.
   Example of setting
   

   <connector-runtime> : <resource-external-property> <optional-name>optional name of DB Connector</optional-name> </resource-external-property> </connector-runtime>

   For details on how to assign optional names of DB Connector, see 2.6 Assigning optional name to Enterprise Bean or J2EE server (user-specified name space functionality) in the uCosminexus Application Server Common Container Functionality Guide.
   For details on how to set up DB Connector, see 3.3 Resource connections in the uCosminexus Application Server Common Container Functionality Guide.
   
2. Perform lookup of DB Connector with the optional name specified in step 1 and acquire the connection factory (javax.sql.DataSource interface).
   Acquire java.sql.Connection from the acquired connection factory. The following example shows coding:
   

   String dbName = <Optional name of DB Connector>; InitialContext ic = new InitialContext(); DataSource ds = (DataSource) ic.lookup(dbName); Connection con = ds.getConnection();

3. Connect to resources using the acquired java.sql.Connection.
   java.sql.Connection provided by JDBC driver and API are the same.
   

   Note

   When using DB Connector, start DB Connector on a batch server, and then start the batch application.

When migrating from an existing batch application (Java application), following two methods are used to connect to resources:

• Changing to resource connections that use DB Connector provided with Cosminexus.
• Connecting to resources by using JDBC driver (without changing connection method).

When you do not use DB Connector, you need not modify code of the batch application. However, you cannot use the functionality provided with DB Connector and the garbage collection control functionality. This section describes the migration method of changing the resource connection method to DB Connector and the migration method of using JDBC driver (without changing connection method).

(a) Changing to resource connections that use DB Connector

If you want to use DB Connector, change the batch application so that you can acquire java.sql.Connection from DB Connector. You use the following method for changing batch applications:

1. Set up DB Connector on batch server.
   You assign an optional name to an object of DB Connector by using the user-specified name space functionality and register the object in JNDI name space. Make sure to use the user-specified namespace functionality, when connecting to a database from a batch application.
   You deploy DB Connector on the batch server and then set up the optional name in the HITACHI Connector Property file. As shown in the following example, you add the <optional-name> tag in the <resource-external-property> tag of the HITACHI Connector Property file and set up an optional name.
   Example of setting
   

   <connector-runtime> : <resource-external-property> <optional-name>optional name of DB Connector</optional-name> </resource-external-property> </connector-runtime>

   For details on how to assign optional names of DB Connector, see 2.6 Assigning optional name to Enterprise Bean or J2EE server (user-specified name space functionality) in the uCosminexus Application Server Common Container Functionality Guide.
   For details on how to set up DB Connector, see 3.3 Resource connections in the uCosminexus Application Server Common Container Functionality Guide.
   
2. Change the code of resource connection processing in batch application so as to use DB Connector.
   The following example shows a batch application before processing. The underlined parts show the Connection acquisition processing. Change this processing to the underlined processing with Batch application after change. The underlined part of Batch application after change is the Connection acquisition processing of DB Connector.
   
   • Batch application before change
     

     Class.forName("oracle.jdbc.driver.OracleDriver"); Connection con = DriverManager.getConnection(uri,"user","pass"); con.setAutoCommit(false); Statement stmt = con.createStatement(); stmt.executeBatch(); con.commit();

   • Batch application after change
     

     String dbName = <Optional name of DB Connector> InitialContext ic = new InitialContext(); DataSource ds = (DataSource)ic.lookup(dbName); Connection con = ds.getConnection(); con.setAutoCommit(false); Statement stmt = con.createStatement(); stmt.executeBatch(); con.commit();

You can use java.sql.Connection acquired from DB Connector in the same way as java.sql.Connection of JDBC driver. Hence, if you change only the acquisition method of java.sql.Connection, there is no need to change the code of other batch applications.

Note

When using DB Connector, start DB Connector on a batch server, and then execute the batch application.

(b) Connecting to resources by using JDBC driver

When using a JDBC driver, you need not modify code of a batch application. However, you must add libraries of the JDBC driver to be used to the class path of batch server. For details, follow the settings of the JDBC driver to be used. The following example describes how to add libraries of the JDBC driver to the class path of a batch server. To add libraries to the class path of a batch server, you add the following code to usrconf.cfg (option definition file for batch server):

add.class.path = full-path-of-library-of-JDBC-driver

For details on usrconf.cfg (option definition file for a batch server), see 3.2 usrconf.cfg (option definition file for batch server) in the uCosminexus Application Server Definition Reference Guide.

Note the following, when creating a batch application to be connected to resources:

Points to be considered when executing a batch application

Do not stop or change the settings of DB Connector, when a batch application is running. You stop or change the settings of DB Connector after the batch application ends.

Closing a connection

With a batch server, connection is not automatically closed. Therefore, implement in the application in such a way so that the used connections close without fail.

Using local transactions of JTA

You can use local transactions of JTA in a batch application. You use local transactions of JTA with the following methods:

1. Acquire the UserTransaction object with one of the following methods:
   
   • Acquire by performing lookup of Naming Service.
     Lookup name: HITACHI_EJB/SERVERS/Server-name/SERVICES/UserTransaction
     
   • Acquire by using the getUserTransaction method of the com.hitachi.software.ejb.ejbclient.UserTransactionFactory class.
2. Invoke the begin() method of the UserTransaction object and start the transaction.
3. Connect to resources.
4. Invoke the commit() or rollback method of the UserTransaction object and conclude the transaction.

For details on how to use the UserTransaction interface, see 3.4.8 Processing overview and points to be considered when using UserTransaction interface in the uCosminexus Application Server Common Container Functionality Guide.

The points to be considered when using UserTransaction are as follows:

• You can use only the main thread for UserTransaction. You cannot use with a user thread.
• Start and conclude the transaction with main thread.
• Transaction is not inherited when a thread is generated.
• You cannot pass connections or interface (statement) acquired from connections between threads. If you use this interface, the operation becomes invalid.

Concluding a transaction

If you start a transaction in a batch application, make sure to implement conclude processing in the batch application. If you close the batch application without implementing conclude processing of the transaction, the transaction is rolled back after a timeout time exceeds.

In this case, depending on the specified value of ejbserver.batch.application.exit.enabled parameter in Easy Setup definition file, behavior at the time of starting a transaction (javax.transaction.UserTransaction#begin()) in the batch application to be executed new, varies.

If "true" is specified in ejbserver.batch.application.exit.enabled parameter

You can start the transaction in the batch application to be executed next (accepts javax.transaction.UserTransaction#begin()).

If "false" is specified in ejbserver.batch.application.exit.enabled parameter

You cannot start the transaction in the batch application to be executed next. In this case, javax.transaction.NotSupportedException occurs and KDJE31009-E No nested transaction is supported is output as detailed information.

Restart the batch server for recovering from the State in which you cannot start a transaction.

For details on the settings of the ejbserver.batch.application.exit.enabled parameter, see 2.3.10 Settings in the execution environment (batch server settings).