Prosys OPC UA SDK for Java

In the previous example, the serverAddress argument defines the server you are connecting to. Some sample addresses are provided in the following table:

<hostname> is the hostname of the computer in which the server is running. If it is running on the same machine localhost and 127.0.0.1 also typically work in addition to the hostname.

The first part of the address defines the transport protocol to use. opc.tcp refers to OPC UA TCP communication which is usually the preferred protocol. An alternative transport protocol is OPC UA HTTPS, which some servers may support as well, but in general it is not used very much as it does not offer real benefits to the highly optimized OPC UA TCP protocol. You can use opc.https addresses to communicate with those servers.

OPC UA Specification 1.04 defines a new way to open OPC UA TCP connections, called Reverse Connection. In this mode, the server application will open the connection, contrary to the normal connection opened by the client. This can be useful in situations where the server is behind a firewall that cannot let client connections go through to the server.

In order to enable the reverse connection, the client application will first open a TCP/IP socket in a custom port. The Server may then open the connection to the client socket. After that the client will create the OPC UA TCP secure channel and session to the server as usual, including all security details.

In UaClient this can be achieved by defining the socket to be listened with either UaClient.setReversePort() or UaClient.setReverseAddress(). For example:

Now, when you call connect(), the client will go waiting for connections from servers. Note that you should not use UaClient.setAddress() in this case.

You should also define a listener to validate incoming connections from the server using UaClient.setReverseConnectionListener(). For example:

All OPC UA applications must define some characteristics of themselves. This information is communicated to other applications via the OPC UA protocol when the applications are connected.

For secure communications, the applications must also define an Application Instance Certificate, which they use to authenticate themselves to other applications they are communicating with. Depending on the selected security level, servers may only accept connections from clients that they trust.

In addition to verifying the identity of the applications, OPC UA also enables verification of user identities. In UaClient, you can define the identity of the user with the UserIdentity class. The SampleConsoleClient does not do that by default, as each server defines what kind of user identities it supports. You can define a user identity that uses a standard username and password combination

Another alternative is to use a certificate and private key, similar to the application instance identity, or a WS-SecurityToken provided by an external security system (e.g. SAML or Kerberos). To find out which user token types are supported by the server, call

An integral part of all OPC UA applications, in addition to defining their own security information, is of course, to validate the security information of the other party.

To validate the certificates of OPC UA servers, you need to define a CertificateValidator in the UaClient. This validator is used to validate the certificates received from the servers automatically.

To provide a standard certificate validation mechanism, the SDK contains a specific implementation of the CertificateValidator, the DefaultCertificateValidator. You can create the validator as follows:

The way this validator stores the received certificates is defined by the certStore, which in the example is an instance of PkiDirectoryCertificateStore. It keeps the certificates in files in specific directories, such as 'PKI/CA/certs' and 'PKI/CA/rejected'. The trusted certificates are stored in the 'certs' folder and the untrusted in 'rejected'. By default, the certificates are not trusted so they are stored in 'rejected'. You can then manually move the trusted certificates to the 'certs' directory.

Additionally, you can plug in a custom handler to the Validator by defining a ValidationListener:

where

The SampleConsoleClient application uses the listener to prompt the user how previously untrusted certificates should be treated. The user can accept the certificate permanently, just once or reject it. In the first case, the certificate is placed in the 'certs' folder automatically, and in the latter cases, it is placed in the 'rejected' folder. In the last case, connection to the server is cancelled due to the certificate rejection.

You are, of course, free to use the listener to define any custom logic, but in principle, you should only trust certificates for which passedChecks equals CertificateCheck.COMPULSORY. Although self-signed certificates should not be used in proper onsite installations, that check is not included in the COMPULSORY definition. Most OPC UA certificates are still self-signed, because they are easy to generate automatically. A proper Certificate Authority should be preferred in real systems, though, to enable a proper, centrally administered certificate management.

The hostname check for OPC UA Application Instance Certificates is used for a similar purpose. But in practice this is only really useful when CA certs are used (as should be the case in real world installations). The SDK does not provide any implementation for this check, yet, so it must be done on the application level. See MyCertificateValidationListener.validateHostnameOfCertificate(Cert) for details. Also, note that the users of your application should be able to suppress or disable this check, for use cases where it does not apply.

OPC UA uses security heavily to guarantee that the applications can be safely used in real production environments. The security only works when configured properly, so you should make yourself familiar with the concepts and learn to configure these systems.

Read the OPC Unified Architecture book by Mahnke et al., for example, for more details on the OPC UA security settings and how they should be applied. The security technology follows standard PKI (Public Key Infrastructure) principles, so all material related to that can also be used to understand the basics.

Also, try different settings in different environments, so that you know more than you guess.

Each service call that you make to the server can fail, for example, if the connection is lost due to network problems or the server is simply shut down.

Typically, the first thing to do is to find the server items you wish to read or write. The OPC UA address space is a bit more complex structure than you might expect, but nevertheless, you can explore it by browsing.

In the UaClient, the address space is accessed through the AddressSpace property. You can call browse() to request Nodes from the server.

The SampleConsoleClient uses an internal variable, called nodeId to keep track of the "Current Node" that is the target of all client operations. The nodeId is initialized to the value Identifiers.RootFolder, which is a standard NodeId defined in the OPC UA specification. It corresponds to the root of the address space, which all servers must support. In addition, the servers must provide three standard subfolders under the RootFolder: ObjectsFolder, TypesFolder and ViewsFolder. You can start browsing from one of these to dynamically explore the available data and metadata (such as types) available from the server.

So, in order to browse the address space with the SampleConsoleClient, you start from the RootFolder and follow References between the Nodes. There may be a huge number of References from a Node, so you can define some communication limits to the server. You can set these with the different properties of the AddressSpace, e.g.:

by which you define a limit of 1000 References per call to the server and that you only wish to receive the hierarchical References between the Nodes.

Now, if you call

you will get a list of ReferenceDescription entries from the server. From these, you can find the target Nodes, which you can browse next. In the SampleConsoleClient, you may choose which Node to browse next, or to end browsing and stay at the Node you are at that point. Check the sample code to see the specifics of the methods that are used to let you browse around the address space.

An alternative way to browsing using specific NodeIds is to follow the references between Node objects. You can access the References simply with node.getReferences(), for example. See the section Using Node Objects for more about that.

OPC UA has also a specific service that enables you to find the NodeId of a node by following a BrowsePath - a sequence of references from another node. This is most often used to locate components and properties of object and variable instances, corresponding to a known structure that is defined in the respective type definition. But, you can use it to find nodes, if you know their relative location anywhere in the address space.

The AddressSpace object has methods translateBrowsePathToNodeId and translateBrowsePathsToNodeIds that you can use. As input, you will need to prepare a list of RelativePathElement structures and as a result you will get an array of BrowsePathTarget structures. In the sample, we prompt the user for s path string and we split that using '/' characters. We also assume that the path should be followed using HierarchicalReferences only. But in real, you can defined any references, for each RelativePathElement.

To monitor data changes in any Variable, you can use a MonitoredDataItem. For example:

The subscription defines the default monitoring properties, namely the PublishingInterval that are shared by all items. Alternatively, the items may define individual details through their own properties.

Once the subscription and monitored items are defined, you can just listen to data change notifications via a DataChangeListener:

In order to listen to events in Event Notifier Objects, you can use MonitoredEventItems.

Basically, all objects that send events, should have the SubscribeToEvents bit set in their EventNotifier attribute. But, since not all servers obey this rule, you can always try to monitor any object and we also ignore that in our example.

First of all, you must define an EventFilter that specifies more details on which events and which data from them you wish to monitor. To start, you must define the SelectClauses for the filter. They will specify the event fields that you wish to monitor. Additionally, you may also define WhereClauses, which you can use to actually choose which exact events you wish to receive.

In the SampleConsoleClient, we have defined the event fields using a custom manner as follows:

You may also wish to listen to the alive and timeout events in the subscription. These will help you verify that the server is actively monitoring the values, even in the case that the values are not actually changing and therefore new data change notifications are not being sent. The example below demonstrates how to add such a listener to a subscription:

The functionality related to different events must be implemented in the respective methods of the listener class:

The Subscription is always attached to a client Session, but you can transfer the Subscription to another Session, if necessary.

The SDK typically handles connection breaks automatically and creates new sessions whenever required. It can also transfer the Subscription automatically to a new Session when required or even create a new Subscription with new MonitoredItems, if the Subscription also times out.

Additionally, you can create a new UaClient instance and use the Subscription.transferTo(UaClient) method to move the Subscription to the new client. It is recommended to connect the new client to the server first.

transferTo will use the OPC UA TransferSubscription service to enable seamless continuation of monitoring in fail-over situations. The SDK only enables that within the same application, though, using the Subscription and MonitoredItems objects.

Should you need to move a Subscription to another, redundant, client application, you will need to exchange information about the MonitoredItems between the applications. This will enable creating a new Subscription with similar parameters in the other client, but not the TransferSubscription service.

To actually read history data, you have several options. The basic way is to use UaClient.historyRead(), which is recommended if you need to do several readings at once. This example reads a complete history for a single Node (specified by nodeId):

What you need to be aware of is that there are several “methods” that the historyRead() actually supports, depending on which HistoryReadDetails you use. For example, in the above example we used ReadRawModifiedDetails, to read a raw history (the same structure is used to read modified history as well, therefore the name).

To modify existing history data in the server, you can use the historyUpdate() method or, again, one of the convenience methods that provide you with more semantics. See the documentation for the various historyUpdateXxx() and historyDeleteXxx() methods in UaClient for more about those.

You can generate Java classes based on information models stored in the NodeSet files with the Code Generator provided with the Prosys OPC UA SDK for Java. The Code Generator is located in the 'codegen' folder of the distribution package.

Follow the instructions in the included manual and experiment with the samples to learn how to configure and execute the code generation procedure. Then you may return to this tutorial and read the following sections on how to utilize the generated classes in your own applications.

The Java classes generated with the Code Generator enable simple usage of the OPC UA information models. With the generated classes, the client application is able to handle the instances of the custom types in OPC UA servers as Java objects.

This section explains how the Java classes generated using the Code Generator can be imported and utilized in applications developed with the Prosys OPC UA Client SDK for Java.

The generated Java classes for ObjectTypes and VariableTypes are more extended versions of the standard UaNode implementations. In order to let the SDK use the generated classes, the SDK must be made aware of the generated classes. This is done by registering the model.

The client implementation classes are generated into 'client' sub-packages under the defined generation folders.

To use the generated Java classes in your applications:

The SDK distribution package provides a sample information model in the 'SampleTypes.xml' file that is in the 'models' folder (both the command line and Maven version of Codegen). A complete example of the procedure for using an instance of the ValveObjectType from the 'SampleTypes.xml' model is demonstrated in the following example:

The OPC UA builtin types define how to communicate integers and floating point values of different precision, strings, byte arrays (ByteStrings) and a few custom OPC UA types, such as LocalizedText, QualifiedName etc.

All of these can be extended in practice, but for the simple types the values don’t really change and the custom types only define more refined semantics.

The OPC UA specification defines a DataType called Structure that can represent any complex datatype. The custom structures are all extending this and they can consist of any number of Fields that can be of any data type. Fields can also be arrays of any data type.

Enumeration types define a fixed set of values. They are transferred as Int32 (i.e. Integer) on the wire and thus you will get it as such from UaClient.readValue(), for example.

OptionSet types are split into 2 categories, but both represent bitsets; collections of Boolean on/off flags. There are both 'Structure OptionSets' and 'UInteger OptionSets'.

'Structure OptionSets' are subtypes of the OptionSet structure. 'UInteger OptionSets' are subtypes of any UInteger type (Byte, UInt16, UInt32, UInt64) and they have an OPC UA Property called OptionSetValues.

In order to enable processing the metadata and values of the different types, including all simple types, the SDK defines a Java interface UaDataTypeSpecification, that has specific implementation for each variety, as follows:

SimpleTypeSpecification has only a name, TypeId, BaseTypeId and the Java class corresponding to it. All simple types in OPC UA are encoded as their base type on the wire.

EnumerationSpecification includes the alternative Values for the specific Enumeration type.

OptionSetSpecification includes the alternative Options for the OptionSet. They are modeled as OptionSpecification.

StructureSpecification includes all Fields for the Structure. They are modeled as FieldSpecification.

OptionSetStructureSpecification models both Fields (similar to the OptionSet Structure, which means that new fields cannot be added to it) and Options.

The Enumeration, UaOptionSet, Structure and OptionSetStructure all have a method .specification() that can be used to obtain the respective UaDataTypeSpecification. Additionally they have API that allows generic processing. For example, Structure has get/set methods that can be used with a FieldSpecification or field name. This allows building generic handling when reading the Value Attribute. Note that for Enumeration the value is still a Integer (as they are encoded as Int32), thus you must also read the DataType Attribute, and then find the correct EnumerationSpecification from the EncoderContext.

By default SDK reads metadata from the server as part of UaClient.connect and forms the UaDataTypeSpecification that represents the custom types. The Prosys OPC UA SDK for Java Code Generator also creates UaDataTypeSpecification that SDK loads when the model is registered.

Every UaClient and UaServer instance uses an EncoderContext, which includes all known type specifications. UaClient initializes them when it connects to the server as part of the TypeDictionary initialization. Alternatively, the client can also access the type specifications directly from the DataTypeDefinition attributes of the DataType nodes.