Consider the following information when upgrading from Diffusion™ version 6.4 to version 6.5.
Upgrading your applications
- Server-side components
Recompile all Java™ application components that are deployed to the
Diffusion server, such as authorization handlers, against the new version
diffusion.jar file. This file is located in
the lib directory of your new Diffusion server installation.
Server-side publishers written in Java are no longer supported. If your application
uses publishers, replace them with clients. DAR files are no longer supported.
The server now supports Java 11 as well as Java 8. See System requirements for the Diffusion server for further details.
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.
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,
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.
Your client applications may use features that have been removed or deprecated.
Review the API changes information
in the following section to see if these changes affect your
Further information about removed or deprecated features is available in the release notes
provided online at
The following table lists features that have
been deprecated. If your application code uses these classes or methods, consider
rewriting your application code to not include these features.
Table 1. API features deprecated in version
||"TopicPermission" methods have been deprecated because the name is misleading.
Some of the permissions they cover apply to message paths or to session lock names, which
are separate from topics.
||Use new PathPermission methods (equivalent apart from the name).
||The MessagingControl feature has been deprecated and all types and methods have been moved to the Messaging feature.
||Use types and methods in Messaging for compatibility with legacy code.
||The ClientServiceConfig compressionThreshold setting is no longer used.
||The efficiency of HTTP polling transport when the client supports 'deflate' compression has been improved,
so this setting is ignored and will be removed in a future release.
The following table lists API
classes and methods that have
been removed. If your application code uses these classes or methods, consider
rewriting your application code to not include these features.
Table 2. API features removed in version
||Use request-response messaging instead
||Use REMOVAL topic property instead
||Most publisher functionality removed as publishers no longer supported by server
||Replace publishers with clients
||Use topic_removal instead
|JMS Adapter one-way messaging support
||The JMS Adapter no longer uses Diffusion one-way messaging.
||The adapter now supports request-response messaging instead.
Connection security configuration changes
Diffusion 6.5 now supports secure connection to the server with TLSv1.3
(in addition to earlier TLS/SSL protocols).
If you wish to use TLSv1.3, ensure that the Java runtime you are using supports it.
It is available in most Java 11 JDKs, but is less well supported by Java 8 JDKs.
The TLS versions used by the Diffusion server and Diffusion Java client are no longer configured with
the diffusion.tls.protocols system property. To enable or disable particular protocols,
use the interfaces provided by the JDK. For the Oracle JDK, see the
Oracle JDK cryptographic
The cipher suites used by the Diffusion server and Diffusion Java client are no longer configured
with the https.cipherSuites system property, which is now ignored.
To enable or disable particular ciphers, use the interfaces provided by the JDK.
See Network security for more information.
Upgrading your server installation
To upgrade your Diffusion
server installation, complete the
- Use the graphical or headless installer to install the new version of Diffusion.
For more information, see Installing the Diffusion server.
Contact Push Technology for an updated license
- 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.
The following configuration items are now deprecated. Consider removing them from your configuration files.
Path permission evaluation with multiple roles
This release significantly changes the evaluation of path permissions for a client session with multiple roles.
In previous releases, path permission rules from different roles were merged before evaluation,
so creating a permission rule for a particular path would mask rules for parent paths from other roles.
From this release, path permissions are evaluated independently for each role. A session has a permission if any
of its assigned roles has that permission.
A new isolate path security language statement has been added that
disables inheritance of path permissions assigned to parent paths, allowing a branch of the path
hierarchy to be configured independently.
If a Diffusion 6.5 server is started against a security store file from Diffusion 6.4 or earlier, the file will
automatically be translated to an equivalent configuration under the new rules.
For each path in a path permission assignment for a role,
a separate statement is added to isolate the path.
In practice you will typically find that many of the path isolation statements can be removed without
affecting your application's security policy, resulting in a simpler configuration.
See Permissions for more details about how the new system works.
New management console
The web-based management console has been completely redesigned, with many improvements.
The classic console, as found in Diffusion 6.4, is still available,
but will be removed in a future release.
If you select the console during installation, both the new and classic consoles
will be installed.
Behavior changes at the Diffusion server
In previous releases, changes to the security store which altered read_topic
permission assignments were not applied to existing subscriptions until the role assigned to an existing session changed
(if the session reauthenticated, or a control session changed the session's role).
From this release, changes to the security store which affect read_topic
permissions are immediately applied to all sessions, resulting in the
appropriate subscriptions and unsubscriptions. Each session's topic selections will be re-evaluated against topics for
which the session has gained read_topic permission, and sessions will be unsubscribed
from topics for which they no longer have read_topic permission.
Performance with large numbers of path permissions has been greatly improved, enabling scaling up to millions
of path permissions.
From this release, the session ID and security principal are included as additional fields in log messages where they are available.
The log fields are available in the Log4j thread context map under the session and principal keys.
You can use this for context-sensitive logging: for example, logging debug messages only for a particular security principal.
You can configure this without restarting the server by setting a new log configuration using JMX.
If you are upgrading an existing configuration, review etc/log4j2.xml from a
fresh installation to see the required changes. Also, see etc/log4j.xml for a commented example of context-sensitive logging.
- Server-side publishers are no longer supported. The Publisher API
is now known as the Server API. Publisher-related functions have been removed. The remaining API is used for
server configuration and running Diffusion embedded within a Java application.
See Server API documentation for details.
- The management console is no longer packaged as a DAR file.
The installer deploys the console (and classic console) within /html/.
- The demos are no longer packaged as DAR files. If you choose to install
demos and examples, the installer copies the source files for the demos into /examples/demos.
If you also select the option to deploy the demos, they will be deployed in /html/demos.
- Path permission evaluation with multiple roles has changed, but your existing configuration
will be automatically updated to keep the same behavior (see above). You should check
that the updated configuration behaves correctly.