Expand Collapse
Just a second...

Upgrading from version 5.5 to version 5.6

Consider the following information when upgrading from Diffusion™ version 5.5 to version 5.6.

Upgrading your applications

Server-side components

Recompile all Java™ application components that are deployed to the Diffusion server, such as publishers and authorization handlers, against the new version diffusion.jar file. This file is located in the lib directory of your new Diffusion server installation.

Some features that your Java application components might use have been removed or deprecated. Pay attention to new deprecation warnings and compilation failures that occur during recompilation and review the API changes information in the following section to see if these changes affect your applications.

Clients

You can choose not to recompile your client applications and continue to use client libraries from a previous release. If you choose to use client libraries from a previous release, ensure that the libraries are compatible with the new server. For more information, see Interoperability.

You can choose to upgrade your client applications to use the new client libraries. To do this, recompile the client applications against the client libraries located in the clients directory of your new Diffusion server installation and repackage your client application with the new library.

Alternatively, the Java library is available in the Push Public Maven Repository and the JavaScript® library from NPM.

Some features that your client applications might use have been removed or deprecated. Review the API changes information in the following section to see if these changes affect your applications.

API changes

Further information about removed or deprecated features is available in following locations:
The following table lists API classes and methods that have been removed. If you attempt to recompile application code that uses these classes or methods against the version 5.6 APIs, it fails. Rewrite your application code to not include these features.
Table 1. API features removed in version 5.6
API affected Removed feature Suggested alternative
Java Methods that navigate up from a configuration item to its parent configuration item.

This excludes the getServerConfig method in ReplicationConfig, which is only deprecated at this release.

 Instead navigate down from the root configuration item.
Java Methods that navigate up from a configuration item to its parent configuration item. Instead navigate down from the root configuration item.
.NET Unified API The IRecordContentReader.HasMore property. The HasMoreFields() or HasMoreRecords() methods.
Publisher API Topic fetch handlers. Applications can provide fetch results for stateless topics using the Publisher.fetchForClient() API.
The following table lists API classes and methods that have been deprecated. If your application code uses these classes or methods, consider rewriting your application code to not include these features.
Table 2. API features deprecated in version 5.6
API affected Deprecated feature Suggested alternative
Unified API API The setSessionDetailsListener, setSessionDetails, and getSessionDetails in ClientControl Use a session properties listener instead.
Java The getServerConfig method in ReplicationConfig Accessors for the parent configuration object are no longer used. Instead navigate down from the parent configuration item.
Java Publisher API The Management class, which provided JMX Management utilities. Instead use methods available through the JVM runtime.
Java Publisher API All topic locking methods and associated properties. TopicProperty.LOCKABLE, TopicProperty.LOCK_TIMEOUT, TopicData.lock(), TopicData.unlock(), TopicData.isLockedByCurrentThread(), Topic.isLockable(), Topic.lock(), Topic.unlock(), Topic.isLockedByCurrentThread(), Topic.setLockTimeout(), and Topic.getLockTimeout() Topic locking is handled implicitly for stateless topics. Stateful topics can be updated transactionally. This transactional mechanism manages the topic locks.
Java Publisher API Publisher.publishMessage() methods and Publisher.publishExclusiveMessage() For stateless topics, use Topic.publishMessage(). For stateful topics (those with topic data), use PublishingTopicData.publishMessage().
Java Publisher API TopicStatistics.getInboundMessageStatistics() None.
Java Publisher API Client.getFetchReply(), TopicClient.sendFetchReply() This change is part of deprecating fetch for stateless topics. Publisher.fetchForClient()
The following list includes behavior that has changed in the API. If your application code relies on the previous behavior, rewrite your application code to take into account the new behavior.
  • In the C Unified API, the session_create_async() no longer returns a session object. To prevent the creation of an invalid pointer The method now returns NULL regardless of success or failure.

    Instead retrieve the session object on_connected callback passed to session_create_async().

  • On Java Unified API clients, new tasks that cannot be added to the inbound thread pool queue because the queue is full block until there is space for them on the queue. This is a change in behavior, as previously the calling thread ran the task instead of blocking, resulting in out of order processing.

    Java clients that run more than one client session within the same JVM must increase their inbound thread pool queue size to at least 3 times the number of sessions.

  • In the Publisher API, the TopicClient.subscribe() and TopicClient.unsubscribe() methods now return false or an empty list, depending on their return type. In future releases, the return type of the TopicClient.unsubscribe() methods will be void.
  • In the Publisher API, the Topic.publishMessage() methods now enforce an order to topic updates made using stateless topics. In previous releases, it was possible for clients to receive updates through stateless topics in different orders.
  • In the Publisher API, the Topic.publishMessage() methods now check whether the topic is deleted before publishing to it. If the topic is deleted, the method throws an exception.
  • In the Publisher API, the Topic.publishMessage() methods print a warning to the log file if they are used to update stateful topics, which are topics with topic data. In future releases, using Topic.publishMessage() methods this way will cause an exception.
  • In the Publisher API, the PublishingTopicData.publishMessage() methods print a warning to the log file if they are called outside of an update block. In future releases, using PublishingTopicData.publishMessage() methods this way will cause an exception.
  • All inbound message statistics now have a value of -1. Topic inbound message statistics are disabled and all related methods deprecated.
  • Changes to how the number of subscribers to a topic are counted. Each subscription by another Diffusion server using either fan-out replication or high-availability replication is counted in the total number of subscribers to a topic.

Upgrading your server installation

Note:

At release 5.6, the Diffusion server is tested and supported on Java HotSpot™ Development Kit 8 (latest update).

The Diffusion server also runs on Java HotSpot Development Kit 7. However, Oracle® withdrew support for Java 7 in April 2015. We recommend that you move to the latest update of Java 8 as soon as possible.

To upgrade your Diffusion server installation, complete the following steps:
  1. Use the graphical or headless installer to install the new version of Diffusion.

    For more information, see Installing the Diffusion server.

  2. You can copy your existing license file from your previous installation to the etc directory of your new installation.
  3. You can copy most of your existing configuration files from the etc directory of your previous installation to the etc directory of your new installation. When you do, consider making the following changes:
    • In the Server.xml configuration file, replace the <multiplexers> element and its child elements with the <multiplexer> element and its child elements.

      The <multiplexers> element is deprecated and will be removed in a future release. For more information, see Server.xml.

Behavior changes at the Diffusion server

The following list includes behavior that has changed at the server. If your solution relies on the previous behavior, adjust your solution to take into account the new behavior.

This page last modified: 2016/10/05