TeleStax.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.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();
}
execute(JdbcTask)
method:Executes the specified task. An exception event will be fired if the task execution throws an exception.
endActivity()
method:Ends the activity and its related Activity Context.
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);
}
execute(JdbcTaskContext)
method:Invoked by the JDBC RA, executes the task logic. The result of the task execution, which if not null, and valid (not null event object and type), will be used by the RA to fire an event into the SLEE
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();
}
setConnectionCredentials(String,String)
method:Sets the authentication credentials used to retrieve the JDBC Connection.
getConnection()
method:Retrieves the connection to be used by the task. The connection, if open once the task execution ends, will be closed automatically by the RA.
getSleeTransactionManager()
method:Retrieves the SLEE TransactionManager, which a task may use to create and manage Java transactions. Note that the RA will commit any open transaction once the task execution ends.
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();
}
getEventObject()
method:Retrieves the event object, which may be very specific to the application. This data may not be null.
getEventTypeID()
method:Retrieves the event type ID. This data may not be null. Note that the JDBC RA is able to fire any kind of event type.
Besides the tasks framework interfaces, the Resource Adaptor provides an abstract implementation of it, so applications may take advantage of the framework without the burden to implement custom SLEE Event Types.
The abstract task is JdbcTask.SimpleJdbcTask
, and concrete implementations need to implement the executeSimple(JdbcTaskContext)
method. The Resource Adaptor will fire a specific Event Type as result, which includes the object returned by the simple task execution.
An example of usage can be seen in the SBB Code Examples section.
JDBC Resource Adaptor may fire any SLEE Event Type, upon request by JDBC Tasks, yet it includes two types on its own.
Table 2.1. Event Types deployed by JDBC Resource Adaptor
Name | Vendor | Version | Event Class | Description |
---|---|---|---|---|
Jdbc Task Execution Throwable Event | org.restcomm | 1.0 | org.restcomm. slee.resource. jdbc.event. Jdbc Task Execution Throwable Event | Provides the exception or error which was thrown in a unsuccessful task execution. |
Simple Jdbc Task Result Event | org.restcomm | 1.0 | org.restcomm. slee.resource. jdbc.event. Simple Jdbc Task Result Event | Default event type which results from task execution. This event type is used for tasks extending the abstract SimpleJdbcTask . |
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;
}
createActivity()
method:Creates a new JdbcActivity
instance.
getConnection()
method:Retrieves a JDBC Connection, which may then be used to execute statements (prepared or not) synchronously. Note that applications must close the connection whenever it is not needed, failure to do so may result in no available JDBC Connections for additional application instances.
getConnection(String, String)
method:Retrieves a JDBC Connection using username and password authentication, which may then be used to execute statements (prepared or not) synchronously. Note that applications must close the connection whenever it is not needed, failure to do so may result in no available JDBC Connections for additional application instances.
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.
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 concrete SimpleJdbcTask
implementation and the request for its execution on a JdbcActivity
:
// build task
SimpleJdbcTask task = new SimpleJdbcTask() {
@Override
public Object executeSimple(JdbcTaskContext context) {
try {
Connection connection = context.getConnection();
PreparedStatement preparedStatement = connection
.prepareStatement("INSERT INTO TestTable VALUES(?)");
preparedStatement.setString(1, "Restcomm");
return true;
} catch (Exception e) {
tracer.severe("faile to execute task", e);
return false;
}
}
};
// execute the task on the jdbc activity
jdbcActivity.execute(task);
The following code examples the handling of the simple task result event, following the service logic execution. It also shows the explicit ending of the activity:
public void onSimpleJdbcTaskResultEvent(SimpleJdbcTaskResultEvent event,
ActivityContextInterface aci) {
tracer.info("Received a SimpleJdbcTaskResultEvent, task = "
+ event.getTask() + ", result object = " + event.getResult());
((JdbcActivity) aci.getActivity()).endActivity();
}
The SBB XML descriptor code to declare the handling of such event:
<event event-direction="Receive" initial-event="False">
<event-name>SimpleJdbcTaskResultEvent</event-name>
<event-type-ref>
<event-type-name>SimpleJdbcTaskResultEvent</event-type-name>
<event-type-vendor>org.restcomm</event-type-vendor>
<event-type-version>1.0</event-type-version>
</event-type-ref>
</event>