Upgrading from version 6.11 to version 6.12

Significant changes

The server and the Java client now require Java 17, or later.

The licensing framework has been updated. Licences for older versions of Diffusion will not work with 6.12 and vice-versa. Please contact support if you need a new licence.

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.

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 deprecations

API items that have been deprecated at this version are detailed below. These items will be removed at a future version. If your application code uses these classes or methods, consider rewriting your application code to not include these features.

.NET Client

Some remaining callback methods have been deprecated in favour of corresponding task based methods. The session properties listener has also been deprecated in favour of the new session event listener. The full list is given below.

PushTechnology.ClientInterface.Client.Features.Control.Clients.IClientControl.SetQueueEventHandler(IQueueEventHandler)
PushTechnology.ClientInterface.Client.Features.Control.Clients.IQueueEventHandler.OnLowerThresholdCrossed(ISessionId,IMessageQueuePolicy)
PushTechnology.ClientInterface.Client.Features.Control.Clients.IQueueEventHandler.OnUpperThresholdCrossed(ISessionId,IMessageQueuePolicy)
PushTechnology.ClientInterface.Client.Features.Control.Clients.IQueueEventHandler 
PushTechnology.ClientInterface.Client.Features.Control.Clients.ISessionPropertiesListener.OnSessionClose(ISessionId,IDictionary<string,string>,CloseReason)
PushTechnology.ClientInterface.Client.Features.Control.Clients.ISessionPropertiesListener.OnSessionEvent(ISessionId,SessionPropertiesListenerEventType?,IDictionary<string,string>,IDictionary<string,string>)
PushTechnology.ClientInterface.Client.Features.Control.Clients.ISessionPropertiesListener.OnSessionOpen(ISessionId,IDictionary<string,string>)
PushTechnology.ClientInterface.Client.Features.Control.Clients.ISessionPropertiesListener
PushTechnology.ClientInterface.Client.Session.ISessionFactory.Open(string,ISessionOpenCallback)
PushTechnology.ClientInterface.Client.Session.ISessionFactory.Open<TContext>(string,TContext,ISessionOpenContextCallback<TContext>)
PushTechnology.ClientInterface.Client.Session.ISessionOpenCallback.OnOpened(ISession)
PushTechnology.ClientInterface.Client.Session.ISessionOpenCallback
PushTechnology.ClientInterface.Client.Session.ISessionOpenContextCallback<in TContext>.OnOpened(TContext,ISession)

Apple Client

tidyOnSubscribePropertyKey is now deprecated in favour of tidyOnUnsubscribePropertyKey due to an error in the property name.

JavaScript Client

The Result type was an alias of the native Promise type. It has been deprecated in favour of Promise.

API removals

The following previously deprecated items have now been removed. If your application used any of these items they will need to be amended to use the alternatives. See the upgrade notes from the release at which they were deprecated for details of the alternatives.

Java Client

All callback methods and associated interfaces deprecated in 6.7 have been removed.

TopicControl.newSpecification - deprecated at 6.7.

ExclusiveUpdaterConflictException - deprecated at 6.6

The createRemoteServer methods in the RemoteServers feature that took individual parameters - deprecated at 6.7

The SERVER_CLOSING value of ClientControl.CloseReason has been removed - deprecated at 6.6

.NET Client

All callback methods and associated interfaces deprecated in 6.7 have been removed.

ITopicControl.NewSpecification - deprecated at 6.7

The CreateRemoteServerAsync methods in the RemoteServers feature that took individual parameters - deprecated at 6.7

JavaScript Client

UpdateFailReason.INVALID_UPDATER - deprecated at 6.6

UpdateFailReason. EXCLUSIVE_UPDATER_CONFLICT - deprecated at 6.6

TopicType.id - deprecated at 6.5

TopicType.stateful - deprecated at 6.5

TopicType.functional - deprecated at 6.5

All internal fields of TopicType have been removed.

The TopicType class has been converted to a TypeScript enum.

Apple Client

PTDiffusionSessionError - deprecated since 6.7

PTDiffusion PTDiffusionErrorDomain - deprecated since 6.7

PTDiffusionErrorCode - deprecated since 6.7

PTDiffusionCloseReason serverClosing - deprecated since 6.6

PTDiffusionMessagingFeature PTDiffusionMessagingFeatureErrorCode - deprecated since 6.7

PTDiffusionMessagingFeatureErrorDomain - deprecated since 6.7

PTDiffusionRemoteServersFeature createRemoteServer:withURL:principal:credentials:completionHandler - deprecated since 6.7

createRemoteServer:withURL:principal:credentials:connnectionOptions:completionHandler - deprecated since 6.7

PTDiffusionSessionError - deprecated since 6.7

PTDiffusionSessionResponseStreamDelegate diffusionStream:didFailWithError - deprecated since 6.6

diffusionDidCloseStream: - deprecated since 6.6

PTDiffusionSubscriptionControlFeature PTDiffusionSubscriptionControlFeatureErrorCore - deprecated since 6.7

PTDiffusionTopicControlFeature PTDiffusionTopicControlFeatureErrorCore - deprecated since 6.7

removeDiscreteWithTopicSelectorExpression:completionHandler - deprecated since 6.6

PTDiffusionTopicsFeature addFallbackStream - deprecated since 6.5

addStream:withSelector - deprecated since 6.5

addStream:withSelectorExpression - deprecated since 6.5

PTDiffusionUpdateStream PTDiffusionUpdateStreamErrorCore - deprecated since 6.7

PTDiffusionVersion - major, minor and patch - deprecated since 6.5

C Client

metrics diffusion_session_metric_collector_builder_create_collector - deprecated since 6.8

diffusion_topic_metric_collector_builder_create_collector - deprecated since 6.8

topic-control ADD_TOPIC_FAILURE_REASON_USER_CODE_ERROR - deprecated since 6.2

topic-update diffusion_topic_update_create_update_stream - deprecated since 6.9

diffusion_topic_update_create_update_stream_with_constraint - deprecated since 6.9

diffusion_topic_update_create_update_stream_adding_topic - deprecated since 6.9

diffusion_topic_update_create_update_stream_adding_topic_with_constraint - deprecated since 6.9

content_types content_free - deprecated since 6.1

session_types SESSION_LISTENER_T.on_handler_error - deprecated since 6.9

selector selector_match - deprecated since 6.7

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 alongside your existing installation.
For more information, see Installing the Diffusion server.
Replace the default licence in the new server's etc directory with your production licence. If your licence needs updating contact DiffusionData for an updated file.
Copy all of the files from the persistence directory of your previous installation to the persistence directory of your new installation.

Configuration files from the etc directory of your previous installation can be copied to the etc directory of your new installation, taking note of any files which have changed between versions.

The following table lists changes to configuration files.

Configuration affected	Changes	Notes
`Server.xml`	The optional, `journal`, element has been added for configuring the Diffusion Journal.	See Diffusion Journal for full details.
journaling-status.properties	A new file used to indicate which operations will be journalled.	Only used when `journal` is enabled in `Server.xml`
`log4j2.xml`	Example configuration for the Diffusion Journal has been added.

Upgrading in a cluster

To upgrade a Diffusion server cluster, complete the following steps:

Follow the steps above to upgrade your Diffusion servers. However, only copy the persistence files to one of the servers in the cluster.
Ensure that the server you copied the persistence files to is started first. This server will restore the persisted state.
Start the other upgraded servers in the cluster one-by-one allowing them to restore persisted state from the first server.