Prosys OPC UA Java SDK 2.0.0

Feature Highlights

• OPC Foundation Java Stack 1.02
• HTTPS protocol
• New SecurityPolicy: Basic256Sha256
• More flexible security library usage (Bouncy Castle/Spongy Castle(for Android)/Sun JCE)
• Standard OPC UA types as (generated) Java classes both on the client and server side
• Option to use types for companion specifications (DI, ADI, PLCopen)
• Code generator for enabling usage of custom types, both on the server and client side
• Support for OPC UA File Transfer (FileType)
• Enables disabling SecurityMode.None in the server
• Enables disabling the internal discovery server
• Enables binding the server to network interfaces independent of the EndpointUrls

New features

Main new features of the stack are support for HTTPS protocol and SecurityProfile.BASIC256SHA256 security profile. The stack also enables alternative security libraries, instead of the fixed Bouncy Castle. This was done using standard Java APIs (JCE) instead of Bouncy Castle's API (meaning Bouncy Castle is now just another security provider).

The stack is now using the standard Java Cryptography Extension (JCE) framework for enabling the selection of security library that is used (via SecurityProvider). The main consequence is that since the standard security policy in the JCE allows a maximum of 128-bit encryption algorithms, you must install the "JCE Unlimited Strength Jurisdiction Policy Files" into the JRE to enable 256- bit security. The downloads are available for JRE6, JRE7 and JRE8.

The SDK has also been taken through the Compliance Test Tool and it passes all the tests except for a few cases. We will continue improving the compliance still to get a fully compliant SDK.

The SDK now includes a code generation tool which generates Java classes from types defined in NodeSet2.xml files. The generated code contains getters and setters for child variables and objects. Methods can be implemented and called. Custom structures and enumerations can be used. Generated code can be used on both client- and server-side, although only getters are implemented on the client-side.

New types include the FileType, which enables File Transfer over OPC UA. The SDK introduces a FileNodeManager and FileSyncClient for working with those. See the Server Tutorial for more about that.

Migration Guide

The tutorials have also been updated to reflect current functionality.

OPC Foundation Java Stack changes

• Build 1.02.335.6
• New: Support for certificates bigger than 2048 bits (work in progress)
• New: CertificateUtils.createIssuerCertificate()
• New: CertificateUtils.getApplicationUriOfCertificate()
• New: SecurityProfile.BASIC256SHA256 (requires big certificates)
• New: SecurityAlgorithm, replacing old SecurityConstants
• New: equals() and hasCode() generated to Structure types
• New: ExpandedNode(uri,value) constructor (assuming serverIndex=0)
• New: ObjectUtils.equals(left, right)
• New: valueOf(int[]), valueOf(Integer[]), valueOf(UnsignedInteger[]) for all Enumeration types
• New: LocalizedText(string) constructor (assumin NO_LOCALE)
• New: IEncoder.put(), IDecoder.get, EncoderUtils
• New: DataValue.clone()
• New protocol: HTTPS
• Fixed: GetEndpoints request handled even if SecurityMode.None is not enabled in the server
• Changed: Security reworked to make Bouncy Castle an optional security library to use.
• Changed: Server side implementation reworked also affecting the binary communications (should be compatible with the old one, though)
• Changed: NumericRange supports several dimensions
• Changed: ExpandedNodeId used in places where NodeId was previously used. In addition, EncoderContext is required in some methods. The EncoderContext object is available from Server and Client objects.
• Changed: XmlDecoder.setNamespaceTable() to enable mapping of namespace indexes between XmlElements and the target system
• Changed: Refactored HttpsServerSecureChannel to inherit from AbstractServerSecureChannel
• Fixed: Do not check the securityMode when opening the channel - to enable only secure endpoints used for actual connections (since GetEndpoints must be performed over an insecure channel, anyway)
• Fixed: Do not use namespace to calculate ExpandedNodeId.hashCode() - since the same namespace will give different hashCodes depending on which is used
• Fixed: CryptoUtil.asymmEncrypt() did not use the correct transformation - failing with 256 bit user password encryption.
• Fixed: Use createNonce() with the symmetricEncryptionAlgorithm, instead of asymmetric, in OpenSecureChannel
• Plus a lot of other minor changes

Library Changes

• Changed: bc is Bouncy Castle security library, which is updated to v1.47, but is now optional, although still recommended. The Sun sceurity implementation is used (when available), if Bouncy Castle is not included.
• New: sc is Spongy Castle, which is only needed for Android applications
• New: http is Apache HTTP Core, which is only needed to support the HTTPS protocol
• New: commons-logging is only used by the Apache HTTP Core classes
• Unchanged: log4j is necessary for SDK & stack internal logging

Changes to both SDK Client and Server

• Changed: UaApplication.Protocol.Opc renamed to OpcTcp
• Changed: AddressSpace.getNode() no longer throws StatusException
• Changed: UaClient.getNamespaceTable() and getServerTable() no longer throw exceptions
• Changed: PkiFileBasedCertificateValidator returns Bad_SecurityChecksFailed instead of Bad_CertificateUntrusted (according to CTT requirements)
• Changed (thrown exception change): DataTypeConverter.convert() to throw ServiceResultException instead of ClassCastException.
• New + Interface Change!: UaNode.getAddressSpace(): returns UaAddressSpace of the node
• New + Interface Change!: UaVariable.addDataChangeListener(DataChangeListener), UaVariable.removeDataChangeListener(DataChangeListener) (not implemented on client-side yet)
• New + Interface Change: UaVariable.setValue(Object)
• New: UaApplication.getSdkVersion(), replacing getVersion()
• New: UaApplication.getAddressSpace()
• Removed: PkiFileBasedCertificateValidator.getApplicationUriOfCertificate() - use CertificateUtils.getApplicationUriOfCertificate() instead
• New: UaApplication.Protocol.Https
• New: UaApplication.Protocol.getTransportProfileUri()
• New: ApplicationIdentity.set/getHttpsCertificate
• New: ApplicationIdentity.getCertificates
• New: ApplicationIdentity.loadOrCreateHttpsCertificate()
• New: ApplicationIdentity.loadOrCreateIssuerCertificate()
• New: ApplicationIdentity.loadOrCreateCertificate() with a new overload
• New: ValueRank.toString()
• New: UaAddressSpace, a common inteface of UA address space viewed from server and client side. Both AddressSpace and NodeManagerTable implement this
• New: UaApplication.getAddressSpace()
• New: UaApplication.registerModel(CodegenModel): registers a generated information model
• New: UaApplication.getEncoderContext(): returns EncoderContext of the application
• New: UaServer.registerAndLoadModel(CodegenModel, URI): registers a generated information model and loads the respective Nodeset XML
• New: AddressSpace.getNode(NodeId, Class)
• Fixed: DataTypeConverter.convert to UnsignedByte threw exceptions for values > 128

Changes to SDK Client

• Changed: MonitoredDataItem.setDataChangeFilter() & MonitoredEventItem.setEventFilter() to throw ServiceException instead of StatusException
• New: MonitoredDataItem.set/getDataChangeListener() replacing the former add/removeChangeListener(), etc. which are now deprecated (but work for one listener)
• New: MonitoredEventItem.set/getEventListener() replacing the former add/removeEventListener(), etc. which are now deprecated (but work for one listener)
• New: UaClient.get/setHttpsSecurityPolicies()
• New: UaClient.get/setHttpsHostnameVerifier()
• New: UaClient.setEndpoint()
• New: UaClient.discoverEndpoints(Protocol...)
• New: Subscription.setPublishingInterval(long,TimeUnit)
• New: MonitoredDataItem.setSamplingInterval(long,TimeUnit)
• New: FileSyncClient
• New: New overloads to UaClient.readXxx & writeXxx
• New: UaClient.getOperationLimits()
• New: Subscription.getSetMaxMonitoredItemsPerCall()
• Fixed: UaClient.setUserIdentity no longer return the old identity in use, if it fails
• Fixed: UaClient ServerState will change to Unknown if re-activation (impersonation) fails
• Fixed: AddressSpace.readReferences to remove node's references that have been removed from the server.

Changes to SDK Server

• Moved: static methods BaseEventType.createEventId() createFullEventId() and extractUserEventId() to EventManager
• Removed: All standard node implementations in com.prosysopc.ua.server.nodes.opcua package removed
• Interface Change!: NodeManagerListener.onDeleteReference(); parameter list changed to include NodeId and UaNode of each (source, target, referenceType)
• New + Interface Change!: HistoryManager.begin/endHistoryRead() & begin/endHistoryUpdate() and the signatures of all specific methods changed
• New + Interface Change!: HistoryManagerListener.begin/endHistoryRead() & begin/endHistoryUpdate() and the signatures of all specific methods changed
• New + Interface Change!: SessionManagerListener.onActivateSessionError() & onAfterActivateSession()
• New + Interface Change!: UserValidator.onValidationError()
• New + Interface Change!: abstract NodeManager.getNodeClass(NodeId)
• New + Interface Change!: UaServerListener.onRegisterServer()
• New + Interface Change!: NodeManagerListener.onGetReferences(NodeId, UaNode, List)
• New + Interface Change!: UaServer.getAddressSpace() replacing getNodeManagerTable()
• Interface Change!: NodeManager.getNodeClass(ExpandedNodeId) is no longer abstract
• New: NodeManagerTable.getNodeClass(NodeId)
• Changed: EventType and FireEventMethod have been moved to com.prosysopc.ua.server.nodes.
• Changed: Default implementation of NodeManager.deleteNode and NodeManager.deleteReference to use findNodes for the params, and not throw an exception (Bad_NotImplemented)
• Changed: NodeManagerTable to call deleteReference to the node manager of target node as well, if different than the one that owns the source node
• Changed: ServerNode stores references internally in a HashSet instead of ArrayList
• New: UaServer.get/setHttpsPort()
• New: UaServer.get/setHttpsSecurityPolicies()
• New: UaServer.get/setHttpsWorkerThreadCount()
• New: UaServer.get/setEndpointConfiguration()
• New: UaServer.get/setBindAddresses()
• New: UaServer.get/setBindAddresses(Protocol)
• New: UaServer.get/setServerName(Protocol)
• New: UaServer.getHttpsUris()
• New: IoManager.begin/endRead & begin/endWrite
• New: ServerUserIdentity, which is also used as parameter instead of UserIdentity in the server side
• New: FileNodeManager
• New: FileFolderType
• New: ServerNode.addNewReference() - fast implementation without checks
• New: BrowsePath
• Fixed: UserIdentity.decryptPassword tries to use all certificates of the ApplicationIdentity to decrypt
• Fixed: ServiceHandler.validateRequest will check for inactive sessions
• Fixed: The DiscoveryUrls of the application are updated to the ApplicationDescription
• Fixed: IoManager.readAttribute; Executable, AccessLevel & WriteMask are used to "retain" User-specific values
• Fixed: Server node attribute fields changed to volatile to inhibit possible threading clashes
• Fixed: CacheVariable initialValue changed to a new DataValue() to inhibit changes
• Fixed: UaVariableNode initializes the DataType to BaseDataType (to ensure it's never null)
• Deprecated: UaServer.is/setUseLocalhost() (use BindAddresses)
• Deprecated: UaServer.is/setUseAllIpAddresses() (use BindAddresses)
• Deprecated: UaServer.is/setHostName() (use BindAddresses)
• Deprecated: UaServer.is/setCanonicalHostName() (use BindAddresses)

Code Generation

Server Type Instantiation

• New: NodeManagerUaNode.createInstance(NodeId, String)
• New: NodeManagerUaNode.createInstance(Class, String)
• New: NodeManagerUaNode.createNodeBuilder(NodeId)
• New: NodeManagerUaNode.createNodeBuilder(Class)
• New: NodeBuilder
• New: NodeBuilderException
• New: NodeBuilderConfiguration, DefaultNodeBuilderConfiguration, CreateAllNodeBuilderConfiguration, JoinedNodeBuilderConfiguration
• New: UaInstantiationException
• New: InvalidTypeNodeException
• New: InstanceNodeIdFactory
• New: InstanceNodeIdFactoryImpl
• New: BrowsePath
• New: InstanceDeclarationHierarchy
• New: InstanceDeclarationSet
• New: TemporaryInstanceDeclaration
• New: TemporaryTypeNodeInstanceDeclaration
• New: InstanceDeclaration
• New: InstanceDeclarationImpl
• New: TypeNodeInstanceDeclaration
• New: ModelledInstanceDeclaration
• New: ReferenceDeclaration
• New: InstanceReferenceDeclaration
• New: InternalReferenceDeclaration
• New: ExternalReferenceDeclaration
• New: ModellingRule
• New: UaNodeUtils
• New: GeneratedNode

Changes to the Sample applications

• New: SampleConsoleClient.discoverEndpoints()
• New: SampleConsoleServer: MyEnumType and the respective UA nodes
• New: SampleConsoleServer.initialize() to include sample code, how to create the HTTPS certificate, signed by a self-created issuerCertificate
• New: SampleConsoleServer.initialize() to include sample code (commented out), how toinitialize the server with two application instance certificates and to use an issuerCertificate
• New: SampleConsoleServer.loadInformationModels, which enables loading of the DI,ADI & PLCopen information models from the respective XML files (disabled by default)
• New: SampleConsoleServer.createFileNodeManager()
• Changed: SampleConsoleServer.MyEventType
• Changed: SampleConsoleClient: display used SecurityPolicy, instead of the requested (which may be different when discovering the endpoint)
• Changed: Show usage of AnalogItemType on the client side etc.