Home


Upgrade and migrate WebSphere eXtreme Scale

Updating eXtreme Scale servers

You can upgrade WebSphere eXtreme Scale using the latest available release and maintenance package from the IBM support portal for WebSphere eXtreme Scale .

To upgrade without service interruption,

  1. Upgrade catalog servers
  2. Upgrade the container servers
  3. Upgrade client servers

To support enterprise data grid configurations, upgrade your transport mechanism from ORB to XIO. If you are not already using XIO, all of your servers and clients must be migrated to version 8.6 before you can switch to using the XIO transport. Your servers and clients can use the ORB transport while you are upgrading. When the upgrade is complete, you can move to XIO.

  1. Upgrade the catalog service tier, repeating the following steps for each catalog server in the data grid. Upgrade the catalog service tier before upgrading any container servers or clients. Individual catalog servers can interoperate with version compatibility, so you can apply upgrades to one catalog server at a time without interrupting service.

    1. Check for a healthy quorum status.

        xscmd -c showQuorumStatus

      This result indicates that all the catalog servers are connected.

    2. If you are using multi-master replication between two catalog service domains, dismiss the link between the two catalog service domains while you are upgrading the catalog servers.

        xscmd -c dismissLink -cep host:2809 -fd domain_name

      You only need to run this command from one of the catalog service domains to remove the link between two catalog service domains.

    3. Shut down one of the catalog servers. Use the stopOgServer or stopXsServer command, the xscmd -c teardown command, or shut down the application server running the catalog service in WebSphere Application Server. There are no requirements for the order in which you stop the catalog servers, but shutting down the primary catalog server last reduces turnover. To determine which catalog server is the primary, look for the CWOBJ8106 message in the log files. Under normal conditions, quorum is maintained when a catalog server is shut down, but it is a best practice to query quorum status after each shutdown with the xscmd -c showQuorumStatus command.

      If you use the xscmd -c teardown command, you can filter the server names. The stopOgServer or stopXsServer command requires an exact server name or list of server names to stop in parallel to be entered. You should group the shutdown process instead of calling the stop or teardown process for many servers in parallel. By grouping the servers to be shut down, the data grid can react to the servers that are being shut down by moving shards around the data grid. Use one of the following commands to shut down your servers:

      You can provide a specific list of servers to stop to the stopOgServer or xscmd -c teardown commands:

        stopOgServer <server_name>[,<server_name>]
        stopXsServer <server_name>[,<server_name>]
        xscmd -c teardown -sl <server_name>[,<server_name>]

      With the previous examples, the stopOgServer or stopXsServer, or xscmd -c teardown commands are completing the same shutdown tasks.

      You can filter the servers to stop using xscmd -c teardown, which can filter out the matching servers and ask if the selected servers are correct.

    4. Install the updates on the catalog server. You can either migrate the catalog server to a new major release of the product or apply a maintenance package.

    5. Update the JAVA_HOME environment variable to point to a supported Java Development Kit (JDK) installation.

    6. Restart the catalog server.

      If you are using a stand-alone environment, see Start a stand-alone catalog service that uses the ORB transport or Start a stand-alone catalog service that uses the IBM eXtremeIO (XIO) transport for more information. If you are using a WebSphere Application Server environment, see Start and stopping servers in a WebSphere Application Server environment for more information.

      The catalog server runs in compatibility mode until all the catalog servers are moved to the same level. Compatibility mode mostly applies to major release migrations because new functions are not available on the servers that are not migrated. No restrictions exist on how long catalog servers can run in compatibility mode, but the best practice is to migrate all catalog servers to the same level as soon as possible.

    7. Apply updates to the remaining catalog servers in the configuration.

  2. Upgrade the container servers, repeating the following steps for each container server in the data grid. You can upgrade container servers in any order. However, consider updating the servers first, then the clients, if you are using new functions in the upgrade.

    1. Stop the container servers to upgrade. You can stop the container server tier in groups with the stopOgserver or stopXsServer command or the teardown command. By batching teardown operations and running start server operations in parallel, the placement mechanism can move shards in larger groups.

      xscmd -c teardown -z false Zone 
      Connecting to Catalog service  at localhost:1099
      
      Processing filter options for Server teardown 
      The following servers will be torn down: 
      
        container00
        container01
        container02
        container03
        container04
      
      
      Do you want to tear down the listed servers? (Y/N)

    2. Install the updates on the container servers . You can either migrate the container servers to a new major release of the product or apply a maintenance package.

    3. Update the JAVA_HOME environment variable to point to a supported Java Development Kit (JDK) installation.

    4. Restart your container servers .

    5. Upgrade any remaining container servers in the configuration.

  3. If you are using multi-master replication, reconnect the catalog service domains. Use the xscmd -c establishLink command to reconnect the catalog service domains.

      xscmd -c establishLink -cep host:2809 -fd dname -fe fdHostA:2809,fdHostB:2809

  4. To check that all servers are using the new version of WXS, run xscmd -c showinfo

      xscmd -c showinfo


What to do next

Migrate to WebSphere eXtreme Scale Version 8.6

With the WebSphere eXtreme Scale installer, you cannot upgrade or modify a previous installation. You must uninstall the previous version before you install the new version. You do not need to migrate the configuration files because they are backward compatible. However, if you changed any of the script files that are shipped with the product, reapply these changes to the updated script files.

Verify that your systems meet the minimum requirements for the product versions you plan to migrate and install.

Merge any modified product script files with new product script files in the /bin directory to maintain your changes.

If you did not modify the script files that are installed with the product, you are not required to complete the following migration steps. Instead, you can upgrade to Version 8.6 by uninstalling the previous version and installing the new version in the same directory.

  1. Stop all processes that are using WebSphere eXtreme Scale.

    • Stop all processes running in your stand-alone WebSphere eXtreme Scale environment.
    • Read about command-line utilities to stop all processes running in your WebSphere Application Server or WebSphere Application Server Network Deployment environment.

  2. Save any modified scripts from your current installation directory to a temporary directory.

  3. Uninstall the product.

  4. Install WebSphere eXtreme Scale Version 8.6.

  5. Merge your changes from the files in the temporary directory to the new product script files in the /bin directory.

  6. Start all of the WXS processes to begin using the product.

Updating WebSphere eXtreme Scale on WebSphere Application Server

When you migrate WebSphere Application Server to a new version, you can also migrate the WebSphere eXtreme Scale configuration to the new WebSphere Application Server installation.

When you install a new version of WebSphere Application Server that has WebSphere eXtreme Scale integration, you first upgrade WebSphere Application Server with the normal process. Then, install the new version of WXS on your new installation. Then, you can use the xsmigration script to move the WebSphere eXtreme Scale configuration information to the new WebSphere Application Server installation.

  1. Migrate the dmgr-related configuration from Version 7 to Version 8.

    1. Run the WebSphere Application Server backup script (WASPreUpgrade command)

    2. Stop the dmgr.

    3. Access the dmgr server in the WXS configuration and run the migration script.

        cd $ROOT_WAS8/bin 
        ./xsmigration.sh -targetwashome $WAS8_HOME  \
                       -sourcewashome $WAS_HOME  \
                       -targetprofilepath $DMGR_PROFILE_WAS8 \
                       -sourceprofilepath $DMGR_PROFILE_WAS7
        

        ...where...

        WAS8_HOME Location of WAS v 8.x appserver Example: /opt/IBM/WebSphere8
        WAS_HOME Location of WAS v 7.x appserver: /opt/IBM/WebSphere7
        DMGR_PROFILE_WAS8 Location of WAS v 8.x dmgr profile. Example: /opt/IBM/WebSphere8/profiles/Dmgr01
        DMGR_PROFILE_WAS7 Location of WAS v 7.x dmgr profile. Example: /opt/IBM/WebSphere7/profiles/Dmgr01

  2. Migrate the application server related configuration from Version 7 to Version 8.

      cd ROOT_WAS8/bin
      ./xsmigration.sh -targetwashome $WAS8_HOME  \
                       -sourcewashome $WAS_HOME  \
                       -targetprofilep$ath $PROFILE_WAS8 \
                       -sourceprofilepath $PROFILE_WAS7 
      

      where

      WAS8_HOME Location of WAS v 8.x appserver Example: /opt/IBM/WebSphere8
      WAS_HOME Location of WAS v 7.x appserver: /opt/IBM/WebSphere7
      PROFILE_WAS8 Location of WAS v 8.x appserver profile. Example: /opt/IBM/WebSphere8/profiles/AppServer01
      PROFILE_WAS7 Location of WAS v 7.x appserver profile. Example: /opt/IBM/WebSphere7/profiles/AppServer01

  3. Restart the WAS v 8 dmgr and synchronize all the managed nodes.

xsadmin tool to xscmd tool migration

In previous releases, the xsadmin tool was a sample command-line utility to monitor the state of the environment. The xscmd tool has been introduced as an officially supported administrative and monitoring command-line tool. If you were previously using the xsadmin tool, consider migrating your commands to the new xscmd tool.


xsadmin and xscmd command equivalents

xsadmin xscmd xscmd parameters
-bp

  • -cep hostname:listener_port
  • --catalogEndpoint hostname:listener_port

n/a
-ch

  • -cep hostname:listener_port
  • --catalogEndpoint hostname:listener_port

n/a
-clear -c clearGrid -g, -ms, -v, -m, (-cep)
-containers

  • -c showPlacement -containercontainerName
  • -c showPlacement -server serverName

-e, -i, , -st, -snp, -ct, -s, -p, -hf, -z, -g, -m, -ms
-continuous n/a n/a
-coregroups

  • -c listCoreGroupMembers -cg core_group

n/a
-dismissLink <catalog_service_domain> -c dismissLink

  • -fd <foreignCatalogServiceDomain>
  • --foreignCatalogServiceDomain <foreignCatalogServiceDomain>

-dmgr n/a - this argument is automatically determined with xscmd n/a
-empties arg specific to a new command n/a
-establishLink <foreign_domain_name> <host1:port1,host2:port2...> -c establishLink

  • -fd <foreignCatalogServiceDomain> -fe <host1:port1,host2:port2...>
  • --foreignCatalogServiceDomain <foreignCatalogServiceDomain> -foreignEndPoints <host1:port1,host2:port2...>

-fc

  • -ct
  • --container

n/a
-fh

  • -hf
  • --hostFilter

n/a
-fm

  • -m
  • --map

n/a
-fnp

  • -snp
  • --serversWithNoPrimaries

n/a
-fp

  • -p
  • --partitionId

n/a
-fs

  • -s
  • --server

n/a
-fst

  • -st <shard_type>
  • --shardType <shard_type>

Shard values: P=primary A=asyncReplica S=syncReplica

n/a
-fz

  • -z
  • --zone

n/a
-force arg specific to a new command  
-g

  • -g
  • --objectGrid

n/a
-getstatsspec -c getStatsSpec n/a
-getTraceSpec -c getTraceSpec n/a
-h You can run help with or without a specific command name:

  • -h
  • --help
  • -h <command_name>
  • --help <command_name>

n/a
-hosts -c listHosts -g, -ms, -st, -c, -s, -hf, -z
-jmxUrl

  • -cep hostname:listener_port
  • --catalogEndpoint hostname:listener_port

n/a
-l -c listObjectGridNames n/a
-m

  • -ms
  • --mapSet

n/a
-mapsizes -c showMapSizes -g, -ms, -i, [-ct, -z, -s, -hf, sht [P,A,S], -p]
-mbeanservers -c listAllJMXAddresses n/a
-overridequorum -c overrideQuorum n/a
-password

  • -pwd
  • --password

n/a
-p

  • -cep hostname:listener_port
  • --catalogEndpoint hostname:listener_port

n/a
-placementStatus -c placementServiceStatus -g, -ms
-primaries -c showPlacement -sf P -e, -i, , -st, -snp, -ct, -s, -p, -hf, -z, -g, -m, -ms
-profile To save the current security settings as a security profile:

  • -ssp profile_name
  • --saveSecProfile profile_name

To use a specified security profile:

  • -sp profile_name
  • --securityProfile profile_name

 
-quorumstatus -c showQuorumStatus n/a
-releaseShard <container_server_name> <objectgrid_name> <map_set_name> <partition_name> -c releaseShard -c, -g, -ms, -p
-reserved

  • -sf R
  • --shardFilter R

n/a
-reserveShard <container_server_name> <objectgrid_name> <map_set_name> <partition_name> -c reserveShard -c, -g, -ms, -p
-resumeBalancing <objectgrid_name> <map_set_name> -c resumeBalancing -g, -ms
-revisions -c revisions -s,-p,-g,-m
-routetable -c routetable -z, -hf,-p,-g,-ms
-settracespec <trace_string> -c setTraceSpec -spec <trace_string>
-swapShardWithPrimary <container_server_name> <objectgrid_name> <map_set_name> <partition_name> -c swapShardWithPrimary -c -g, -ms, -p
-setstatsspec <stats_spec> -c setStatsSpec -spec <stats_spec>
-suspendBalancing <objectgrid_name> <map_set_name> -c suspendBalancing -g, -ms
-ssl

  • -ssl
  • --enableSSL

n/a
-teardown -c teardown -f, , -st, -snp, -c, -s, -p, -hf, -z, -g, -ms, -m
-triggerPlacement -c triggerPlacement -g, -ms
-trustPass

  • -tsp
  • --trustStorePassword

n/a
-trustPath

  • -ts
  • --trustStore

n/a
-trustType

  • -tst
  • --trustStoreType

n/a
-unassigned -c showPlacement -sf U -e, -i, , -st, -snp, -ct, -s, -p, -hf, -z, -g, -m, -ms
-username

  • -user
  • --username

n/a
-v

  • -v

  • --verbose

n/a
-xml -c showPlacement n/a

Configuring security profiles for the xscmd utility

Administering with the xscmd utility

Monitoring with the xscmd utility

Deprecated properties and APIs

The following list of properties and APIs were deprecated in the specified releases. Use the recommended migration action to determine how to update the configuration.

Deprecated items in Version 8.6

Table 1. Deprecated properties and APIs
Deprecation Recommended migration action

numberOfBuckets attribute

The numberOfBuckets attribute in the ObjectGrid descriptor XML file described the number of buckets for the BackingMap instance to use. When set to 0, the client near cache was disabled.

The numberOfBuckets attribute in the ObjectGrid descriptor XML file was replaced with the nearCacheEnabled attribute.

client-replicated maps

WebSphere eXtreme Scale clients can replicate maps. However, this function is deprecated, and therefore, not available in the XIO transport protocol of the Java client in Version 8.6. 

Use the continuous query function, instead, which is a superset of the replicated map capability. When you develop client applications that interact with the data grid, you might require queries that retrieve automatic, real-time results when new entries are inserted or updated.

Object Request Broker (ORB)

The Object Request Broker (ORB) is a transport used to communicate over a TCP stack. The ORB is dependent on all client applications being written in the Java programming language.
If you are using the ORB, consider migrating the configuration to use IBM eXtremeIO (XIO). XIO is a new transport mechanism that supports both Java and .NET client applications in an enterprise data grid .

INSERTUPDATE enumeration to the setPutMode

The setPutMode(PutMode.UPSERT) method is added to change the default behavior of the ObjectMap and JavaMap put() and putAll() methods to behave like ObjectMap.upsert() and upsertAll() methods.

The PutMode.UPSERT method replaces the setPutMode(PutMode.INSERTUPDATE) method. Use the PutMode.UPSERT method to tell the BackingMap and loader that an entry in the data grid needs to place the key and value into the grid. The BackingMap and loader does either an insert or an update to place the value into the grid and loader. If you run the upsert API within the applications, then the loader gets an UPSERT LogElement type, which allows loaders to do database merge or upsert calls instead of using insert or update.

startOgSever and stopOgServer commands

The startOgSever and stopOgServer commands are used to start and stop servers that use the ORB transport. If you are using XIO, you can no longer use these scripts to start your servers.
 If you are using the XIO transport, use the startXsSever and stopXsServer commands to start and stop your container and catalog servers.

wxs_home/ObjectGrid/legacy/session/bin

This file path location was used for session management scripts prior to WebSphere eXtreme Scale Version 7.1
.
If you are using the addObjectFilter script to augment your web application to use WebSphere eXtreme Scale for session management, then use the scripts at this location: wxs_home/ObjectGrid/session/bin. The previous location, wxs_home/ObjectGrid/legacy/session/bin, is now deprecated.

XIO container TCP secure and non-secure port properties

These ports were used to specify the listener port numbers of the IBM eXtremeIO transport on the server. You set these ports with the xioChannel.xioContainerTCPNonSecure.Port and xioChannel.xioContainerTCPSecure.Port properties in the server properties file.
You no longer need to specify these properties when you are using the XIO transport. The value specified by the listenerPort property in the server properties file is used.


Deprecated items in Version 8.5

Table 2. Deprecated properties and APIs
Deprecation Recommended migration action

WebSphereTransactionCallback

This plug-in was used to manage data grid transactions with enterprise applications that run in a WebSphere Application Server environment.

The WebSphereTransactionCallback interface has been replaced by the WebSphere eXtreme Scale resource adapter, which enables Java Transaction API (JTA) transaction management. You can install this resource adapter on WebSphere Application Server or other Java Platform, Enterprise Edition (Java EE) application servers. The WebSphereTransactionCallback plug-in is not an enlisted JTA API, and therefore, is not designed to roll back the JTA transaction if the commit fails.


Deprecated items in Version 7.1.1

Table 3. Deprecated properties and APIs
Deprecation Recommended migration action

com.ibm.websphere.objectgrid.plugins.builtins.TranPropListener class

This class was used to propagate successful ObjectGrid transaction commit processes to other WebSphere application servers hosting the same ObjectGrid instance, based upon the ObjectGrid name.

The TranPropListener interface has been replaced by the JMSObjectGridEventListener interface, which is a JMS-based implementation of the ObjectGridEventListener interface. It supports client-side, near cache invalidation and peer-to-peer replication.

com.ibm.websphere.objectgrid.plugins.OptimisticCallback class

This class was used to provide optimistic comparison operations for the values of a map.

The OptimisticCallback plug-in has been replaced by the ValueDataSerializer.Versionable interface, which you can implement when you use the DataSerializer plug-in with the COPY_TO_BYTES copy mode or when you use the @Version annotation with the EntityManager API.

com.ibm.websphere.objectgrid.plugins.NoVersioningOptimisticCallback plug-in

This plug-in was used for optimistic locking without doing version checking. With this built-in OptimisticCallback handler, the loader handled version checking, but optimistic locking was used to ensure that committed data is always returned on a read.

The NoVersioningOptimisticCallback interface extends the OptimisticCallback interface. Therefore, use the pessimistic locking strategy with a default transaction isolation of READ_COMMITTED or lower.

com.ibm.websphere.objectgrid.plugins.ObjectTransformer class

This plug-iin was used to serialize, deserialize, and copy objects into the cache.

The ObjectTransformer interface has been replaced by the DataSerializer plug-ins , which you can use to efficiently store arbitrary data in WebSphere eXtreme Scale so that existing product APIs can efficiently interact with your data.

com.ibm.websphere.objectgrid.BackingMap.setMapEventListeners method

This method was used to set the list of MapEventListener objects.

Use either the addMapEventListener(EventListener) or removeMapEventListener(EventListener) methods to add or remove event listeners from a backing map.

com.ibm.websphere.objectgrid.ObjectGrid.setEventListeners method

This method was used to overwrite the current list of ObjectGridEventListener objects and replace it with the supplied list of ObjectGridEventListeners objects.

Use either the addEventListener(EventListener) or removeEventListener(EventListener) methods to add or remove event listeners or life cycle listeners from the data grid.


Stabilized features in Version 7.1.1

If a feature is listed as stabilized, IBM does not currently plan to deprecate or remove this capability in a subsequent release of the product; but future investment will be focused on the alternative function. Users do not need to change any existing applications and scripts that use a stabilized function; but they should consider using the strategic alternative for new applications.

Table 4. Deprecated properties and APIs
Stabilized feature Recommended migration action

xsadmin

The xsadmin utility is provided as a sample of how you can create custom utilities for the deployment.

Use the xscmd utility to complete administrative tasks in the environment such as: establishing multi-master replication links, overriding quorum, and stopping groups of servers with the teardown command.


Deprecated items in Version 7.1

Table 5. Deprecated properties and APIs
Deprecation Recommended migration action

catalog.services.cluster cell and server property: This custom property was used to define a group of catalog servers in the WebSphere Application Server configuration.

This custom property is deprecated starting in the Version 7.1 release.

Create a catalog service domain in the WebSphere Application Server administrative console, which creates the same configuration as using the custom property.

CoreGroupServicesMBean MBean and interface

This MBean is deprecated starting in the Version 7.1 release.

Use the CatalogServiceManagementMBean instead.

ServerMBean.updateTraceSpec() MBean operation

This operation is deprecated starting in the Version 7.1 release.

Use the TraceSpec attribute on the DynamicServerMBean instead.

CoreGroupServicesMBean MBean

This MBean is deprecated starting in the Version 7.1 release.

Use the CatalogServiceManagementMbean MBean instead.

ServiceUnavailableException exception

This exception is deprecated starting in the Version 7.1 release.

Use the TargetNotAvailableException exception instead.

 

The capabilities of WPF can be alternatively realized in WebSphere eXtreme Scale.

StreamQuery: A continuous query over in-flight data stored in ObjectGrid maps.

None

Static grid configuration: A static, cluster-based topology using the cluster deployment XML file.

Replaced with the improved, dynamic deployment topology for managing large data grids.

Deprecated system properties: System properties to specify the server and client properties files are deprecated.

You can still use these arguments, but change your system properties to the new values.

-Dcom.ibm.websphere.objectgrid.CatalogServerProperties

The property was deprecated in WebSphere eXtreme Scale Version 7.0. Use the -Dobjectgrid.server.props property.

-Dcom.ibm.websphere.objectgrid.ClientProperties

The property was deprecated in WebSphere eXtreme Scale Version 7.0. Use the -Dobjectgrid.client.props property.

-Dobjectgrid.security.server.prop

The property was deprecated in WebSphere eXtreme Scale Version 6.1.0.3. Use the -Dobjectgrid.server.prop property.

-serverSecurityFile

This argument was deprecated in WebSphere eXtreme Scale Version 6.1.0.3. This option is passed into the startOgServer script. Use the -serverProps argument.

Removed properties and APIs

If you are migrating the configuration from an earlier release of WXS, some features might be removed from this and earlier releases. Use the recommended migration action to determine how to update the configuration.

If a feature is listed as deprecated in Deprecated features , IBM might remove this capability in a subsequent release of the product. Future investment will be focused on the strategic function listed under Recommended Migration Actions in Deprecated features. Typically, a feature is not removed until at least two major releases or three full years (whichever time period is longer) after the release in which that feature is deprecated. In rare cases, it might become necessary to remove features sooner; such cases are indicated clearly and explicitly in the descriptions of these deprecated features in Deprecated features .

The following information describes removed features, APIs, scripting interfaces, tools, and publicly exposed configuration data. Where possible, the recommended replacement is identified.


Removed items in Version 8.5

Table 1. Removed properties and APIs
Removed item Recommended migration action

Keyword support: Keywords are string tags that can be applied to cache entries and later queried using ObjectMap API methods.

Use the index or query function to get objects with specific attributes.

MapAuthorization interface: This plug-in was used to authorize ObjectMap and JavaMap to access the principals that were represented by a subject object.

Use ObjectGridAuthorization to plug in authorization implementations. An ObjectGridAuthorization can be used to authorize permissions to ObjectGrid, ObjectMap, and JavaMap accesses.

WebSphere partitioning facility (WPF): The partitioning facility is a set of programming APIs that allowed Java EE applications to support asymmetric clustering.

You can configure partitioning with WebSphere eXtreme Scale.

StreamQuery: A continuous query over in-flight data stored in ObjectGrid maps.

None