Version 5.2.

0
Starting Guide

Guide
Starting
-
Java
for
SDK
UA
OPC
Prosys
Table of Contents
1. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
3. Tools for Java Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
3.1. Eclipse Integrated Development Environment (IDE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
3.1.1. Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3.2. Java Runtime Environment (JRE) and Java Development Kit (JDK). . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3.3. Build and dependency management tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3.4. Version control software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Using the Prosys OPC UA SDK for Java in Eclipse IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
4.1. Eclipse first start and creating a workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4.2. Creating New Java Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
4.3. Importing the Prosys OPC UA SDK for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.4. Adding Javadoc documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5. Extra information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
5.1. Eclipse code navigation and basic shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
5.2. Selecting Java version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.3. Regarding exporting and making the application run outside of the IDE . . . . . . . . . . . . . . . . . . . . 14
5.4. Maven integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1. Requirements
In order to follow this guide, you will need:

• A computer with an existing installation of Eclipse Integrated Development Environment (IDE) or

internet connection and permissions to download and install it. This is explained later in the guide.
• Basic Java development skills
• The Prosys OPC UA SDK for Java distribution. This is provided as a .zip file.

Not all operating systems by default show file endings, thus you might not see

 the .zip-ending, but anyway we mean the 'prosys-opc-ua-sdk-for-java-VERSION-

EDITION.zip' file.

2. Introduction
The purpose of this guide is to setup a "my first Java project" (i.e. the SDK samples) within Eclipse. If you
are an experienced Java developer, you can probably skip most of the tutorial and read the README,
javadocs and the other SDK tutorial for more specific details about the SDK itself.

If you know and use Apache Maven, see Maven integration for more information.

This guide will setup a simple Java development environment directly using Eclipse.

You might wish to eventually learn one of Build and dependency management

 tools, such as Apache Maven or Gradle. Most Java projects nowadays use either of
the two. However, they do have a learning curve and are considered outside of this
tutorial. Once you wish to build your application outside of Eclipse or have multiple
people in the team using different IDEs, it is recommended to learn one.

3. Tools for Java Development

This section contains info about the required software for Java development. If you are an experienced
Java developer, you can probably skip to the next chapter.

3.1. Eclipse Integrated Development Environment (IDE)

Java is one of the programming languages that needs good tooling to be productive. Luckily, it also has
very good tools. Thus, except for some very specific cases (you would/should already know everything
this guide has to offer), it is extremely heavily recommended that you use an Integrated Development
Environment (IDE) to write your own Java applications instead of a bare text editor.

An IDE typically offers a lot of support:

• Auto-completion (Java tends to have long names; auto-complete avoids the need to type
everything manually).
• Following code paths (Java doesn’t need any ordering function declarations, or methods as they are
called in java) thus navigating manually can be hard (each Class is also in their own file as well). In
general you should not be scanning a file manually from method to method, but use IDE shortcuts

1
 and commands to move around. Also there is typically an 'Outline' view of all the methods of a
given class file you have open, that should be used instead whenever you look for a method.
• Displaying (java)docs to see documentations of classes and methods.
• Compiling fast while you are typing and saving to spot errors early and offering suggestions for
fixes.
• Finding all the places a method is called.

3.1.1. Eclipse
This guide uses Eclipse as the example IDE. It is free and open source. The reason for selecting Eclipse is
that the writers of this guide have the most experience with it, but you should try out other IDEs as well.
The main point is that you use one. It is outside the scope of this tutorial to teach Eclipse, other than
making the project. You can download and install from the Eclipse website. On the Download page, or if
using the installer one, select the "Eclipse IDE for Java Developers" one.

Current Eclipse versions only support 64-bit operating systems, including AArch64-

 based Linux/macOS. If you are on 32-bit Windows, you might be able to use an
older version of Eclipse.

It is recommended to read Eclipse code navigation and basic shortcuts. Please at

 least do once you start looking at the samples and coding. Menus and right-click
context menus can be used, but in general it is a lot faster to do so via shortcuts.

 Other popular IDEs are the IntelliJ IDEA and the NetBeans IDE.

3.2. Java Runtime Environment (JRE) and Java Development

Kit (JDK)
Modern Java applications typically come with a JRE bundled as part of the application, thus even the fact
that it is a Java-based application becomes implementation details. However, for developing them you
would typically require a JDK to compile them. Eclipse is a Java program by itself and requires a JRE to
run, but depending on the version and installation method it might also come with a bundled JRE.

Eclipse also comes with it’s own compiler, so technically you do not need a JDK to start out (typically the
javac compiler is part of a JDK), however, in general you will most likely need one at some point. You can
look at Selecting Java version at end of this guide when needed, also do that if your Eclipse installation
wont start. If you want to run your application outside of Eclipse, you will also most likely need to do
this.

3.3. Build and dependency management tools

Modern Java project uses some kind of tool for building the final package of the project (to be used by
users or as a dependency to another project). The same tool is usually handling all the dependencies
(and the dependencies of the dependencies) that the project might have.

This guide ignores this part and instead stops at the point where you can run the samples provided in
the SDK package from Eclipse. Build paths are configured manually. However, learning to use these
tools is eventually very recommended (they all have their advantages and disadvantages and having a

2
basic understanding of all of them might be beneficial). Basically with these you would typically just
type what dependency name and version you would need, and the IDE integration with the tool would
handle the rest.

Common tools in this category are:


• Apache Maven, see Maven integration for more info.
• Gradle
• Apache Ant (sometimes combined with Apache Ivy)

3.4. Version control software

The last piece is a Version control software. However, using one is outside of the scope of this tutorial,
but it is important enough that you use one to be still mentioned. Using one will allow you to go back to
an older versions of your code. Eclipse has limited history information while it is running, but it is lost
once you shut down the application.

Common tools in this category are:

Common tools in this category are:

• Git

 • SVN ("Subversion")
• CVS ("Concurrent Versions System")
• Mercurial

In general the authors of this guide recommend Git, it is the most used and recognized one. It is
extremely likely that if a company is using a version control (and everyone should!), it is nowadays Git.
SVN and CVS are more historical ones, it is possible to encounter them on more legacy projects, but
anything new should use Git. Though, it might have a bit more learning curve. Basically use whatever
your workplace or school provides you, it is important that you have also stored the info outside of your
computer in the case of hardware failures. Also typically the version control software is also the way
multiple people work on the code and handle code reviews and so on.

4. Using the Prosys OPC UA SDK for Java in Eclipse

IDE
This chapter demonstrates how to create a new Java project in the Eclipse IDE and how to import the
Prosys OPC UA SDK for Java into the project so that you can easily get started on testing the features of
the SDK. After completing the steps in this chapter, you should be ready to go through the tutorials for
developing OPC UA applications found next to this guide in the SDK distribution package.

The step-by-step instructions provided in this chapter are based on Eclipse 2022-09

 Release (4.25.0) running on Windows 10. The steps might be slightly different on
other versions of Eclipse or in other operating systems.

3
4.1. Eclipse first start and creating a workspace
When you first start Eclipse, you’ll be asked to create a so called workspace folder:

Figure 1. Eclipse workspace selection.

You’ll be treated with a welcome tab, which you can close.

Figure 2. Eclipse Welcome screen.

4
4.2. Creating New Java Project
To create a new Java project for using the SDK in Eclipse, follow the steps below:

1. Go to the File menu and click New → Java Project. Alternatively since there are no projects, the
'Package Explorer' on the left will have a shortcut to do this.

Figure 3. New Java Project.

2. Uncheck the 'Create module-info.java' checkbox at the bottom.

Newer Eclipse versions will by default create a module-info.java file if on Java

9+. The SDK has not been tested in so called "module path" (compared to the
traditional "class path"), and it is outside of this tutorial to try use or explain
 the Java Module system. Thus, in this tutorial we uncheck the 'Create module-
info.java file' in the 'Module' section and not use the Java Platform Module
System. In practice you can basically forget that it exists.

5
 Figure 4. Settings for new Java project.

3. Enter a Project name, e.g. "SDK Test".

4. The Use default location checkbox is enabled by default and points to the Eclipse workspace, which
is suitable for this tutorial. You may untick the checkbox and define another location where the
project will be saved.
5. The other settings are fine with their default values, press Finish.

4.3. Importing the Prosys OPC UA SDK for Java

After creating a new empty Java project in Eclipse, follow these steps to import the required SDK files to
the project so that you can start testing the functionality:

1. Open the project folder (either in Eclipse or your operating system’s file manager).

You can use the 'Show In → System Explorer' menu action to open the project
 folder.

6
 Figure 5. Open in System Explorer menu action.

2. Create two new folders called lib and javadoc at the project root folder. A src folder should already
be created, but if not, then create it as well.

Figure 6. Project root folder.

7
 3. Copy the contents of the samples/sampleconsoleserver/src/main/java and
samples/sampleconsoleclient/src/main/java of the SDK package into the src folder (no need to copy
the .bat, .sh and pom.xml files from the base folder). You can replace the files in the destination if
prompted.

The available samples depend on the SDK edition. The evaluation edition has
all samples, but otherwise only the samples that could be run are included.
This tutorial shows 'sampleconsoleclient' and 'sampleconsoleserver' examples,
 but the "pubsub" examples can also be added the same way. Also, for
simplicity sake, they are imported to the same project, but in a typical case you
would have a different project for each.

4. Copy the contents of the lib folder of the SDK package into the lib folder of the project.

5. Copy the contents of the javadoc folder of the SDK package into the javadoc folder of the project.

6. If you did the operations in your operating system’s file manager, refresh the project in Eclipse (by
selecting it and either pressing F5 or via right-click menu). At this point it is normal to get a warning
for each file, because we have not yet added the libs to the so called 'Build Path'.

Figure 7. View of the Eclipse Package Explorer after adding the required files to the project folder and
refreshing the project.

7. Add each file from the lib folder to the projects Build Path (select one or more and right-click and
click Build Path → Add to Build Path).

8
 Figure 8. Add library to Build Path.

8. Finally, you can expand the src folder and find the SampleConsoleClient and SampleConsoleServer
Java classes. You can run these by right-clicking them and selecting Run As → Java Application.

9
 Figure 9. Running the sample application.

4.4. Adding Javadoc documentation

For development, it is highly recommended that the Javadoc code documentations are attached to the
provided libraries. The SDK package provides Javadocs for the Prosys OPC UA SDK for Java. The
Javadocs can be attached to their respective libraries in Eclipse with these steps:

1. Right-click on the SDK library in the Referenced Libraries section of the Eclipse Package Explorer.

2. From the pop-up menu select Properties.

10
 Figure 10. Library Properties.

3. Click Javadoc Location from the left-side menu.

4. Select Javadoc in archive.

5. Select Workspace file.

6. Click Browse next to the Archive path: field.

7. Locate the javadoc folder under the root folder (named according to what you defined in the
beginning).
8. Inside the javadoc folder, you should click the Javadoc file that should be associated to the current
library, i.e. prosys-opc-ua-sdk-client-server-evaluation-5.x.x-xxx-javadoc.zip for the SDK.
9. Click OK.

11
 Figure 11. Setting the Javadoc for a library.

The project structure created here is suited for testing out the SDK. In general,
more advanced development typically uses some build tool, which usually follows
some conventions on how the project folders should be organized. In addition, the
libraries are typically not within a project folder, but instead they are linked by the
dependency management tool (which is typically also the build tool). Furthermore,

 they also typically link the Javadocs from the same place where they link the
libraries. The reason for this is that typically the project folder is in a version
control system (e.g. Git) and putting binaries to it is not generally seen as a good
idea (size grows large when new versions of libraries are released). Instead the
library and Javadoc dependencies are declared in a file for the dependency
management tool.

5. Extra information
This section contains extra information, that are not 100% necessary for the purpose of this tutorial, but
are still useful and can be referenced from other parts of the guide.

5.1. Eclipse code navigation and basic shortcuts

Before you start coding or even looking at the SDK samples, you should learn some of the basic IDE
shortcuts. You can do this via Google or Youtube by searching "Eclipse shortcuts", but the most

12
important ones are below. Obviously you can learn these on the go, but it is important to be aware of
them.

• You may wish to start with turning on "Toggle Show Key Bindings" via CTRL-3 Actions menu (at least
on newer eclipses). Then whenever you do any action in the IDE via menus or shortcuts a popup
will show in the lower part of the screen that will show the used shortcut. This way you can learn
the shortcuts for an action you do. Also if you do any kind of tutorials etc. this will help the
shortcuts usage be visible on a video.
• 'F3 (one of the "F-keys" on a typical keyboard right to the "Esc" key) or Ctrl-left click also works for
this that will follow the code path to where-ever the cursor is. Thus you can "F3" a method, which
will jump the editor (opening the target if different file) to the place where it is defined.
• Ctrl-space, which is the autocomplete shortcut. You can write a few characters and the hit 'crtl-
space' to see a popup of variable, method or class names. Java tends to have long names, thus this
will avoid the need to type them in full. You can also trigger the autocompletion by pressing '.' after
a variable etc., which will prompt all the methods you can call for the object.
• "F4" will open a type view when the cursor is in a class, which will show all the subtypes of a given
type, this is not needed as often, but is still useful.
• If you have a mouse with back-forward thumb-buttons (or Alt-left/right arrow keys), you can use
them to jump back to the previous place the cursor was, if you jumped around with "F3".
• CTRL-1 (the number 1) will open suggestions for fixing errors.
• Not a shortcut, but please use the 'Outline' view in the right side of the screen when searching a
method, it is way faster than looking at the .java file.
• CTRL-SHIFT-T, will open a dialog to open a type' source file (if you have sources), CTRL-SHIFT-R does
the same for resource files; this can be useful when you know the type name, but do not have it
written nearby (to "F3 into it").
• CTRL-ALT-H, "Open Call Hierarchy" in the r-click menu, shows all places where a field or method is
accessed (and this is a tree, that will then show where those are called etc.).

5.2. Selecting Java version

Nowadays there exists many so called "JVM vendors" (Java Virtual Machine vendors). Historically most
Java developers did just use Oracle’s Java, but due to some changes in Oracle’s licensing people moved
away from it. Regardless of the current terms, it is probably just easier and safer to go with an OpenJDK
instead. Choosing one of them is outside of the scope of this tutorial, but we have used
https://adoptium.net/ ourselves. If you are running on Linux, you might be able to get OpenJDK directly
from the Linux distribution.

Prosys OPC UA SDK for Java support Java versions from 8 to 21. In practice, we only test against the LTS
versions (see below), and recommend those.

Java is in general a very backwards compatible language, but version 9 introduced

some compatibility-breaking changes. The biggest change was the introduction of

 the "Module path" concept, in addition to the traditional "Class path" concept. SDK
is not tested with the Module path so you should leave the module-info out of your
projects or find another way to deal with it.

New Java versions are nowadays published every 6 months. Some of them are designed for Long Term
Support (LTS) whereas the ohters are intermediate development versions. The SDK is tested only
against the LTS versions, although in general, it should work with the other versions as well. What Java

13
versions are 'LTS' is vendor-specific, but usually it means versions 8, 11, 17 and 21
(https://adoptium.net/support/). The oldest versions are not typically updated any more, except by Azul,
who still provide updates even to Java 6 (https://www.azul.com/downloads/?package=jdk).

5.3. Regarding exporting and making the application run

outside of the IDE
You can Export the application/project as a runnable JAR file from Eclipse. Please check the README.txt
at the base of the SDK distribution zip for more info about the dependencies for different use cases.

IMPORTANT! Do not merge the BouncyCastle library into your application JAR. It is
signed and cannot be repackaged (that would break the jar signatures, some JVMs

 wont load this). So you will need to distribute the BouncyCastle libraries together
with your application jar and have them on the classpath to get properly loaded
together with your application.

5.4. Maven integration

If you already are using Maven or Gradle or anything that can consume Maven artifacts, see folder
'maven-integration' for more info (copied below). It contains the POM file for the SDK and a helper
project to install it to the local Maven cache.

The folder 'maven-install-helper' contains a Maven project which can be used to install the SDK to your
local (.m2) Maven repo/cache.

You will need to run 'mvn install' in the 'maven-install-helper' directory (or via your favorite IDE).

 SDK contains optional dependencies, please refer to the main README.

You might need to edit the POM file inside the 'data' if developing on android or
 wish to remove the optional libs required for OPC.HTTPS transport protocol.

The SDK samples can be imported (they have a POM file and follow Maven Standard Directory Layout)
as 'Maven projects' instead of the steps of Importing the Prosys OPC UA SDK for Java.

14