Maven is a build management tool that is central to project build tasks such as compilation, packaging, and artifact management. Maven uses a strict XML-based rule set to promote consistency while maintaining flexibility. Because most Java-centric continuous integration systems integrate well with Maven, it is a good choice for an underlying build system. This chapter describes how to install and configure Maven.
This chapter contains the following sections:
A distribution of Maven 3.0.4 is included with Oracle Fusion Middleware. After you install Oracle WebLogic Server, you can find Maven in your Oracle home in the following location:
ORACLE_HOME/oracle_common/modules/org.apache.maven_3.0.4
This is a copy of the standard Maven 3.0.4 release, without any modifications.
Alternatively, you can download and install your own copy of Maven from the Maven website:
Oracle Fusion Middleware supports Maven 3.0.4 or higher.
After installation, add Maven to your operating system's PATH environment variable:
On UNIX:
You must update your shell startup script, your .profile or .bash_profile, to update the path.
For example, if you have installed Oracle WebLogic Server in /u01/fmwhome and you are using the bash shell, then you must add the following to the PATH environment variable:
export M2_HOME=/u01/fmwhome/oracle_common/modules/org.apache.maven_3.0.4 export PATH=${M2_HOME}/bin:$PATH
You also need to set the JAVA_HOME environment variable to point to your JDK installation. For example:
export JAVA_HOME=/u01/jdk1.7.0_21
On Windows:
Edit your PATH environment variable and add the correct path to Maven at the beginning of the PATH environment variable.
For example, if you have installed WebLogic Server in c:\fmwhome, then you must add the following:
C:\fmwhome\oracle_common\modules\org.apache.maven_3.0.4\bin
You also need to set the JAVA_HOME environment variable to point to your JDK installation, for example, export JAVA_HOME=/u01/jdk1.7.0_21.
You must create a Maven settings file if:
You are working behind a firewall or proxy server.
Your organization has its own internal Maven Repository Manager.
The Maven settings file is called settings.xml and is usually kept in the .m2 directory inside your home directory. However, if you want to point Maven to a different location, see the Maven documentation.
If you have installed Maven for the first time, either as part of the Oracle WebLogic Server installation, or by downloading it from the Maven website, you will not have a settings file yet.
On UNIX:
If your user name is bob, then the directory path should look similar to the following:
/home/bob/.m2/settings.xml
On Windows:
If your user name is bob, then the directory path should look similar to the following:
C:\Users\bob\.m2\settings.xml
The following is an example of a Maven settings file:
<settings>
<proxies>
<proxy>
<active>true</active>
<protocol>http</protocol>
<host>proxy.mycompany.com</host>
<port>8080</port>
<nonProxyHosts>mycompany.com</nonProxyHosts>
</proxy>
</proxies>
<servers>
<server>
<id>maven.mycompany.com</id>
<username>me@mycompany.com</username>
<password>{COQLCE6DU6GtcS5P=}</password>
</server>
</servers>
<mirrors>
<mirror>
<id>archiva</id>
<name>Internal Archiva Mirror of Central</name>
<url>http://archiva.mycompany.com/repositories/internal</url>
<mirrorOf>central</mirrorOf>
</mirror>
</mirrors>
</settings>
This example shows three common configuration settings that you may need to use:
Proxy enables you to communicate with Maven about the HTTP proxy server that is required to access Maven repositories on the Internet.
Servers enables you to communicate with Maven about your credentials for the Maven repository, so that you do not have to enter them every time you want to access the repository.
Mirrors informs Maven that instead of trying to access the Maven central repository directly, it should use your internal Maven repository manager as a mirror (cache) of Maven's central repository.
If you are not familiar with these terms, review the introduction in Chapter 1. For more information about available Maven settings, see the Maven documentation at:
After you have configured your Maven Repository Manager, for example, you set up Archiva in Chapter 4, you will want to populate it with Oracle artifacts.
For this reason, a Maven Synhronization plug-in is provided, which will allow you to populate a local or shared Maven repository from an Oracle home. When you install a Fusion Middleware 12c product, the Maven archetypes, plug-ins, and POMs are installed with the product so that the synchronization plug-in can find them.
This section contains the following topics:
Oracle Fusion Middleware 12c provides a Maven Synchronization plug-in that simplifies the process of setting up repositories and completely eliminates the need to know what patches are installed in a particular environment. This plug-in enables you to populate a Maven repository from a given Oracle home. After you patch your Oracle home, you should run this plug-in to ensure that your Maven repository matches Oracle home. This ensures that your builds use correct versions of all artifacts in that particular environment.
The Oracle Maven Synchronization Plug-in is included in the Oracle WebLogic Server, Oracle Coherence and Oracle JDeveloper installations. To use the plug-in, you must specify the location of the Oracle home and the location of the Maven repository. The Maven repository can be specified using either a file system path or a URL. The plug-in checks for all Maven artifacts in the Oracle home, ensures that all artifacts are installed in the specified Maven repository, and that the versions match exactly. This means that the version numbers and the files are exactly same at the binary level, ensuring that all patched files reflects accurately in the Maven repository.
Oracle homes in 12c contains maven directories which contains Maven Project Object Models (POMs) for artifacts provided by Oracle, archetypes for creating projects, and Maven plug-ins provided by Oracle, for executing various build operations.
Before you start using the Oracle Maven Synchronization plug-in, you must install it into your Maven repository. You can install it into your local repository on your computer, or you can deploy it into your shared internal repository, if you have one.
The plug-in is located in your Oracle WebLogic Server 12c home and consists of two files:
The Maven Project Object Model (POM) file that describes the plug-in, which is located at:
ORACLE_HOME/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/12.1.2/oracle-maven-sync.12.1.2.pom
The JAR file that contains the plug-in, which is located at:
ORACLE_HOME/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/12.1.2/oracle-maven-sync.12.1.2.jar
To install the plug-in into your local Maven repository, run the following command from the ORACLE_COMMON/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/12.1.2 directory:
mvn install:install-file -DpomFile=oracle-maven-sync.12.1.2.pom -Dfile=oracle-maven-sync.12.1.2.jar
The simplest way deploy the plug-in into a shared internal repository, use the web user interface provided by your Maven Repository Manager to upload the JAR file into the repository.
An alternative method is to use the deploy plug-in, which you can do by using a command like the following from the ORACLE_COMMON/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/12.1.2 directory:
mvn deploy:deploy-file -DpomFile=oracle-maven-sync-12.1.2.pom -Dfile=oracle-maven-sync-12.1.2.jar -Durl=http://servername/archiva/repositories/internal -DrepositoryId=internal
To use the deploy plug-in as shown, you will need to define the repository in your Maven settings.xml file and also define the credentials if anonymous publishing is not allowed.
For information about this command, refer to the Maven documentation at:
http://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html
The Oracle Maven Synchronization Plug-in supports two Maven goals:
Help, which prints out help information
Push, which is used to populate a repository
You can execute the help goal by running the following command:
mvn com.oracle.maven:oracle-maven-sync:help
The output of the help goal is as follows:
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building odm 1.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] --- oracle-maven-sync:12.1.2:help (default-cli) @ odm ---
[INFO] ------------------------------------------------------------------------
[INFO] ORACLE MAVEN SYNCHRONIZATION PLUGIN - HELP
[INFO] ------------------------------------------------------------------------
[INFO] The following goals are available:
[INFO]
[INFO] help prints this help
[INFO]
[INFO] push Install to the local repository and optionally deploy
[INFO] to a remote repository from the specified oracle home
[INFO]
[INFO] The plugin will use your current Maven settings to
[INFO] determine the path to the local repository and,
[INFO] optionally, a remote deployment repository. For
[INFO] details on how to configure Maven's repository
[INFO] settings, see the Maven settings reference:
[INFO] http://maven.apache.org/settings.html
[INFO] parameters:
[INFO] oracle-maven-sync.oracleHome
[INFO] - This is the path to the Oracle Home
[INFO] oracle-maven-sync.testOnly
[INFO] - Must be set to 'false' or no action will be taken
[INFO] Defaults to 'true'
[INFO] oracle-maven-sync.failOnError
[INFO] - If set to 'true' the plugin will stop and return an
[INFO] error immediately upon the first failure to deploy
[INFO] an artifact. Otherwise, the plugin will log the
[INFO] error and attempt to complete deployment of all
[INFO] other artifacts.
[INFO] Defaults to 'false'
[INFO] oracle-maven-sync.serverId [OPTIONAL]
[INFO] - This is the ID of the server (repository) in
[INFO] your settings.xml file - where you have
[INFO] specified the remote Maven repository and its
[INFO] authentication information. The plugin will
[INFO] only install to the local repository if this
[INFO] parameter is not set.
[INFO]
[INFO]
[INFO] You can specify the parameters on the command line like this:
[INFO] -Doracle-maven-sync.serverId=archiva-internal
[INFO] -Doracle-maven-sync.testOnly=false
[INFO] -Doracle-maven-sync.failOnError=false
[INFO]
[INFO] To override the localRepository target used by the plugin, you
[INFO] can specify the following option on the command-line:
[INFO] -Dmaven.local.repo=/alternate/path/to/repository
[INFO]
[INFO] To supply an alternate settings.xml for purposes of this operation,
[INFO] use the --settings option. For example:
[INFO] mvn --settings /alternate/path/settings.xml ...
[INFO]
[INFO] ...or in your POM like this:
[INFO] <plugin>
[INFO] <groupId>com.oracle.maven</groupId>
[INFO] <artifactId>oracle-maven-sync</artifactId>
[INFO] <version>12.1.2</version>
[INFO] <configuration>
[INFO] <oracleHome>/home/mark/Oracle/Middleware</oracleHome>
[INFO] <failOnError>false</failOnError>
[INFO] </configuration>
[INFO] </plugin>
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 0.689s
[INFO] Finished at: Day Month Year Time Year
[INFO] Final Memory: 3M/119M
[INFO] ------------------------------------------------------------------------
This output shows the parameters that are available for the plug-in's push goal. Table 5-1 describes the parameters:
Table 5-1 Push Goal Parameters and Description
| Parameter | Description |
|---|---|
|
|
A pointer to the server entry in your Maven |
|
|
The path to the Oracle home that you wish to populate the Maven repository from. |
|
|
This controls whether the plug-in attempts to publish the artifacts to the repository. If you test this to |
|
|
If you set this property to If you set this property to |
Some Maven Repository Managers have a setting that controls whether you will able to replace an existing artifact in the repository. If your Maven Repository Manager has such a setting, you must ensure that you have set it correctly so that the Oracle Maven Synchronization Plug-in is able to update the artifacts in your repository. This screen is accessed by selecting Repositories under the Administration menu. Then, click Edit to change the setting of the repository you want to change.
If you are using Archiva, you must deselect the Block Re-deployment of Released Artifacts option in the Managed Repository settings.
Other Maven Repository Managers have similar settings. If you are using a different tool, consult the documentation for that tool to find out how to change this setting.
To populate your repository, you must use the push goal. You can specify the parameters given in Table 5-1 on the command line or in your Project Object Model file.
This section contains the following topics:
If you are populating your local repository, you only need to specify oracleHome and testingOnly=false.
For example:
mvn com.oracle.maven:oracle-maven-sync:push
-DoracleHome=/path/to/oracleHome
--Doracle-maven-sync.testingOnly=false
The localRepository element in your settings.xml file indicates the location of your local Maven repository. If you exclude the localRepository element in settings.xml, the default location is in the ${HOME}/.m2/repository directory.
If you want to override the localRepository value, then you must specify the override location on the command line as a Maven option.
For example:
mvn com.oracle.maven:oracle-maven-sync:push -Doracle-maven-sync.oracleHome=/path/to/oracleHome -Dmaven.repo.local=/alternate/path
To specify the parameters in your Project Object Model file, you must add a plug-in entry similar to the following in your Project Object Model file:
<plugin>
<groupId>com.oracle.maven</groupId>
<artifactId>oracle-maven-sync</artifactId>
<version>12.1.2</version>
<configuration>
<oracleHome>/path/to/oracleHome</oracleHome>
<testOnly>false</testOnly>
</configuration>
</plugin>
After adding the plug-in, execute Maven by running the following command on the command line:
mvn com.oracle.maven:oracle-maven-sync:push
If you are populating your remote repository, you must specify serverId and oracleHome on the command line interface or in the plug-in configuration. You must also have a repository configuration in your settings.xml that matches the serverId you provide to the plug-in. If authentication is required for deployment, you must also add a server entry to your Maven settings.xml.
For example:
mvn com.oracle.maven:oracle-maven-sync:push -Doracle-maven-sync.oracleHome=/path/to/oracleHome -Doracle-maven-sync.serverId=internal
The corresponding Maven settings.xml with authentication details look like the following:
...
<profiles>
<profile>
<id>default</id>
<repositories>
<repository>
<releases>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
<checksumPolicy>warn</checksumPolicy>
</releases>
<snapshots>
<enabled>true</enabled>
<updatePolicy>never</updatePolicy>
<checksumPolicy>fail</checksumPolicy>
</snapshots>
<id>internal</id>
<name>Team Internal Repository</name>
<url>http://some.host/maven/repo/internal</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
...
<server>
<id>internal</id>
<username>deployer</username>
<password>welcome1</password>
</server>
...
<activeProfiles>
<activeProfile>default</activeProfile>
</activeProfiles>
You must define the target repository in a profile, and activate that profile using the activeProfiles tag as shown in the preceding example.
Note:
You should specify an encrypted password in the server section. For details on how to encrypt the server passwords, see:
http://maven.apache.org/guides/mini/guide-encryption.html#How_to_encrypt_server_passwords
To specify the parameters in your Project Object Model file, you must add a plug-in entry similar to the following in your Project Object Model file:
<plugin>
<groupId>com.oracle.maven</groupId>
<artifactId>oracle-maven-sync</artifactId>
<version>12.1.2</version>
<configuration>
<serverId>internal</serverId>
<oracleHome>/path/to/oracleHome</oracleHome>
<testOnly>false</testOnly>
</configuration>
</plugin>
After adding the plug-in, execute Maven by running the following command on the command line:
mvn com.oracle.maven:oracle-maven-sync:push
When you run the push goal, it takes the following actions:
Checks the Oracle home you have provided and makes a list of all of the Maven artifacts inside that Oracle home. This is done by looking for Project Object Model files in the ORACLE_HOME/oracle_common/plugins/maven dependencies directory and its subdirectories, recursively and in the ORACLE_HOME/PRODUCT_HOME/plugins/maven directory and its subdirectories recursively for each PRODUCT_HOME that exists in the ORACLE_HOME.
Checks if the JAR file referred to by each Project Object Model file is available in the Oracle home.
Calculates a SHA1 checksum for the JAR file.
Attempts to publish the JAR, Project Object Model, and SHA1 files to the repository that you have provided.
The following types of Maven artifacts are installed into your repository:
Maven dependencies provided by Oracle, which include the following:
Client API classes
Compilation, packaging, and deployment utilities, for example, appc and wlst
Component JARs that must be embedded in the application
Client-side runtime classes, for example, t3 and JAX-WS client runtimes
Maven plug-ins provided by Oracle that handle compilation, packaging, and deployment
Maven archetypes provided by Oracle that provide project templates
Patching is the practice of updating a system with minor changes, usually to fix bugs that have been identified after the software goes into production. Oracle Fusion Middleware uses Oracle Patch (OPatch) to manage application of patches to installed software in the Oracle home. When you use Oracle Patch to apply a patch, the version number of the installed software may not change.
Maven uses a different approach to patching which assumes that released software will never be changed. When a patch is necessary, a new version of the artifact, with a new version number, is created and distributed as the patch.
This difference creates an issue when you use Maven to develop applications in an Oracle Fusion Middleware environment. Oracle Fusion Middleware 12.1.2 provides a mechanism to address this issue.
If any problems are found after a release of Oracle Fusion Middleware (for example, 12.1.2) into production, a one-off patch is created to fix that problem. Between any two releases, for example 12.1.2 and 12.1.3, a number of these patches are released. You can apply many combinations of these patches, including all or none of these patches.
This approach gives a great deal of flexibility and you can apply only the patches that you need, and ignore the rest. However, it can create an issue when you are using Maven. Ensure that the artifacts you are using in your build system are the exact same (potentially patched) versions that are used in the target environment.
The complications arises when you have a number of environments, like test, QA, SIT, and production, which are likely to have different versions (or patches) installed.
It is recommended that, in such a situation, you set up one Maven repository for each environment that you wish to target. For example, a Maven test repository that contains artifacts that matches the versions and patches installed in the test environment and a Maven QA repository that contains artifacts that match the versions and patches installed in the QA environment.
After you patch your Oracle home, you should run this plug-in to ensure that your Maven repository matches the Oracle home. This ensures that your builds use correct versions for all artifacts in that particular environment.
By running the Oracle Maven Synchronization Plug-in's push goal, you may have installed new Maven archetypes into your Maven repository. You might need to run a command to rebuild the index of archetypes. Some Maven repository managers do this automatically.
To rebuild your archetype catalog, execute a command like the following:
mvn archetype:crawl -Dcatalog=$HOME/.m2/archetype-catalog.xml
This example, settings.xml, provides a template for Maven integration with the rest of the continuous integration system described in this book. It provides configuration to support central Archiva repository interaction and Hudson continuous integration server integration as described in Chapter 4 and Chapter 12. You must change values of URLs, passwords, and so on to match your system's values:
<settings>
<profiles>
<profile>
<id>default</id>
<repositories>
<repository>
<id>dev-group</id>
<name>Dev Group</name>
<releases>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
<checksumPolicy>warn</checksumPolicy>
</releases>
<snapshots>
<enabled>false</enabled>
<updatePolicy>never</updatePolicy>
<checksumPolicy>fail</checksumPolicy>
</snapshots>
<url>http://SERVER:PORT/archiva/repository/dev-group</url>
<layout>default</layout>
</repository>
<repository>
<id>dev</id>
<name>Dev</name>
<releases>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
<checksumPolicy>warn</checksumPolicy>
</releases>
<snapshots>
<enabled>false</enabled>
<updatePolicy>never</updatePolicy>
<checksumPolicy>fail</checksumPolicy>
</snapshots>
<url>http://SERVER:PORT/archiva/repository/dev</url>
<layout>default</layout>
</repository>
<repository>
<id>prod-group</id>
<name>Prod Group</name>
<releases>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
<checksumPolicy>warn</checksumPolicy>
</releases>
<snapshots>
<enabled>false</enabled>
<updatePolicy>never</updatePolicy>
<checksumPolicy>fail</checksumPolicy>
</snapshots>
<url>http://SERVER:PORT/archiva/repository/prod-group</url>
<layout>default</layout>
</repository>
<repository>
<id>prod</id>
<name>Prod</name>
<releases>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
<checksumPolicy>warn</checksumPolicy>
</releases>
<snapshots>
<enabled>false</enabled>
<updatePolicy>never</updatePolicy>
<checksumPolicy>fail</checksumPolicy>
</snapshots>
<url>http://SERVER:PORT/archiva/repository/prod</url>
<layout>default</layout>
</repository>
<repository>
<id>qa-group</id>
<name>QA Group</name>
<releases>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
<checksumPolicy>warn</checksumPolicy>
</releases>
<snapshots>
<enabled>false</enabled>
<updatePolicy>never</updatePolicy>
<checksumPolicy>fail</checksumPolicy>
</snapshots>
<url>http://SERVER:PORT/archiva/repository/qa-group</url>
<layout>default</layout>
</repository>
<repository>
<id>qa</id>
<name>QA</name>
<releases>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
<checksumPolicy>warn</checksumPolicy>
</releases>
<snapshots>
<enabled>false</enabled>
<updatePolicy>never</updatePolicy>
<checksumPolicy>fail</checksumPolicy>
</snapshots>
<url>http://SERVER:PORT/archiva/repository/qa</url>
<layout>default</layout>
</repository>
<repository>
<id>test-group</id>
<name>Test Group</name>
<releases>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
<checksumPolicy>warn</checksumPolicy>
</releases>
<snapshots>
<enabled>false</enabled>
<updatePolicy>never</updatePolicy>
<checksumPolicy>fail</checksumPolicy>
</snapshots>
<url>http://SERVER:PORT/archiva/repository/test-group</url>
<layout>default</layout>
</repository>
<repository>
<id>test</id>
<name>Test</name>
<releases>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
<checksumPolicy>warn</checksumPolicy>
</releases>
<snapshots>
<enabled>false</enabled>
<updatePolicy>never</updatePolicy>
<checksumPolicy>fail</checksumPolicy>
</snapshots>
<url>http://SERVER:PORT/archiva/repository/test</url>
<layout>default</layout>
</repository>
<repository>
<id>archiva-snapshots</id>
<name>Archiva Snapshots</name>
<releases>
<enabled>false</enabled>
<updatePolicy>always</updatePolicy>
<checksumPolicy>warn</checksumPolicy>
</releases>
<snapshots>
<enabled>true</enabled>
<updatePolicy>never</updatePolicy>
<checksumPolicy>fail</checksumPolicy>
</snapshots>
<url>http://SERVER:PORT/archiva/repository/snapshots</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
</profiles>
<servers>
<server>
<id>dev</id>
<username>hudson</username>
<password>PASSWORD</password>
</server>
<server>
<id>dev-group</id>
<username>hudson</username>
<password>PASSWORD</password>
</server>
<server>
<id>archiva-snapshots</id>
<username>hudson</username>
<password>PASSWORD</password>
</server>
</servers>
<mirrors>
<mirror>
<id>dev-mirror</id>
<name>All else</name>
<url>http://SERVER:PORT/archiva/repository/dev-group</url>
<mirrorOf>*</mirrorOf>
</mirror>
</mirrors>
<activeProfiles>
<activeProfile>default</activeProfile>
</activeProfiles>
</settings>
The Maven deploy plug-in can also be used to deploy an artifact (or artifacts) and Project Object Module to the remote artifact repository.
For example, run the following command to deploy to the archiva-releases repository, as defined in the sample settings.xml file.
mvn deploy:deploy-file -Dfile=/path/to/oracle-maven-sync-12.1.2.jar -DrepositoryId=archiva-releases -DpomFile=/path/to/oracle-maven-sync-12.1.2.pom -Durl=http://server:port/archiva/repository/internal