JDeveloper / Maven Integration

This document explains how-to work with Oracle JDeveloper 11g on Apache Maven-based projects. As an example I'll illustrate two possible scenarios. First I'll demonstrate importing a Apache Maven application from maven.apache.org and then I'll demonstrate creating an application in Oracle JDeveloper 11g configured for using Apache Maven technologies. The new application will include a project that is preconfigured to use Maven technologies.

Important to note is that this is a developers preview release of Apache Maven integration within JDeveloper 11g.

Introduction

Apache Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information.

Maven's primary goal is to allow a developer to comprehend the complete state of a development effort in the shortest period of time. In order to attain this goal there are several areas of concern that Maven attempts to deal with:

Maven is essentially a project management and comprehension tool and as such provides a way to help with managing:

For further details on what Maven is and isn't, please visit the Maven Getting Started Guide. The Feature Summary page provides the key features of Maven in a nutshell. Apache Maven Project documentation is available online.

Much of Maven's power comes from the standard practices it encourages. Time need not be wasted reinventing directory structures, conventions, and customized Ant build scripts for each project. Although you can override any particular directory location for your own specific needs, it's best to stick with the standard Maven 2 directory structure as much as possible, for several reasons:

The directory layout expected by Maven and the directory layout created by Maven follows. You should try to conform to this structure as much as possible; however, if you can't these settings can be overridden via the project descriptor.

At the top level files descriptive of the project: a pom.xml file (and any properties, maven.xml or build.xml if using Ant). In addition, there are textual documents meant for the user to be able to read immediately on receiving the source: README.txt, LICENSE.txt, etc.

There are just two subdirectories of this structure: src and target. The only other directories that would be expected here are metadata like CVS or .svn, and any subprojects in a multiproject build (each of which would be laid out as above).

The src directory contains all of the source material for building the project, its site and so on. It contains a subdirectory for each type: main for the main build artifact, test for the unit test code and resources, site and so on.

Within artifact producing source directories (ie. main and test), there is one directory for the language java (under which the normal package hierarchy exists), and one for resources (the structure which is copied to the target classpath given the default resource definition).

If there are other contributing sources to the artifact build, they would be under other subdirectories: for example src/main/antlr would contain Antlr grammar definition files.

Required Software

Downloading and Installing JDeveloper 11g, Java JDK 1.6 & Maven 2.1.0

Download JDeveloper 11g and run the installer. Select the options that best fit your requirements for your development environment. Under most circumstances you will simply go with the defaults. Upon first running JDeveloper, select NO if prompted to migrate from previous versions. In addition, select the Default Role upon startup. After downloaded and running JDeveloper 11g you'll want to download and install the required Maven extensions for JDeveloper. To do so, from the JDeveloper "Help" Menu select "Check for Updates" from the context. There are two extension to install in the order listed and JDeveloper will require a restart after each extension is installed:

Download the appropriate Maven 2.1.0 distribution and install as follows for Windows 2000/XP:

Windows 2000/XP

Unzip the distribution archive, i.e. apache-maven-2.2.1-bin.zip to the directory you wish to install Maven 2.2.1. These instructions assume you chose C:\Program Files\Apache Software Foundation. The subdirectory apache-maven-2.2.1 will be created from the archive.
Add the M2_HOME environment variable by opening up the system properties (WinKey + Pause), selecting the "Advanced" tab, and the "Environment Variables" button, then adding the M2_HOME variable in the user variables with the value C:\Program Files\Apache Software Foundation\apache-maven-2.2.1. Be sure to omit any quotation marks around the path even if it contains spaces. Note: For Maven < 2.0.9, also be sure that the M2_HOME doesn't have a '\' as last character.
In the same dialog, add the M2 environment variable in the user variables with the value %M2_HOME%\bin.
Optional: In the same dialog, add the MAVEN_OPTS environment variable in the user variables to specify JVM properties, e.g. the value -Xms256m -Xmx512m. This environment variable can be used to supply extra options to Maven.
In the same dialog, update/create the Path environment variable in the user variables and prepend the value %M2% to add Maven available in the command line.
In the same dialog, make sure that JAVA_HOME exists in your user variables or in the system variables and it is set to the location of your JDK, e.g. C:\Program Files\Java\jdk1.5.0_02 and that %JAVA_HOME%\bin is in your Path environment variable.
Open a new command prompt (Winkey + R then type cmd) and run mvn --version to verify that it is correctly installed.

Validate Maven Installation: Run mvn --version

Note: For optional installation settings/configuration please visit the Apache Maven installation page.

Import a Maven Application into JDeveloper

The first thing to do is run the Maven Archetype create to create a project with the proper directory structure and a pom.xml

mvn archetype:create -DgroupId=com.mycompany.app -DartifactId=my-app

Create Archetype

You will notice that the create goal created a directory with the same name given as the artifactId. The pom.xml file is the core of a project's configuration in Maven. It is a single configuration file that contains the majority of information required to build a project in just the way you want.

<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>com.mycompany.app</groupId>
<artifactId>my-app</artifactId>
<packaging>jar</packaging>
<version>1.0-SNAPSHOT</version>
<name>my-app</name>
<url>http://maven.apache.org</url>
<dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
</dependencies>
</project>

pom.xml

For details of what you just did please refer to the Maven Users Centre The 5 minute test.

In the rest of the steps of this section I'll demonstrate Maven integration within JDeveloper 11g.

Select File | Import from the JDeveloper Menu.

Import

Select what you want to import. In this case "Source into New Project".

Select source into NewProject

Provide a Application Workspace name or go with the default.

Provide a Application Workspace Name

Provide a Project name or go with the default name.

Provide a Project Name

Select the content that you would like to import. You are importing the Maven Application that you previously created in the directory c:\mvnProjects. This is your application content including your pom.xml.

Select content to import

Add additional content into "Java Source Paths" as required. Select "Include content from Subfolders" and ensure "Copy files to Project Directory" is selected.

Import Source into New Project: Ensure "Copy Files to Project Directory" is selected

Add additional Libraries as required.

Import source into New Project: Add additional libraries as needed

Review the summary page of what you will import.

Summary Import Page

Review the imported Maven project.

JDeveloper Application Workspace

Right select the pom.xml file and select "Manage Goals".

Manage Goals

Shuttle additional Goals from Available to Selected so that the options are available from context upon choosing to run goals when right-selecting on the pom.xml and seleting the goal of your choice from context.

Maven: Goals

Optional Maven Configuration

Here you can Customize your Maven Setting, Specify your Maven Version, Add Proxy to Settings if you're behind a firewall and more. In addition, the Maven extension that was downloaded and installled earlier is version 2.1.0. If you prefer you can work with a more recent release of Maven such as version 2.2.1 and here is where you would specify that newer Maven Version with your Project Properties in the MAven Project Settings.

Maven Settings

Here you can customize the Maven Process as needed. Add Java Options, change the Java SE Version, specify the Working Directory and more.

Maven: Process

Here you can specify additional Maven Settings and customize as needed. Review the available options.

Maven: Settings

Right select the pom.xml and select Run Goal(s) from context. Choose the goal that you would like to run. For detailed information on the various goals please refer to the Apache Maven Build Lifecycle Page.

Run the Goal of your choice

Run the package goal to take the compiled code and package it in its distributable format, sucha as a JAR.

Run the package goal

Ensure the build is successful as illustrated below.

Review the package goal completed successfully

This section has demonstrated importing a pom.xml from a Maven Application. You may also want to review the application code provided within App.java and AppTest.java. This is but a simple HelloWorld application and this theme will be utilized further in the next section where I'll create a JDeveloper 11g HelloWorld Application Workspace configured to leverage Apache Maven. This section has touched on some of the Apache Maven features available within JDeveloper 11g and more features will be demonstrated in the following section.

Create JDeveloper 11g Application Configured for Maven

The first thing to do is to create a new application workspace in JDeveloper. Here are the steps:

Create a new application workspace either from the File menu or Application Navigator within JDeveloper. Provide a name or go with the default.

This section has demonstrated creating a Application Workspace in JDeveloper 11 g configured for Apache Maven. You may also want to review the application code provided within App.java . This is but a simple HelloWorld application as in the first section. This section has touched on some of the Apache Maven features available within JDeveloper 11g as before with some additional features of Code Insight within the pom.xml and more.