JBoss.orgCommunity Documentation

Chapter 2. Resource Adaptor Type

2.1. Activities
2.2. Events
2.3. Activity Context Interface Factory
2.4. Resource Adaptor Interface
2.5. Restrictions
2.6. Sbb Code Examples
2.6.1. Retrieving the RA Interface and ACI Factory
2.6.2. Create and Attach to RA Activities
2.6.3. Execute a Statement
2.6.4. Handling Events and Ending an Activity

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();
}
     
The 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.

The 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.

The 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.

The 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.

The 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.

The 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.

The 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.

The 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.

The 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.

The 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.

The 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. If the execution throws an exception, it will be provided as an event too.

The 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.

The 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.


Important

Spaces where introduced in the Name and Event Class column values, to correctly render the table. Please remove them when using copy/paste.


Important

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;
}
    

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 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>