Expand Collapse
Just a second...

Upgrading from version 5.1 to version 5.5

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

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.

Event publishers

The event publisher APIs have been removed. Reimplement your event publisher as a client using the Unified API control features. For more information, see .

JMS adapter

The legacy JMS adapter has been deprecated and replaced with a new version. These JMS adapters are not compatible.

To move to the latest JMS adapter, use the JMSAdapter.xml configuration file to configure the behavior. Refer to the provided XML and XSD file because the configuration has changed since the previous version. For more information, see JMSAdapter.xml.

Note: Not recommended: To continue using the legacy JMS adapter, version 5.1, rename the JMSAdapter.xml configuration file used with the previous versions of Diffusion to JMSAdapter51.xml.
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.

Note: Java clients: When you recompile your Java clients with the new version of the libraries, be aware that the Diffusion log framework is no longer included in the Java client library. Applications should add an SLF4J implementation to their classpath, such as Logback, Log4j 2, or the SLF4J bridge to java.util.Logging.
Note: .NET clients: When you recompile your .NET clients with the new version of the libraries, be aware that the latest .NET client libraries require version 4.5 or later of the .NET Framework. In addition, only a single Diffusion DLL is now required to compile a Diffusion .NET client. For more information, see .NET.

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.5 APIs, it fails. Rewrite your application code to not include these features.
Table 1. API features removed in version 5.5
API affected Removed feature Suggested alternative
Event Publisher API All Use the Unified API.
Java API getConflation method on RootConfig getConflation method on ServerConfig
.NET Classic API Credentials V4Credentials This change was made to disambiguate between the credentials object in the Classic API and that in the 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.5
API affected Deprecated feature Suggested alternative
Java Unified API, .NET Unified API, C Unified API Session.start() and the associated 'initialising' state. Now a no-op. The asynchronous 'open' method on SessionFactory which has callback to notify session opened (or error).
Java Classic API Client.setCredentials(), Client.getCredentials() None
Publisher API AuthorisationHandler.credentialsSupplied() None
Java Unified API TopicSubscriptionHandler Use routing topics instead
Publisher API XMLPropertiesListener, XMLProperties None
Publisher API MultiplexerConfig.getLoadBalancer() and MultiplexerConfig.setLoadBalancer() None

These methods enable you to specify the load balancing policy for multiplexers. Previously, round robin and least clients policies were available. In future, only the default, round robin, policy will be provided.
Java API com.pushtechnology.com.api.config.ManagementUserConfig and related methods in com.pushtechnology.com.api.config.ManagementConfig Instead use the system authentication store or a custom authentication handler to configure remote Java Management Extensions (JMX) users.
.NET API Session.getFetchFeature and the Fetch feature Session.getTopicFeature. The fetch capabilities are included in the Topics feature.
.NET API, Java API Headers interface ReceiveContext.getHeaderList() and SendOptions.headers(List<String>). Headers are now represented in the API as a list of Strings. .
Java API RootConfig.getMessageLengthSize, RootConfig.setMessageLengthSize These methods are both deprecated and no-ops. The message length size is now hard-coded to 4 bytes.
Publisher API TopicProperty.AUTO_SUBSCRIBE property. This is ignored. Auto-subscribe is always true. None
Unified API ClientControl.close methods that include a String reason parameter Use ClientControl.close methods that do not include this parameter.

The reason parameter is not passed to the client being closed. If you want to notify the client being closed of the reason for its closure, use the MessagingControl feature to send a message to the client. To ensure that the message is received before closing the client session, wait for callback to return before calling ClientControl.close.
Configuration API WriteSelectorConfig This is ignored. Write selectors have been unified with other types of selector. SelectorThreadPoolConfig All selectors are now drawn from the selector thread pool.
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.
  • You can now create a SessionId object from the session ID String in the Java Unified API and .NET Unified API.
  • The result of calling the AuthorisationHandler.canWrite() is no longer cached. If an authorisation handler is registered, it is called every time a client sends a message to the server.
    Note: We recommend you use role-base security instead of authorisation handlers.
  • Auto-subscription is enabled for every topic and cannot be disabled. If a client attempts to subscribe to a topic that does not exist, the subscription request is saved and when the topic is created, the client is automatically subscribed to the topic.
  • The Publisher.subscription() method no longer sends a load message for a topic that has state. When a topic with state — that is, a topic whose data type is not TopicDataType.NONE — is first subscribed to, the topic load message is sent before Publisher.subscription() is called. The default implementation of the Publisher.subscription() method does nothing.
  • Topic loaders are only called for topics that have no state — that is, topics whose data type is TopicDataType.NONE.
  • SlaveTopicData no longer extends PublishingTopicData.
  • Updates to slave topics no longer update the master topic.
  • Changes to how the number of subscribers to a topic are counted:
    • Slave topics only count subscriptions made directly to the slave topic.

      In previous releases, subscriptions to the master topic and other slave topics of the same master were counted as subscriptions to a slave.

    • Master topics count all subscriptions made directly to the master topic and all subscriptions made indirectly through slave topics.
    • Topics subscribed to through a routing topic count both direct subscriptions to the topic and indirect subscriptions through the routing topic.
    These changes affect the return values from methods that query whether a topic has subscribers or the number of topic subscribers.
  • Classic API clients are no longer required to be subscribed to topic paths that they send messages on. However, a topic must exist at the topic path for a Classic API client to receive a message through the topic path.

    Classic API clients are still required to be subscribed to topic paths to receive messages on those topic paths.

Upgrading your server installation

Note:

At release 5.5, 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:
    • The structure of JMSAdapter.xml file has changed. Do not copy your existing JMSAdapter.xml file to the etc directory of your new installation. Instead copy it to etc/JMSAdapter51.xml. This change is because the legacy JMS adapter is deprecated and is replaced with a new version. For more information, see Configuring the JMS adapter
    • The SubscriptionValidationPolicy.xml configuration file is now deprecated. Use the roles and permissions provided in the new security model to define which clients can subscribe to which topics.
    • Configuring remote JMX users in the Management.xml configuration file is now deprecated. Instead use the system authentication store or a custom authentication handler to configure remote JMX users.
    • When configuring log levels in the Logs.xml configuration file, use the SLF4J log levels: ERROR, WARN, INFO, DEBUG, or TRACE. The java.util.Logging log level values (SEVERE, WARING, INFO, FINE, and FINEST) are still supported, but are deprecated.
    • You can now configure the format of the date in log file names in the Logs.xml configuration file by using the optional <date-format> element.
    • Configuring the multiplexer load balancing policy in the Server.xml configuration file is now deprecated. In future, only one load balancing policy will be provided for multiplexers: the default, round robin, policy.
    • In the Server.xml configuration file, when defining the file name of the GeoIP database file you must use an absolute path or a path relative to the Diffusion installation directory. Backwards compatibility with version 4.6 has been removed. You can no longer specify a path relative to the configuration directory.
    • The connector for port 8081 has been removed from the Connectors.xml configuration file. If your clients connect on this port, you must either configure this port in Connectors.xml or change the port that your clients connect on.
    • You are now required to configure a selector thread pool definition. Update your Server.xml configuration file to ensure that it includes this definition.
    • The write selector configuration in the Server.xml configuration file is deprecated and any configuration associated with write selectors is ignored. All selectors are now drawn from the same pool. Use the selector thread pool definition elements to define the number and behavior of selectors.

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.

  • The message fragmentation capability has been removed from Diffusion.

    Topic message fragmentation was intended to prevent head-of-line blocking by large messages. The API allowed messages for a given topic messages to be delivered out of order, which is incompatible with snapshot/delta processing.

    If you applied topic message fragmentation to work around the maximum message size limitations, particularly for large topic load messages, we recommend instead that you increase the maximum message size to accommodate the largest possible application message.

    Increasing the maximum message size to support large topic load messages will also require increasing the client input buffer and server output buffer sizes. The peak memory requirement is lower than needed when topic message fragmentation is enabled, but is approximately twice the maximum message size. In a future release, we will improve the buffer handling to allow the maximum message size to exceed the network buffer size.

    The default value of the input buffer size has been increased to 1M.

  • The default number of multiplexers has changed from 2 to the number of available processors.

  • Changes to how input buffers are allocated improve the performance and memory usage of the Diffusion server.

    Input buffers are no longer bound to clients, instead they are shared by all reading tasks. Where previously the number of connected clients defined the number of input buffers, now the maximum number of input buffers is bounded by the configured thread pool size.

    The maximum amount of memory used for input buffers is less than the thread pool size multiplied by the input buffer size plus any small memory usage resulting from partial reads.

  • It is possible to define a set of selector thread pools and have a connector refer to a member of this set name. If no pool is defined, each connector is assigned a default pool with size = 1.
  • Reconnection is enabled by default, with a reconnection timeout of 60 seconds. If you do not want client sessions to be able to reconnect, disable reconnect in the Connectors.xml configuration file.

    When reconnection is enabled, the Diffusion server continues to queue messages for a client session for the whole reconnection period. This can affect performance.

  • The etc directory of your Diffusion installation is no longer on the classpath. If you have included any files in the etc directory that you require to be on the classpath, ensure that these files are included in the classpath by other means:
    • Place resource files such as hazelcast.xml that must be on the Java Virtual Machine (JVM) system classpath in the data directory of the Diffusion installation.
    • Place resource files that are only loaded by deployed application code, such as publishers or authentication handlers, in the ext directory of the Diffusion installation.
  • Wrapper scripts for jstatd and jstack are no longer provided in the tools directory of your Diffusion server installation.
  • Messages sent on topic paths are no longer counted in the topic statistics. Only updates to the topic are counted.
  • The message length size is no longer configurable. In all cases it is hard-coded to 4 bytes. If you have earlier versions of the Diffusion server as part of your solution, ensure that their message length size is configured to be 4 bytes or the servers will not interoperate.
  • The names of the keystores provided in the Diffusion installation have changed.
    • publicKeys.store is now licence.keystore
    • keystore is now sample.keystore

    The start scripts provided by the Diffusion installation have been updated accordingly. If you use these scripts, you do not need to make any changes.

    If you start the Diffusion server from your own scripts, you must update them to take into account this change. Update the following property in the Java command that starts the server to point to the new keystore name: 
    -Ddiffusion.keystore.file=diffusion_installation/etc/licence.keystore

    If you start the server from a Java program and supply the keystore name as a VM arguments, update the VM to point to the new keystore name. For more information, see Running from within a Java application

  • The supported version of Google protocol buffers is now 2.6.1. In previous versions it was 2.4.1.
  • Due to the addition of the new JavaScript Unified API, the JavaScript API you might have been using with previous versions of Diffusion is now called the Classic API.

    The library for the JavaScript Classic API is now called diffusion-js-classic-version.js and the API documentation for it is now located in the js-classic folder of the documentation.

This page last modified: 2016/10/19