Enterprise Java Development@TOPIC@

Development Environment Overview

Revision: v2013-09-09

Built on: 2014-03-07 00:44 EST

Copyright © 2014 jim stafford (jcstaff@apl.jhu.edu)

Abstract

This presentation provides an introduction to development tools and techniques for building enterprise Java applications.

Purpose
1. Goals
2. Objectives
1. Maven Basics
1.1. Directory Structure
1.1.1. Source Tree
1.1.2. Build Tree
1.2. Maven POM
1.2.1. Packaging
1.2.2. Project Identity
1.2.3. Maven Repositories
1.2.4. Properties
1.2.5. Dependencies
1.2.6. Build Definition
1.3. Maven Commands
2. Maven Profiles
2.1. Profile Definition
2.2. Activation
2.2.1. Explicit Activation/Deactivation
2.2.2. Activation/Deactivation By Rule
3. Maven Modules
3.1. POM Inheritance
3.2. Submodules
4. Dependency/Plugin Management
4.1. Dependency Management
4.2. Plugin Management
5. Maven Eclipse Integration
5.1. Project Import
5.2. Project Update
5.3. Project Refresh
6. Eclipse
6.1. Project Organization
6.2. Project Testing
6.2.1. Maven test from Eclipse
6.2.2. Raw JUnit within Eclipse
6.3. Program Debugging
6.3.1. Debugging within Eclipse
6.3.2. Debugging Maven test from Eclipse

Purpose

At the completion of this topic, the student shall

Chapter 1. Maven Basics

1.1. Directory Structure
1.1.1. Source Tree
1.1.2. Build Tree
1.2. Maven POM
1.2.1. Packaging
1.2.2. Project Identity
1.2.3. Maven Repositories
1.2.4. Properties
1.2.5. Dependencies
1.2.6. Build Definition
1.3. Maven Commands
|-- pom.xml
|-- src
|   |-- main
|   `-- test
`-- target
    |-- classes
    |-- ex1-1.0-SNAPSHOT.jar
    |-- surefire-reports
    `-- test-classes
src

Source tree for all developed code

target

Build tree for artifacts created by the build

pom.xml

Defines the build

src
|-- main
|   |-- java
|   |   `-- myorg
|   |       `-- mypackage
|   |           `-- ex1
|   |               `-- App.java
|   `-- resources
`-- test
    |-- java
    |   `-- myorg
    |       `-- mypackage
    |           `-- ex1
    |               `-- AppTest.java
    `-- resources
        `-- log4j.xml
main

Contains production artifacts for module

test

Contains test artifacts for module

[main or test]/java

Contains Java classes

[main or test]/resources

Contains property or other data files

Note

Resource filtering is when substitution ${placeholder}s in source files are replaced by their declared property values in the target tree. This is quite useful in customizing URLs, credentials, and other properties that might be unique to the current build environment. Properties can be defined in the pom.xml, settings.xml or injected into the build through various plugins (e.g., inject current date). 

target
|-- classes
|   `-- myorg
|       `-- mypackage
|           `-- ex1
|               `-- App.class
|-- ex1-1.0-SNAPSHOT.jar
|-- log4j-out.txt
|-- surefire-reports
|   |-- myorg.mypackage.ex1.AppTest.txt
|   `-- TEST-myorg.mypackage.ex1.AppTest.xml
`-- test-classes
    |-- log4j.xml
    `-- myorg
        `-- mypackage
            `-- ex1
                `-- AppTest.class
classes

An exploded directory tree for built artifacts to be placed into the module archive

test-classes

An exploded directory tree for built artifacts used for test

*-reports

Results of unit and integration testing

{artifactId}-{version}.jar

Results of unit and integration testing

log4j-out.txt

An example output file of the build/tests written to the target directory


<?xml version="1.0"?>

<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/maven-v4_0_0.xsd">

    <modelVersion>4.0.0</modelVersion>



    <groupId>myorg.myproject</groupId>

    <artifactId>ex1</artifactId>

    <version>1.0-SNAPSHOT</version>

    <packaging>jar</packaging>



    <name>My First Simple Project</name>

        ...

    <properties>

        ...

    </properties>



    <dependencies>

        ...

    <dependencies>



    <build>

        <plugins>

            ...

        </plugins>

    </build>

</project>

Defines the type of module and automatically enacts a profile of plugs (default=jar)

Value assigned relates to dependency type element

<dependency>
    <groupId>ejava.coursedocs</groupId>
    <artifactId>ejbsessionBankEAR</artifactId>
    <version>3.0.2013.2-SNAPSHOT</version>
    <type>ear</type>
    <scope>compile</scope>
</dependency>

Used to uniquely identify the module


<groupId>myorg.myproject</groupId>

<artifactId>ex1</artifactId>

<version>1.0-SNAPSHOT</version>
groupId

Hierarchical name used to group a set of one or more artifacts

artifactId

Base name for the artifacts produced by this module

1.0-SNAPSHOT/
|-- ex1-1.0-SNAPSHOT.jar
|-- ex1-1.0-SNAPSHOT.pom
|-- ex1-1.0-SNAPSHOT-tests.jar
version

Version ID for the artifact

Figure 1.1. Maven Repositories [1]

Maven Repositories fusesource.com

  1. Maven will first look for a dependency artifact in the local repository

  2. Maven will then look for a dependency artifact in a remote repository like ibiblio

  3. Maven will search all known repositories until the artifact is found or all repositories have been checked

  4. Maven will install module artifacts into the local repository during the install phase of the build

    $ mvn install
    ...
[INFO] --- maven-install-plugin:2.3.1:install (default-install) @ ex1 ---
[INFO] Installing /home/jcstaff/proj/ejava-javaee/solutions/ex1/target/ex1-1.0-SNAPSHOT.jar to 
    /home/jcstaff/.m2/repository/myorg/myproject/ex1/1.0-SNAPSHOT/ex1-1.0-SNAPSHOT.jar
[INFO] Installing /home/jcstaff/proj/ejava-javaee/solutions/ex1/pom.xml to 
    /home/jcstaff/.m2/repository/myorg/myproject/ex1/1.0-SNAPSHOT/ex1-1.0-SNAPSHOT.pom
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

Use -U to force an update check

Maven will limit its search of a remote repository to expressed time limits. If it attempts and fails to locate an artifact from a remote repository it will not re-attempt to query that repository until the time limit expires. Sometimes the failure has nothing to do with the repository not having the artifact (e.g., wireless network down) and when you clear the error you can force Maven to retry before the timeout period expires by adding a -U to the command line.

Use the -o offline flag to eliminate repository checks

Many times Maven will be too aggressive searching for artifacts you already know are not of value to the current build. You can tell Maven to work in an offline mode to bypass the work involved. This is helpful when you are disconnected from the network but will fail if you are truly missing a required artifact. You can activate/deactivate the offline more consistently using an element in the settings.xml 


<offline>false</offline>



<properties>

    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

    <maven-compiler-plugin.version>2.5.1</maven-compiler-plugin.version>

    <java.source.version>1.6</java.source.version>

    <java.target.version>1.7</java.target.version>

</properties>



<dependencies>

    <dependency>

        <groupId>commons-logging</groupId>

        <artifactId>commons-logging</artifactId>

        <version>1.1.1</version>

        <type>jar</type>

        <scope>compile</scope>

    </dependency>

    <dependency>

        <groupId>junit</groupId>

        <artifactId>junit</artifactId>

        <version>4.10</version>

        <scope>test</scope>

    </dependency>

....

</dependencies>
GAV

Must provide its groupId, artifactId, and version for each dependency

scope

Defines when the dependency applies (default=compile)

type

Defines the artifact type of ther module (default=jar)

Value directly relates to the project packaging element of the dependency

|-- ejbsessionBankImpl
|       |-- ejbsessionBankImpl-3.0.2013.2-SNAPSHOT.jar
|-- ejbsessionBankEJB
|       |-- ejbsessionBankEJB-3.0.2013.2-SNAPSHOT.jar
|-- ejbsessionBankWAR
|       |-- ejbsessionBankWAR-3.0.2013.2-SNAPSHOT.war
|-- ejbsessionBankEAR
|       |-- ejbsessionBankEAR-3.0.2013.2-SNAPSHOT.ear
classifier

Defines a special type of artifact/custom from a module

`-- target
...
    |-- txHotelDAO-3.0.2013.2-SNAPSHOT.jar
    |-- txHotelDAO-3.0.2013.2-SNAPSHOT-sources.jar
    `-- txHotelDAO-3.0.2013.2-SNAPSHOT-tests.jar
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>2.5.1</version>
            <configuration>
                <source>1.6</source>
                <target>1.7</target>
            </configuration>
        </plugin>
         <!-- surefire.argLine is set in debugger profile -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>2.12.2</version>
            <configuration>
                <argLine>${surefire.argLine}</argLine>
            </configuration>
        </plugin>
        ...

  • New plugins can be added, but will need to be wired into a specific lifecycle phase of the build. 

    
<plugin>
    
    <groupId>org.apache.maven.plugins</groupId>
    
    <artifactId>maven-failsafe-plugin</artifactId>
    
    <version>2.16</version>
    
    <configuration>
    
        <argLine>${surefire.argLine}</argLine>
    
    </configuration>
    
    <executions>
    
        <execution> <!-- run the tests here -->
    
           <id>integration-tests</id>
    
               <phase>integration-test</phase>
    
           <goals>
    
               <goal>integration-test</goal>
    
           </goals>
    
        </execution>
    
        <execution> <!--  delay failures to after undeploy -->
    
            <id>verify</id>
    
            <phase>verify</phase>
    
            <goals>
    
                <goal>verify</goal>
    
            </goals>
    
        </execution>
    
    </executions>
    
</plugin>

    The above example shows the failsafe plugin being configured to share some properties with surefire and have specific goals wired into the integration-test and verify lifecycle phases.

$ mvn (phase) (plugin:goal) -D(system-property) -P(profile)

  • phase

    clean

    Remove contents of target tree

    test

    Build the src/main and src/test tree and execute the unit tests as defined by the surefire plugin

    pre-integration

    Perform unit tests and perform any steps required to ready for integration test

    integration-test

    Perform integration tests as defined by the failsafe plugin

    post-integration-test

    Tear down anything required to perform integration tests

    verify

    Evaluate results of integration tests

    install

    Install module artifacts into local repository

  • (plugin:goal)

    • Manually trigger a plugin goal without a specific build lifecycle

    • ex. jetty:run, dependency:tree, or dependency:help

  • -D(system-property)

    • Manually define a system property key or key and value to be used as a property in the build

    • Must configure surefire/failsafe to promote these as properties Junit -- these are system properties of the maven build and not of the JVM tasks kicked off by the maven build.

  • -P(profile)

    • Manually trigger build configurations latched by a profile

    • e.g., which DB driver to use

  • -P!(profile)

    • Manually turn off a profile

    • e.g., turn off a profile activated by a rule or settings.xml

    Use -P\!(profile) with bash shell

    The bash shell requires the bang ("!") character to be escaped. Use -P\!(profile) when using the bash shell.


[1] fusesource.com

Chapter 2. Maven Profiles

2.1. Profile Definition
2.2. Activation
2.2.1. Explicit Activation/Deactivation
2.2.2. Activation/Deactivation By Rule

  • Provide groups of conditional configuration

  • Adds flexibility to build

  • Flexibility can sometimes add confusion for both developers and build tools -- be careful


<profile> <!-- defines our default database -->

        <id>h2db</id>

        <properties>

              <jdbc.driver>org.h2.Driver</jdbc.driver>

              <jdbc.url>jdbc:h2:${basedir}/target/h2db/ejava</jdbc.url>

              <jdbc.user>sa</jdbc.user>

              <jdbc.password/>

              <hibernate.dialect>

                  org.hibernate.dialect.H2Dialect

              </hibernate.dialect>

        </properties>

        <dependencies>

            <dependency>

                <groupId>com.h2database</groupId>

                <artifactId>h2</artifactId>

                <scope>test</scope>

            </dependency>

        </dependencies>

    </profile>

The example above defines the properties and dependencies for the H2 database driver when the h2db profile is active

more tests

Chapter 3. Maven Modules

3.1. POM Inheritance
3.2. Submodules

  • Maven modules boundaries are highly influenced by the re-usable artifacts that must be produced

    • If you have many .jars, you likely have many maven modules

    • If you have few but large .jars, you likely have few but large maven modules

    • If you require different types of artifacts, you likely have different maven modules

  • Maven can be used in multi-module configuration

  • Many maven modules share the same configuration needs -- could lead to duplication

  • POM Inheritance helps mitigate duplication issues

Avoid defining thick parents

Be careful not to attempt to blindly merge all project definition into a single parent pom. This can bloat the inheriting children with unwanted dependency, cause slower builds, and can even break a build. When in doubt -- push active definitions (like dependencies and plugin declarations) to the leaf modules and leave only passive declarations (like properties, dependencyManagement, and pluginManagement) in the parent. 


<project>

   <parent>

        <groupId>ejava</groupId>

        <artifactId>ejava-root</artifactId>

        <version>3.0.2012.2-SNAPSHOT</version>

        <relativePath>..</relativePath>

    </parent>

    <modelVersion>4.0.0</modelVersion>

        

    <groupId>ejava.javaee.ejb</groupId>

    <artifactId>ejbsessionBank</artifactId>

    <packaging>pom</packaging>

    

    <name>Session Bean</name>

    <description>

        This project is the root project for the core session bean example.

    </description>

    <modules>

        <module>ejbsessionBankImpl</module>

        <module>ejbsessionBankEJB</module>

        <module>ejbsessionBankWAR</module>

        <module>ejbsessionBankEAR</module>

        <module>ejbsessionBankTest</module>

    </modules>

</project>

The example above has several child modules that it will build in the order they are specified.

Chapter 4. Dependency/Plugin Management

4.1. Dependency Management
4.2. Plugin Management

  • Defines what is possible without actively imposing the dependency or plugin defined

  • Placed in a parent of multi-module project

Chapter 5. Maven Eclipse Integration

5.1. Project Import
5.2. Project Update
5.3. Project Refresh

Maven/Eclipse integration is handled by adding the M2E plugin to your Eclipse environment and followng a pom-first configuration strategy.

Figure 5.1. Import Existing Maven Project into Eclipse

Import Existing Maven Project into Eclipse

  • M2E provides mechanisms to create new maven projects (we will not discuss)

Figure 5.2. Keeping Eclipse Dependencies in Sync

Keeping Eclipse Dependencies in Sync

  • Dependency hierachy shows

    • Which modules bring in other modules

    • Specific versions and where there are conflicts

Figure 5.3. Viewing Dependency Tree

Viewing Dependency Tree

When things are not automatically updated, try...

Note

A build from the command line that includes a clean and fails to complete can leave Eclipse in an unhappy state (lots of red unresolved references). Resolve with a successful build and repeat some/all of the above actions.

Chapter 6. Eclipse

6.1. Project Organization
6.2. Project Testing
6.2.1. Maven test from Eclipse
6.2.2. Raw JUnit within Eclipse
6.3. Program Debugging
6.3.1. Debugging within Eclipse
6.3.2. Debugging Maven test from Eclipse

Figure 6.1. Organize Multi-module Workspaces into Working Sets

Organize Multi-module Workspaces into Working Sets

Figure 6.2. Unit test directly within Eclipse

Unit test directly within Eclipse

Figure 6.3. Unit test directly within Eclipse

Unit test directly within Eclipse

Make your Unit Tests Eclipse-friendly

Maven is quite useful in setting up robust test environments but at a cost of repeated seconds of unnecessary work at times. Have your unit tests assume reasonable defaults and provide the ability to optionally override those values through surefire or launcher configurations. That way you can develop by compiling only changes classes within Eclipse and move forward in only a few seconds. Delegate the maven build at that point to batch regression testing.

Figure 6.4. Set Breakpoint within Eclipse

Set Breakpoint within Eclipse

Set program breakpoints where problems have been identified

Figure 6.5. Debug directly within Eclipse

Debug directly within Eclipse

Figure 6.6. Setup Remote Debugging Session with Maven

Setup Remote Debugging Session with Maven

Figure 6.7. Connect and Remote Debug any Java process

Connect and Remote Debug any Java process

  • Remote debugging requires special system properties issued to JVM

  • surefire and failsafe can be setup to optionally pass system properties to JUnit JVM

    
<plugin>
    
    <groupId>org.apache.maven.plugins</groupId>
    
    <artifactId>maven-surefire-plugin</artifactId>
    
    <version>2.16</version>
    
    <configuration>
    
        <argLine>${surefire.argLine}</argLine>
    
        <testSourceDirectory>src/test/java</testSourceDirectory>
    
    </configuration>
    
</plugin>
    

    
<profile> <!-- tells surefire to run JUnit tests with remote debug -->
    
    <id>debugger</id>
    
    <activation>
    
        <property>
    
            <name>debugger</name>
    
        </property>
    
    </activation>
    
    <properties>
    
        <surefire.argLine>-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000 -Xnoagent -Djava.compiler=NONE</surefire.argLine>
    
    </properties>
    
</profile>