TeleStax.orgCommunity Documentation

Restcomm JAIN SLEE JDBC Resource Adaptor User Guide


Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Provide feedback to the authors!
1. Introduction to Restcomm JAIN SLEE JDBC Resource Adaptor
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
3. Resource Adaptor Implementation
3.1. Configuration
3.2. Default Resource Adaptor Entities
3.3. Traces and Alarms
3.3.1. Tracers
3.3.2. Alarms
4. Setup
4.1. Pre-Install Requirements and Prerequisites
4.1.1. Hardware Requirements
4.1.2. Software Prerequisites
4.2. Restcomm JAIN SLEE JDBC Resource Adaptor Source Code
4.2.1. Release Source Code Building
4.2.2. Development Master Source Building
4.3. Installing Restcomm JAIN SLEE JDBC Resource Adaptor
4.4. Uninstalling Restcomm JAIN SLEE JDBC Resource Adaptor
5. Clustering
A. Revision History
Index

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:

The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.

Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:

The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in Mono-spaced Bold. For example:

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.

Note the > shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select Mouse from the Preferences sub-menu in the System menu of the main menu bar' approach.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in the the Issue Tracker, against the product Restcomm JAIN SLEE JDBC Resource Adaptor, or contact the authors.

When submitting a bug report, be sure to mention the manual's identifier: Restcomm_JAIN_SLEE_JDBC_RA_User_Guide

If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

The JDBC Resource Adaptor adapts JDBC Datasources to JAIN SLEE domain, providing means to execute JDBC statements in asynchronous fashion. JDCB statements are executed in the RA runtime resources, freeing the JAIN SLEE Event Router from the burden of having its executors (threads) resources blocked by interactions with JDBC Datasources, and results are provided to applications through JAIN SLEE events. The JAIN SLEE application is also completely free from having to manage connection closings.

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

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 following code examples shows how to use the Resource Adaptor Type for common functionalities.

This chapter documents the JDBC Resource Adaptor Implementation details, such as the configuration properties, the default Resource Adaptor entities, and the JAIN SLEE 1.1 Tracers and Alarms used.

The name of the RA is JDBCResourceAdaptor, its vendor is org.restcomm and its version is 1.0.

There is a single Resource Adaptor Entity created when deploying the Resource Adaptor, named JDBCRA.

The JDBCRA entity is also bound to Resource Adaptor Link Name JDBCRA, to use it in an Sbb add the following XML to its descriptor:



        <resource-adaptor-type-binding>
            <resource-adaptor-type-ref>
                <resource-adaptor-type-name>
                    JDBCResourceAdaptorType
                </resource-adaptor-type-name>
                <resource-adaptor-type-vendor>
                    org.restcomm
                </resource-adaptor-type-vendor>
                <resource-adaptor-type-version>
                    1.0
                </resource-adaptor-type-version>
            </resource-adaptor-type-ref>
            <activity-context-interface-factory-name>
                slee/ra/jdbc/1.0/acifactory
            </activity-context-interface-factory-name>
            <resource-adaptor-entity-binding>
                <resource-adaptor-object-name>
                    slee/ra/jdbc/1.0/sbbinterface
                </resource-adaptor-object-name>
                <resource-adaptor-entity-link>
                    JDBCRA
                </resource-adaptor-entity-link>
            </resource-adaptor-entity-binding>
        </resource-adaptor-type-binding>
    

  1. Downloading the source code

    Use Git to checkout a specific release source, the Git repository URL is https://github.com/RestComm/jain-slee.jdbc/ , then switch to the specific release version, lets consider 3.0.9.

    				[usr]$ git clone https://github.com/RestComm/jain-slee.jdbc/ restcomm-jain-slee-jdbc
    				[usr]$ cd restcomm-jain-slee-jdbc
    				[usr]$ git checkout tags/3.0.9
    					
  2. Building the source code

    Important

    Maven 2.0.9 (or higher) is used to build the release. Instructions for using Maven2, including install, can be found at http://maven.apache.org

    Use Maven to build the deployable unit binary.

    				[usr]$ cd resources/jdbc
    				[usr]$ mvn install
    				    

    Once the process finishes you should have the deployable-unit jar file in the target directory, if Restcomm JAIN SLEE is installed and environment variable JBOSS_HOME is pointing to its underlying WildFly directory, then the deployable unit jar will also be deployed in the container.

Similar process as for Section 4.2.1, “Release Source Code Building”, the only change is the Git reference should be the master. The git checkout tags/3.0.9 command should not be performed. If already performed, the following should be used in order to switch back to the master:

		    [usr]$ git checkout master
			

The JDBC Resource Adaptor is cluster aware, it supports Activity replication, which means that any application instance may retrieve and interact with any JDBC Activity, in any node in a Restcomm SLEE cluster. The RA defines no failover mechanisms.

Revision History
Revision 1.0Wed Apr 20 2011Eduardo Martins
Creation of the Restcomm JAIN SLEE JDBC RA User Guide.