Upgrading agents and data models dynamically from OSGi bundles in the Liberty

Upgrade your OSGi bundles without interruption in the Liberty.

About this task

You can declare packages that contain classes that WebSphere® eXtreme Scale needs to load based on the WXS-Packages manifest header in your bundle. However, if you are exporting those packages anyway, you can export them with the wxs-visibility="public" attribute.
See the following scenarios that can apply to this task:
Agent evolution: You have version 1 of an agent on your servers but you want to upgrade to version 2 without restarting the server.
  1. You create a bundle with version 2 of the agent and copy it into the grids directory for the server.
  2. WebSphere eXtreme Scale detects the new version of the same packages and prioritizes the newer version.
  3. When you invoke the agent, eXtreme Scale loads version 2.
Data model evolution: You want to upgrade a class for objects that are stored with eXtreme Data Format (XDF) enabled in the data grid.
  1. You create a bundle with version 2 of the data model class and install it into the OSGi framework. If the bundle is collocated with a WebSphere eXtreme Scale server, then you can copy it into the grids directory.
  2. WebSphere eXtreme Scale detects the new version of the same packages and prioritizes the newer version.
  3. When you get an instance of this object in the client, XDF loads the new version of the class.
    Note: Make sure that the two versions of the class are compatible. Incompatibilities exist when you make the following changes in the newer version that are not applied to the older version:
    • The newer version of the class adds a field. When the object is deserialized from XDF, the newly added field is null, unless a default value is provided.
    • The newer version of the class removes a field. When the object is deserialized from XDF, the remaining fields are populated. Data for the removed fields continue to exist in the data grid, but are ignored on the client. After the object in the data grid is updated to the newer version, the data from the removed field is removed.
    • The newer version of the class changes the field type. Avoid such changes because it results in a serialization error.
You can use one of the following approaches to complete either of these scenarios.

Procedure

  • Declare the packages, which contain the classes that Liberty must load with the version=1.0.0 attribute on either the WXS-Packages header or the Export-Packages header.
  • Declare the wxs-visibility="public" attribute in your fragment META-INF/MANIFEST.MF file.

Example

See the following META-INF/MANIFEST.MF file example where both approaches are used in the highlighted lines. Only one of the highlighted lines is necessary; although it would still work if you declare both lines. Also, notice that this feature honors the version attribute. In general, the highest version of a particular package is the one that is loaded.
Manifest-Version: 1.0 
Ant-Version: Apache Ant 1.6.5 
Created-By: 2.6 (IBM Corporation) 
Bundle-ManifestVersion: 2 
Bundle-Name: com.ibm.websphere.xs.sample.airport.agent 
Bundle-SymbolicName: com.ibm.websphere.xs.sample.airport.agent 
Bundle-Version: 1.0.0 
Bundle-RequiredExecutionEnvironment: JavaSE-1.6 
WXS-Packages:  com.ibm.websphere.xs.sample.airport.agent;version=1.0.0 
Export-Package: com.ibm.websphere.xs.sample.airport.agent;version=1.0.0;wxs-visibility="public" 
Import-Package: com.ibm.websphere.objectgrid.query, 
 com.ibm.websphere.objectgrid.datagrid, 
 com.ibm.websphere.objectgrid, 
 com.ibm.websphere.objectgrid.plugins.osgi, 
 com.ibm.websphere.objectgrid.plugins, 
 com.ibm.websphere.xs.sample.airport.domain