5 Installing and Configuring Maven for Build Automation and Dependency Management
This chapter describes how to install and configure Maven.
Topics:
- Setting Up the Maven Distribution
A distribution of Maven 3.2.5 is included with Oracle Fusion Middleware. - Customizing Maven Settings
You can create a Maven settings file to specify proxy servers, servers, and mirrors. - JDBC Drivers, UCP and Companion Jars
The Oracle JDBC drivers and the Universal Connection Pool (UCP) are now available on the Oracle Maven Repository. - Populating the Maven Repository Manager
After you have configured your Maven Repository Manager, for example, you set up Archiva, you populate it with Oracle artifacts.
Setting Up the Maven Distribution
A distribution of Maven 3.2.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.2.5
This is a copy of the standard Maven 3.2.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 Linux:
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 thebash
shell, then you must add the following to the PATH environment variable:export M2_HOME=/u01/fmwhome/oracle_common/modules/org.apache.maven_3.2.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.2.5\bin
You also need to set the JAVA_HOME environment variable to point to your JDK installation.
Customizing Maven Settings
You can create a Maven settings file to specify proxy servers, servers, and mirrors.
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.
-
You plan to access the Oracle Maven Repository.
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. You must create it, naming it 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 Introduction to Continuous Integration. For more information about available Maven settings, see the Maven documentation at:
http://maven.apache.org/settings.html
The Maven settings file, settings.xml
, 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 your user name is bob, then the directory path should look similar to the following:
(Linux) /home/bob/.m2/settings.xml (Windows) C:\Users\bob\.m2\settings.xml
JDBC Drivers, UCP and Companion Jars
The Oracle JDBC drivers and the Universal Connection Pool (UCP) are now available on the Oracle Maven Repository.
The following versions are available on the Oracle Maven Repository: 12.2.0.2, 12.1.0.2, 12.1.0.1, and 11.2.0.4.
In addition, the companion jars, including ons.jar
, orai18n.jar
, xmlparserv2.jar
, simplefan.jar
and others required for specific features, are also available on Oracle maven repository. See JDBC and UCP Landing page on OTN for more information.
Table 5-1 shows the Oracle JDBC, UCP, and companion jars from the Oracle Database 12c Release 2 (12.2.0.1).
Table 5-1 JDBC Drivers, UCP, and Companion Jars for 12.2.0.1
Name of Jar | groupID, artifactID, and version Details | Description |
---|---|---|
ojdbc8.jar |
<groupIdcom.oracle.jdbc</groupId> <artifactId>ojdbc8</artifactId> <version>12.2.0.1</version> |
Oracle JDBC driver for use with JDK8 |
ojdbc8_g.jar |
<groupId>com.oracle.jdbc</groupId> <artifactId>ojdbc8_g</artifactId> <version>12.2.0.1</version> |
Debug version of ojdbc8.jar for tracing |
ojdbc8dms.jar |
<groupId>com.oracle.jdbc</groupId> <artifactId>ojdbc8dms</artifactId> <version>12.2.0.1</version> |
ojdbc8.jar with instrumentation to support DMS calls |
ojdbc8dms_g.jar |
<groupId>com.oracle.jdbc</groupId> <artifactId>ojdbc8dms_g</artifactId> <version>12.2.0.1</version> |
ojdbc8_g.jar with instrumentation to support DMS. |
ucp.jar |
<groupId>com.oracle.jdbc</groupId> <artifactId>ucp</artifactId> <version>12.2.0.1</version> |
Universal Connection Pool for use with JDK 8 |
simplefan.jar |
<groupId>com.oracle.jdbc</groupId> <artifactId>simplefan</artifactId> <version>12.2.0.1</version> |
Java APIs for subscribing to RAC events via ONS |
ons.jar |
<groupId>com.oracle.jdbc</groupId> <artifactId>ons</artifactId> <version>12.2.0.1</version> |
Oracle Notification Services (ONS) daemon |
dms.jar |
<groupId>com.oracle.jdbc</groupId> <artifactId>dms</artifactId> <version>12.2.0.1</version> |
Required for DMS enabled jar (ojdbc8dms.jar and ojdbc8dms_g.jar) |
osdt_core.jar |
<groupId>com.oracle.jdbc</groupId> <artifactId>osdt_core</artifactId> <version>12.2.0.1</version> |
Required to access Oracle Wallets from Java |
osdt_cert.jar |
<groupId>com.oracle.jdbc</groupId> <artifactId>osdt_cert</artifactId> <version>12.2.0.1</version> |
Required to access Oracle Wallets from Java |
oraclepki.jar |
<groupId>com.oracle.jdbc</groupId> <artifactId>oraclepki</artifactId> <version>12.2.0.1</version> |
Required to access Oracle Wallets from Java |
xdb6.jar |
<groupId>com.oracle.jdbc</groupId> <artifactId>xdb6</artifactId> <version>12.2.0.1</version> |
Classes to support standard java.sql.SQLXML interface (Java SE 8). |
xmlparserv2.jar |
<groupId>com.oracle.jdbc</groupId> <artifactId>xmlparserv2</artifactId> <version>12.2.0.1</version> |
To support standard java.sql.SQLXML interface |
orai18n.jar |
<groupId>com.oracle.jdbc</groupId> <artifactId>orai18n</artifactId> <version>12.2.0.1</version> |
Classes for NLS or Internationalization support |
Populating the Maven Repository Manager
After you have configured your Maven Repository Manager, for example, you set up Archiva, you populate it with Oracle artifacts.
Setting up Archiva is described in Installing and Configuring the Archiva Maven Repository Manager.
A Maven Synhronization plug-in 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:
- Introduction to the Maven Synchronization Plug-In
- Installing the Oracle Maven Synchronization Plug-In
- Running the Oracle Maven Synchronization Plug-In
- Replacing Artifacts
- Populating Your Maven Repository
- Running the Push Goal on an Existing Maven Repository
- Things to Know About Patching
- Considerations for Archetype Catalogs
- Example settings.xml file
- Deploying a Single Artifact
Introduction to the Maven Synchronization Plug-In
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, 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 reflect 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.
Parent topic: Populating the Maven Repository Manager
Installing the Oracle Maven Synchronization Plug-In
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, which describes the plug-in. It is located at:
ORACLE_HOME/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/12.2.1/oracle-maven-sync-12.2.1.pom
-
The JAR file, which contains the plug-in. It is located at:
ORACLE_HOME/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/12.2.1/oracle-maven-sync-12.2.1.jar
To install and deploy the plug-in:
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, 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
.
To configure your Maven installation and download, and use the plug-in from the Oracle Maven Repository, you must register for access in the Oracle Public Maven Repository and add a server entry to your Maven settings.xml file, as described in About the Oracle Maven Repository.
Parent topic: Populating the Maven Repository Manager
Running the Oracle Maven Synchronization Plug-In
The Oracle Maven Synchronization plug-in supports a single push goal used to populate a repository.
To obtain usage and parameter descriptions, 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-2 describes the parameters.
Table 5-2 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. |
|
A parameter to control 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 |
Parent topic: Populating the Maven Repository Manager
Replacing Artifacts
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.
For Archiva:
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.
Parent topic: Populating the Maven Repository Manager
Populating Your Maven Repository
To populate your repository, you must use the push goal. You can specify the parameters given in Table 5-2 on the command line or in your Project Object Model file.
This section contains the following topics:
Parent topic: Populating the Maven Repository Manager
About Running the Push Goal
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 theORACLE_HOME
/
PRODUCT_HOME
/plugins/maven
directory and its subdirectories recursively for eachPRODUCT_HOME
that exists in theORACLE_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
andwlst
-
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
Parent topic: Populating Your Maven Repository
Populating a Local Repository
You need to populate a local repository:
Parent topic: Populating Your Maven Repository
Populating a Remote Repository
To populate a 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 looks similar to 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>username</username> <password>password</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.2.1-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. Refer to the documentation for the repository manager to check if any such operations are necessary or recommended.
Parent topic: Populating Your Maven Repository
Running the Push Goal on an Existing Maven Repository
When you run the push goal against a Maven repository that 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.
Parent topic: Populating the Maven Repository Manager
Things to Know About Patching
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 the OPatch utility to manage application of patches to installed software in the Oracle home. When you use OPatch 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 provides a mechanism to address this issue.
This section contains the following topics:
Parent topic: Populating the Maven Repository Manager
Oracle's Approach to Patching
If any problems are found after a release of Oracle Fusion Middleware (for example, 12.2.1) into production, a one-off patch is created to fix that problem. Between any two releases, for example 12.2.1 and 12.2.1, 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 you a great deal of flexibility. 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.
Oracle recommends 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.
Parent topic: Things to Know About Patching
Run the Oracle Maven Synchronization Plug-In Push Goal After Patching
After you patch your Oracle home, 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. See Running the Oracle Maven Synchronization Plug-In.
Parent topic: Things to Know About Patching
Considerations for Archetype Catalogs
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 similar to the following:
mvn archetype:crawl -Dcatalog=$HOME/.m2/archetype-catalog.xml
Parent topic: Populating the Maven Repository Manager
Example settings.xml file
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 Installing and Configuring the Archiva Maven Repository Manager and From Build Automation to Continuous Integration. You must change values, such as URLs and passwords, 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>
Parent topic: Populating the Maven Repository Manager
Deploying a Single Artifact
You can use the Maven deploy plug-in 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.2.1.jar -DrepositoryId=archiva-releases -DpomFile=/path_to_oracle-maven-sync-12.2.1.pom -Durl=http://server:port/archiva/repository/internal
Parent topic: Populating the Maven Repository Manager