Expand Collapse
Just a second...

Upgrading from version 4.x to version 5.1

Consider the following information when upgrading from Diffusion™ version 4.x to version 5.1.

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. Review the API changes information in the following section to see if these changes affect your applications.

Remote control

The remote control APIs are no longer supported. Reimplement your remote control as a control client using the Unified API control features. For more information, see and .

Event publishers

The event publisher APIs are deprecated. Reimplement your event publisher as a control client using the Unified API control features. For more information, see and .

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. 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 the release notes provided in the docs directory of your Diffusion installation.

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.1 APIs, it fails. Rewrite your application code to not include these features.
Table 1. API features removed in version 5.0 and 5.1
API affected Removed feature Suggested alternative

Java API

.NET API

 Remote control Reimplement your remote control applications as control clients using the Unified API.

For more information, see and .

Java API

 Methods in the APIProperties class:
  • setInboundThreadPoolSize
  • getInboundThreadPoolSize
 Use the ThreadsConfig class instead.

For more information, see Java Unified API documentation.
Android™ API Methods in the DiffusionClient class:
  • getCredentials
  • setCredentials
 Use the methods in ServerDetails or ConnectionDetails instead.

For more information, see Android Unified API documentation.
Java API MessageComparator interface and compareTo and equals methods on all Message classes. Use conflation policies instead.

For more information, see see Java Unified API documentation.
Java API TopicDetails class Use the TopicDefinition class instead.

For more information, see Java Unified API documentation.
Java API Methods in the ThreadsConfig class:
  • setWriterSelectors
  • getWriterSelectors
 No longer used and no alternative required.
Java API Management, Proxy, and ServerProxy interfaces No longer used and no alternative required.
Java API Publisher.consoleLogLevelChange No longer used and no alternative required.
Java API ThreadServer.getOutboundThreadPool  

Publisher API

Event Publisher API

 The capability to set the maximum queue size to -1, which specified an unbounded queue size, using Client.setMaximumQueueSize(). Set the maximum queue size value to a positive integer.
Java Classic API TopicFetchHandler Use the Publisher API or Unified 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.0 and 5.1
API affected Deprecated feature Suggested alternative
Java API Using authorization handlers for authentication and the AuthorisationHandler.canConnect method. Use authentication handlers instead.

For more information, see User-written authentication handlers.
Java API APIProperties class Use methods in the Utils or RootConfig classes instead.

For more information, see Java Unified API documentation.

Java API

.NET API

 Event publishers Reimplement your event publishers as control clients using the Unified API.

For more information, see and .
Java Client.getNumberOfMessagesSent and Client.getNumberOfMessagesReceived Use Client.getStatistics instead.

For more information, see Java Unified API documentation.
Java Methods that navigate up from a configuration item to its parent configuration item. Instead navigate down from the root configuration item.
Java MNode.getMessage No longer used and no alternative required.
Unified API

TopicUpdateControl.TopicSource

TopicUpdateControl.TopicSource.Default

TopicUpdateControl.TopicSource.Updater

TopicUpdateControl.UpdateSource

TopicUpdateControl.UpdateSource.Default

TopicUpdateControl.Updater
Java Unified API Messaging.Listener and associated methods Messaging.MessageStream
Java Unified API Topics.Listener and associated methods Topics.TopicStream
Java Unified API Updater.update() methods that take both Content and UpdateOptions as parameters Updater.update() methods that take Update as a parameter
Java Unified API comparator() and duplicatesPolicy() methods in the PagedTopicDetails.Builder class order(String), order(Duplicates, String), or unordered()
Java Unified API getComparator() and getDuplicatesPolicy() methods in the PagedTopicDetails.Attributes class getOrderingPolicy()
.NET Unified API All SetProperty() methods in the ISessionFactory class, where Property is the name of the value you want to change Property()
Unified API The autoSubscribe method in the TopicDetails.Builder interface. In future, auto-subscribe is always true. None
JavaScript® Classic API The functions setCrypted() and getCrytped() setEncrypted() and isEncrypted()
Java Server API The functions getStartTimeMillis(), getUptime(), and getUptimeMillis() on the c.p.d.api.topic.Subscription class You can use a publisher to get equivalent functionality.
Java Unified API All static fields in the c.p.d.client.types.Constants class These fields are now available in the c.p.d.client.content.Record class.
Java Unified API, .NET Unified API RecordContentReader.hasMore() RecordContentReader.hasMoreRecords(), RecordContentReader.hasMoreFields()
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.
  • The Publisher API methods that add topics no longer block until automatic pre-emptive subscriptions have been processed. Matching pre-emptive subscriptions are be completed in the background.
  • The Java API now enables you to set auto-subscribe using a TopicDefinition
  • The format of the generated client IDs has changed
  • getStatistics no longer returns null if statistics recording is disabled. Instead it returns a value of -1.
  • Clients that subscribe to topics that they are already subscribed to, no longer receive an initial topic load.
  • An anonymous user (a user with an empty string as username) cannot authenticate with a password. If a client provides a password but no username or an empty username, the authorization handler cannot retrieve the password from the getCredentials() method.
  • The UpdateSource API that replaces the TopicSource API in the Unified API behaves in a very similar way, but has some differences.
    • UpdateSource includes an onRegister callback, which provides a RegisteredHandler that the client can use to deregister as an update source. Previously, TopicSource only provided the ability to deregister as an update source to the client that was the active update source.
    • UpdateSource includes an onError callback, which indicates to a client when an update source is prematurely closed.
    • Updaters do not accept an UpdateOptions object as a parameter. Instead an Update object is used to contain the update content and any additional information about the update.
    For more information about how update sources work, see Updating topics.
  • In the Unified API, the logging level at which the Topics.Listener.Default logs updates has changed from "warn" to "debug".
  • In the Unified API, topic and messaging listeners are called in the order that they were registered. In previous releases, these listeners might have been called in any order.
  • In the Unified API, you must set a fallback topic or messaging listener explicitly. In previous releases, a fallback topic or messaging listener was set by default.
  • In the Unified API, a notification occurs for any type of selector that does not match with any topics. In previous releases, a missing topic notification occurred only if a topic path selector was used for subscribe or fetch and there was no such topic.
  • In the Unified API, you can add multiple session listeners and remove session listeners. In previous releases, you could add only one session listener.

Upgrading your server installation

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 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 WebServer.xml configuration file for your production installation, remove or comment out the configuration for the HTTP deploy service.

      Access to this service is not restricted. If you enable the deploy service, you must restrict access to the deploy URL by other methods to prevent unauthorized or malicious access. For example, by setting up restrictions in your firewall.

    • Remove the writer-selector configuration from the Server.xml configuration file. Writer selectors are no longer used.
      Warning: Do not confuse writer selectors with write selectors.
    • If you now use authentication handlers for authentication, configure these handlers in the Server.xml configuration file.
    • If you now use the replication high availability features, configure these in the Replication.xml configuration file.
    • If you use the WhoIs service, but do not explicitly configure it, you must now configure the service in the Server.xml configuration file.

      In previous releases, if no configuration was specified for the WhoIs service, the service started with the default configuration. In this release, the service does not start unless configuration is present in the Server.xml configuration file.

    • In the Server.xml and Connectors.xml configuration files, if you have set maximum client queue depths to be unbounded (0), change these values. Unbounded outbound client queues are no longer allowed.
    The validation of the configuration files has been relaxed. The order of the element within the files is less strict.
  4. If you start the Diffusion server from your own scripts or Java programs, you must update them to take into account the following changes:
    • The Java license agent has been removed. Remove the following argument from the Java command you use to start the server: 
      -javaagent:../lib/licenceagent.jar=../etc/licence.lic,../etc/publicKeys.store
    • New system properties are required by the Diffusion server.
      Include the following properties in the Java command that starts the server: 
      -Ddiffusion.license.file=diffusion_installation/etc/licence.lic
-Ddiffusion.keystore.file=diffusion_installation/etc/publicKeys.store
-Ddiffusion.home=diffusion_installation/lib
      You can also supply these properties as VM arguments.

      For more information, see Running from within a Java application

    If you use the start scripts provided with the Diffusion installation, you do not need to make any changes.

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.
  • In previous releases, messages that required acknowledgment were prioritized over other messages. This might have caused ordering problems. From 5.1, messages that require acknowledgment are queued for sending in the order of receipt. You might have to increase your acknowledgment timeout value to allow for the additional queuing time.
  • The non-configurable 5s timeout between HTTP polls has been removed. Use <system-ping-frequency> for HTTP connectors.

This page last modified: 2016/10/05