Universal Messaging 10.7 | Release Notes | What's New in Universal Messaging 10.7
 
What's New in Universal Messaging 10.7
Universal Messaging 10.7 is the successor of Universal Messaging 10.5.
Universal Messaging 10.7 includes new features, enhancements, and changes as described in the following topics.
New features in v10.7
The following Universal Messaging features have been added in Universal Messaging 10.7:
*JMS Engine automatic purging of individual events
The automatic purging feature of the JMS engine has been extended to include automatic purging of individual events.
By default, automatic purging of individual events in a channel is activated.
For details, see the section Automatic purging of individual events in the Developer Guide.
*Enterprise Manager - Adding client API build number in realm connections list
The Enterprise Manager display showing the list of client connections for a realm has been extended to include an additional column build number. This column lists the version of the client API that was used to build the client application.
For details, see the section Realm Connections in the Enterprise Manager part of the Administration Guide.
*Support for Command Central asset inventory commands
You can view and install Universal Messaging assets from an asset repository, using the Command Central asset inventory commands.
Important:
The Command Central asset inventory commands are a preview feature that is subject to change in the future without any deprecation announcements. This preview has limited functions and is not intended for use in a production environment. If you want to provide feedback for this preview feature, go to the Command Central area on the Software AG TechCommunity website.
For details, see the section Asset Deployment in the Administration Guide.
*New command line tools
The following command line tools have been added:
Tool name
Description
AddHealthMonitorPlugin
This tool adds an HTTP REST endpoint to the URL of the session to which the realm server is connected, allowing you to access information about health checks that run on the server at periodic intervals. See the entry Health Monitor Plugin below for details.
ExportEventsFromOfflineMemFile
This tool dumps events from the .mem files of a Universal Messaging realm server store to XML or JSON format. The events can be re-imported using the RepublishEventsFromOfflineFile tool.
ListInterfaces
This tool lists the details of all of a realm's interfaces.
RepublishEventsFromOfflineFile
This tool imports events from XML or JSON files that were created by the ExportEventsFromOfflineMemFile tool and republishes them to the specified Universal Messaging realm server store. The tool can also import events from a single .mem file or from a directory which contains .mem files.
For details, see the sections Syntax: Interface Tools and Syntax: Recovery Tools in the Command Line Administration Tools part of the Administration Guide.
*Getting the current status of the realm service/daemon
The command line command nserverdaemon -q has been added to allow Windows users to query the current status of the Universal Messaging server.
For details, see the section Getting the current status of the realm service/daemon in the Installation Guide.
*Event lifecycle logging (trace logging)
Event lifecycle logging, also called trace logging, is used for creating detailed log files that describe the flow of events as they pass from client to Universal Messaging server, or vice versa, through channels or queues.
For details, see the section Event Lifecycle Logging in the Concepts guide.
*Product usage metering
Product usage metering is a feature that allows Universal Messaging to collect metrics relating to the usage of the product, such as total number of events sent and received, and total number of bytes sent and received. If a transaction-based product license is activated, the metrics can be used as a basis of transaction-based pricing.
For details, see the section Product Usage Metrics in the Concepts guide.
*Health Monitor Plugin
A new health monitor plugin is available, which adds an HTTP REST endpoint to the URL of the session to which the realm server is connected. This allows clients to query the current state of the realm server. The endpoint defines the "liveness" of the server. The plugin returns the result of the health checks that run on the server at periodic intervals. You can add the plugin using either the Enterprise Manager or a command line interface.
Information on the use of the plugin is available in the section Health Monitor Plugin in the Administration Guide.
*Active/Active Cluster Mode "Replication"
Universal Messaging Active / Active clustering now supports a new mode - Replication. This mode ensures that non-admin client connections can be established only on the master node, and the other cluster nodes are used only to replicate the master's state. In this mode, nodes that are not the master node will reject all non-admin connections. This is similar to when the client's FollowTheMaster (FTM) flag is set, so this mode behaves like a server-side FTM.
To achieve this behavior in clients of earlier Universal Messaging versions, the FTM flag had to be set for each client. Also this capability was available only in the Java client API.
To enable the new Replication mode, a new property ClusterMode is available in the Cluster Config configuration group of the realm server properties. Setting ClusterMode to "Replication" activates the Replication mode.
If you are using C# or C++ client version 10.3 or 10.5, make sure that the client is upgraded with the latest client libraries, before enabling Replication mode. Also, C#/C++ clients in v10.1 and earlier cannot make use of the feature.
In general, the new Replication mode might be chosen to resolve performance or cluster synchronization issues where we have Universal Messaging clients connected to all cluster nodes simultaneously.
For details, see the topic Cluster Mode Configuration in the section Client Connection in the Concepts guide.
*Bi-directional client compatibility
Universal Messaging is now backwards and forwards compatible with the Universal Messaging Java client, JMS, and Resource Adapter. In addition to clients connecting to the same or higher-release servers, Universal Messaging now enables Java clients version 10.5 and higher to connect to lower-release servers.
For more information about the functionality and compatible client and server versions, see Bi-directional Client and Server Compatibility.
*New release identifiers
You can use the following objects and APIs on the Java client to identify the release version of the components that are in use in your landscape:
*com.pcbsys.nirvana.client.ReleaseDetails - object that provides release and URL details.
*com.pcbsys.nirvana.client.ReleaseIdentifier - object that provides a list of release identifiers.
*com.pcbsys.nirvana.client.nSession APIs:
*getClientReleaseIdentifier() - returns the current client release.
*getServerReleaseIdentifier() - returns the current server release or, in case of a horizontal scalability (HS) connection, the release versions of the HS servers.
*getConnectionProtocol() - returns the negotiated release between the server and client components.
For more details, see the Universal Messaging Java Client API documentation.
*Horizontal scalability (HS) behaves consistently in mixed environments
Now that Universal Messaging is backwards and forwards compatible with Java clients, for consistency in a mixed server environment, you must restrict the HS URL of your application to use the lowest server release version available in the HS landscape. For the purpose, you can use a new parameter, hsReleaseVersion, as part of the HS URL. This functionality has been delivered with Universal Messaging 10.7 Fix 1.
For more information about the functionality and about configuring the hsReleaseVersion parameter, see Horizontal Scalability Behavior in a Mixed Landscape.
*Prefetch APIs for synchronous message consumers
Synchronous consumers now use a client-defined prefetch size parameter to define the maximum number of events which the consumer can receive in a single call. When events are delivered in batches, the whole batch of events is returned to the consumer and no events stay cached client-side.
In Universal Messaging versions prior to v10.7, the client had no control over the number of events returned in a single call; instead, the number of events returned by the server was controlled by the defined window and batch sizes. Also if events were delivered in batches some of them were cached in the client without this being transparent, as the APIs were returning only one event at a time.
In Universal Messaging v10.7 we refer to a client-defined prefetch size, which replaces both window-size and batch parameters, to describe the maximum number of events returned to a synchronous consumer in a single call.
The window size used up to Universal Messaging v10.5 is removed in Universal Messaging v10.7 clients.
Note:
While the new synchronous consumers will not be using a window size, clients from before the prefetch feature's changes will still be doing so. The new server will honor the window size (and the v10.5 queue batching) for older clients. This was done to preserve the behavior of old consumer applications until they can be migrated.
Note:
This new prefetch processing only applies to synchronous consumers. The server-defined window size still applies in Universal Messaging v10.7 for asynchronous consumers.
For a description of the new prefetch API, including a list of the new APIs, see the section Using the Prefetch API in the Concepts guide.
For information about the deprecated APIs for the old window-style processing for synchronous consumers, see the topic Window-related APIs for synchronous consumers in the section Deprecated features in v10.7 in these Release Notes.
*MaxNoOfConnectionsPerUserName realm property
A new realm configuration property that defines the number of concurrent connections to a Universal Messaging server per user. The property is introduced in Universal Messaging 10.7 Fix 14. For more information about using the property, see Realm Configuration.
*AuthenticationTimeLogThreshold property
A new system property that enables the server to report warning messages if a connection takes more than a specified time to authenticate. The property is introduced in Universal Messaging 10.7 Fix 16. For more information about using the property, see Server Behavior when Authenticating Connections.
Changed features in v10.7
The following Universal Messaging features already available in the previous product release have been changed in Universal Messaging 10.7:
*Realm configuration parameter PauseServerPublishing
The realm server configuration property PauseServerPublishing, which you can use to pause the publishing of new events from clients to the realm server, has moved from the "Advanced" category to the "Basic" category. This means that if you are viewing the set of realm server properties in the Enterprise Manager, you will now find the property under the Global Values configuration group under the Basic heading.
The purpose of the property remains unchanged.
See the description of the realm configuration parameter PauseServerPublishing in the section Realm Configuration of the Administration Guide. See also the description of the Pause Publishing feature in the section Pause Publishing of the Concepts guide
*Changed default value for client logging level
The default log level for client applications is now 7 (OFF). This value can be changed by using the parameter LOGLEVEL when the client application is started from the command line.
See the section Client Parameters in the Concepts guide for information on setting client application parameters.
*Out-of-memory configuration has been modified
The order of the realm server configuration parameters FlowControlWaitTimeOne and FlowControlWaitTimeThree has been swapped, so that FlowControlWaitTimeOne is triggered at a threshold of 70% (previously 90%) of memory capacity, and FlowControlWaitTimeThree at 90% (previously 70%). The threshold for FlowControlWaitTimeTwo remains unchanged at 80%.
The processing when the realm server configuration parameter EmergencyThreshold is exceeded has changed. Previously, the server would aggressively remove as many client requests as necessary in order to reduce the memory requirements to under the EmergencyThreshold value. Now, the server blocks client requests for a long period of time, namely 24 days.
The realm server configuration parameter ThrottleAllPublishersAtThreshold has been removed.
For details, see the section Out-of-Memory Protection in the Concepts guide.
*Automated scan of free disk space
The way in which the realm server performs automated scans of free disk space has changed. Previously, this was managed by the server startup parameters DISK_USAGE_SCAN_ENABLE, DISK_USAGE_FREE_THRESHOLD and DISK_USAGE_SCAN_INTERVAL.
Now, functionality managed by these parameters is provided by the new realm server configuration parameters DiskScanEnable, DiskUsageFreeThreshold and DiskUsageScanInterval.
By moving this configuration from the server startup parameters to the realm server configuration parameters, it is now possible to change the configuration while the realm server is running.
Additionally, the old server startup parameter EXIT_ON_FREE_SPACE_ERROR has been removed.
Note: 
The server startup parameter DISK_USAGE_SCAN_ENABLE is still available in v10.7, but marked as deprecated. See the section Deprecated features in v10.7 below for additional information.
Under certain circumstances, the value of DISK_USAGE_SCAN_ENABLE can override the value of DiskScanEnable. The server startup parameters DISK_USAGE_FREE_THRESHOLD and DISK_USAGE_SCAN_INTERVAL are no longer available in v10.7.
For details of the new parameters, see the section Realm Configuration in the Administration Guide.
*Client disconnect when server leaves the cluster
An option has been added to configure the Universal Messaging server to disconnect client sessions if the server falls out of the cluster. Up to now, such an option was available only client side using the APIs nSessionAttributes.setDisconnectIfClusterFails() and nSession.init(bool disconnectIfClusterFails), and there was no global option to set this behavior for all client connections of a server.
The option doesn't affect Admin connections.
To enable the feature use the realm configuration property DisconnectWhenNotReady. This property existed in previous product versions, but was used in a slightly different way. Similarly, the purpose of the realm configuration property DisconnectWait has been slightly modified to fit in with the new DisconnectWhenNotReady handling.
For details of DisconnectWhenNotReady and DisconnectWait, see the configuration group Cluster Config in the section Realm Configuration in the Administration Guide.
*JMX Handling and Prometheus support
There have been updates in the way that Universal Messaging manages JMX beans. Also, it is now possible to export JMX metrics for subsequent analysis by Prometheus, which is an open source monitoring system for time series data.
Several realm configuration properties have been modified or added:
*The purpose of EnableJMX has been modified slightly, so that it only applies to the JMX handling provided in Universal Messaging v10.7 and upwards.
*There is a new property EnableLegacyJMX, which enables the JMX handling that was available in Universal Messaging versions up to and including v10.5.
*There is a new property JMXRMIPort for defining the port number to be used for JMX RMI connections.
In the user documentation, there is a new section JMX User Guide. This summarizes the various ways in which you can set up and use JMX processing, and includes information about setting up a JMX connection to Prometheus.
In Universal Messaging v10.7, tools such as JConsole that can display JMX metrics from Universal Messaging can show the new view com.softwareag.um.server in addition to the known view NirvanaRealmServer. The view com.softwareag.um.server is visible in JConsole if you enable EnableJMX, and the view NirvanaRealmServer is visible in JConsole if you enable EnableJMX.
For related information, see these pages:
* Realm Configuration in the Administration Guide
* JMX User Guide in the Concepts Guide
* JMX Administration and Management in the Concepts Guide
*MaxNoOfConnections realm property
A realm configuration property that defines the total number of concurrent connections to a Universal Messaging server. Now a user with both the Override Connection Count realm permission and an admin connection can override this property. Previously, users with full permissions could override the property. The change is introduced in Universal Messaging 10.7 Fix 14. For more information about using MaxNoOfConnections, see Realm Configuration.
Deprecated features in v10.7
The following Universal Messaging features are now deprecated in Universal Messaging 10.7. Features listed as deprecated are still available in the product, but will be removed in a future release.
*Command line tool GetEventsInfo
This tool has been deprecated in Universal Messaging v10.7 and will be removed from the product in a future release.
The functionality of GetEventsInfo is covered by the new command line tool ExportEventsFromOfflineMemFile introduced in v10.7.
*Client-side authentication with JAAS
The client side authentication with JAAS has been deprecated in Universal Messaging v10.7 and will be removed from the product in a future release. This deprecation affects the use of the system property Nirvana.auth.client.jaaskey for setting up client-side authentication.
For related information see the section Using SASL in the Concepts guide.
*Deprecated APIs and Methods
*Methods setHeader and getHeader in nConsumeEvent API
The methods setHeader and getHeader in the com.pcbsys.nirvana.base.nConsumeEvent API have been deprecated. You should access nHeader fields only through the setters and getters exposed in the nConsumeEvent API.
*nRealmAdmin API
This API has been deprecated in Universal Messaging v10.7 and will be removed from the product in a future release.
The functionality of the nRealmAdmin API is covered by the existing nRealmNode API.
*Client side disconnectOnClusterFailure control flag
The client side DisconnectOnClusterFailure control flag and all APIs that use it have been deprecated. In future, all non-administrative client applications will be disconnected on cluster failure, so the client side control flag is redundant.
The following Java APIs under com.pcbsys.nirvana.client have been deprecated:
nSessionAttributes#isDisconnectOnClusterFailure()
nSessionAttributes#setDisconnectOnClusterFailure(boolean disconnectOnClusterFailure)
The following C++ API has been deprecated:
nSession.init(bool disconnectOnClusterFailure)
The following C# API has been deprecated:
nSession.init(bool fails)
*Method setProperties in nProtobufEvent API
The method setProperties in the nProtobufEvent client APIs for Java, C# and C++ has been deprecated. If the method is used from now on it will do nothing.
If old clients are connected to a v10.7 server and properties are set explicitly on a Protobuf Event they will not be processed.
*APIs for Fragment/Compress for Readers and Writers
All APIs for Fragment/Compress Readers and Writers have been deprecated in Java, C# and C++.
The affected APIs are:
nQueueSyncFragmentReader
nQueueSyncTransactionFragmentReader
nConsumeEventCompressWriter
nConsumeEventCompressReader
nConsumeEventFragmentReader
nConsumeEventFragmentWriter
Also deprecated are any tools or samples which use these APIs, and any other public API related to these APIs.
*XML document type APIs
In a previous product version, some XML document type APIs were deprecated. In the current product version, all remaining XML document type APIs have been deprecated.
Also deprecated are any samples or tools that use these APIs, such as the REST Plugin, and any other public APIs related to XML document type APIs.
*nMessageSigner APIs
All nMessageSigner APIs have been deprecated in Java, C# and C++.
The affected APIs are:
nCertificateSigner
nCertificateValidator
nMessageValidator
nPassphraseValidator
nSignedEventListener
nMessageSigner
nPassphraseSigner
Also deprecated are any tools or samples which use these APIs, and any other public API related to these APIs.
*Window-related APIs for synchronous consumers
Due to the introduction of the new prefetch processing for synchronous consumers (see the New features section above), various APIs associated with server-side window processing for synchronous consumers have been deprecated.
For a list of the deprecated APIs, see the section Using the Prefetch API in the Concepts guide.
*Multiplexing sessions
The feature allowing multiplexing of sessions has been deprecated in Universal Messaging v10.7 and will be removed from the product in a future release.
For related information see the section Multiplexing Sessions in the Concepts guide.
*Server startup parameter DISK_USAGE_SCAN_ENABLE
The server startup parameter DISK_USAGE_SCAN_ENABLE has been deprecated in Universal Messaging v10.7 and will be removed from the product in a future release.
For related information see the section Server Parameters in the Concepts guide.
*Pre-compiled sample applications
Universal Messaging pre-compiled sample applications are deprecated as of version 10.7. Note that the sample source code will remain available and can be used for reference when coding, but the compiled binaries will be removed from the product distribution in the next release. Please use the Universal Messaging command line administration tools instead.
For related information see the sections Running the Sample Applications and Command Line Administration Tools in the Administration guide.
*Display of JMX metrics using the view NirvanaRealmServer
Tools such as JConsole that can display JMX metrics from Universal Messaging can show the view NirvanaRealmServer. This view is deprecated in Universal Messaging v10.7 and will be removed from the product in a future release.
Notice of deprecation of Solaris v.11.3 support
The original provider of the operating system Solaris (Oracle) strongly recommends to upgrade from version 11.3 to 11.4 as of now.
In order to provide for enough time for Software AG customers to react to the upgrade policy of Oracle for Solaris versions after v.11.3, production environments based on Software AG products of this October 2020 release will in general continue to work without the immediate need to upgrade.
However, Software AG customer support will only handle issues for Software AG products that can be reproduced in a Solaris v.11.4 environment.
All newer versions of Software AG products AFTER the October 2020 release will no longer work with Solaris v.11.3.
Software AG therefore strongly recommends to address necessary migration steps timely.
Removed Features in v10.7
The following Universal Messaging features have been removed in Universal Messaging 10.7:
*Realm server configuration property JMSEngineIndividualPurgeEnabled
The realm server configuration property JMSEngineIndividualPurgeEnabled, which was introduced in v10.5 as a short-term measure to switch on/switch off the JMS engine's functionality for automatic purging of individual events on a channel, has been removed. Now, automatic purging of individual events in a channel is by default activated.
For related information, see the entry JMS Engine automatic purging of individual events in the above section New features in v10.7.
*Server system parameter JMSEngineIndividualPurgeEnabled
The server system parameter globalIndexedIteratorWindowSize has been removed. It was used as a temporary mechanism in early releases of v10.3 but was otherwise undocumented.
Documentation Changes
*Migrating from IPv4 to IPv6
A section has been added in the Administration Guide to summarize points to look out for in the configuration of Universal Messaging if you are moving from an IPv4 infrastructure to an IPv6 infrastructure.
For details, see the section Migrating from IPv4 to IPv6 in the Administration Guide.
*Availability of Docker images
Docker support for Universal Messaging now covers the following:
*There are container images in Docker Hub for the Universal Messaging server and associated command line administration and monitoring tools.
*There are scripts in GitHub for building a Universal Messaging image to run in a Docker container.
For related information, see the section Using Containers in the Installation Guide.
*Server startup parameter for log rolling depth
There is a server startup parameter LogFileDepth that specifies the maximum number of log files to keep on disk when using log rolling. The oldest log files will be deleted when new log files are created.
This parameter was undocumented in previous releases.
Information on the use of the server startup parameter is available in the section Server Parameters in the Concepts guide.
*Command Central documentation in Administration Guide
The Command Central documentation for Universal Messaging in the Administration Guide has been restructured to follow the workflow of managing a product in Command Central. In addition, the topics about using the command-line interface to manage Universal Messaging have been reorganized based on functionality.
*You can find information about using Nginx as a reverse proxy server for Universal Messaging in the topic "Using Nginx with Universal Messaging" in the Administration Guide.