This document contains release notes for Prosys OPC UA SDK for Java Version 5. The versioning scheme is x.y.z-b, with the following meanings:

  • x: Incremented when we start adding support for a newer version of the OPC UA Specification (in which case y and z will reset back to 0). SDK versions 5.y.z are tied to OPC UA 1.05, SDK 6.y.z will be for 1.06, etc. assuming OPC UA versioning keeps as-is. Also, it is possible that in the future we decide to break this link). Largest changes are preferably done here.

  • y: Incremented on a bit larger updates (z is reset back to 0), that do not add support for a newer version of the OPC UA Specification.

  • z: Incremented on not so large updates. Even number of z indicate releases, while odd ones are betas. In general only releases have release notes and are public. We may give beta versions as part of support cases.

  • b: Incremented internally when we make builds. Sometimes we reset this number.

The Code Generator tool that comes with the SDK uses similarly named version number. It is tied to the SDK version, except the build number is different. Also, if there are no changes, then SDK ships with the one from previous releases.

Migration Guides

See following documents (you can also find these from the SDK zip) for migrating from older versions to 5.x:

Version 5.2.8

Build: 5.2.8-159

Release date: 11.11.2024

This is a bug fix release of the SDK that includes security fixes.

This version of the SDK fixes issues related to the deprecated 'Basic128Rsa15' SecurityPolicy in relation to UserTokenPolicies. This policy should be avoided, since there are known vulnerabilities related to it.

In practice, the constants UserTokenPolicies.SECURE_USERNAME_PASSWORD and UserTokenPolicies.SECURE_CERTIFICATE were removed from the SDK and cannot be used any more.

This leads to a breaking change in how the UserTokenPolicies should be initialized in server applications. Namely, you should configure your server to use the UserTokenPolicies.SECURE_USERNAME_PASSWORD_BASIC256SHA256 instead of the old UserTokenPolicies.SECURE_USERNAME_PASSWORD - and respectively with the CERTIFICATE-policy. See the updated code in SampleConsoleServer.initialize.

The 'Basic256Sha256' policy requires at least 2048 bit Application Instance Certificates. If you need to ensure backwards compatibility and might need to update running server instances that still use 1024 bit certificates, you should also add UserTokenPolicies.SECURE_USERNAME_PASSWORD_BASIC256 and/or UserTokenPolicies.SECURE_CERTIFICATE_BASIC256.

Only in the specific case that you need to support old client applications that can only work 'Basic12Rsa15' policy, you may still consider to also include UserTokenPolicies.SECURE_USERNAME_PASSWORD_BASIC128RSA15 and/or UserTokenPolicies.SECURE_CERTIFICATE_BASIC128RAS15. But beware that there is a known security vulnerability related to it.

Additionally SecurityPolicy and HttpsSecurityPolicy constants representing and related to policies deprecated in the OPC UA Specification are now marked as Deprecated. They shouldn’t be enabled by default, but may be needed to inter-operate with old applications.

Changes to Common parts

  • Security improvement: CryptoProvider.verifySymm implementation detail.

  • New: DateTime new methods: isAfter, isAfterOrAt, isBefore and isBeforeOrAt.

  • Deprecated: SecurityPolicy constants BASIC128RSA15 and BASIC256 and related ALL_SECURE_XXX containing them.

  • Deprecated: HttpsSecurityPolicy constants TLS_1_0 and TLS_1_1 and related ALL_XXX containing them.

  • Fixed: Regression from 5.2.4, SDK 2.x backwards compatible legacy code handling regarding byte[] given to Variant.

  • Fixed: UaNodeSet parsing incorrectly took Description and DisplayName Attribute values from <Value>, if it was a Structure having field names 'Description' or 'DisplayName'.

Changes to Client SDK

  • Fixed: UaNode.getValue() returned empty arrays of BigDecimal instead of empty arrays of the specific Structure DataType.

Changes to Server SDK

  • Security fix: Removed constants UserTokenPolicies.SECURE_USERNAME_PASSWORD and UserTokenPolicies.SECURE_CERTIFICATE that used the deprecated 'Basic128Rsa15' SecurityPolicy.

  • Security fix: Do not allow client defined EncryptionAlgorithm within UserNameIdentityToken to differ from what is defined by the selected UserTokenPolicy.

  • New (deprecated): UserTokenPolicies.SECURE_USERNAME_PASSWORD_BASIC128RSA15 and UserTokenPolicies.SECURE_CERTIFICATE_BASIC128RSA15. These policies are introduced as deprecated, indicating that they are no longer recommended. Kept for enabling backwards compatibility.

  • Deprecated: UserTokenPolicies.SECURE_USERNAME_PASSWORD_BASIC256 and UserTokenPolicies.SECURE_CERTIFICATE_BASIC256 as these are no longer recommended, either. Kept for enabling backwards compatibility.

  • Fixed: Regression from 5.0.0, ResendData didn’t cause any data to be sent.

  • Fixed: NodeManagerUaNode.toNodeSet() should now export all Structure Values(s) properly.

Changes to PubSub SDK

  • No changes.

Changes to Code Generator

  • No changes, uses the same as in 5.2.4.

Changes to SampleConsoleClient

  • No changes.

Changes to SampleConsoleServer

  • Security fix: SampleConsoleServer.initialize to use UserTokenPolicies.SECURE_USERNAME_PASSWORD_BASIC256SHA256 and UserTokenPolicies.SECURE_CERTIFICATE_BASIC256SHA256 instead of the removed UserTokenPolicies.SECURE_USERNAME_PASSWORD and UserTokenPolicies.SECURE_CERTIFICATE.

Other

  • Plus a number of other small changes.

Version 5.2.6

Build: 5.2.6-151

Release date: 23.09.2024

This is a bug fix release of the SDK. It additionally contains one new feature and some performance improvements.

SubscriptionManager.setTrackModelChanges(true) can now be used to enable internal tracking of adding and deleting of UaNodes. MonitoredDataItems whose UaNode has been deleted will return Bad_NodeIdUnknown to Clients. If an UaNode with the same NodeId is added back, the item will start to work again, using that UaNode. This also works for MonitoredEventItems, but there is no OPC UA way of informing Clients that the node is deleted. While enabled, adding and deleting UaNodes can be slower. By default this is not enabled, but this may change in a future version.

Additionally, unrelated to the above, adding and removing UaNodes or references to them while a ModelChange transaction is active (NodeManagerRoot.beginModelChange() + NodeManagerRoot.endModelChange()) is significantly more performant.

This release fixes also two regressions from 5.2.4 and we would recommend using this release instead of 5.2.4.

Changes to Common parts

  • Improvement: UaNodeSet can now parse models that do not set default xml namespace as 'xmlns="http://opcfoundation.org/UA/2011/03/UANodeSet.xsd"'.

  • Fixed: Regression from 5.2.4, BinaryEncoder/BinaryDecoder, custom types having numeric NodeId identifier part value from '1' to '25' and '50' now work again.

Changes to Client SDK

  • No Changes

Changes to Server SDK

  • New: SubscriptionManager.setTrackModelChanges(boolean).

  • Improvement: Node and Reference addition/removal performance increases while ModelChange transaction is active.

  • Fixed: Regression from 5.2.4, the not-yet-supported Attributes RolePermissions, UserRolePermissions, AccessRestrictions, AccessLevelEx incorrectly returned StatusCode Good (with null Value).

Changes to PubSub SDK

  • Fixed: DataSetWriters wrote both timestamps even if only SourceTimestamp was configured in DataSetFieldContentMask.

Changes to Code Generator

  • No changes, uses the same as in 5.2.4.

Changes to SampleConsoleClient

  • No Changes

Changes to SampleConsoleServer

  • No Changes

Other

  • Plus a number of other small changes.

Version 5.2.4

Build: 5.2.4-147

Release date: 04.09.2024

This is a bug fix release of the SDK. It additionally contains some new features and performance increases.

UaClient reconnecting can now be observed via the added UaClientListener.onReconnect(ReconnectStatus). It allows listening to reconnect attempts starting, reconnect attempts succeeding and reconnect attempts failing. This is intended to be used to monitor automatic reconnection attempts when AutoReconnect is enabled, which is the default.

The following interfaces: UaClientListener, NodeManagerTableListener, UaServerListener and SessionListener methods are now default methods, thus you only need to implement the ones you want. The default implementation does nothing or returns a value which have the same effect as-if the listener is never set. Any existing XXXAdapter related to these are now deprecated as no longer needed.

Changed NodeManagerTable.loadModel(UaNodeSet…​) to throw by default if any UaNodeSet.getLog() indicates ERROR(s) in any of the given model(s). Any WARNING(s) by default are accepted. Added NodeManagerTable.loadModel(UaNodeSetLoadOptions, UaNodeSet…​) overload to allow accepting or throw on ERROR(s) and/or WARNING(s). Please note that generally it is not recommended to allow ERROR(s), it is just provided as a "try anyway" option in case a model cannot be fixed, the resulting AddressSpace on the Server can be invalid, might miss Nodes or the loading can still fail depending on the contents.

UaNodeSet parsing now ignores UTF-8 Byte Order Mark (BOM) character, thus models using that encoding will now work. Also added support for other encodings, though UTF-8 is recommended. Additionally any models using AccessLevelEx bits in the AccessLevel XML attribute values now work, but the AccessLevelEx-specific bits are ignored (SDK doesn’t yet support AccessLevelEx).

Fixed various encoding related bugs of Unions, regression from 5.0.0. Additionally, their getters now return null if that field is not set. Previously this could cause ClassCastException for different-typed fields.

Changes to Common parts

  • New: Attributes.AsInt, holds the same constants as Attributes, but as int. Can be useful for switch-cases that do require constant int fields.

  • New: StatusCodes.getKnownStatusCodes(), returns all constants that exist in the StatusCodes. Note that doesn’t include all "info bit" variations.

  • New: UaNodeSet.parseXml overload that takes Charset.

  • Fixed: UaNodeSet parsing now ignores UTF-8 BOM character, thus models that start with it now work.

  • Fixed: UaNodeSet parsing now ignores AccessLevel bits that would be related to AccessLevelEx.

  • Fixed: UnionWithSubtypedValues binary encoding is now correct.

  • Fixed: Regression from 5.0.0, UaDataType.getJavaClass() can no longer incorrectly interpret SimpleTypes inheriting UInteger subtypes as "OptionSet-like type".

Changes to Client SDK

  • New: UaClientListener.onReconnect(ReconnectStatus).

  • Changed: UaClientListener methods are now default methods.

Changes to Server SDK

  • New: NodeManagerTable.loadModel(UaNodeSetLoadOptions, UaNodeSet…​) overload.

  • Changed: NodeManagerTable.loadModel(UaNodeSet…​) now throws if any UaNodeSet.getLog() indicates ERROR(s) in any of the given model(s).

  • Changed: NodeManagerTableListener, UaServerListener and SessionListener methods are now default methods.

  • Fixed: The Value of Server/ServerDiagnostics/ServerDiagnosticsSummary/CurrentSubscriptionCount Node could be calculated incorrectly in some cases.

Changes to PubSub SDK

  • New: PubSubDataSetMetaDataConf ConfigurationMajorVersion and ConfigurationMinorVersion fields. SDK doesn’t yet itself use these, but can be obtained in application code, if needed.

Changes to Code Generator

  • Changed/Fixed: Unions getters now return null, if that exact field was not the one set to the Union. Same also for their Builders.

  • Some performance related changes in the generated classes.

Code must be regenerated with the Codegen of this release.

Changes to SampleConsoleClient

  • New: In MyUaClientListener added example of the added onReconnect method.

  • Changed: When showing the instructions regarding certificate handling for some known servers, wait for the user to press the 'Enter' key before continuing.

  • Changed: For certificate handling tips, check SampleConsoleServer only based on port and servername parts.

Changes to SampleConsoleServer

  • No Changes

Other

  • Some performance increases

Plus a number of other small changes.

Version 5.2.2

Build: 5.2.2-139

Release date: 05.06.2024

This is a bug fix release of the SDK that also contains security fixes:

  • Regression from 5.2.0: Diagnostics leaked memory, if you have enabled them.

  • Default MaxArrayLength, MaxByteStringLength and MaxStringLength changed to 4194240 from unlimited.

  • SampleConsoleClient by default didn’t validate opc.https certificates.

This version changes the default MaxArrayLength, MaxByteStringLength and MaxStringLength within EncoderContext to be 4194240. Previous default was 0, i.e. 'unlimited'. These 'safety limits' complement the security fixes of 5.2.0 in the case the old defaults were used. Depending on the data your applications process, you might wish to use larger or smaller limits. The 4194240 was chosen as that was (already in prev. versions) the server-side default for the maximum message size.

Logback (used in SDK samples) is updated to version 1.2.13. Fixes CVE-2023-6378, though it should be noted that the SDK samples do not use the Receivers feature and thus as-is are unaffected.

Commons-codec (used in optional opc.https protocol) is updated to version 1.16.0, which is assumed to be the last "true Java 8 compatible" version, since later versions contain Java-9 introduced MultiReleaseJars features, which will not work properly in all Java 8 environments.

We recommend everyone to update to this release.

Changes to Common parts

  • Security fix: EncoderContext default MaxStringLength, MaxByteStringLength, MaxArrayLength are now 4194240 from previous 0 (unlimited).

  • Changed: Updated commons-codec to version 1.16.0, used in optional opc.https protocol.

  • Changed: Updated Logback to version 1.2.13, used in samples.

  • Fixed: Regression from 5.2.0, UaNodeId.getValueAsParseForm() returned namespace-included form.

Changes to Client SDK

  • No Changes, but the Common EncoderContext limit(s) changes can potentially affect applications dealing with huge data amounts and may require configuring larger values.

Changes to Server SDK

  • New: When synchronizing structure-related node Values upwards, if the value of parent node is null, form initial value based on the sub-nodes.

  • Fixed: Regression from 5.2.0, Diagnostics leaked memory, if you have enabled them.

  • Fixed: UaServer.getLoopbackClient() if initially called by multiple threads could return null.

Changes to PubSub SDK

  • No Changes

Changes to Code Generator

  • No changes, uses the same as in 5.2.0.

Changes to SampleConsoleClient

  • Security fix: CertificateValidator.ALLOW_ALL was used by the sample for opc.https certificates thus all were accepted. Now uses the same validator that is used for opc.tcp.

Changes to SampleConsoleServer

  • No Changes

Plus a number of other small changes.

Version 5.2.0

Build: 5.2.0-133

Release date: 29.05.2024

This is a new minor release of the SDK. It contains new features, bug fixes, improvements and few security-related fixes.

Notable new features:

  • NodeManagerUaNode.toNodeSet can be used to get UaNodeSet from it. UaNodeSet.toXml can be used to obtain the XML back as String.

  • Variant.defaultValue and DataValue.defaultValue can be used to obtain a "default value" for given type(s).

  • UaServer.getLoopbackClient can be used to get a limited UaClient-like API for the UaServer.

Notable security-related fixes:

  • Decoders didn’t properly validate Array lengths in some cases, thus a client could cause OutOfMemoryError in the server.

  • Updated BouncyCastle dependency to version 1.78.1. BC 1.78 fixed some CVEs. Per our understanding those are not relevant for the SDK, but we still do recommend updating BC, even if you cannot update to this SDK version.

  • Method calls (User)Executable bits were incorrectly queried from the IoManager(Listener) of the 'objectId' parameter of the Call, when it should have done based on the 'methodId'. This can be mitigated in earlier SDK versions by checking the user from the ServiceContext parameter in the actual method implementation. Affects only if the Method node and Object node are in separate namespaces.

Notable fixes and improvements:

  • UaClient(s) used to ignore Discovery GetEndpoints EndpointUrl and just use the original connection address (e.g. helps with NATs). Starting from 5.2.0, the ServerName component from GetEndpoints EndpointUrls will be used in place of the original ServerName (other components remain the same). This allows connecting to a server, whose main endpoint doesn’t support NONE at all (GetEndpoints is done using NONE), but has a separate Discovery endpoint in separate ServerName subpart, such as 'opc.tcp://host:port/Discovery'. In this case, 'opc.tcp://host:port/Discovery' can be given to UaClient and it will discover the real ServerName and use that.

  • The server side Subscriptions no longer by default have a "Immediate Publish" mode on. Previously if no notification had occurred in a PublishInterval, on first datachange (i.e. MonitoredItem) the Subscription would publish (possibly leaving other just-changed items out, depending on the timings). The previous functionality can be restored via SubscriptionManager.setImmediatePublishing(true), but we recommend using the new one where possible.

  • Additionally in the server "one-shot-event" events (event types that are not ConditionType-subtypes) are now only deleted after triggering if the top-level instance (i.e. the instance node matching the EventType TypeDefinition node) has a NodeId for which NodeId.isNullNodeId is true, which happens automatically if the event is created by NodeManagerUaNode.createEvent. If you create one-shot-events manually (with a non-null NodeId), care should be taken to manually delete them e.g. with NodeManagerUaNode.deleteNode(UaNode, true, true) after triggering. While normally one-shot-event nodes should’t exist in the address space, this change allows e.g. storing an one-shot-event configuration as nodes.

  • Having 64 (the default number of threads in OPC-UA-Stack-Blocking-Work-Executor) or more UaClient instances in the same JVM renewing their SecureChannel at the same exact time could cause a deadlock causing all those connections to break until reconnected. This can be mitigated in an earlier release by setting com.prosysopc.ua.stack.utils.StackUtils.setBlockingWorkerThreadPoolCoreSize(int) before other interactions with the SDK to the number of clients plus one.

Changes to Common parts

  • SECURITY/Fixed: Decoders didn’t validate array lengths in all scenarios.

  • Updated: BouncyCastle dependency is updated to version 1.78.1.

  • New: UaNodeSet parses now multi-locale DisplayName and Description Attributes.

  • New: UaNodeSet.toXml, gives the NodeSet XML as String.

  • New: StatusCode.parseStatusCode.

  • New: UnsignedShort.toHex, UnsignedInteger.toHex, UnsignedLong.toHex.

  • New: Added 'UserData` property to Subscription+MonitoredItems, can be used to hold custom data related to the subscription/item.

  • New: UaReferenceType.isHierarchical, UaReferenceType.isNonHierarchical

  • New: DiagnosticInfo now implements Cloneable.

  • New: UaArrayDimensions static methods: isNullOrEmpty, ones, unlimited, valueOf.

  • New: UaArrayDimensions methods: get(int index), isEmpty, isUnlimited, isUnlimited(int index), size, toList.

  • New: UaNodeSet.NodeData.getLog().

  • New: Variant.defaultValue and DataValue.defaultValue.

  • New: Non-encoded ExtensionObject support UaNamespaceTranslateable. Encoded-ones will be supported in a future release.

  • Fixed: UaNode.getReference(NodeId, boolean) did incorrectly return empty array when given null as the referenceTypeId parameter.

  • Fixed: UaNode.getAttributesMap() was missing BrowseName Attribute.

  • Deprecated: com.prosysopc.ua.stack.utils.ReflectionUtils.

  • Deprecated: All XXXAdapter abstract classes (such as NodeManagerAdapter), their functionality has been moved to their respective interfaces (such as NodeManagerListener) as Java 8 default methods.

Changes to Client SDK

  • New: UaClient.setSocketFactory, for some advanced use-cases.

  • New: UaClient.setAddressResolver, can be used to override discovery endpoint servername logic added in this release.

  • Fixed: Subscription.updateMonitoringModes() now properly calls protected MonitoredItem.clearMonitoringModeModified() (and not MonitoredItem.clearModified()).

  • Fixed: Deadlock scenario when running 64+ Clients, which all renewed the SecureChannel at the same exact time (caused all connections to break until reconnected).

  • Fixed: TypeDictionary.decode didn’t work if UaClient InitTypeDictionaryAutoUsage was set to false.

  • Fixed: UaClient.write could get ArrayIndexOutOfBoundsException, if server sent empty DiagnosticInfo array.

  • Fixed: When deleting MonitoredItems, skip server-side deletion if the item never existed in the server (MonitoredItemId 0).

  • Changed: Added a wait to reconnect retry, if after reconnecting cannot activate session or any other failure than getting the actual connection.

  • Changed: Use ServerName component of Discovery EndpointDescription. Previously the whole EndpointUrl was ignored and connection made to the original configured address. Now the protocol, host, port info is kept, but the ServerName part is taken from the EndpointUrl that was obtained during Discovery.

Changes to Server SDK

  • SECURITY/Fixed: For Method calls, the IoManager(Listener) of the 'objectId' was used to check the Executable attributes, when it should have been 'methodId' one.

  • New: Added better options for using subtyped Subscription, MonitoredDataItem and MonitoredEventItem via protected methods: SubscriptionManager.createSubscription, Subscription.createMonitoredDataItem and Subscription.createMonitoredEventItem.

  • New: NodeManagerUaNode.toUaNodeSet. Gives UaNodeSet representing the nodes within the manager.

  • New: SubscriptionManagerListener.onAfterCreateMonitoredItems, SubscriptionManagerListener.onAfterDeleteMonitoredItems, SubscriptionManagerListener.onDeleteMonitoredItems,

  • New: UaLoopbackClient, via UaServer.getLoopbackClient() returns an UaClient interface directly connected (within java) to the UaServer.

  • New: NodeManagerTable.removeNodeManager(int, boolean) overload to NodeManagerTable.removeNodeManager(int). Fixed removeNodeManager(int) to also update the NamespaceArray node by default.

  • New: Standard information model is parsed only once per JVM, and a memory-optimized form is cached (estimated extra memory consumption <1.5MB).

  • Changed: Subscriptions are no longer published immediately ( if previous notification was sent longer than PublishInterval ago) if data changes occur. Previous functionality can be obtained via SubscriptionManager.setImmediatePublishing(true).

  • Changed: One-shot events (non-ConditionType-subtypes) are now only deleted by BaseEventTypeNode.triggerEvent if the top-lvl node’s NodeId is a null-NodeId (which it is if created by NodeManagerUaNode.createEvent()). While non-ConditionType-nodes shouldn’t exist in the address space for event-purposes, this allows e.g. storing an event configuration as nodes.

  • Fixed: Do not call individual HistoryUpdate operations, if results already set by HistoryManager.beginHistoryUpdate or HistoryManagerListener.onBeginHistoryUpdate.

  • Fixed: NoConnectionPendingException could happen for Reverse Connections.

  • Fixed: ReverseConnectionParameters.toBuilder() didn’t set RetryWaitIntervals for the returned builder.

  • Fixed: NodeManagerTable.loadModel(URI) logs the URI once again. Removed "Loading model from inputStream" INFO log for the NodeManagerTable.loadModel(InputStream inputStream).

Changes to PubSub SDK

  • New: PubSubBrokerConnectionConf.Builder.setDisableMqttRetain can be used to disable MQTT RETAIN bit (some Brokers do not support it).

  • New: PubSubBrokerConnectionConf.Builder.setEnableStatusMessage, can be used to enable 'Status' Message as listed in Part 14 6.3.5.7, by default off, future releases will add more of the new message types.

  • Fixed: Added 'Timestamp' field to MQTT-JSON DataSetMetaData Messages.

  • Fixed: Parsing MQTT-JSON DataSet messages without header didn’t work properly.

Changes to Code Generator

  • New: Identifiers, Ids, UaIds and NodeClass-specific interface parts of them now have methods for obtaining all identifiers.

Code must be regenerated with the Codegen of this release.

Changes to SampleConsoleClient

  • New: Prints more tips regarding certificates and gives advice (based on the connection address) on accepting them in the server side, when connected to SampleConsoleServer, Prosys OPC UA Simulation Server or Prosys OPC UA Forge.

Changes to SampleConsoleServer

  • Fixed: MyEventType, getMyPropertyNode+getMyVariableNode, getNodeManager().getNamespaceIndex() was incorrect as the NodeManager of one-shot top-lvl-node for events in SDK 5.x is the NodeManagerRoot.

Other

  • Some performance increases

Plus a number of other small changes.

Version 5.1.0

Build: 5.1.0-116

Release date: 23.01.2024

This is a new minor release of the SDK that includes the following main improvements:

  • Support for OPC UA version 1.05.03 and Java 21 (classpath mode).

  • Security improvements: SecureRandom initialization, Bouncy Castle 1.77 and connection handling details

  • New classes and API changes related to Browse Paths.

  • New classes: UaNodeSet & UaBinaryFile.

  • One memory leak fix and plenty of other new features and bug fixes.

This release contains important security improvements, so we recommend everyone to update to this version. See the details below.

Changes to Common parts

  • Updated: Using Core OPC UA Information Model version 1.05.03.

  • Updated: Using GDS OPC UA Information Model version 1.05.02.

  • Updated: BouncyCastle dependency is updated to version 1.77.

  • Verified: This version of the SDK is tested to work with Java 21 (in classpath mode).

  • API CHANGE: com.prosysopc.ua.UaBrowsePath renamed to com.prosysopc.ua.UaBrowseNamePath

  • API CHANGE: com.prosysopc.ua.UaRelativePath renamed to com.prosysopc.ua.UaRelativeNamePath

  • API CHANGE: com.prosysopc.ua.server.BrowsePath renamed to com.prosysopc.ua.RelativeNamePath

  • API CHANGE: There are now new classes com.prosysopc.ua.UaBrowsePath and com.prosysopc.ua.UaRelativePath with additional semantic, they now are equivalent to com.prosysopc.ua.stack.core.BrowsePath and com.prosysopc.ua.stack.core.RelativePath

  • SECURITY IMPROVEMENT: CryptoUtil.getRandom() defaults to SecureRandom.getInstance("Windows-PRNG") on Windows and SecureRandom.getInstance("NativePRNGNonBlocking") in other operating systems. The previous default ("SHA1PRNG") is still used as the fallback. This is used as the internal random provider in the SDK and requires no change to your application.

  • New: UaNodeSet, an intermediate format that enables parsing a NodeSet2 XML file before loading it to the server with NodeManagerTable.loadModel, for example.

  • New: UaBinaryFile, can be used to read UABinaryFileDataType encoded in a file.

  • New: Attributes.getAttributeId(String)

  • New: UnsignedByte, UnsignedShort, UnsignedInteger and UnsignedLong: added methods incOrWrap, incOrWrapTo, decOrWrap and decOrWrapTo

  • New: UaNode.getAttributesMap()

  • New: UaNode.addOrganizes(UaNode)

  • New overload: UaNode.addReference(ExpandedNodeId nodeId, NodeId referenceTypeId)

  • New overload: UaNode.addReference(NodeId nodeId, NodeId referenceTypeId)

  • New overload: UaNode.addReference(UaNode targetNode, NodeId referenceTypeId)

  • New: QualifiedName, UaNodeId, UaExpandedNodeId, UaQualifiedName, UaNamespace and UaApplicationURI now implement Comparable.

  • New: UaNode.getBrowsePaths() and UaNode.getUaBrowsePaths()

  • New: UaArrayDimensions.parse(String)

  • Changed: UaArrayDimensions.toString() format changed to "[x, y, z]", respective to what parse expects.

  • Changed: JsonEncoder to use reversible decoding only when instructed (PubSub uses the JsonDataSetMessageContentMask.Options.ReversibleFieldEncoding flag that was added in 1.05).

  • Fixed: UaAddress.parse can now handle FQN addresses ending in a dot (the dot is removed).

  • Fixed: DataValue.clone() didn’t deep-clone the value.

  • Fixed: com.prosysopc.ua.stack.core.OptionSet.Fields now implements FieldSpecification directly, com.prosysopc.ua.stack.core.OptionSet.Fields.getSpecification() is now deprecated (and was changed to return 'this').

  • Fixed: XmlDecoder.getMatrix worked incorrectly in some cases.

  • Fixed: JsonDecoder, Variant decoding to treat the value as raw string if "Type" field is missing (in addition to previous functionality that checked whether "Body" exists).

Changes to Client SDK

  • Improvement: Refresh the NamespaceTable before re-creating failed MonitoredItems for Subscriptions.

  • Fixed: Possible NPE if the server didn’t send (although required) any Certificate, when UserName or Certificate based user authentication was defined.

  • Fixed: Client-side decoding failures of Server-sent messages caused a timeout (instead of failing with Bad_DecodingError).

Changes to Server SDK

  • SECURITY IMPROVEMENT: Add more randomness when decryption or signature verification fails to reduce the risk of timing-based attacks.

  • SECURITY IMPROVEMENT: Corrected maximum connection management.

  • Memory leak fix: Non-activated Sessions that were closed due to reaching MaxSessionCount were not cleaned up properly.

  • New: SessionManager.closeSession, can be used to close a Session from the server side. Useful, if you need to distrust an application and close the earlier connections immediately.

  • New: SubscriptionManager.getSubscriptions().

  • New: ServerCapabilities nodes (/Root/Objects/Server/ServerCapabilities/*): MinSupportedSampleRate, MaxSessions, MaxSubscriptionsPerSession, MaxMonitoredItemsPerSubscription, MaxSubscriptions and MaxMonitoredItems. The MaxSubscriptions/MaxMonitoredItems are calculated based on the SDK limits for Sessions and Subscriptions.

  • New: com.prosysopc.ua.server.Subscription.beginNotify(), can be used as a transaction for advanced use cases to prevent automatic notifications of data changes until endNotify() is called.

  • New: Support com.prosysopc.ua.stack.core.GenericAttributes for AddNodes service.

  • New: InstanceDeclarationHierarchy.findFirstMatch(RelativeNamePath, boolean, Predicate<UaNode>), for advanced use cases of searching UaNode that matches the given Predicate.

  • New: NodeManagerTable.loadModel(UaNodeSet…​)

  • New: UaServer.addReverseConnection(String)

  • New: UaServer.addReverseConnection(ReverseConnectionParameters)

  • Improvement: UaServer.addReverseConnection(String) and ReverseConnectionParameters.from(String) now accept "inv+opc.tcp" and "rcp+opc.tcp" URL prefixes, in addition to "opc.tcp", to be used for the Reverse Connection address.

  • Changed: SubscriptionIds for Subscription now start by default from a value based on the current time, to avoid reusing old SubscriptionIds at startup. This can be changed via SubscriptionManager.setNextSubscriptionId(UnsignedInteger).

  • Changed: Protected IoManager methods beginRead and endRead call sequence (same applies for beginWrite and endWrite). Previously they were called in pairs for each Namespace, now beginRead is called first for each Namespace before starting processing, thus enabling better handling in asynchronous implementations.

  • Changed: Use StatusCodes.Bad_SecurityPolicyRejected over Bad_SecurityModeRejected in CreateSession if the SecurityMode is not supported. Required by the CTT.

  • Fixed: SecureChannel Token lifetime was not revised. New defaults are: minimum 10 minutes, maximum 1 hour. These can be configured via StackUtils.setSecurityTokenLifetimeMin(UnsignedInteger) and StackUtils.setSecurityTokenLifetimeMax(UnsignedInteger).

  • Fixed: Added a (fixed) retry delay for Reverse Connections.

  • Fixed: Clear BrowseContinuationPoints and HistoryContinuationPoints immediately, when a Session is closed.

  • Fixed: Do not return InverseName Attribute for Symmetric ReferenceTypes. Required by the CTT.

  • Fixed: Do not fail loading NodeSets that contain 'RolePermission' and 'RolePermissions' XML elements (they are ignored, since Roles are not yet supported).

  • Fixed: Incorrect HasTypeDefinition References were created, if an UaNodeBuilderConfiguration instantiated something for PlaceHolder nodes whose TypeDefinition is the same as the one to be instantiated.

  • Fixed: Use StatusCodes.Bad_MethodInvalid (instead of Bad_NodeIdUnknown) when Calling a Method that doesn’t exist.

  • Fixed: SessionManager.getSessions() didn’t return Sessions that were not yet activated.

Changes to PubSub SDK

  • New: PubSubConnectionCommands.PUB_SUB_RESTART_CONNECTION, allows restarting an enabled connection (mainly useful for UDP-UADP).

  • Fixed: Do not send UADP Discovery requests, if receiving messages without a PublisherId.

Changes to Code Generator

  • New: Automatically exclude certain BrowseNames (such as "Description") that would cause generated code to conflict with the SDK core API.

Changes to SampleConsoleClient

No Changes.

Changes to SampleConsoleServer

  • New: Added an option to toggle ServerState between Running and Failed for testing purposes.

  • Changed: Don’t enable engineering units and other semantic properties to be written from client applications, as it is not recommended in general.

Other

  • Javadocs are back in Java 8 format due to issues with some Integrated Development Environments (IDEs).

Plus a number of other small changes.

Version 5.0.2

Build: 5.0.2-105

Release date: 18.10.2023

This is a bug fix release of the SDK. It additionally contains some new features.

The Client side UaClient.historyReadXXX methods each now have an overload that takes multiple NodeId.

The Server side localization (LocalizedText) now handles a "best match" search (based on OPC UA Specification rules) when none of the locales given by the Client is a direct match.

Changes to Common parts

  • New: LocalizedText.asSingleLocale, supports "best match" search (mostly used internally in the server side).

  • Fixed: JsonEncoder now escapes control characters for Strings.

  • Fixed: XmlElement.hashCode no longer throws NPE.

  • Changed: XmlElement now stores data internally always as a String.

  • Changed: XmlElement now allows invalid XML. Calling XmlElement.getNode for invalid XML throws.

Changes to Client SDK

  • New: Added NodeId[] overloads of multiple UaClient.historyReadXXX methods.

  • Fixed: UaClient.connect process hang if connecting to a server that had a custom SimpleType whose supertype was a custom SimpleType.

  • Fixed: Calling UaClient.connect directly after a UaClient.disconnect caused a race condition, which could result in multiple errors.

Changes to Server SDK

  • Fixed: Reverse Connections didn’t work in 5.0.0.

  • Fixed: Having sampling interval larger than publish interval for a MonitoredItem caused an NPE if DataValue timestamp was before Java Epoch.

  • Fixed: Removed UaNode is no longer cached in the "last operation UaNode" cache.

  • Changed: Allow Session.INTERNAL_SESSION to read /Root/Objects/Server/ServerDiagnostics/SessionsDiagnosticsSummary/SessionSecurityDiagnosticsArray node.

Changes to Code Generator

  • Fixed: Having an UInteger-OptionSet Method argument from a different namespace than the one being generated caused an NPE.

It is recommended to re-generate code using this version of Codegen.

Changes to SampleConsoleClient

No Changes

Changes to SampleConsoleServer

No Changes

Other

Plus a number of other small changes.

Version 5.0.0

Build: 5.0.0-95

Release date: 20.09.2023

This is a new major release of the Prosys OPC UA SDK for Java.

The SDK version 5 is based on the OPC UA specification version 1.05. The 5.0.0 release adds support for the 1.05 information model. Other 1.05-specific functionality will be added later, if needed.

This release for the first time in SDK history changes the minimum required Java version needed to run the SDK from Java 6 to Java 8. Thus now every edition requires Java 8 (in 4.x the PubSub-capable editions already required 8).

LocalizedText now handles all localized versions of a String within the same java object. LocalizedTextMap is removed and most of the API is found now directly in LocalizedText. Note that this mainly affects the Server side as Clients receive a single localized value based on the locale of the Session.

There is now a "super-concept" for all XXXSpecifications: UaDataTypeSpecification. Every OPC UA DataType shall now have an UaDataTypeSpecification within the EncoderContext. Simple types are represented by the added SimpleTypeSpecification. OptionSets (both numeric and Structure-based) are represented via added OptionSetSpecification.

This release adds XmlEncoder, the long missing counter-part of XmlDecoder. In addition, this internal encoding system now "keys" on UaNodeId as the DataTypeId and uses UaDataTypeSpecification instead of keying and being Java Class-based. The old "Serializer" system and related classes (and Codegen outputs) are removed. This change allows better handling of custom Structures, e.g. now it is possible to load a custom Structure <Value> from NodeSet2 XML that also has a field that is a custom Structure.

Codegen now generates a CommonInformationModel, which holds the generated UaDataTypeSpecifications. This model is automatically registered when ClientInformationModel or ServerInformationModel is registered. It is possible to load the CommonInformationModel manually via EncoderContext.registerModel(CommonCodegenModel model) if operating outside of UaClient/UaServer. The constructors of EncoderContext automatically register the core OPC UA information model that is generated by us and used also internally in the SDK.

In addition this release removes some of the internal use of reflection, but it is is not completely removed. As a related change (and future-proofing effort) the constructor of code-generated UaNodes has been changed to take in UaNode.Parameters.

The samples no longer create private keys with passwords. The functionality is NOT removed in the SDK, it is just not used anymore in the samples. In practice we feel this is better than using a hardcoded password in the sample code. A real application should support user-created certs and offer a way to enter and store the password. Note that due to this change if the new code of samples tries to load a private key made with the previous version samples it will fail.

Finally, the SampleConsoleServer sample also no longer by default enables the opc.https endpoint. It can be enabled by setting -P httpsPortNumber with a non-0 free port number, if needed. This is to reduce confusion, as opc.tcp is the endpoint every OPC UA Application supports (and must support) and should use. The SDK technically supports opc.https as well, but some of the security semantics regarding application level authentication work differently to opc.tcp and missing this fact can leave the server more open than desired. See the sample for a larger explanation.

Prosys OPC UA SDK Development Team

Migration Guide

Please see the Migration Guides section for more information on how to accommodate your applications to the new SDK. The tutorials have also been updated to reflect current functionality.

Changes to Common parts

  • New: com.prosysopc.ua.UaIds that holds the same constants as com.prosysopc.ua.types.opcua.Ids, but as UaNodeId (vs. ExpandedNodeId).

  • New: UaDataTypeSpecification, super-interface for all XXXSpecification interfaces.

  • New: SimpleTypeSpecification, models types that are either built-in or subtypes of those and not Enumerations, OptionSets or Structures.

  • New: In general propely support OptionSets, including custom ones.

  • New: OptionSetSpecification, OptionSpecification and UaOptionSet, offer generic handling of OptionSets similar to StructureSpecification+Structure

  • New: OptionSetStructureSpecification, generic description of OptionSet-structure subtypes.

  • New: Structure.toFieldsMap and toFieldNamesMap.

  • New: Ids (and UaIds) now contains additional identifiers from Identifiers that were not directly related to Types, e.g. the Server node constant now exist as UaIds.Server and Ids.Server.

  • New: ByteString.toBitSet returning java.util.BitSet and fromBitSet static factory method.

  • New: UaAddressSpace.getObjectsFolder() and getRoot helpers.

  • New: StatusCode now implements com.prosysopc.ua.BitField.

  • New: UaNodeId.parse(String).

  • New: UaQualifiedName.parse(String).

  • Changed: ExpandedNodeId.toString format now only escapes % and ; characters for the namespace uri component

  • Changed: LocalizedText now handles all localizations of the same value within the same LocalizedText instance. LocalizedTextMap is removed and majority of it’s API is now found directly from LocalizedText.

  • Changed: LocalizedText no longer has separate null vs. empty handling (as the binary encoding form for both should be the same "not present"). Null locales and values are instead now interpreted as empty strings.

  • Changed: StructureSpecification is now an interface instead of a class. Allows OptionSetStructureSpecification multiple inherit it and OptionSetSpecification.

  • Changed: UaType.getJavaClass() moved to UaDataType.getJavaClass(). Setter is removed. Getter returns based on EncoderContext.

  • Changed: Undo deprecation of UaAddressSpace.findNode.

  • Changed: IEncoder and IDecoder are now UaNodeId based, methods taking Class are removed.

  • Changed: AbstractOptionSetDataType.toSet() (the base for Codegen numeric OptionSet types) now returns a Set with deterministic iteration order. The order is order in which the Options are defined in OptionSetSpecification.getOptions().

  • Changed: UaNodeId.toString now uses the same format as ExpandedNodeId.toString.

  • Changed: UaQualifiedName.toString() now uses a format "nsu=NAMESPACE_URI;name=NAME_PART".

  • Deprecated: All constructors of DateTime. Use static factory methods instead.

  • Deprecated: StructureSpecification.toStructureBuilder, use toInstanceBuilder instead (this change allows it to be overridden in OptionSetStructureSpecification).

  • Deprecated: ObjectUtils, use methods from java.util.Objects instead.

  • Removed: UnsignedByte.assertValueInRange (is internal functionality).

  • Removed: Variant.compareTo. Variant was not Comparable and the implementation did throw for non numeric data.

  • Removed: KeyPairsKeyManager, not used internally and all methods just returned null.

  • Removed: SnapshotArray (use java.util.concurrent.CopyOnWriteArrayList instead)

  • Removed: Old Structure "Serializer system" and related classes that were used in 4.x and older major versions.

  • Removed: com.prosysopc.ua.stack.builtintypes.DataTypes (previously deprecated)

  • Removed: com.prosysopc.ua.stack.builtintypes.NodeReference, not used and com.prosysopc.ua.UaExpandedNodeId gives equivalent functionality, if needed.

Changes to Client SDK

  • Fixed: Connections failed to servers that missed the MaxNodesPerRead OperationLimit node.

  • Changed: Removed throws StatusException from UaClient.writeValues(NodeId[] nodeIds, Object[] value) and writeValues(NodeId[] nodeIds, Object[] values, NumericRange[] indexRanges) signatures as the exception is not thrown by the code.

  • Changed: AddressSpace.findNode is no longer deprecated, functionality was changed to call getNode instead of it’s NodeCache.findNode. Returns null if any exception thrown.

  • Deprecated MonitoredEventItem constructors that do not take an EventFilter (use the ones that do).

Changes to Server SDK

  • New: Support larger SamplingInterval(s) than PublishInterval for data-MonitoredItems.

  • Fixed: Nested custom structures in custom structure fields <Value> are now supported when loading NodeSets.

  • Fixed: Protected beginXXX and endXXX for IoManager and HistoryManager contained the whole request data, now it is properly split per namespace and only the relevant operations are given as parameter.

  • Changed: Use fully qualified version of the hostname when making the certificate (other samples already did this).

  • Changed: Using core OPC UA NodeSet version 1.05.02.

  • Removed: Previously deprecated StructureInfo+StructureInfoCache. Use StructureSpecification(s) from EncoderContext instead.

  • Removed: Internal BrowseContinuationPoint.getData and setData.

Changes to PubSub SDK

  • Changed: PubSubEvents is now PubSubSystemEvents.

  • Fixed: PUB_SUB_JSON_DATASET_MESSAGE_RECEIVED and PUB_SUB_UADP_DATASET_MESSAGE_RECEIVED are now Reader-level events and contain Reader configuration.

  • Fixed: In some cases PubSubSystemEvents were sent more than once.

Changes to Code Generator

  • New: Added option to split output packages per NodeClass. This is by default enabled, but not used for the core namespace that SDK embeds. Avoids rare conflicts where the same name exist within the same namespace for different NodeClass.

  • New: Generates a CommonInformationModel, which holds the generated UaDataTypeSpecifications.

  • Removed: internal defaults for the DI, ADI + PLCOpen models. Now the namespace package mappings must always be specified. See the sample di_adi_plcopen.xml configuration in the SDK distribution zip.

Changes to SampleConsoleClient

  • Changed: Generated private keys no longer use passwords. Loading of existing private keys made with older version (having a password) will fail.

Changes to SampleConsoleServer

  • Changed: Generated private keys no longer use passwords. Loading of existing private keys made with older version (having a password) will fail.

  • Changed: The opc.https endpoint is no longer by default enabled.

Changes to PubSub samples

  • Changed: Generated private keys no longer use passwords. Loading of existing private keys made with older version (having a password) will fail.

Other

  • The distribution now contains Migration Guides from all earlier major versions i.e. 1→2, 2→3, 3→4 in addition to the new 4→5 guide.

  • Evaluation edition start-up text now only appears in logger, similar to start-up text of other editions. This is part of our internal quality improvement effort, which one part is to ensure via forbidden-apis that e.g. system out/err is not used by the SDK code (outside of samples).

  • Also as a result for quality improvements, we internally run forbidden-apis default checks for "unsafe API". In addition, Some reflection-related code no longer calls setAccessible(true), this has the potential to impact old code regarding reflection. If you encounter an issue, let us know.