Upgrading from 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.

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.

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 applications.

API changes

Further information about removed or deprecated features is available in the release notes provided online at http://docs.diffusiondata.com/docs/6.11.2/ReleaseNotice.html

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 6.5
API affected	Deprecated feature	Suggested alternative
All	"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).
All	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.
All	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 6.5
API affected	Removed feature	Suggested alternative
All	One-way messaging	Use request-response messaging instead
All	removeTopicsWithSession	Use REMOVAL topic property instead
Publisher API	Most publisher functionality removed as publishers no longer supported by server	Replace publishers with clients
C Client	`remove_topics` function	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 configuration documentation.

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 following steps:

Use the graphical or headless installer to install the new version of Diffusion .
For more information, see Installing the Diffusion server.
Contact DiffusionData for an updated license file.
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.
- Publishers.xml

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.