1. Getting Started

To work successfully with the programs needed for PRC2, you need to install them first. Properly installing Java and other programs is not hard but must be done precisely. What will follow is a description on how to do that under Ubuntu Linux, which is my preferred way of working and will give you the best user experience. You can adapt this configuration for other operating systems too, possibly with a few tweaks.

It is best to get fairly familiar with the command line pretty soon, because in the end it will make you much more effective. Since 2018, bash is also available on Windows 10, and it is the default shell on both OS-X and Ubuntu-Linux.

Before you install any software from the internet, please validate the the package. You typically see signature files such as SHA-256 or PGP-ASC, os something similar, which can help to ascertain that the package is the one you think it is.
For instance with sha512sum ~/Downloads/netbeans-11.2-bin.zip you can check the download of that version of netbeans, and the command should produce the same signature as is available on the download website.

2. Install Java and adapt PATH.

The default installation directory for Java on debian based Linuxes, such as Ubuntu is /usr/lib/jvm. On other systems it may vary, under windows do NOT use Program Files, because of the space in the name, but instead create a separate directory simply called e.g. c:\usr\lib\jvm if you insist on using MS-Windows. TODO OS-X?

Fetch the Java distribution from AdoptOpenJDK and choose the distribution/version of choice. For PRC2 we will use Java 11 as a minimum, but you may want to pick up Java 8 for older projects and maybe Java 13 (or even Java 14 when it becomes available) too. Choose the proper platform, download it to your Download folder and unpack the distribution in the installation directory, /usr/lib/jvm under Ubuntu, adapt for your OS.

In the example below we assume that the distribution is packed as a tar.gz archive. The example shows the archive name as of 3 December 2019, OpenJDK11U-jdk_x64_linux_hotspot_11.0.5_10.tar.gz

unpack java distribution using the commandline
sudo mkdir -p /usr/lib/jvm
cd /usr/lib/jvm
sudo tar xf ~/Downloads/OpenJDK11U-jdk_x64_linux_hotspot_11.0.5_10.tar.gz

2.1. Make Java available on the PATH

The $PATH environment variable is used by the command line processor to find the commands or programs whose name you type as first word in a command line. If you type java -version, and your bash says command not found, then your path does not include the java program yet.

Since we want the best Java experience, we will use some common environment variables.

  • JAVA_HOME Define JAVA_HOME first. That will help Java, but also tell other programs to find the desired Java version.
    Set it with export JAVA_HOME=/usr/lib/jvm/jdk-11.0.5+10.

  • PATH Prepend the directory under JAVA_HOME to your path, so all java related programs, such as java , javac, jar etc can be found, by just typing the name.
    Append it by doing export PATH=${JAVA_HOME}/bin:$PATH.

To avoid having to do this every time you start the command-line, add the command to your ~.bashrc script file, at the bottom.

add these lines to your startup script
export JAVA_HOME=/usr/lib/jvm/jdk-11.0.5+10
export PATH=${JAVA_HOME}/bin:$PATH

for OS-X users, adding lines along this design may help you to switch.

alias j8="export JAVA_HOME=`/usr/libexec/java_home -v 1.8`; java -version"
alias j11="export JAVA_HOME=`/usr/libexec/java_home -v 11`; java -version"
alias j13="export JAVA_HOME=`/usr/libexec/java_home -v 13`; java -version"

2.2. Install Apache Maven

We will use Apache Maven, or maven for short throughout the PRC2 course, so you will need that too.

The application is called Maven but as command spelled as mvn.

Maven is the default build tool in the Java world and can build your program from sources without the use of and IDE. This makes your project agnostic to the IDE used, so they work with NetBeans as first class projects out of the box and also with other IDEs with little or no tweaks to that IDE. It is also the way the teachers use to compile and test the students work for the practical assignments and performance assessments.

Fetch a fresh copy of Apache Maven from the website.

To install it, do (example uses version 3.6.3 as of 2019-11-03)

install apache maven and add to path
cd /usr/share
sudo rm -fr maven
sudo tar xf ~/Downloads/apache-maven-3.6.3-bin.tar.gz
sudo ln -sf apache-maven-3.6.3/ maven
cd /usr/bin
sudo ln -sf ../share/maven/bin/mvn .

Once this is done, entering mvn --version should produce output similar to

mvn --version command.
hom@threehundred: /usr/share
🐧$ mvn --version
Apache Maven 3.6.3 (cecedd343002696d0abb50b32b541b8a6ba2883f)
Maven home: /usr/share/maven
Java version: 11.0.5, vendor: AdoptOpenJDK, runtime: /usr/lib/jvm/jdk-11.0.5+10
Default locale: en_GB, platform encoding: UTF-8
OS name: "linux", version: "5.0.0-36-generic", arch: "amd64", family: "unix"

TODO: Adapt for windows.

2.3. Install or update your IDE

The official Java IDE at Fontys ICT Venlo is Apache NetBeans IDE. The long time stable version for the moment is 11.0. At the time of writing version 11.2 serves me very well. At the time of reading a newer version might be available.

To install Apache NetBeans on Ubuntu simply fetch the binary as zip file and unpack it, then either add the contained bin directory to the path, or make a wrapper netbeans command in your personal ~/bin directory.

For my installation I simply used the binaries, in the zip file, and install it in the traditional (as in same directories as the installer would) /usr/local.

Assuming you downloaded the binary, installing it is easy
cd /usr/local
sudo unzip ~/Downloads/netbeans-11.2-bin.zip
sudo mv netbeans{,-11.2}

For extra creature comfort, add a simple netbeans script to your path

netbeans script in ~/bin
/usr/local/netbeans-11.2/bin/netbeans "$@" & (1)
1 Invoke netbeans using its absolute path.

Then make that script executable with chmod +x netbeans.

NetBeans IDE should now be startable from the command line (fine for me) as well as from the menu.

For OS-X users: because your OS has the annoying habit to add spaces in the application path, its default shell (bash) typically stumbles on any addition to the $PATH variable. To circumvent this issue, it appears to be useful to add a symlink to the installed netbeans exe and use that symlink in the script

mkdir -p ~/bin
cd ~/bin
ln -sf <PATH-TO-NETBEANS> nbexe

and then in the script above use that link instead of the absolute path above.

${HOME}/bin/nbexe "$@" (1)
1 Use symlink instead of absolute path of netbeans installation to circumvent the spaces problem.

2.3.1. Other IDE’s

This section is left empty. We will not answer any support questions on other IDE’s but the one we use in the performance assessment.

3. Configuring Maven

Maven and maven projects are first class citizens in the NetBeans world.

Since we build with maven, we are not really bound to particular IDE, other than for editing and maybe the odd debug session.[1]. This means that you can use other IDE’s, but expect no help from the teachers.

We have many things to share with you, and we use maven for that.

We share libraries and project configuration files (pom.xml) with our students. To make them work as intended, you will need to configure the maven settings.xml only once. Since this is a maven setting, your IDE should pick these settings up as well. Certainly NetBeans IDE will.

Start NetBeans IDE and create a Java project with New Project ▷ Java with Maven ▷ Java Application.

In the project, right click on Project Files and choose create settings.xml. Add the Fontys Venlo repository to the settings, which is best done by replacing the xml in the settings file with

settings.xml which adds https://www.fontysvenlo.org/repository as repository
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
        <profile>  (1)
                    <id>fontysvenlo.org</id> (2)
                    <url>https://www.fontysvenlo.org/repository</url> (3)
        <activeProfile>sebivenlo</activeProfile> (4)
1 You define a profile inside the profiles section of your settings.xml.
2 Give the profile a name.
3 Specify the URL.
4 Use the given name to make it an active profile by default.

Note that the project provided through the PRC2 personal repository will NOT work without the settings file above. From February 2020 will use sebipom version 2.3.0 or above.

4. Sebipom 2.3.8

Spelled all lower case: sebipom, is a super pom to use in Fontys Venlo projects. It keeps your own pom.xml file simple and focused to declare just the dependencies needed. Niceties to do proper Test Driver Development are provided for in the sebipom definitions, including things as being able to create javadoc in a professional looking way, including code highlighted code snippets, checkstyle, reporting, code coverage with maven, pmd, spotbugs etc.

  • sebipom does declares no dependencies other than those for dynamic (e.g. JUnit, AssertJ etc) and static testing in the form of plugins and their configuration.

This way of using maven, having a super or parent pom defined globally (in a repository, not on a local path), is the modern usage. It can be seen in well known big java projects such as Spring Boot and quarkus, to name two contenders in the java-web technology world.

Note that I am using a separately installed maven (3.6.3 at the time of writing) which you can download from apache maven, not the one bundled with NetBeans or any other IDE. You can tell NetBeans (via tools→ options →java→maven) to use the installed one instead of the bundled one.

Doing this gives you the access to sebipom, which defines a parent pom for projects. This again provides some goodies that you would otherwise have to provide yourselves.
Such a parent pom is similar to a super class in Java; your pom inherits all the traits of the parent.
Including that parent is simple. See below for the sebipom (version 2.1.0 at the time of writing).

Setting sebipom as parent.
      <relativePath/> (1)
1 The parent pom does not live in a local directory near (relative to) the project, but instead in a repository. This makes a parent pom 'portable'.

All of the starter projects we provide already use this parent in some version. To get those working, apply the settings show in the paragraph Configuring Maven.

If you want to use sebipom in your own project, either copy the parent definition into the pom file or start by replacing the NetBeans provided pom.xml file in your project by the basic one below. Add dependencies as required.

Basic pom.xml file setting sebipom as parent.
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <!-- The name in the IDE -->
    <name>My App</name>
        <!-- change mainClass to the proper starting point of your program, if any.-->
      <!--example  -->


4.1. Sebipom and Java FX

If you want to use semipom and build a JavaFX project, you need to activate the fx-profile. In the commandline that would be

mvn withfx profile
Figure 1. Commandline. Real software engineers can use the command line.

In netbeans you can do that by setting the configuration like in this picture:

fx profile nb
Figure 2. Activate a profile in netbeans

4.2. Using the SeBiPom in your own projects

To use the test libraries and other goodies that will be used throughout our course, you should add the sebipom and kind of super-pom (yes, thinking super class is not far off).

Modify the pom.xml file in your project to include sebipom as parent by adding these lines to the pom file:

        <version>2.3.8</version> (1)
1 Modify version when required. 2.x.x is for Java 11 and above, 1.x.x is for Java 8.

2.3.8 provides modular testing, required from week 12.
2.3.7 provides mockito support for JUnit 5, required from week 6.

  • Version 2.3.7 brings a proper fail message back instead of just a silent assertion failed exception.

  • Version 2.3.7 has preview feature. If you would like to play with new java features such as java 14 instanceof to variable, enable the preview profile in netbeans. If you want to use more profiles, add them as a comma separated list as parameter to the -P (profile) flag, as in
    mvn -P fx,preview package. Then run it with java --enable-preview …​.

As of 2020-04-22, sebipom reached version 2.3.8. Not all projects may have this version number for the parent sebipom. We improve as we go, sometimes because of tips we receive from our students, you for instance. Anyway, if the version is not at the newest, set it to the newest and rebuild. Revisit this part of the site to check the latest version number or look in the fontysvenlo maven reposity for the sebipom version.

Sebipom enables testing for modular projects but does not enforce modular projects.

4.3. Upgrade all projects with one command

Since sebipom is a somewhat moving target, you may have to update the parent pom of the projects that depend on it. All PRC2 projects do. This oneliner will do that for all projects below the current directory. After navigating to the parent of all such projects, do this in the shell:

for i in $(find . -name pom.xml); do (cd $(dirname $i); mvn versions:update-parent  & )   ; done

It works on any bash supporting machine, tested on ubuntu and should work on OS-X and under windows when using git-bash or the windows subsystem for Linux.

5. Additional Pointers

1. Working test driven will typically not need those