Starting eXtreme Scale containers automatically in WebSphere Application Server applications

Container processes in a WebSphere® Application Server environment start automatically when a module starts that has the eXtreme Scale XML files included.

Before you begin

WebSphere Application Server and WebSphere eXtreme Scale must be installed, and you must be able to access the WebSphere Application Server administrative console.

About this task

Java™ Platform, Enterprise Edition applications have complex class loader rules that greatly complicate loading classes when using a shared WebSphere eXtreme Scale within a Java EE server. A Java EE application is typically a single Enterprise Archive (EAR) file with one or more Enterprise JavaBeans™ (EJB) or Web archive (WAR) modules deployed in it.

WebSphere eXtreme Scale watches for each module start and looks for eXtreme Scale XML files. If WebSphere eXtreme Scale detects that a module starts with the XML files, it registers the application server as an eXtreme Scale container Java virtual machine (JVM) with the catalog service. By registering the containers with the catalog service, the same application can be deployed in different grids and still be treated as a single grid by the catalog service. The catalog service is not concerned with cells, grids or dynamic grids. Everything either is an eXtreme Scale container JVM or is not. A single logical grid can span multiple WebSphere Extended Deployment cells if required.

Procedure

  1. Package your EAR file to have modules that include the eXtreme Scale XML files in the META-INF folder. WebSphere eXtreme Scale detects the presence of the objectGrid.xml and objectGridDeployment.xml files in the META-INF folder of EJB and WEB modules when they start. If only an objectGrid.xml file is found, then the JVM is assumed to be client, otherwise, it is assumed this JVM acts as a container for the grid that is defined in the objectGridDeployment.xml file.

    You must use the correct names for these XML files. The file names are case sensitive. If the files are not present, then the container does not start. You can check the systemout.log file for messages that indicate that shards are being placed. An EJB module or WAR module using eXtreme Scale must have eXtreme Scale XML files in its META-INF directory.

    The eXtreme Scale XML files include:
    • An objectGrid.xml file, commonly referred to as an eXtreme Scale descriptor XML file.
    • An objectGridDeployment.xml file, commonly referred to as a deployment descriptor XML file.
    • An entity.xml file, if entities are used (optional). The entity.xml file name must match the name that is specified in the objectGrid.xml file.
    The eXtreme Scale run time detects these files, then contacts the catalog service to inform it that another container is available to host shards for that eXtreme Scale.
    Tip: If you plan to try an application with entities using one eXtreme Scale server, set the minSyncReplicas value to 0 in the deployment descriptor XML file to avoid a CWPRJ1005E: Error resolving entity association exception caused by The EntityMetadata repository is not available. Timeout threshold reached message.
  2. Deploy and start your application.

    The container starts automatically when the module is started. The catalog service starts to place partition primaries and replicas (shards) as soon as possible. This placement occurs immediately unless you define a numInitialContainers attribute in the objectGridDeployment.xml file. If you define the numInitialContainers attribute, then placement starts when that number of containers has started.

What to do next

Applications within the same cell as the containers can connect to these grids by using a ObjectGridManager.connect(null, null) method and then call the getObjectGrid(ccc, "object grid name") method. The connect or getObjectGrid methods might be blocked until the containers have placed the shards, but this blocking is only an issue when the grid is starting.

ClassLoaders

Any plug-ins or objects stored in an eXtreme Scale are loaded on a certain class loader. Two EJB modules in the same EAR can include these objects. The objects are the same but are loaded using different ClassLoaders. If application A stores a Person object in an eXtreme Scale Map that is local to the server, application B receives a ClassCastException if it tries to read that object. This exception occurs because application B loaded the Person object on a different class loader.

One approach to resolve this problem is to have a root module contain the necessary plug-ins and objects that are stored in the eXtreme Scale. Each module that uses eXtreme Scale must reference that module for its classes. Another resolution is to place these shared objects in a utility jar that is on a common class loader shared by both modules and applications. The objects can also be placed in the WebSphere classes or lib/ext directory, but this complicates deployment and is not recommended.

EJB modules in an EAR file typically share the same ClassLoader and are not affected by this problem. Each WAR module has its own ClassLoader and is affected by this problem.

Connecting to a grid as a client only

If the catalog.services.cluster property is defined in the cell, node or server custom properties, any module in the EAR file can call the ObjectGridManager.connect (ServerFactory.getServerProperties().getCatalogServiceBootstrap(), null, null) method to get a ClientClusterContext and call the ObjectGridManager.getObjectGrid(ccc, "grid name") method to gain a reference to the eXtreme Scale. If any application objects are stored in Maps, verify that that those objects are present in a common ClassLoader.

Java Platform, Standard Edition clients or clients outside the cell can connect using the bootstrap IIOP port of the catalog service (default in Websphere is the deployment manager) to obtain a ClientClusterContext and then obtain a named eXtreme Scale the usual way.

Entity manager

The entity manager helps because the Tuples are stored in the Maps, not the application objects, so that there are less class loader problems of concern. Plug-ins can be a problem, however. Also note that a client override eXtreme Scale descriptor XML file is always required when connecting to an eXtreme Scale that has entities defined: ObjectGridManager.connect("host:port[,host:port], null, objectGridOverride) or ObjectGridManager.connect(null, objectGridOverride).