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

4.1. Maven Installation

  1. Download Maven 3 http://maven.apache.org/download.html

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

    $ ls apache-maven-3.3.3/
bin  boot  conf  lib  LICENSE.txt  NOTICE.txt  README.txt

  3. Add an environment variable for MAVEN_HOME and add MAVEN_HOME/bin to your PATH 

    //my linux system -- should be done in .bashrc
export MAVEN_HOME=/opt/apache-maven-3.3.3
export PATH=$MAVEN_HOME/bin:$PATH

//my windows system -- should be done in Advanced System Settings->Environment Variables
set MAVEN_HOME=/apps/apache-maven-3.3.3
set PATH=%MAVEN_HOME%\bin;%PATH%

  4. Verify maven is installed and in the path

    //my fedora system
$ mvn --version
Apache Maven 3.3.3 (7994120775791599e205a5524ec3e0dfe41d4a06; 2015-04-22T07:57:37-04:00)
Maven home: /opt/apache-maven-3.3.3
Java version: 1.8.0_40, vendor: Oracle Corporation
Java home: /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.40-21.b25.fc21.x86_64/jre
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "3.19.2-201.fc21.x86_64", arch: "amd64", family: "unix"

//my windows xp system
> mvn --version

4.2. Maven Configuration

  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. Add the following to the.m2/settings.xml file in your HOME directory. 

      

      
<?xml version="1.0"?>
      
<settings 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/settings-1.0.0.xsd">
      

      
    <offline>false</offline>
      
    
      
    <profiles>
      
    </profiles>
      
    
      
    <activeProfiles>
      
    </activeProfiles>
      
</settings>    

    2. 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

    3. 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. 

      

      
    <activeProfiles>
      
        <activeProfile>h2db</activeProfile>
      
    </activeProfiles>

    4. 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. 

      

      
    <offline>false</offline>
      
    <!-- this overrides the default $HOME/.m2/repository location. --> 
      
    <localRepository>c:/jhu/repository</localRepository>

4.3. Test Maven Build

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.

  1. Change your current directory to the root of the cloned repository and make sure you have a current copy. 

    $ ls
README.md  async  build  common  coursedocs  ejb  javase  jpa  pom.xml  projects  src
$ git checkout master
$ git pull origin master
From github-ejavaguy:jhu-ep-coursera/fullstack-course1-module3
 * branch            master     -> FETCH_HEAD
Already up-to-date.

  2. Test your configuration using 

    $ mvn clean install
[INFO] Scanning for projects...
...

OutOfMemoryError

If you receive an "OutOfMemoryError: PermGen space" error, you can update the amount of memory allocated to the build by setting MAVEN_OPTS.

You can set this in the current shell using one of the following commands 

bash> export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=256m"

windows> set MAVEN_OPTS=-Xmx512m -XX:MaxPermSize=256m

You can optionally set these properties in one of the shell-specific environment scripts. 

bash> $HOME/.mavenrc

windows> %HOME%\mavenrc_pre.bat

You can also set them using shell-specific techniques.

4.4. Missing Dependencies

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.

Figure 4.1. Missing Maven Dependency Error/Warning Message

Failure to find com.oracle:ojdbc6:pom:11.2.0.3 in ... 
was cached in the local repository, resolution will not be reattempted until the update interval of 
... has elapsed or updates are forced.

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.

Note

This is only an example. You are not required to download if the Oracle database driver for class if you do not wish. 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=11.2.0.3 -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/11.2.0.3/ojdbc6-11.2.0.3.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
...

Artifacts are Best Placed in Network Repositories

This artifact would ideally be placed within a network cache/repository (i.e., Nexus) and not into individual localRepositories. In the next chapter you will be shown how could could setup a Maven Nexus for team use. If you go that route -- it would be better to upload the file to that archive.

Rogue Internet Repositories

Probably violating license restrictions, but the following network repository does contain the missing Oracle driver. One could add that as an upstream repository in their Nexus or define it as an artifact repository in the pom to avoid having to manually import the artifact.

4.5. Build Local Site

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 -Pcobertura
$ 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 followng from the coursedocs directory. 

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