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 {@link javax.resource.cci.LocalTransaction} interface or the {@link com.ibm.websphere.objectgrid.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.
Use auto-commit, local transactions:Use an ObjectGrid Session to demarcate a local transaction:
- Retrieve a {@link com.ibm.websphere.xs.ra.XSConnection}
- Retrieve and use the {@link com.ibm.websphere.objectgrid.Session} to interact with the data grid.
- Close the connection.
Use a javax.resource.cci.LocalTransction to demarcate a local transaction:
- Retrieve a {@link com.ibm.websphere.xs.ra.XSConnection}
- Retrieve the {@link com.ibm.websphere.objectgrid.Session}
- Use the Session.begin() method to start the transaction.
- Use the Session to interact with the data grid.
- Use the Session.commit() or rollback()) methods to end the transaction.
- Close the connection.
Enlist the connection in a global transaction:
- Retrieve a {@link com.ibm.websphere.xs.ra.XSConnection}
- Retrieve the javax.resource.cci.LocalTransaction using the XSConnection.getLocalTransaction() method.
- Use the LocalTransaction.begin() method to start the transaction.
- Retrieve and use the {@link com.ibm.websphere.objectgrid.Session} to interact with the data grid.
- Use the LocalTransaction.commit() or rollback() methods to end the transaction.
- Close the connection.
- Lookup the UserTransction.
- Begin the global transaction
- Retrieve a {@link com.ibm.websphere.xs.ra.XSConnection}
- Retrieve and use the {@link com.ibm.websphere.objectgrid.Session}
- Close the connection.
- Commit or rollback the global transaction.
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.
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. |
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");
After the {@link com.ibm.websphere.xs.ra.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");
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.
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.