Migration Notes
If you are migrating from an earlier version of the product to a new version, there may be some migration issues that you should be aware of. Such issues are described in the document Installation and Upgrade Information for Software AG Products that is available on the Software AG documentation web site.
Additionally, we list some of the issues below.
Migrating queues that use the JMS engine from v9.x to v10.x
During the migration of Universal Messaging from version 9.x to version 10.x, any queues that were configured to use the JMS engine with version 9.x will be migrated successfully. However, from version 10.1 onwards, Universal Messaging doesn't support queues using the JMS engine. Therefore, on the first server restart in version 10.x, any queues that previously used the JMS engine will be permanently reconfigured to use the Universal Messaging default engine instead.
Migration of removed store types on v10.5 server startup
In Universal Messaging version 10.5, the store types Simple, Transient, Off-heap and Paged have been removed. If Universal Messaging v10.5 is installed to the same disk location as a previous version of the product, and there are any of these store types from the older version at this disk location, these store types will be mapped to other store types when the v10.5 server is started for the first time.
The mapping from removed store types to available store types is as follows:
Simple -> Reliable
Transient -> Reliable with a TTL (time to live) of 1 millisecond
Off-heap -> Reliable
Paged -> Mixed
For Paged stores, events might be persisted on disk and the Universal Messaging server is responsible for copying them to the migrated store. Please have in mind that this can lead to difference in the event IDs, but apart from that everything else will be available.
Also, note that there will be log entries for new stores being created and old ones being deleted.
Example
Assume we have a Paged channel called PagedChannel. This will be migrated to a channel of type Mixed via several steps :
1. A new temporary channel PagedChannel_new will be created as a copy of PagedChannel.
2. Events present on PagedChannel will be copied to PagedChannel_new.
3. The type of PagedChannel will be switched to MIXED.
4. Events will be copied from PagedChannel_new to PagedChannel, and PagedChannel_new will be removed.
The log entries will be like this:
[...] [main] Startup: Opening store PagedChannel_new
...
[...] [main] Startup: Opening store PagedChannel
...
[...] [main] Deleting store PagedChannel_new
[...] [main] Mixed-Store> junit2\data\StoreMigrationStandaloneTest100000_26010\
data\PagedChannel_new6716f746102986.mem : File has been deleted
[...] [main] Deleting store complete PagedChannel_new
For related information, see the section
What's New in Universal Messaging 10.5 that is specific to version 10.5.
Migration of client applications using the nNamedObject API
In v10.5, the previously deprecated nNamedObject-based API has been removed from the nChannel API. nNamedObject was used for coding applications that used durable types "Priority" and "Shared-Queued", and these durable types have also been removed in v10.5.
You will need to manually adapt any of your applications that used nNamedObject to use the nDurable API instead. The following table shows the mapping between nNamedObject and nDurable.
Type | NamedObject API | nDurable API |
Named Object | channels.createNamedObject(name, startEid, persistent, isClusterWide, false); | long startEid = startEID;
boolean isClusterWide = clusterWide;
nDurable named = null;
nDurableAttributes.nDurableType type = nDurableAttributes.nDurableType.Named;
if (enablePriority) {
type = nDurableType.Serial;
}
nDurableAttributes attr = nDurableAttributes.create(type, name);
attr.setPersistent(persistent);
attr.setClustered(isClusterWide);
attr.setStartEID(startEid);
try {
named = channels.getDurableManager().add(attr);
}
catch (nNameAlreadyBoundException exception) {
return channels.getDurableManager().get(name);
} |
Named Priority Durable | channels.createNamedObject(name, startEid, persistent, isClusterWide, true); | long startEid = startEID;
boolean isClusterWide = clusterWide;
nDurable named = null;
nDurableAttributes.nDurableType type = nDurableAttributes.nDurableType.Serial;
nDurableAttributes attr = nDurableAttributes.create(type, name);
attr.setPersistent(persistent);
attr.setClustered(isClusterWide);
attr.setStartEID(startEid);
try {
named = channels.getDurableManager().add(attr);
}
catch (nNameAlreadyBoundException exception) {
return channels.getDurableManager().get(name);
} |
Shared Named Object | channels.createSharedNamedObject(name, persistent, isClusterWide, startEid); | // create the shared durable using new implementation.
nDurableAttributes attr =
nDurableAttributes.create(nDurableAttributes.nDurableType.Shared, name);
attr.setPersistent(persistent);
attr.setClustered(isClusterWide);
attr.setStartEID(startEid);
// Need to check first in case shared durable already exists
try {
return channels.getDurableManager().get(attr.getName());
} catch (nNameDoesNotExistException ex) {
return channels.getDurableManager().add(attr);
} |
Deletion | channel. delNamedObject("myNamedObject") | channel.getDurableManager().delete("myDurable"); |
Deleting Local Stores when Migrating a Cluster to 10.11
When you migrate an active/active cluster that contains local stores to version 10.11, the local stores are deleted when you start the Universal Messaging 10.11 server instance for the first time.
In previous releases, it is possible to create non-cluster-wide stores in an active/active cluster. The stores are created with a cluster-wide flag set to false. These local stores exist only on the cluster node on which you created them and are not replicated to the other cluster nodes. Support for local stores has been removed in version 10.11 and they are deleted during migration.
You can obtain a list of all deleted local stores as part of the following message in the nirvana.log server log file:
Unsupported store configuration - non clustered stores in a clustered environment.
The following stores will be removed:
<list of the deleted local stores>
If the local stores contain important data, you can republish events to the 10.11 server instances using the RepublishEventsFromOfflineFile tool.
For more information about using the tool, see
The RepublishEventsFromOfflineFile Tool.
Client Session Behavior During Cluster Failure
In version 10.11 and higher, Universal Messaging client, non-admin sessions in an active/active cluster are always terminated if the server to which the client application connects is not in a good cluster state, that is, either master or slave state.
Prior to Universal Messaging 10.11, you could use the DisconnectIfClusterFails flag to configure the behavior of client sessions when the server is not in a good cluster state. The DisconnectIfClusterFails flag has been removed in Universal Messaging 10.11.
Previously, if you set the flag to false and the server was not in a good cluster state, the session would remain active even though the server node was not part of the cluster at that moment. In 10.11, with the removal of support for local stores in an active/active cluster, the flag has become redundant.
Consider the following information:
Now client sessions always behave as if the
DisconnectIfClusterFails flag is set to
true.
Clients that had the
DisconnectIfClusterFails flag set to
false will experience more disconnected sessions if the cluster state of the server changes.
If the
DisconnectIfClusterFails flag is set to
false in lower-version clients that connect to Universal Messaging servers version 10.11 or higher, the flag is ignored and the session behaves as if the flag is set to
true.
This behavior is valid only for client session that use the UM Client API. Admin sessions, which use the UM Admin API, can connect to the server regardless of its cluster state.