Expand Collapse
Just a second...

Upgrading from version 5.x to version 6.0

Consider the following information when upgrading from Diffusion™ version 5.x to version 6.0.

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
Note:

The Classic API has been removed and is no longer supported. To upgrade your solution to use Diffusion version 6, you must create clients that use the Unified API.

From this point onward all references to clients are to Unified API 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.

The minimum supported framework or platform version for a number of our client libraries has changed:
  • Java client must use Java 8 or above (minimum update 1.8.0_131-b11).

The C client now depends on zLib. Ensure that you have zLib version 1.2 or later available on your development system and add -lz to the LDFLAGS in your Makefile. For more information, see http://www.zlib.net.

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 6.0 APIs, it fails. Rewrite your application code to not include these features.
Table 1. API features removed in version 6.0
API affected Removed feature Suggested alternative
Classic API Every Classic client API Rewrite your clients to use the API
All APIs Methods and classes related to removed topic types, see Removed components. Use alternative topic types.
All APIs Methods and classes related to removed transport protocols, see Removed components. Use alternative transport protocols.
Apple® API All methods that use content when creating and interacting with topics and messages. Equivalent methods that use value.
Apple API PTDiffusionSessionErrorHandler The error property on PTDiffusionSessionState
Apple API diffusionTopicStream:didUnsubscribeFromTopicPath:reason: in PTDiffusionTopicStreamDelegate diffusionStream:didUnsubscribeFromTopicPath:reason:
Apple API removeTopicStream: in PTDiffusionTopicsFeature removeStream:
.NET API The SetSessionDetailsListener, SetSessionDetails, and GetSessionDetails in IClientControl Use a session properties listener instead.
.NET API Session.Start method and the CONNECTED_INITIALISING and RECOVERING_FAILOVER states None
Java API The setSessionDetailsListener, setSessionDetails, and getSessionDetails in ClientControl Use a session properties listener instead.
Java 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.
Java API Topics.removeTopicStream method Topics.removeStream method
Java API TopicControl.removeTopics method TopicControl.remove method
Java API sendFetchReply method None
Java API Session.start method and the CONNECTED_INITIALISING and RECOVERING_FAILOVER states None
Java API SessionClosedException exception thrown from synchronous methods.  
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 6.0
API affected Deprecated feature Suggested alternative
Apple API PTDiffusionTopicDetails PTDiffusionTopicSpecification
Apple API sendWithTopicPath sendWithPath
Java API Messaging.getStreamsForTopic None
Java API TopicDetails TopicSpecification
.NET API IMessaging.GetStreamsForTopic None
.NET API ITopicDetails ITopicSpecification
JavaScript® API TopicDetails TopicSpecification
All APIs Setting headers on one-way messages Send information in the message body instead. Note this only applies to the legacy one-way messaging. Custom headers are not supported for request-response messaging.
Publisher API Unused values in TopicProperty: LOAD_ENCODING, DELTA_ENCODING, LOAD_HEADERS, LOAD_ACK_REQUIRED, DELTA_ACK_REQUIRED. Methods in PublishingTopicData that get and set these values. None
Configuration API ServerStatisticsConfig None
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.
  • Java API methods throw a NullPointerException when a null value is provided for a non-optional parameter. In previous releases, an IllegalArgumentException was thrown.
  • Slave topics created by the client API no longer require that the master topic exists when the slave topic is created. The behavior of slave topics created by the Publisher API remains unchanged.
  • Slave topics created by the client API are no longer removed when the master topics they are linked to are deleted. The behavior of slave topics created by the Publisher API remains unchanged.
  • If a client session selects a set of topics to remove, all those that the session has permission to remove are removed. This is a change from the previous behavior, where the remove operation failed if the session did not have permission for one or more of the selected topics.
  • "Remove with session" now removes only those topics that the session has permission to remove at the time the session closes. Previously, "remove with session" was able to remove all topics in a branch if the session had remove permission at the branch path.
  • The client API can no longer remove topics created using the Publisher API and the Publisher API can no longer remove topics created using the client API.
  • The Publisher API no longer supports message filters. It is no longer possible to filter topic updates on a session by session basis. Session properties filters can be used to manage subscriptions to topics and to address messages sent to sessions.
  • The Publisher API no longer supports message acknowledgements. The Publisher API methods and configuration that control acknowledgements now have no effect and are deprecated.
  • Topics created using TopicDetails (in Java / JavaScript ), ITopicDetails (in .NET) or PTDiffusionTopicDetails (in Apple APIs) will not work with topic persistence. Use the equivalent TopicSpecification class instead.

Removed components

The following components have been removed from Diffusion in version 6.0:
  • Legacy topic types:
    • Paged string topics
    • Paged record topics
    • Protocol buffer topics
    • Service topics
    • Child list topics
    • Topic notify topics
    • Custom topics
  • Legacy transport protocols:
    • DPT
    • HTTP Duplex
    • HTTP Chunked Streaming
  • The Introspector/Eclipse plugin

    Instead use the console.

  • JMS adapter version 5.1

    Instead use the latest JMS adapter.

Upgrading your server installation

Note:

At release 6.0, the Diffusion server is tested and supported on Oracle® JDK 8 (minimum update 1.8.0_131-b11).

Earlier versions of Java are not supported.

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. Contact DiffusionData for an updated license file.
  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 following configuration items are no longer valid. Remove them from your configuration files.
      In Connectors.xml
      acceptors element
      In Logs.xml
      rotate-daily element
      In Management.xml
      JMS user and password definitions
      In Publishers.xml
      servers element
      In Servers.xml
      multiplexers and its child elements, write-selectors, auto-fragment, retry-interval in the fan-out configuration, elements that set thread priority, and outbound thread pool configuration.
      In WebServer.xml
      websocket-secure-response and close-callback-requests
    • The following configuration items are now deprecated and are ignored. Consider removing them from your configuration files.
      In Connectors.xml
      type and policy-file elements in the connectors definition.
      In Publishers.xml
      topic-aliasing element

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.
  • Topic replication is no longer supported for these deprecated topic types:
    • single value
    • record
    Replace single value topics with the new explicitly-typed topics. Replace record topics with the new recordV2 topic type.
  • Topic replication is no longer supported for publisher-created topics.
  • The Connectors.xml file included in the installation no longer includes backlog elements to define the maximum number of incoming clients that can be waiting to connect. Instead the Diffusion default of 1000 is used. For more information, see Connectors.
  • The Statistics.xml server-statistics element and the related ServerStatisticsConfig API have no function and are deprecated. The Statistics.xml file included in the installation no longer includes the server-statistics element.
  • The enabled attribute on the replication element of the Replication.xml configuration file has been deprecated. The related methods for the ReplicationConfig interface have also been deprecated. The attribute has been made optional and defaults to true. The attribute continues to control whether replication is enabled. Replication can be controlled by the individual settings for session and topic replication.
  • The JMS adapter has moved from the adapters directory in the Diffusion server installation to the adapters/jms directory.
  • The Push Notifications bridge has moved from the pushnotifications directory in the Diffusion server installation to the adapters/pushnotifications directory.