Updating to Maven 3.6.0

On Ubuntu 16.04

Default state:

• installation directory is: /usr/share/maven
• version is 3.3.9

Update to new version (following the official, and this and this linux specific tutorials):

1. download newest version of maven (bin tar.gz) from https://maven.apache.org/download.cgi
2. unpack to /opt folder (the folder for installing unbundled independent applications)
   

   sudo tar xvf apache-maven-*.tar.gz --directory /opt

3. add environmental variables (see also: official reference):
1. create script file to set the variables system wide:
   

   sudo gedit /etc/profile.d/maven.sh

2. add these lines and save it (change jdk path if needed):
   

   ## Environmental variables needed by Maven
   export JAVA_HOME=/usr/lib/jvm/jdk-11.0.2/

3. set the file executable
   

   sudo chmod +x /etc/profile.d/maven.sh

4. log out and log in again to see its effect
4. update alternatives for the specific new version (change path if needed)
   

   sudo update-alternatives --install "/usr/bin/mvn" "mvn" "/opt/apache-maven-3.6.0/bin/mvn" 100
   sudo update-alternatives --set mvn /opt/apache-maven-3.6.0/bin/mvn

Note: With the above approach, the M2_HOME and MAVEN_HOME environmental variables are not needed, and the bin folder doesn't have to be added to the PATH manually.

On Windows 10

1. download newest version of maven (bin zip) from https://maven.apache.org/download.cgi
2. unpack zip to "C:\Program Files\Apache\"
3. add "C:\Program Files\Apache\apache-maven-3.6.0\bin\" to Path environmental variable, or replace older maven version in Path variable with new one
4. log out and log in for the environmental variable to take effect

Note: the M2_HOME and MAVEN_HOME environmental variables are not needed.

Maven dependencies basics

Source: https://maven.apache.org/pom.html

Always required in a POM:

• groupId
• artifactId
• version

Dependency hierarchy:

• All POMs inherit from Maven's Super POM.
  This is why some properties you specify but not use have effect. For example you can set the compiler version with these properties:
  

  <maven.compiler.source>1.7</maven.compiler.source>
  <maven.compiler.target>1.7</maven.compiler.target>

• To set up a POM hierarchy within your project, all POMs that are specified as <parent> in other POMs or that have <modules> (aggregation aka. multi-module projects) must use <packaging>pom</packaging>.
  
• Note:  A POM project may be inherited from - but does not necessarily have any modules that it aggregates. Conversely, a POM project may aggregate projects that do not inherit from it.
  

Dependency scope:

• compile - this is the default scope, used if none is specified. Compile dependencies are available in all classpaths. Furthermore, those dependencies are propagated to dependent projects.
• provided - this is much like compile, but indicates you expect the JDK or a container to provide it at runtime. It is only available on the compilation and test classpath, and is not transitive.
• runtime - this scope indicates that the dependency is not required for compilation, but is for execution. It is in the runtime and test classpaths, but not the compile classpath.
• test - this scope indicates that the dependency is not required for normal use of the application, and is only available for the test compilation and execution phases. It is not transitive.
• system - this scope is similar to provided except that you have to provide the JAR which contains it explicitly. The artifact is always available and is not looked up in a repository.

Exclusion of transitive dependencies:

• One by one: specify them one by one
• All: use the * wildcard for both the groupId and artifactId

Show README and CHANGELOG on Maven Site

It is common that the project's README contains valuable information about the project. For example on a repository's webpage in Gitlab or Github, the README is displayed by default.
Here's a way to publish the README and CHANGELOG markdown files on the project's Maven Site:

In the Site descriptor (/src/site/site.xml) reference the files you want to publish:

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <body>
    <menu name="Documentation">
      <item name="README" href="docs/README.html"/>
      <item name="CHANGELOG" href="docs/CHANGELOG.html" />
    </menu>
  </body>
</project>

In the pre-site build phase copy the files to the markdown resource directory. The site plugin transforms the documentation to HTML and outputs it to the corresponding target directory.
After the site building finished, clean up the duplicate files:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-resources-plugin</artifactId>
        <configuration>
          <encoding>${project.build.sourceEncoding}</encoding>
        </configuration>
        <executions>
          <execution>
            <!-- Copy the readme and such files to the site source files so that a page is generated from it. -->
            <id>copy-docs</id>
            <phase>pre-site</phase>
            <goals>
              <goal>copy-resources</goal>
            </goals>
            <configuration>
              <outputDirectory>${basedir}/src/site/markdown/docs</outputDirectory>
              <resources>
                <resource>
                  <directory>${basedir}</directory>
                  <includes>
                    <include>README.md</include>
                    <include>CHANGELOG.md</include>
                  </includes>
                </resource>
              </resources>
            </configuration>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <artifactId>maven-clean-plugin</artifactId>
        <!-- Delete the markdown/docs directory to remove the readme and such duplicate files from the site source files. -->
        <executions>
          <execution>
            <id>clear-docs</id>
            <phase>site</phase>
            <goals>
              <goal>clean</goal>
            </goals>
            <configuration>
              <filesets>
                <fileset>
                  <directory>src/site/markdown/docs</directory>
                  <followSymlinks>false</followSymlinks>
                </fileset>
              </filesets>
              <excludeDefaultDirectories>true</excludeDefaultDirectories>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>

To show the process in terms of file structure:
The normal state:

.
+-- src 
| +-- site
| | +-- site.xml

After the files were copied:

.
+-- src 
| +-- site
| | +-- markdown
| | | +-- docs
| | | | +-- README.md
| | | | +-- CHANGELOG.md
| | +-- site.xml

The output in site target:

.
+-- docs
| +-- README.html
| +-- CHANGELOG.html
+-- index.html

A bonus note regarding the deployment url: it can be changed it the distributionManagement section:

<project>
  ...
  <distributionManagement>
    <site>
      <url>${maven.reports.deployBase}/${project.groupId}</url>
    </site>
  </distributionManagement>
  ...
</project>

Run a Maven Vaadin application on an embedded Jetty server in Eclipse

Source: Embedding Jetty

Add Maven Dependencies

<properties>
 <jetty.version>9.3.0.v20150612</jetty.version>
</properties>

<dependencies>
<dependency>
 <groupId>org.eclipse.jetty</groupId>
 <artifactId>jetty-servlet</artifactId>
 <version>${jetty.version}</version>
</dependency>
<dependency>
 <groupId>org.eclipse.jetty</groupId>
 <artifactId>jetty-continuation</artifactId>
 <version>${jetty.version}</version>
</dependency>
<dependency>
 <groupId>org.eclipse.jetty</groupId>
 <artifactId>jetty-server</artifactId>
 <version>${jetty.version}</version>
</dependency>
</dependencies>

Create a Server

import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.servlet.ServletContextHandler;
import org.eclipse.jetty.util.resource.PathResource;

public class VaadinApplicationServer 
{
    public static void main( String[] args ) throws Exception
    {
        Server server = new Server(8080);
        ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
        context.setContextPath("/");
        context.setBaseResource(new PathResource(new File("src/main/webapp")));
        context.addServlet(MyUIServlet.class, "/*");
        server.setHandler(context);
        server.start();
        server.join();
    }
}

Run as Java application

Now it is possible to run your Vaadin project as a Java application with the Jetty VaadinApplicationServer class.

Getting started with a Maven Vaadin project in Eclipse without the Eclipse Vaadin Plugin

Environment: Eclipse Luna for Java SE on Windows 10 with Apache Tomcat server and Maven

Install Eclipse software

Source: WTP FAQ: How do I install WTP?

• either install Eclipse IDE for Java EE Developers, which has the needed dependencies by default,
• or install the following software for the Eclipse IDE for Java Developers:
• Eclipse Java EE Developer Tools
• JST Server Adapters Extensions

The installation is done by the following procedure:

• in Eclipse, navigate to Help -> Install New Software...
• select Work with: --All Available Sites--
• expand Web, XML, Java EE and OSGi Enterprise Development category menu
• select the following:
• Eclipse Java EE Developer Tools
• (Eclipse Java Web Developer Tools)*
• JST Server Adapters Extensions
• (JST Server Adapters)*
• (JST Server UI)*
• click Next, click Next again, accept Licence agreement, click Finish to install.

As a result, you are able to add a Server runtime.

Try it: follow the tutorial in the Eclipse Help: Adding the Apache Tomcat runtimes

As a result, you now have the Java EE perspective for Eclipse.

As a result, the Run on Server option becomes available for projects.

*(might be needed to fix errors)

Add Maven Archetypes for Vaadin

Source: Set up a Vaadin project with Maven2

• in Eclipse, navigate to Window -> Preferences
• expand Maven menu item, select Archetypes
• click Add Remote Catalog...
• Catalog File: https://repo1.maven.org/maven2/archetype-catalog.xml
• Description: Maven2
• click OK.

As a result, when creating a new Maven project, the Vaadin archetypes became available.

Try it:

• in Eclipse, go to File -> New -> Other... -> Maven -> Maven Project
• leave the Create Simple Project checkbox unselected, click Next
• Filter for Vaadin, select the com.vaadin archetype you would like to create, click Next
• proceed with project creation.

Here is a description of the Archetypes: https://vaadin.com/maven#archetypes

Set up Facets for your project

In order for Eclipse to recognize your Vaadin project as a Web Project that can be deployed to a server, you need to do the following:

• in Eclipse, navigate to your vaadin project's Properties (right click on project name in Project Explorer, select Properties)
• select Project Facets
• click Convert to faceted form...
• leave the Java option selected
• select the option Dynamic Web Module, set version to 3.1
• click Further configuration availiable...
• set Content directory to src/main/webapp (the default maven webcontent directory)
• select Generate web.xml deployment descriptor and click OK.

As a result, you can deploy your project to the server.

Try it: follow the tutorial in Eclipse Help: Deployment: Deploy the Dynamic Web Project to the Server

Set up Project Deployment Assemblies

Add Maven repositories

In order for a the Maven dependencies to be deployed on the Server, you need to do the following:

• in Eclipse, navigate to your vaadin project's Properties (right click on project name in Project Explorer, select Properties)
• select Deployment Assembly
• click Add...
• select Java Build Path Entries, click Next
• select Maven Dependencies, click Finish
• click OK.

As a result, now your Vaadin web application should run on the server.

Ensure the rest is good

• Source --> Deploy Path
• /src/main/java --> WEB-INF/classes
• /src/main/resources --> WEB-INF/classes
• /src/main/webapp --> /

Build Vaadin plugin goals with Maven

In order for a Vaadin application to run, you first need to build the components.

The Plugin Goals can be found in the pom.xml: update-theme, update-widgetset, compile, compile-theme.

• in Eclipse, go to Run-> Run Configurations...
• right click on Maven Build select New
• Name your configuration
• Base directory is the project's directory
• Goals have to be separated by space. Copy-paste in the following:
• com.vaadin:vaadin-maven-plugin:update-theme com.vaadin:vaadin-maven-plugin:update-widgetset com.vaadin:vaadin-maven-plugin:compile com.vaadin:vaadin-maven-plugin:compile-theme
• click Apply.
• click Run to run the build. 

Setting up H2 database connection in Eclipse Luna in a Maven project

Sources:

• Managing databases with Eclipse and the Database Tools - Tutorial
• Eclipse DTP: Configure H2 Datasource using Data Source Explorer
• H2 Frequently Asked Questions
• H2 Tutorial
• Screenshots on adding a database connection

Download the H2 Database Engine

• Open the pom.xml of your project >
• add H2 database engine as a dependency.

For this tutorial version 1.4.191 was used.
Maven repository: http://mvnrepository.com/artifact/com.h2database/h2
To download it, right-click on the Project Name in Eclipse Project Explorer > Maven > Download Sources

Download Eclipse DTP (Data Tools Platform)

• In Eclipse, go to Help > Eclipse Marketplace... > 
• search Data Tools Platform > 
• click Install > 
• select both Extender SDK and Enablement Extender SDK > 
• accept licence agreement > 
• wait patiently until a popup informs you that the installation was successful and Eclipse needs to be restarted.

Open the "Database Development" perspective

This perspective was installed with the DTP.

• In Eclipse, go to Window > Open Perspective > Other... > Database Development 

Add Database Connection

• In the Database Development perspective, in the Data Source Explorere, right-click on Database Connections > New... >
• select Generic JDBC and enter a Name for the connection then click Next >
• select H2 Driver from the list of drivers.
• if the list is empty, click New Driver Definition button >
• on the Name/Type tab, click Generic JDBC Driver and give it a unique Driver Name.
• on the JAR list tab, click Add JAR/Zip... > select H2 JAR file from Maven repository > click Open.
• on the Properties tab, enter a Database Name for the database, and the following:
• Connection URL - jdbc:h2:~/test
• Driver Class - org.h2.Driver
• User ID - sa
• click OK.
• click Test Connection to see that the connection works.
• click Finish.

Now you can connect to the database by right-click on the name > Connect.
Once you connected you can edit the tables by right-click on the table name > Data > Edit

Connect to the Database

To connect to a database, a Java application first needs to load the database driver, and then get a connection. A simple way to do that is using the following code:

import java.sql.*;
public class Test {
    public static void main(String[] a)
            throws Exception {
        Class.forName("org.h2.Driver");
        Connection conn = DriverManager.
            getConnection("jdbc:h2:~/test", "sa", "");
        // add application code here
        conn.close();
    }
}

Create a new Database

By default, H2 creates a new database on the first connection, if the one with the specified name does not exist.
After the  jdbc:h2: prefix a path to the database can be given. The ~/test creates a new test database in the user's home directory.