TeleStax.orgCommunity Documentation

Chapter 2. Resource Adaptor Type

2.1. Activities
2.2. JDBC Tasks Framework
2.2.1. Simple JDBC Tasks
2.3. Events
2.4. Activity Context Interface Factory
2.5. Resource Adaptor Interface
2.6. Restrictions
2.7. Sbb Code Examples
2.7.1. Retrieving the RA Interface and ACI Factory
2.7.2. Create and Attach to RA Activities
2.7.3. Execute a Task
2.7.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.restcomm and its version is 1.0.

The single activity object for JDBC Resource Adaptor is the JdbcActivity interface. Through the activity an SBB can execute JDBC tasks, and receive the related task execution results 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.restcomm.slee.resource.jdbc;
import JdbcTask;
public interface JdbcActivity {
    void execute(JdbcTask task);
    public void endActivity();
}
     

The tasks framework enables SLEE applications with means to interact with JDBC data sources in a very efficient and customized manner. It is a simple yet powerful API, allowing execution of JDBC requests to be decoupled from the SLEE event router, and enabling applications to receive as result SLEE events which may be deployed by the application.

In the framework core is the JDBC Task concept, which provides the logic needed to interact with a JDBC Connection, and is responsible for building a result SLEE event. The Resource Adaptor is responsible for the actual task execution, and fires the resulting event into the SLEE, in the JDBC Activity used to submit the the task. Tasks implement the following interface:



        
package org.restcomm.slee.resource.jdbc.task;
public interface JdbcTask {
    public JdbcTaskResult execute(JdbcTaskContext taskContext);
}
     

The JdbcTaskContext parameter, given to the task when executing it, may be used by the task to retrieve the JDBC Connection, which is closed once the task execution ends, and also the SLEE Transaction Manager, which may be used to include Java transactions in the task logic. The context interface is:



        
package org.restcomm.slee.resource.jdbc.task;
import java.sql.Connection;
import java.sql.SQLException;
import javax.slee.transaction.SleeTransactionManager;
public interface JdbcTaskContext {
    public void setConnectionCredentials(String username, String password);
    public Connection getConnection() throws SQLException;
    public SleeTransactionManager getSleeTransactionManager();
}
     

The task execution result JdbcTaskResult is responsible for providing the result SLEE Event Object and Type, to be fired by the Resource Adaptor:



        
package org.restcomm.slee.resource.jdbc.task;
import javax.slee.EventTypeID;
import javax.slee.resource.SleeEndpoint;
public interface JdbcTaskResult {
    public Object getEventObject();
    public EventTypeID getEventTypeID();
}
     

JDBC Resource Adaptor may fire any SLEE Event Type, upon request by JDBC Tasks, yet it includes two types on its own.


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 JdbcActivityContextInterfaceFactory, it allows the SBB to retrieve the ActivityContextInterface related with a specific JdbcActivity instance. The interface is defined as follows:



        
package org.restcomm.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 JdbcResourceAdaptorSbbInterface, may be used by applications to create RA activities, and retrieve JDBC Connections, its interface is defined as follows:



        
package org.restcomm.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, but it is considered that implementations may forbidden access to some methods in the SBB Resource Adaptor Type, please refer to the implementation documentation for such clarification.

The following code examples shows how to use the Resource Adaptor Type for common functionalities.