Maven is an open source build management tool that is central to project build tasks such as compilation, packaging, and artifact management. Maven uses a strict XML-based ruleset to promote consistency while maintaining flexibility. Most Java-centric continuous integration systems integrate well with Maven, making it a good choice for an underlying build system. This chapter describes how use Maven for Oracle Enterprise Pack for Eclipse (OEPE).
This document contains the following sections:
Maven is installed with your Fusion Middleware in your Oracle home at 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. You can also get Maven from the Apache website.
To use Maven as the build tool for developing ADF applications in OEPE, you need to populate the Maven repository with Oracle artifacts. For populating the repository, a Maven Synchronization 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 Project Object Models (POMs) are installed with the product where the synchronization plug-in can find them.
Using Maven with OEPE requires you to configure and setup the maven environment using the following steps:
For further information see Developing Applications Using Continuous Integration.
Note:
After you patch your Oracle home, you should run the plug-in again to ensure that your Maven repository matches Oracle home. This ensures that your builds use correct versions of all artifacts in that particular environment. For information on patching, see Chapter 5, "Installing and Configuring Maven for Build Automation and Dependency Management" in Developing Applications Using Continuous Integration.Once you have Maven installed, either as part of a Fusion Middleware package, or from the Apache website, you need to perform a few initial steps to set up your environment.
The first thing you need to do to use Maven is to set your environment variables.
To set up your environment on Unix:
Add Maven to your operating system's PATH:
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 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
Set the JAVA_HOME environment variable to point to your JDK installation, for example, export JAVA_HOME=u01\jdk1.7.0
To set up your environment on Windows:
Edit your PATH environment variable and add the correct Maven directory path at the beginning of the PATH environment variable. For example, if you have installed your Fusion Middleware in C:\fmwhome
, then add the following:
C:\fmwhome\oracle_common\modules\org.apache.maven_3.0.4\bin
Set the JAVA_HOME
environment variable to point to your JDK installation, for example, export JAVA_HOME=C:\Oracle\Middleware\jdk1.7.0
Add the M2_HOME environment variable by opening up the system properties (WinKey + Pause), selecting the Advanced tab, then the Environment Variables button. Add the M2_HOME variable in the user variables with the value C:\<ORACLE_HOME>\oracle_ common\modules\org.apache.maven_3.0.4\bin
\. If you installed Maven from the Apache website, the value will be C:\Program Files\Apache Software Foundation\apache-maven-3.0.5.
In the same dialog, add the user variable with the value %M2_HOME%\bin
.
Open a new command prompt (Winkey + R then type cmd
) and run mvn --versio
n to verify that it is correctly installed.
If you have any issues with this process, you can go to this Apache page to problem solve: https://cwiki.apache.org/confluence/display/MAVEN/NoPluginFoundForPrefixException
.
To use Maven you will need a settings file, if any of the following are true:
You have installed Maven for the first time.
You are working behind a firewall or proxy server.
Your organization has its own internal Maven Repository Manager.
To create a Maven settings file, create a XML file called settings.xml
. If your user name is Bob, then the directory path for the settings.xml
file should be the following:
/home/bob/.m2/settings.xml
.
For Windows, If your user name is Bob then the directory path for the settings.xml
file should be the following:
/users/bob/.m2/settings.xml
.
You are going to add the following information to your settings file:
Proxy - sets the HTTP proxy server that is required to access Maven repositories on the Internet.
Servers - sets the credentials for the Maven repository, so that you do not have to enter them every time you want to access the repository.
Mirrors - directs 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 central repository.
Add these settings as shown in the example Maven settings file below.
<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>
For more information about available Maven settings, see the Apache Maven documentation at, http://maven.apache.org/settings.html
The next step is populating your Maven repository with the Oracle artifacts. The Oracle Maven Synchronization plug-in populates a local or shared Maven repository from an Oracle home. When you run the plug-in, it finds the Oracle artifacts and transfers them to a Maven repository.
To use the plug-in start by specifying the location of the Oracle home and the location of the Maven repository using either a file system path, or a URL. The plug-in checks for all Maven artifacts in the Oracle home, then ensures that the artifacts are installed in the specified Maven repository, and that the versions match. This ensures the version numbers and the files match at the binary level, and that all patched files are reflected accurately in the Maven repository.
The plug-in is located in your ORACLE_HOME directory path and consists of two files:
The Maven 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 run the plug-in you first need to install it on your Maven repository. You can install it into your local repository on your computer, or you can deploy it into a remote shared internal repository.
To install the plug-in to a local repository using the command line:
In a command prompt, navigate to the location of your Maven plug-in jar located at ORACLE_COMMON/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/12.1.3
Run the following command to install to the default repository:
mvn install:install-file -DpomFile=oracle-maven-sync.12.1.3.pom -Dfile=oracle-maven-sync.12.1.3.jar
Run the following command to install to a specified directory:
mvn install:install-file -DpomFile=oracle-maven-sync.12.1.3.pom -Dfile=oracle-maven-sync.12.1.3.jar -Dmaven.repo.local=<path to local repository>
To install the plug-in to a shared internal repository using the command line:
In a command prompt, navigate to the location of your plug-in jar at ORACLE_COMMON/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/12.1.3
Run the following command:
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
For information about the deploy command see 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 - prints out help information. Execute the help goal by running mvn com.oracle.maven:oracle-maven-sync:help
Push - populates a repository. Goal semantics depend on how you define your plug-in parameters.
To populate your repository, run the plug-in using the push goal. The push goal requires you define your plug-in parameters. You can populate a local or a remote repository using the push goal.Push goal parameters are defined in Table 6-1. You can specify the parameters either in your command line or in your POM file.
Table 6-1 Push Goal Parameters and Descriptions
Features | 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 deployment information, such as URL, user name, and password. |
|
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 |
If you are populating a local repository, specify oracleHome and 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 your 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=/alter/nate/pa
th
To specify the parameters in your POM file, you must add a plug-in entry similar to the following in your POM file, as shown in Table 6-1.
This example shows the plug-in parameters in your POM file.
<plugin> <groupID>com.oracle.maven</groupID> <artifaceID>oracle-maven-sync</artifactID> <version>12.1.3</version> <configuration>/home/<name>/Oracle/Middleware</oracleHome> </configuration> </plugin>
To populate a local repository:
Open the command prompt and navigate to the following directory in your OEPE install: {install}/plugins/oracle.eclipse.tools.adf/maven/ADF Basic Application Archetype.
Run the following command if you HAVE NOT defined the parameters in your POM file:
mvn com.oracle.maven:oracle-maven-sync:push -Doracle-maven-sync.oracleHome=/path/to/oracleHome-Doracle-maven-sync.testingOnly=false
Run the following command if you HAVE defined the plug-in parameters in your POM file:
mvn com.oracle.maven:oracle-maven-sync:push
If you are populating a remote repository, specify serverId
and oracleHome
on the command line or in the plug-in configuration. You must also have a repository configuration in your settings.xml
that matches the server Id 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
In your settings.xml
file, you must define the target repository in a profile, and activate that profile using the activeProfiles tag as shown in the example below.
Specify an encrypted password in the server section. For details on how to encrypt the server passwords, see the Apache website at http://maven.apache.org/guides/mini/guide-encryption.html#How_to_encrypt_server_passwords
This example shows a Maven setting.xml file with authentication details.
<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> <password>welcome1</password> </server> ... <activeProfiles> <activeProfile>default</activeProfile> </activeProfiles>
To specify the parameters in your POM, add a plug-in entry similar to this example.
<plugin> <groupId>com.oracle.maven</groupId> <artifactId>oracle-maven-sync</artifactId> <version>12.1.3</version> <configuration> <serverId>internal</serverId> <oracleHome>/path/to/oracleHome</oracleHome> <testOnly>false</testOnly> </configuration> </plugin>
To populate a remote repository:
Open the command prompt and navigate to the following directory in your Maven install: {install}/plugins/oracle.eclipse.tools.adf/maven/ADF Basic Application Archetype.
Run the following command:
mvn com.oracle.maven:oracle-maven-sync:push
When you run the push goal, the following actions are completed:
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 POM 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 POM file is available in the Oracle home.
Calculates a SHA1 checksum for the JAR file.
Attempts to publish the JAR, POM, 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 includes 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
To populate your repository with the Maven archetypes, run the clean install, and archetype update local catalog commands, as shown in Figure 6-2 and Figure 6-3.
Install the Maven archetypes from the command line.
To install the Maven archetypes:
Open a command prompt and navigate to the archetype directory of your plugins install: {OEPE install}/plugins/oracle.eclipse.tools.adf/maven/ADF Basic Application Archetype
Run the following command:
mvn clean install
Run a second command:
mvn archetype:update-local-catalog
You can create an ADF application with Maven integration in the following ways:
From a command-line using the OEPE provided ADF Application Archetype
From OEPE using the New Maven Project and using the ADF application Archetype
From OEPE using the New ADF Application Wizard
You can create an ADF application using the command line.
To create an ADF application from the command line:
Open a command prompt and navigate to your project location.
Run the following command:
mvn archetype:generate -DarchetypeGroupId=com.oracle.adf.archetype -DarchetypeArtifactId=adf-basic-application -DarchetypeVersion=12.1.3-0-0
Enter the appropriate required values for groupId
, artifactId
, version
, and package
, as shown in Figure 6-4.
Change directory to newly-created top-level Maven project folder.
Execute the following command:
mvn clean install
You can create a Maven application using the Maven Project wizard.
To create a Maven application from the application wizard:
In your OEPE Eclipse application go to File > New > Project. In the New Project dialog expand the Maven directory and select Maven Project and click Next.
In the New Maven Project dialog, select your project name and location, as shown in Figure 6-5.
Click Next. The Select an Archetype dialog appears. Select the ADF archetype called com.oracle.adf.archetypes
, as shown in Figure 6-6. Type "adf" as a filter to filter out the many other options.
Select the ADF archetype and click Next.
Enter your values in the dialog fields, as shown in Figure 6-7.
Click Finish. The new Maven application appears in your Project Explorer window.
OEPE provides the option to add Maven capabilities to projects in your new ADF application.
To add Maven integration to new ADF application projects:
Go to File > New > ADF Application. You are creating an ADF application in which you will add Maven capabilities to the application projects.
Add the information required for you new ADF application on the first two wizard pages.
The third wizard page is the Maven Integration Page, as shown in Figure 6-8.
Check the Add Maven (m2e) capabilities to projects box. This adds Maven capabilities.
Click Finish.
In OEPE you can import your existing Maven projects into your working application. ADF applications can be imported as well as any J2EE Maven application built outside the OEPE framework.
To import an existing Maven project:
In your Java EE application choose File > Import > Maven > Existing maven projects.
Click Next. the Select Maven Projects dialog appears. Enter the root directory for the Maven project you are importing, and select your project, as shown in Figure 6-9.
Click Next. The connectors dialog appears. Setup your Maven plugin connectors, as shown in Figure 6-10.
Click Finish.
Use the Maven plug-in to deploy, redeploy applications built using Maven to WebLogic Server from within the Maven environment.
Use the command line to deploy using Maven to a running WebLogic server instance.
To Use the Command Line to Deploy using Maven to a Running WebLogic Server:
Open a command prompt and navigate to …/{artifactId}/App
, where {artifactId
} is the name specified during archetype creation.
Run the following command:
mvn com.oracle.weblogic:weblogic-maven-plugin:redeploy -Dwls.adminurl=t3://localhost:7001 -Dwls.user=weblogic -Dwls.password=welcome1