Configuring WebSphere Application Server applications to automatically start container servers

Container servers 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 data grid within a Java EE server. A Java EE application is typically a single Enterprise Archive (EAR) file. The EAR file contains one or more deployed Enterprise JavaBeans (EJB) or web archive (WAR) modules.

WebSphere eXtreme Scale watches for each module start and looks for eXtreme Scale XML files. If the catalog service detects that a module starts with the XML files, the application server is registered as a container server Java virtual machine (JVM). By registering the container servers with the catalog service, the same application can be deployed in different data grids, but used as a single data grid by the catalog service. The catalog service is not concerned with cells, grids, or dynamic grids. A single data grid can span multiple cells if required.

Procedure

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 data 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 descriptor XML file, named objectGrid.xml. See ObjectGrid descriptor XML file for more information.
- A deployment descriptor XML file named objectGridDeployment.xml. See Deployment policy descriptor XML file for more information.
- (Optional) An entity metadata descriptor XML file, if entities are used. The entity.xml file name must match the name that is specified in the objectGrid.xml file. See Entity metadata descriptor XML file for more information.
The 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 your application has entities and you are planning to use one container server, set the minSyncReplicas value to 0 in the deployment descriptor XML file. Otherwise, you might see one of the following messages in the SystemOut.log file because placement cannot occur until another server starts to meet the minSyncReplica policy:
```
CWPRJ1005E: Error resolving entity association. Entity=entity_name, 
association=association_name.
```
```
CWOBJ3013E: The EntityMetadata repository is not available.  Timeout 
threshold reached when trying to register the entity: entity_name.
```
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 configure the environment to delay placement. For more information, see Controlling placement.

What to do next

Applications within the same cell as the containers can connect to these data 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 data 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 with different ClassLoaders. If application A stores a Person object in a 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 file 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, however this placement complicates the deployment.

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 data grid 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. The module can also call the ObjectGridManager.getObjectGrid(ccc, "grid name") method to gain a reference to the data grid. If any application objects are stored in Maps, verify that those objects are present in a common ClassLoader.

Java clients or clients outside the cell can connect with the bootstrap IIOP port of the catalog service. In WebSphere Application Server, the deployment manager hosts the catalog service by default. The client can then obtain a ClientClusterContext and the named data grid.

Entity manager

With the entity manager, the tuples are stored in the maps instead of application objects, resulting in fewer class loader problems. Plug-ins can be a problem, however. Also note that a client override ObjectGrid descriptor XML file is always required when connecting to a data grid that has entities defined: ObjectGridManager.connect("host:port[,host:port], null, objectGridOverride) or ObjectGridManager.connect(null, objectGridOverride).