JBoss.orgCommunity Documentation
The Resource Adaptor Type is the interface which defines the contract between the RA implementations, the SLEE container, and the Applications running in it.
The name of the RA Type is JDBCResourceAdaptorType
, its vendor is org.mobicents
and its version is 1.0
.
The single activity object for JDBC Resource Adaptor is the org.mobicents.slee.resource.jdbc.JdbcActivity
interface. Through the activity an SBB can execute multiple JDBC statements, and receive the related responses asynchronously through events on it. Due to the nature of SLEE activities, this RA activity acts like a queue of requests, allowing the processing of their responses - the events- in a serialized way
An activity starts on demand by an SBB, through the RA SBB Interface, and it ends when an SBB invokes its endActivity()
method.
The activity interface is defined as follows:
package org.mobicents.slee.resource.jdbc;
import java.sql.PreparedStatement;
import java.sql.Statement;
public interface JdbcActivity {
void execute(Statement statement, String sql);
void execute(Statement statement, String sql, int autoGeneratedKeys);
void execute(Statement statement, String sql, int columnIndexes[]);
void execute(Statement statement, String sql, String columnNames[]);
void executeQuery(Statement statement, String sql);
void executeUpdate(Statement statement, String sql);
void executeUpdate(Statement statement, String sql, int autoGeneratedKeys);
void executeUpdate(Statement statement, String sql, int columnIndexes[]);
void executeUpdate(Statement statement, String sql, String columnNames[]);
void execute(PreparedStatement preparedStatement);
void executeQuery(PreparedStatement preparedStatement);
void executeUpdate(PreparedStatement preparedStatement);
public void endActivity();
}
execute(Statement, String)
method:Asynchronous execution of statement with unknown result type, which is provided in an event, fired in the activity. Details about parameters can be seen in the javadoc for java.sql.Statement
method with same signature. This method should only be used when the application has no idea of what is the SQL to be executed. If the execution throws an exception, it will be provided as an event too.
execute(Statement, String, int)
method:Asynchronous execution of statement with unknown result type, which is provided in an event, fired in the activity. Details about parameters can be seen in the javadoc for java.sql.Statement
method with same signature. This method should only be used when the application has no idea of what is the SQL to be executed. If the execution throws an exception, it will be provided as an event too.
execute(Statement, String, int[])
method:Asynchronous execution of statement with unknown result type, which is provided in an event, fired in the activity. Details about parameters can be seen in the javadoc for java.sql.Statement
method with same signature. This method should only be used when the application has no idea of what is the SQL to be executed. If the execution throws an exception, it will be provided as an event too.
execute(Statement, String, String[])
method:Asynchronous execution of statement with unknown result type, which is provided in an event, fired in the activity. Details about parameters can be seen in the javadoc for java.sql.Statement
method with same signature. This method should only be used when the application has no idea of what is the SQL to be executed. If the execution throws an exception, it will be provided as an event too.
executeQuery(Statement, String)
method:Asynchronous execution of statement with result set
result type, which is provided in an event, fired in the activity. Details about parameters can be seen in the javadoc for java.sql.Statement
method with same signature. This method should be used when the application knows that the SQL to execute is a read query. If the execution throws an exception, it will be provided as an event too.
executeUpdate(Statement, String)
method:Asynchronous execution of statement with update count
result type, which is provided in an event, fired in the activity. Details about parameters can be seen in the javadoc for java.sql.Statement
method with same signature. This method should be used when the application knows that the SQL to execute is a write query. If the execution throws an exception, it will be provided as an event too.
executeUpdate(Statement, String, int)
method:Asynchronous execution of statement with update count
result type, which is provided in an event, fired in the activity. Details about parameters can be seen in the javadoc for java.sql.Statement
method with same signature. This method should be used when the application knows that the SQL to execute is a write query. If the execution throws an exception, it will be provided as an event too.
executeUpdate(Statement, String, int[])
method:Asynchronous execution of statement with update count
result type, which is provided in an event, fired in the activity. Details about parameters can be seen in the javadoc for java.sql.Statement
method with same signature. This method should be used when the application knows that the SQL to execute is a write query. If the execution throws an exception, it will be provided as an event too.
executeUpdate(Statement, String, String[])
method:Asynchronous execution of statement with update count
result type, which is provided in an event, fired in the activity. Details about parameters can be seen in the javadoc for java.sql.Statement
method with same signature. This method should be used when the application knows that the SQL to execute is a write query. If the execution throws an exception, it will be provided as an event too.
execute(PreparedStatement)
method:Asynchronous execution of a prepared statement with unknown
result type, which is provided in an event, fired in the activity. PreparedStatements are an effective way to improve performance, since the JDBC driver may cache and pool the SQL. Details about parameters can be seen in the javadoc for java.sql.PreparedStatement
method with same signature. This method should only be used when the application has no idea of what is the SQL to be executed. If the execution throws an exception, it will be provided as an event too.
executeQuery(PreparedStatement)
method:Asynchronous execution of a prepared statement with result set
result type, which is provided in an event, fired in the activity. PreparedStatements are an effective way to improve performance, since the JDBC driver may cache and pool the SQL. This method should be used when the application knows that the SQL to execute is a read query. Details about parameters can be seen in the javadoc for java.sql.PreparedStatement
method with same signature. This method should only be used when the application has no idea of what is the SQL to be executed. If the execution throws an exception, it will be provided as an event too.
executeUpdate(PreparedStatement)
method:Asynchronous execution of a prepared statement with update count
result type, which is provided in an event, fired in the activity. PreparedStatements are an effective way to improve performance, since the JDBC driver may cache and pool the SQL. This method should be used when the application knows that the SQL to execute is a write query. If the execution throws an exception, it will be provided as an event too.
endActivity()
method:Ends the activity and its related Activity Context.
There are eight event types fired by JDBC Resource Adaptor, which provides applications the result of each kind of interaction with the Datasource
- result set, update count, unknown result and exception - from executing a Statement
or PreparedStatement
.
Table 2.1. Events which provide results of Statement
execution
Name | Vendor | Version | Event Class | Description |
---|---|---|---|---|
Statement ResultSet Event | org.mobicents | 1.0 | org.mobicents. slee.resource. jdbc.event. Statement ResultSet Event | Provides the result set from a successful execution of a statement, requested through the activity method executeQuery(Statement statement, String sql) . |
Statement UpdateCount Event | org.mobicents | 1.0 | org.mobicents. slee.resource. jdbc.event. Statement UpdateCount Event | Provides the update count from a successful execution of a statement, requested through the activity methods executeUpdate(Statement statement, ...) . |
Statement UnknownResult Event | org.mobicents | 1.0 | org.mobicents. slee.resource. jdbc.event. Statement UnknownResult Event | Provides the unknown type result from a successful execution of a statement, requested through the activity methods execute(Statement statement, ...) . |
Statement SQLException Event | org.mobicents | 1.0 | org.mobicents. slee.resource. jdbc.event. Statement SQLException Event | Provides the exception thrown from a unsuccessful execution of a statement. |
Spaces where introduced in the Name
and Event Class
column values, to correctly render the table. Please remove them when using copy/paste.
Table 2.2. Events which provide results of PreparedStatement
execution
Name | Vendor | Version | Event Class | Description |
---|---|---|---|---|
PreparedStatement ResultSet Event | org.mobicents | 1.0 | org.mobicents. slee.resource. jdbc.event. Prepared Statement ResultSet Event | Provides the result set from a successful execution of a prepared statement, requested through the activity method executeQuery( Prepared Statement preparedStatement) . |
PreparedStatement UpdateCount Event | org.mobicents | 1.0 | org.mobicents. slee.resource. jdbc.event. Prepared Statement UpdateCount Event | Provides the update count from a successful execution of a prepared statement, requested through the activity method executeUpdate( Prepared Statement preparedStatement ) . |
PreparedStatement UnknownResult Event | org.mobicents | 1.0 | org.mobicents. slee.resource. jdbc.event. Prepared Statement UnknownResult Event | Provides the unknown type result from a successful execution of a prepared statement, requested through the activity method execute( Prepared Statement preparedStatement ) . |
PreparedStatement SQLException Event | org.mobicents | 1.0 | org.mobicents. slee.resource. jdbc.event. Prepared Statement SQLException Event | Provides the exception thrown from a unsuccessful execution of a prepared statement. |
Spaces where introduced in the Name
and Event Class
column values, to correctly render the table. Please remove them when using copy/paste.
The Resource Adaptor's Activity Context Interface Factory is of type org.mobicents.slee.resource.jdbc.JdbcActivityContextInterfaceFactory
, it allows the SBB to retrieve the ActivityContextInterface
related with a specific JdbcActivity
instance. The interface is defined as follows:
package org.mobicents.slee.resource.jdbc;
import javax.slee.ActivityContextInterface;
import javax.slee.FactoryException;
import javax.slee.UnrecognizedActivityException;
import javax.slee.resource.ResourceAdaptorTypeID;
public interface JdbcActivityContextInterfaceFactory {
public static final ResourceAdaptorTypeID RATYPE_ID;
public ActivityContextInterface getActivityContextInterface(
JdbcActivity activity) throws UnrecognizedActivityException,
FactoryException;
}
The Resource Adaptor's Activity Context Interface Factory exposes a static RATYPE_ID field, containing the ResourceAdaptorTypeID
of the Resource Adaptor Type it belongs, which may be used to retrieve the factory instance using the SbbContextExt
JAIN SLEE 1.1 extension.
The JDBC Resource Adaptor interface, of type org.mobicents.slee.resource.jdbc.JdbcResourceAdaptorSbbInterface
, may be used by applications to create RA activities, and retrieve JDBC Connections, its interface is defined as follows:
package org.mobicents.slee.resource.jdbc;
import java.sql.Connection;
import java.sql.SQLException;
import javax.slee.resource.ResourceAdaptorTypeID;
public interface JdbcResourceAdaptorSbbInterface {
public static final ResourceAdaptorTypeID RATYPE_ID;
public JdbcActivity createActivity();
Connection getConnection() throws SQLException;
Connection getConnection(String username, String password)
throws SQLException;
}
createActivity()
method:Creates a new JdbcActivity
instance.
getConnection()
method:Retrieves a JDBC Connection, which may then be used to create statements (prepared or not). Note that the connection is closed automatically after each statement execution done through a JDBC activity, thus applications must not do it (unless the connection is retrieved but not used).
getConnection(String, String)
method:Retrieves a JDBC Connection using username and password authentication, which may then be used to create statements (prepared or not). Note that the connection is closed automatically after each statement execution done through a JDBC activity, thus applications must not do it (unless the connection is retrieved but not used).
The JDBC Resource Adaptor interface also exposes a static RATYPE_ID field, containing the ResourceAdaptorTypeID
of the Resource Adaptor Type it belongs, which may be used to retrieve the factory instance using the SbbContextExt
JAIN SLEE 1.1 extension.
The JDBC Resource Adaptor Type does not defines any restriction when using object instances provided, which means an application may use the provided JDBC connection, and the statements it creates, for any its functionalities (including the synchronous execution of statements through its interface).
The following code examples shows how to use the Resource Adaptor Type for common functionalities
The following code examples the retrieval of the RA's SBB Interface and ACI Factory, usually done in the Sbb's setSbbContext(SbbContext)
:
/**
* the SBB object context
*/
private SbbContextExt contextExt;
/**
* the JDBC RA SBB Interface
*/
private JdbcResourceAdaptorSbbInterface jdbcRA;
/**
* the JDBC RA {@link ActivityContextInterface} factory
*/
private JdbcActivityContextInterfaceFactory jdbcACIF;
@Override
public void setSbbContext(SbbContext context) {
this.contextExt = (SbbContextExt) context;
this.jdbcRA = (JdbcResourceAdaptorSbbInterface) contextExt
.getResourceAdaptorInterface(
JdbcResourceAdaptorSbbInterface.RATYPE_ID, raEntityLinkName);
this.jdbcACIF = (JdbcActivityContextInterfaceFactory) contextExt
.getActivityContextInterfaceFactory(JdbcActivityContextInterfaceFactory.RATYPE_ID);
}
The raEntityLinkName
is the link name of the RA entity to use. The link to the default RA entity, use the link name JDBCRA
..
The following code examples the creation of JdbcActivity
, and the attachment to its ActivityContextInterface
:
// create activity using the RA sbb interface
JdbcActivity jdbcActivity = jdbcRA.createActivity();
// get its aci from the RA ACI factory
ActivityContextInterface jdbcACI = jdbcACIF
.getActivityContextInterface(jdbcActivity);
// attach the sbb entity
jdbcACI.attach(contextExt.getSbbLocalObject());
The following code examples the creation of a Statement
and the execution of SQL on a JdbcActivity
:
// get connection and create statement
Statement statement = jdbcRA.getConnection().createStatement();
// execute SQL in the jdbc activity
jdbcActivity.executeQuery(statement,
"CREATE TABLE TestTable (Name VARCHAR(30));");
The following code examples the handling of events, for both PreparedStatement
and Statement
execution, following the service logic execution. It also shows the explicit ending of the activity:
/**
* Event handler for {@link StatementResultSetEvent}.
*
* @param event
* @param aci
*/
public void onStatementResultSetEvent(StatementResultSetEvent event,
ActivityContextInterface aci) {
tracer.info("Received a StatementResultSetEvent, as result of executed SQL "
+ event.getSQL());
tracer.info("Result: " + event.getResultSet());
try {
PreparedStatement preparedStatement = jdbcRA.getConnection()
.prepareStatement("INSERT INTO TestTable VALUES(?)");
preparedStatement.setString(1, "Mobicents");
tracer.info("Created prepared statement, executing...");
((JdbcActivity) aci.getActivity()).executeUpdate(preparedStatement);
} catch (Throwable e) {
tracer.severe("failed to create statement", e);
}
}
/**
* Event handler for {@link PreparedStatementUpdateCountEvent}.
*
* @param event
* @param aci
*/
public void onPreparedStatementUpdateCountEvent(
PreparedStatementUpdateCountEvent event,
ActivityContextInterface aci) {
tracer.info("Received a PreparedStatementUpdateCountEvent.");
tracer.info("Update Count: " + event.getUpdateCount());
try {
Statement anotherStatement = jdbcRA.getConnection()
.createStatement();
tracer.info("Created statement, executing query...");
((JdbcActivity) aci.getActivity()).executeUpdate(anotherStatement,
"DROP TABLE TestTable;");
} catch (Throwable e) {
tracer.severe("failed to create statement", e);
}
}
/**
* Event handler for {@link StatementUpdateCountEvent}.
*
* @param event
* @param aci
*/
public void onStatementUpdateCountEvent(StatementUpdateCountEvent event,
ActivityContextInterface aci) {
tracer.info("Received a StatementUpdateCountEvent, as result of executed SQL "
+ event.getSQL());
tracer.info("Update Count: " + event.getUpdateCount());
tracer.info("Ending JDBC Activity...");
((JdbcActivity) aci.getActivity()).endActivity();
}
The SBB XML descriptor code to declare the handling of such events:
<event event-direction="Receive" initial-event="False">
<event-name>StatementResultSetEvent</event-name>
<event-type-ref>
<event-type-name>StatementResultSetEvent</event-type-name>
<event-type-vendor>org.mobicents</event-type-vendor>
<event-type-version>1.0</event-type-version>
</event-type-ref>
</event>
<event event-direction="Receive" initial-event="False">
<event-name>PreparedStatementUpdateCountEvent</event-name>
<event-type-ref>
<event-type-name>PreparedStatementUpdateCountEvent</event-type-name>
<event-type-vendor>org.mobicents</event-type-vendor>
<event-type-version>1.0</event-type-version>
</event-type-ref>
</event>
<event event-direction="Receive" initial-event="False">
<event-name>StatementUpdateCountEvent</event-name>
<event-type-ref>
<event-type-name>StatementUpdateCountEvent</event-type-name>
<event-type-vendor>org.mobicents</event-type-vendor>
<event-type-version>1.0</event-type-version>
</event-type-ref>
</event>