Package com.ibm.websphere.xs.ra

These are the eXtreme Scale Resource Adapter APIs that allows integration with a Java EE application.

See:
Description

Interface Summary

ObjectGridJ2CConnectionMBean

Allows administration clients control the lifecycle of the eXtreme Scale resource adapter's connection.

Class Summary

XSConnection	An XSConnection represents an application level connection handle to an eXtreme Scale ObjectGrid.
XSConnectionFactory	The XSConnectionFactory creates connections to eXtreme Scale ObjectGrids.
XSConnectionSpec	The ConnectionSpec for retrieving XSConnections from an XSConnectionFactory
XSManagedConnectionFactory	The XSManagedConnectionFactory create managed connections to the eXtreme Scale ObjectGrids.
XSResourceAdapter	The eXtreme Scale resource adapter

Package com.ibm.websphere.xs.ra Description

These are the eXtreme Scale Resource Adapter APIs that allows integration with a Java EE application.

Introduction

The eXtreme Scale Resource Adapter provides client connection management and local transaction support, allowing Java EE applications to look-up eXtreme Scale client connections and demarcate transactions using the LocalTransaction interface or the Session interface.

When used with WebSphere Application Server with last participant support enabled, the eXtreme Scale transaction can be enlisted in a global transaction as the last, single-phase participant.

Programming Tutorial

The following sections show snippets on the usage of the ConnectionFactory. The resource adapter is is JCA 1.5 compliant. To use the resource adapter the following steps must be followed:

1. Install the resource adapter
2. Configure a J2C ConnectionFactory
3. Configure a javax.resource.cci.ConnectionFactory resource reference in the application.
4. Look-up the XSConnectionFactory
5. Choose one of the following transaction options:

Use auto-commit, local transactions:

1. Retrieve a XSConnection
2. Retrieve and use the Session to interact with the data grid.
3. Close the connection.

Use an ObjectGrid Session to demarcate a local transaction:

1. Retrieve a XSConnection
2. Retrieve the Session
3. Use the Session.begin() method to start the transaction.
4. Use the Session to interact with the data grid.
5. Use the Session.commit() or rollback()) methods to end the transaction.
6. Close the connection.

Use a javax.resource.cci.LocalTransction to demarcate a local transaction:

1. Retrieve a XSConnection
2. Retrieve the javax.resource.cci.LocalTransaction using the XSConnection.getLocalTransaction() method.
3. Use the LocalTransaction.begin() method to start the transaction.
4. Retrieve and use the Session to interact with the data grid.
5. Use the LocalTransaction.commit() or rollback() methods to end the transaction.
6. Close the connection.

Enlist the connection in a global transaction:

1. Lookup the UserTransction.
2. Begin the global transaction
3. Retrieve a XSConnection
4. Retrieve and use the Session
5. Close the connection.
6. Commit or rollback the global transaction.

Installing the resource adapter

The eXtreme Scale resource adapter is included in the wxsra.rar resource adapter archive with the eXtreme Scale product. See the WebSphere eXtreme Scale version 8.5 information center (or later) for details on how to install and configure the resource adapter.

Configuring the J2C ConnectionFactory

The eXtreme Scale resource adapter allows configuring one or J2C ManagedConnectionFactory instances. Each ManagedConnectionFactory is managed by the application server and represents a connection to a single catalog service domain. the ManagedConnectionFactory can include the name of the data grid, or the data grid can be provided when the connection is retrieved by the application.

The ManagedConnectionFactory is configured in the application server configuration, bound to a global JNDI name, and provides the following configuration properties:

ConnectionName	(Optional) The name of the eXtreme Scale client connection.
CatalogServiceEndpoints	The catalog service domain end points in the form: <host>:<port>,<host><port>. Required if catalog service domain is not set.
CatalogServiceDomain	The catalog service domain name. Required if catalog service end points are not set.
ObjectGridName	(Optional) The data grid name. If not specified, the client must provide the data grid name when retrieving the connection resource.
ObjectGridURL	(Optional) The URL of the client data grid, override XML file.
ObjectGridResource	(Optional) The resource path of the client data grid, override XML file.
ClientPropertiesURL	(Optional) The URL of the client properties file.
ClientPropertiesResource	(Optional) The resource path of the client properties file.

Obtaining a ConnectionFactory instance.

The Java EE application can use resource injection to inject a ConnectionFactory resource into the application, or it can be looked-up using a resource reference. The Java EE application must first configure resource reference for a javax.resource.cci.ConnectionFactory.

For example:

InitialContext ctx = new InitialContext();
XSConnectionFactory cf = (XSConnectionFactory) ctx.lookup("java:comp/env/wxsconnection");

Retrieving a Connection

After the XSConnectionFactory has been looked-up or injected into the application, use one of the getConnection() methods to retrieve a client connection to the data grid. The connection will automatically be established when the first connection is retrieved and will be maintained until the resource adapter is stopped or the connection is reset using the ObjectGridJ2CConnection management bean.

For example:

XSConnection con = cf.getConnection("MyGrid");

Obtaining an ObjectGrid Session instance.

The XSConnection provides a getSession() method that gives the application direct access to the ObjectGrid Session. The Session is used to interact with the data grid and is valid for the life of the XSConnection. The XSConnection is a handle to a connection and becomes invalid after the application context completes per the Java EE specification.

An eXtreme Scale local transaction can be driven by the Session, javax.resource.cci.LocalTransaction or a global transaction. The transaction methods cannot be mixed.

Closing a connection

After the application has finished using the connection, the connection must be closed. The Java EE container typically will also close the connection automatically at the appropriate times. When the connection is closed the Session and any other objects retrieved directlly or indirectly from the connection become invalid.