Enterprise Java Development@TOPIC@

Chapter 4. Maven Environment Setup

4.1. Maven Installation
4.2. Maven Configuration
4.3. Test Maven Build
4.4. Missing Dependencies
4.5. Build Local Site

  1. Download Maven 3 http://maven.apache.org/download.html or download thru a package manager

  2. Unzip the contents into a directory with no spaces in its path.

    $ ls apache-maven-3.6.1
    bin  boot  conf  lib  LICENSE  NOTICE  README.txt
  3. Add an environment variable for MAVEN_HOME and add MAVEN_HOME/bin to your PATH

    # my bash systems -- should be done in .bashrc or .bash_profile
    export MAVEN_HOME=/opt/apache-maven-3.6.1
    export PATH=$MAVEN_HOME/bin:$PATH
    # my Windows system -- should be done in Advanced System Settings->Environment Variables
    set MAVEN_HOME=c:/apps/apache-maven-3.6.1
    set PATH=%MAVEN_HOME%\bin;%PATH%
  4. Verify maven is installed and in the path

    //my Ubuntu system
    $ mvn -version
    Apache Maven 3.6.1 (d66c9c0b3152b2e69ee9bac180bb8fcc8e6af555; 2019-04-04T15:00:29-04:00)
    Maven home: /opt/apache-maven-3.6.1
    Java version: 11.0.4, vendor: Ubuntu, runtime: /usr/lib/jvm/java-11-openjdk-amd64
    Default locale: en_US, platform encoding: UTF-8
    OS name: "linux", version: "5.0.0-23-generic", arch: "amd64", family: "unix"
    //my Mac system - installed via brew
    $ mvn -version
    Apache Maven 3.6.1 (d66c9c0b3152b2e69ee9bac180bb8fcc8e6af555; 2019-04-04T15:00:29-04:00)
    Maven home: /usr/local/Cellar/maven/3.6.1/libexec
    Java version: 1.8.0_202, vendor: AdoptOpenJdk, runtime: /Library/Java/JavaVirtualMachines/adoptopenjdk-8.jdk/Contents/Home/jre
    Default locale: en_US, platform encoding: UTF-8
    OS name: "mac os x", version: "10.14.5", arch: "x86_64", family: "mac"
    //my Windows system
    >mvn -version
    Apache Maven 3.6.1 (d66c9c0b3152b2e69ee9bac180bb8fcc8e6af555; 2019-04-04T15:00:29-04:00)
    Maven home: C:\apps\apache-maven-3.6.1\bin\..
    Java version: 11.0.4, vendor: Azul Systems, Inc., runtime: C:\apps\zulu-openjdk11
    Default locale: en_US, platform encoding: Cp1252
    OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"
  1. Add a skeletal settings.xml file that will be used to provide local overrides for the build. This is the place where you can customize the build for local environment specifics like directory locations, server address, server ports, etc.

    1. Create a .m2 directory below your HOME directory.

    2. Add the following to the.m2/settings.xml file below your HOME directory.

      <?xml version="1.0"?>
      <settings xmlns="http://maven.apache.org/POM/4.0.0"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">


    3. You can test whether your settings.xml file is seen by Maven by temporarily making it an invalid XML file and verifying that the next Maven build command fails with a parsing error.

      $ mvn clean
      [ERROR] Error executing Maven.
      [ERROR] 1 problem was encountered while building the effective settings
      [FATAL] Non-parseable settings /home/user/.m2/settings.xml: only whitespace content allowed before start tag and not s (position: START_DOCUMENT seen <?xml version="1.0"?>\ns... @2:2)  @ /home/user/.m2/settings.xml, line 2, column 2
    4. Add a default specification for the database profile we will be using for class at the bottom of the .m2/settings.xml file in your HOME directory.

    5. If your operating system HOME directory has spaces in the path (e.g., Windows XP's Documents and Settings) then add a localRepository path specification to the .m2/settings.xml file and have it point to a location that does not have spaces in the path. The path does not have to exist. It will be created during the next build.

          <!-- this overrides the default $HOME/.m2/repository location. --> 

Each week you will be asked to update your cloned copy of the class examples and perform a test build. This will give both of us some comfort that your environment is setup correctly and act as a baseline for debugging your class assignments. Therefore, do the following to test your initial installation and repeat each week.

PKCS12 trustStores

If you are getting the following error...

[ERROR]     Unexpected error: java.security.InvalidAlgorithmParameterException: the trustAnchors parameter must be non-empty -> [Help 2]

and a -list of the default cacerts file without a password produces a type of PKCS12 and 0 entries ...

$ keytool -list -cacerts
Enter keystore password:
Keystore type: PKCS12
Keystore provider: SUN
Your keystore contains 0 entries

and executing the same command with a changeit password produces entries...

$ keytool -list -cacerts
Enter keystore password: changeit
Keystore type: PKCS12
Keystore provider: SUN
Your keystore contains 134 entries

then you have a post JDK9 generated truststore and will need to supply the password each time you execute a Java command. The former default format of truststores was changed from JKS to PKCS12 in JDK9. JKS allows access to public keys without a password. PKCS12 requires a password.

$ mvn clean install -Djavax.net.ssl.trustStorePassword=changeit

One workaround would be to add the trustStore password to the .mavenrc mentioned earlier.

bash> export MAVEN_OPTS="-Djavax.net.ssl.trustStorePassword=changeit"
windows> set MAVEN_OPTS=-Djavax.net.ssl.trustStorePassword=changeit

Another workaround option is to regenerate the truststore as a JKS that does not require a password to obtain public certs. Edit the security/java.security property file

sudo vi /etc/java-11-openjdk/security/java.security

Change the keystore.type from pkcs12 to jks.

274 # Default keystore type.
 275 #
 276 #keystore.type=pkcs12
 277 keystore.type=jks

Remove the existing cacerts file and re-generate it.

$ sudo rm /etc/ssl/certs/java/cacerts 
$ sudo update-ca-certificates -f

The newly generated cacerts file will be of type JKS and enable access to public certs without a password.

$ keytool -list -cacerts
Enter keystore password:
Keystore type: JKS
Keystore provider: SUN
Your keystore contains 133 entries

There are a few cases where dependencies cannot be hosted in public repositories and must be downloaded and installed manually. Oracle DB Client is one example.

If the message is a warning (i.e., for site/javadoc documentation -- it can be ignored). If you want to eliminate the warning or it is coming up as an error, you can download the artifact directly from the vendor and manually install it in your local repository.

This is only an example!!!

This is only an example. You are *not* required to download if the Oracle database driver for class. You can create a dummy file ($ touch dummy.jar) and register it using a dummy groupId, artifactId, and version if you wish.

  1. Download the driver jar from Oracle accept the license agreement.

  2. Install it manually into your localRepository

    $ mvn install:install-file -Dfile=/home/jcstaff/Downloads/ojdbc6.jar -DgroupId=com.oracle -DartifactId=ojdbc6 -Dversion= -Dpackaging=jar
    [INFO] Scanning for projects...
    [INFO] --- maven-install-plugin:2.4:install-file (default-cli) @ standalone-pom ---
    [INFO] Installing /home/jcstaff/Downloads/ojdbc6.jar to /home/jcstaff/.m2/repository/com/oracle/ojdbc6/
    [INFO] ------------------------------------------------------------------------

The class web site will be pre-built with up-to-date information. However, you may wish to have a local version and can do so by performing the following.

$ mvn clean verify site -DskipTests
$ mvn site:stage       # the output will be in target/staging

If you have more time and wish to generate more detailed reports, execute the following.

$ mvn clean verify site -Preports
$ mvn site:stage        # the output will be in target/staging

If you have less time and are looking only to get up-to-date documents, execute the following from the coursedocs directory.

$ cd coursedocs
$ mvn site:stage        # the output will be in target/site