Installing an eXtreme Scale resource adapter

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.

    1. 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.