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.5 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.5
This is a copy of the standard Maven 3.0.5 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.5 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.5 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_45
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.5\bin
You also need to set the JAVA_HOME environment variable to point to your JDK installation.
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.
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.
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.
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 populate it with Oracle artifacts.
For this reason, a Maven Synhronization plug-in is provided, which allows 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 contain maven
directories which contain 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.3/oracle-maven-sync.12.1.3.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.3/oracle-maven-sync.12.1.3.jar
To install the plug-in into your local Maven repository, run the following command from the ORACLE_HOME/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/12.1.3
directory:
mvn install:install-file -DpomFile=oracle-maven-sync.12.1.3.pom -Dfile=oracle-maven-sync.12.1.3.jar
The simplest way deploy the plug-in into a shared internal repository is to 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_HOME/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/12.1.3
directory:
mvn deploy:deploy-file -DpomFile=oracle-maven-sync-12.1.3.pom -Dfile=oracle-maven-sync-12.1.3.jar -Durl=http://servername/archiva/repositories/internal -DrepositoryId=internal
To use the deploy plug-in as shown, you must define the repository in your Maven settings.xml file and 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
If you would like to use the shorter name for the Oracle Maven Synchronization Plug-in, so that you do not have to provide the full coordinates when using it, you should add an entry to your Maven settings.xml as follows:
<pluginGroups> <pluginGroup>com.oracle.maven</pluginGroup> ... </pluginGroups>
This allows you to refer to the plug-in using the name oracle-sync
.
The Oracle Maven Synchronization Plug-in supports a single push goal used to populate a repository.
To obtain usage and parameter descriptions you can invoke the help:describe goal by running the following command:
mvn help:describe -Dplugin=com.oracle.maven:oracle-maven-sync -Ddetail
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 settings.xml file. This is required only if you intend to deploy to a remote repository. The settings.xml should provide the remote artifact repository's deployment information, such as URL, user name, and password. |
|
The path to the Oracle home from which you want to populate the Maven repository. |
|
This controls whether the plug-in attempts to publish the artifacts to the repository. If you set this to |
|
If you set this property to If you set this property to |
overwriteParent |
If you set this property to |
pushDuplicates |
If you set this property to |
Some Maven Repository Managers have a setting that controls whether you can 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
-Doracle-maven-sync.oracleHome=/path/to/oracleHome
-DtestingOnly=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 -DoracleHome=/path/to/oracleHome -Dmaven.repo.local=/alter/nate/path
To specify the parameters in your Project Object Model file, you must add a plug-in entry similar to the following:
<plugin> <groupId>com.oracle.maven</groupId> <artifactId>oracle-maven-sync</artifactId> <version>12.1.3-0-0</version> <configuration> <oracleHome>/path/to/oracleHome</oracleHome> <testOnly>false</testOnly> </configuration> </plugin>
After adding the plug-in, execute Maven by running the following command:
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 file 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 file.
For example:
mvn com.oracle.maven:oracle-maven-sync:push -DoracleHome=/path/to/oracleHome -DserverId=internal
The corresponding Maven settings.xml file 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:
<plugin>
<groupId>com.oracle.maven</groupId>
<artifactId>oracle-maven-sync</artifactId>
<version>12.1.3-0-0</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:
mvn com.oracle.maven:oracle-maven-sync:push
After you have populated the repository you may want to perform some operations on the repository manager, such as update indexes or update the archetype catalog. You should refer to the documentation for the repository manager to check if any such operations are necessary or recommended.
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
When you run the push goal against a Maven repository which already has Oracle artifacts in it, the Oracle Maven Synchronization Plug-in detects that you have existing Parent POMs in the repository. It does not overwrite these Parent POMs, in case you have modified them, for example, by adding your own settings to them. Instead, it prints a warning message. If you want to overwrite the Parent POMs, you need to specify the extra parameter -DoverriteParents=true
on the push goal.
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.3 provides a mechanism to address this issue.
If any problems are found after a release of Oracle Fusion Middleware (for example, 12.1.3) 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 want 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 local archetype catalog, execute a command like the following:
mvn archetype:crawl -Dcatalog=$HOME/.m2/archetype-catalog.xml
This example settings.xml file 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 16. 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.3.jar -DrepositoryId=archiva-releases -DpomFile=/path/to/oracle-maven-sync-12.1.3.pom -Durl=http://server:port/archiva/repository/internal