Updating OSGi services for eXtreme Scale plug-ins with xscmd

WebSphere® eXtreme Scale supports upgrading container server plug-in bundles while the grid is active. This support allows administrators to complete application updates and additions without needing to restart grid processes.

Before you begin

Complete the following steps before you update eXtreme Scale OSGi bundles to a new version:

Start eXtreme Scale servers in a supported OSGi framework.
Separate all eXtreme Scale plug-ins into bundles, and they must use service rankings to identify each version of the plug-ins.
Specify cache objects as either Java™ primitive types such as byte[], Integer or String, or they must be stored using a MapSerializerPlugin plug-in The data objects are stored in the eXtreme Scale bundle and are not upgraded. Only the plug-ins that interact with the data are updated.
Design cache object data to be version compatible. New plug-ins must be able to interact with data created by older plug-ins.
Design plug-ins to listen for ObjectGridLifecycle and BackingMapLifecycle events to refresh any references to other plug-ins or the metadata that the plug-ins might have so that they can be refreshed when it is updated.
The eXtreme Scale OSGi update process only affects servers. You must independently update any clients that are using plug-ins.

About this task

Without OSGi enablement, if an administrator needs to update the application plug-ins or cache objects, each grid node must be upgraded one-by-one, causing stress on the network, memory and cpu utilization. This is required since plug-ins and cache Java objects are directly stored in the grid. When classes are updated without restarting the processes, the grid plug-ins have conflicts because each class has a different ClassLoader.

The eXtreme Scale product includes the xscmd utility and MBeans that allows administrators to view all the plug-in bundles installed in each grid container's hosting OSGi framework and choose which revision to use. When the xscmd is used to update the plug-ins to a new ranking, the grid is quiesced and all transactions are drained, the plug-ins are updated, and the grid is activated again. If an error occurs during the update process, the process is rolled-back and the old ranking is restored.

Procedure

Create a version of the bundle, increasing the version number in the bundle manifest, and increasing the ranking for each eXtreme Scale plug-in service.
If the original bundle version is Bundle-Version: 1.0.0, then the next version can be defined as Bundle-Version: 1.1.0.
If the original service ranking is ranking="1", then the next ranking can be defined as ranking="2".

Important: OSGi service rankings must be integers.
Copy the new bundle to each OSGi framework node that is hosting an eXtreme Scale container server.
Install the new bundle into the OSGi framework. The bundle is assigned a bundle identifier; for example:
```
osgi> install <URL to bundle>
```
Start the new bundle using the assigned bundle identifier; for example:
```
osgi> start <id>
```
After the new bundle is started, the eXtreme Scale OSGi service tracker detects the bundle and makes it available for updating.

Use the xscmd -c osgiAll command to verify that each container server sees the new bundle. The osgiAll command queries all containers in the grid for all services that are referenced in the ObjectGrid descriptor XML file and displays all rankings that are available; for example:

xscmd -c osgiAll 

Server: server1
   OSGi Service Name          Available Rankings
   -----------------          ------------------
   myLoaderServiceFactory     1, 2
   mySerializerServiceFactory 1, 2

Server: server2
   OSGi Service Name          Available Rankings
   -----------------          ------------------
   myLoaderServiceFactory     1, 2
   mySerializerServiceFactory 1, 2

Summary - All servers have the same service rankings.

Use the xscmd -c osgiCheck command to verify that one or more service rankings are valid update targets; for example:

xscmd -c osgiCheck -sr 
mySerializerServiceFactory;2,myLoaderServiceFactory;2

CWXSI0040I: The command osgiCheck has completed successfully.

If the osgiCheck command did not find any resulting errors, suspend the balancer of the placement service to avoid shard movements, in case of a failure during the update process.
To suspend placement, use the xscmd -c suspendBalancing command for each object grid and map set that are affected by the update; for example:
```
xscmd -c suspendBalancing -g MyGrid -ms MyMapSet
```
After balancing has been suspended for each object grid and map set, use the xscmd -c osgiCheck command again to verify that one or more service rankings are valid update targets; for example:
```
xscmd -c osgiCheck -sr 
mySerializerServiceFactory;2,myLoaderServiceFactory;2

CWXSI0040I: The command osgiCheck has completed successfully.
```
After balancing has been suspended for the object grid and map set, use the osgiUpdate command to update the service on all of the servers for an object grid and map set; for example:
```
xscmd -c osgiUpdate  -sr 
mySerializerServiceFactory;2,myLoaderServiceFactory;2 -g MyGrid -ms MyMapSet
```

Verify that the upgrade succeeded; for example:

Update succeeded for the following service rankings:
Service                     Ranking
-------                     -------
mySerializerServiceFactory  2
myLoaderServiceFactory      2

After you verify that the ranking has been updated successfully, enable balancing again, using the xscmd -c resumeBalancing command; for example:
```
xscmd -c resumeBalancing -g MyGrid -ms MyMapSet
```
Stop and uninstall the old bundle in each OSGi framework that is hosting the eXtreme Scale container.
For example, enter the following code in the Eclipse Equinox console:
```
osgi> stop <id>
osgi> uninstall <id>
```

Results

The eXtreme Scale bundle has been updated to a new version.