Copyright © Cloud Software Group, Inc. All Rights Reserved

JDBC Get Connection

Activity

The JDBC Get Connection activity retrieves an object reference to a JavaConnectionAccessor object for the specified JDBC Connection from the connection pool. This allows you to use the optimized TIBCO ActiveMatrix BusinessWorks database connection pool instead of specifying database configuration information in your Java code. This database connection can then be used within Java activities to access the specified database.

See Using The JDBC Connection in Java for more information on using the JDBC Get Connection activity.

Configuration

The Configuration tab has the following fields.

Field	Global Var?	Description
Name	No	The name to appear as the label for the activity in the process definition.
Description	No	Short description of the activity.
JDBC Connection	Yes	Path to the shared configuration resource containing the JDBC connection information. See JDBC Connection for more information about JDBC resources.
Override Transaction Behavior	No	Overrides the default behavior of a transaction group. If the activity that uses this JDBC connection is in a transaction group, the activity is normally committed or rolled back with the other transactional activities. If this check box is selected, the database connection is in auto commit mode, where each operation is committed as it is performed. You can disable the auto commit mode, if desired, and your code is then responsible for performing the commit or rollback operation before releasing the connection.

Input

This activity has no input.

Output

The output for the activity is dependent upon the output parameters of the database procedure.

Output Item	Datatype	Description
JavaConnectionAccessor	Java Object	A Java object reference to a JavaConnectionAccessor object. This object can be passed as input to a Java activity where custom Java code can use the connection to perform database operations.
Elapsed Time	long	This field displays the time taken for the execution of the activity in milliseconds. This is an optional element that appears only when the property java.property.bw.activity.output.stats.elapsedTime.JDBCGetConnectionActivity is set to true in designer.tra. For run-time, set the property to true in the bwengine.tra file. By default, the property is set to false. If set in the design-time, this property must be carried forward to the run-time; else it can cause run-time errors. Enabling this property causes additional performance overhead. Hence, it is recommended that you use this property only when this information is to be consumed by some other ActiveMatrix BusinessWorks activity. Also, it is recommended that this property be used only in a non-production environment as a diagnostic tool and the property be turned off at run-time. You can turn off the property and not calculate the elapsed time at run-time by setting the property java.property.bw.activity.output.stats.elapsedTime.turnoff in the bwengine.tra file. However, note that setting this property will turn off the calculation of elapsed time at run-time for all the JDBC activities.

Error Output

The Error Output tab lists the possible exceptions that can be thrown by this activity. See TIBCO ActiveMatrix BusinessWorks Error Codes for more information about error codes and corrective action to take.

Exception	Thrown When...
JDBCSQLException	A SQL error occurred.
LoginTimedOutException	A timeout has occurred while attempting to connect to the database.

Using The JDBC Connection in Java

The database connection obtained with the JDBC Get Connection activity has the following restrictions:

•	Checkpoints should not be taken after a JDBC Get Connection activity completes.

•	Do not pass the JavaConnectionAccessor object reference to a subprocess that spawns a new process.

The JDBC Get Connection activity creates a JavaConnectionAccessor object reference that can be passed to an input parameter of a Java Code or Java Method activity. See Passing Java Objects Between Java Code Activities for details on how to pass Java object references between activities.

JavaConnectionAccessor has the following methods:

•	java.sql.Connection getDBConnection(); — retrieves a database connection from the connection pool.

•	void releaseConnection(); — releases a database connection so that it can return to the connection pool.

•	boolean isTransactional(); — returns true if the activity using the JDBC connection is in a transaction group and the Override Transaction Behavior on the Configuration tab of the JDBC Get Connection activity is unchecked.

•

void releaseConnection(SQLException ex) — releases the connection obtained by way of the getDBConnection() method. Use this method instead of the standard releaseConnection method because this method detects if the SQL Exception passed as input is due to a connection problem. If the connection is no longer usable, it is destroyed and it is not returned to the connection pool.

When the connection is part of a transaction, the JavaConnectionAccessor object prevents you from committing or rolling back the transaction. The transaction will complete when the transaction group either commits or rolls back. If the connection is part of an XA transaction group, the enlist and delist operations are performed by the getDBConnection and releaseConnection methods.

When the connection is not part of a transaction, the database connection is in auto commit mode, where each operation is committed as it is performed. You can disable the auto commit mode, if desired, and your code is then responsible for performing the commit or rollback operation before releasing the connection.

If your Java code does not release the connection, the connection is automatically released when the process instance terminates. This could have undesirable consequences.

Your code should check for SQL Exceptions returned when executing JDBC statements. If you encounter an unexpected SQL Exception, you can use the releaseConnection(SQLException ex) method to release the connection. This allows you to check if the connection is no longer valid. If the connection is no longer valid, your Java code should return an appropriate exception for subsequent activities so that transactions can be rolled back, if necessary.

Copyright © Cloud Software Group, Inc. All Rights Reserved