The WebSphere® eXtreme Scale resource adapter is Java™ Connector Architecture (JCA)
1.5 compatible and can be installed on a Java 2
Platform, Enterprise Edition (J2EE) 1.5 1.6 or
later, or on an application server such as WebSphere Application Server.
Before you begin
The resource adapter is in the
wxsra.rar resource
adapter archive (RAR) file, which is available in all installations
of
eXtreme Scale. The RAR
file is in the following directories:
- For WebSphere Application
Server installations: wxs_install_root/optionalLibraries/ObjectGrid
- For stand-alone installations: wxs_install_root/ObjectGrid/lib
directory
The resource adapter is coupled with the eXtreme Scale runtime environment.
It requires the eXtreme Scale runtime
JAR files in the correct classpath. In general, you can upgrade the eXtreme Scale runtime environment
without updating the resource adapter. Upgrading the eXtreme Scale runtime environment
also upgrades the resource adapter runtime environment. The resource
adapter supports version 8.5 and up to two versions later of the eXtreme Scale runtime environment.
Later versions of the resource adapter might require later versions
of the eXtreme Scale runtime
environment as they become available.
The wxsra.rar file
requires one of the eXtreme Scale client
runtime JAR files to operate. For details about which client runtime
JAR file is appropriate, see Runtime files for WebSphere eXtreme Scale stand-alone installation and Runtime files for WebSphere eXtreme Scale integrated with WebSphere Application Server, which include details about
the available runtime JAR files.
About this task
You can install the eXtreme Scale resource adapter
using several options that allow for flexible deployment scenarios.
The resource adapter can be embedded with the Java Platform, Enterprise Edition (Java EE) application, or it can be installed
as a stand-alone RAR file that is shared between applications.
Embedding
the resource adapter with the application simplifies deployment because
connection factories are only created within the scope of the application
and cannot be shared between applications. With the resource adapter
embedded in the application, you can also embed the cache objects
and ObjectGrid client plug-in classes within the application. Embedding
the resource adapter also protects the application from inadvertently
sharing cache objects between applications, which can result in java.lang.ClassCastException exceptions.
By
installing the
wxsra.rar file as a stand-alone
resource adapter, you can create resource manager connection factories
at the node scope. This option is useful in the following situations:
- When it is not practical to embed the wxsra.rar file
inside the application
- When the version of eXtreme Scale is
not known at build time
- When you want to share an eXtreme Scale client connection
with multiple applications
Important: In multiple versions of
WebSphere Application Server, up to Version 8.0.2,
you cannot install the
eXtreme Scale resource
adapter in an application EAR file and in the stand-alone server simultaneously.
The result, when you use the enterprise archive (EAR) file that also
has the RAR file installed, is that the application experiences an
exception, such as
ClassCastException: com.ibm.websphere.xs.ra.XSConnectionFactory
incompatible with com.ibm.websphere.xs.ra.XSConnectionFactory.
The following example
WebSphere Application Server message
and call stack for this error are displayed when a servlet encounters
this exception:
SRVE0068E: An exception was thrown by one of the service methods of the servlet [ClientServlet]
in application [JTASampleClientEAR]. Exception created : [java.lang.ClassCastException:
com.ibm.websphere.xs.ra.XSConnectionFactory incompatible with com.ibm.websphere.xs.ra.XSConnectionFactory
at com.ibm.websphere.xs.sample.jtasample.WXSClientServlet.connectClient(WXSClientServlet.java:484)
at com.ibm.websphere.xs.sample.jtasample.WXSClientServlet.doGet(WXSClientServlet.java:200)
at javax.servlet.http.HttpServlet.service(HttpServlet.java:575)
at javax.servlet.http.HttpServlet.service(HttpServlet.java:668)
at com.ibm.ws.webcontainer.servlet.ServletWrapper.service(ServletWrapper.java:1214)
at com.ibm.ws.webcontainer.servlet.ServletWrapper.handleRequest(ServletWrapper.java:774)
at com.ibm.ws.webcontainer.servlet.ServletWrapper.handleRequest(ServletWrapper.java:456)
Procedure
- Install an embedded eXtreme Scale resource adapter.
When the wxsra.rar file is embedded in
the application EAR file, the resource adapter must have access to
the eXtreme Scale runtime libraries.For applications that run in WebSphere Application Server,
the following choices and subsequent actions are available:
Option |
Description |
If eXtreme Scale is
integrated with the WebSphere Application
Server node |
The runtime library files are already available in the system
classpath, and no other action is required. |
If eXtreme Scale is
not integrated with the WebSphere Application
Server node |
You must include the wsogclient.jar file
in the wxsra.rar classpath. |
For applications that do not run in WebSphere Application Server, the client
runtime library file, ogclient.jar, or the server
runtime library file, objectgrid.jar, must be
in the classpath of the RAR file.
- Install a stand-alone eXtreme Scale resource adapter.
When you install the wxsra.rar file as
a stand-alone resource adapter, it must have access to the eXtreme Scale runtime libraries.For
applications that run in WebSphere Application
Server, the following choices and subsequent actions are available:
Option |
Description |
If eXtreme Scale is
integrated with the WebSphere Application
Server node |
The runtime library files are already available in the system
classpath, and no other action is required. |
If eXtreme Scale is
not integrated with the WebSphere Application
Server node |
You must include the wsogclient.jar file
in the wxsra.rar classpath. |
For applications that do not run in WebSphere Application Server, the client
runtime library file, ogclient.jar, or the server
runtime library file, objectgrid.jar, must be
in the classpath of the RAR file.
- Give the resource adapter access to any shared classes. All ObjectGrid plug-in classes and the applications that use
them must share a class loader. Since the resource adapter is shared
by multiple applications, all classes must be accessible by the same
class loader. You can create this access by using a shared library
between all applications that interact with the resource adapter.
What to do next
Now that you have installed the
eXtreme Scale resource adapter,
you can configure connection factories so that your Java EE applications
can connect to a remote
eXtreme Scale data
grid.