Automating Application Builds With Maven

1 Automating Application Builds With Maven

Oracle Fusion Middleware (FMW) application developers typically use an Integrated Development Environment (IDE), such as Oracle JDeveloper, Eclipse IDE, or JetBrains IntelliJ IDEA during the development of their application. To ensure application quality, industry best practices suggest using a Continuous Integration (CI) system to automate building and testing application changes.

This typically requires the application builds to be automated so that the CI system can produce the application binaries. Apache Maven is one of the most popular build tools for Java-based applications. As such, most application-centric FMW products provide Maven plug-ins, archetypes, and Project Object Models (POMs) to support automating application builds with Maven.

Oracle FMW artifacts for this release are not published in public Maven repositories, such as the Oracle Maven Repository. You must populate your Maven repository with the Oracle FMW artifacts required prior to trying to build FMW applications with Maven.

Installing and Configuring Maven

To get started with Maven, download and install a Maven distribution from https://maven.apache.org. To use Maven, set the following environment variables to point to the JDK and Maven installation directories and add them to the PATH.

On Linux:

export JAVA_HOME=/usr/lib/jvm/jdk-17
export M2_HOME=/usr/lib/apache-maven
export PATH=${M2_HOME}/bin:${JAVA_HOME}/bin:${PATH}

On macOS:

export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home
export M2_HOME=/opt/apache-maven
export PATH=${M2_HOME}/bin:${JAVA_HOME}/bin:${PATH}

On Windows:

set "JAVA_HOME=c:\java\jdk-17"
set "M2_HOME=c:\apache-maven"
set "PATH=%M2_HOME%\bin;%JAVA_HOME%\bin;%PATH%"

Verify your environment is properly configured by running the following command to ensure that you are picking up the expected versions of both Maven and Java:

mvn -v
Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937)
Maven home: /scratch/maven/apache-maven-3.9.9
Java version: 17.0.9.0.3, vendor: Oracle Corporation, runtime: /scratch/java/jdk-17.0.9.0.3
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "5.4.17-2136.308.9.el8uek.x86_64", arch: "amd64", family: "unix"

Customizing Maven Settings

Maven uses a settings file to customize Maven to work properly in your environment. You will typically want to create a settings.xml file in the following situations:

You require the use of a proxy server to reach the Internet.
Your organization requires you to use their internal Maven Repository Manager.
You need to deploy artifacts into your organization's Maven Repository Manager.

If this is the first time you have used Maven, then typically you will not have a Maven settings file. 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, then see the Maven documentation.

Here is a sample settings file.

<settings
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"
  xmlns="http://maven.apache.org/SETTINGS/1.1.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <servers>
    <server>
      <id>artifactory</id>
      <username>fred</username>
      <password>gV4akMViBM4vVWxG4F9GTu</password>
    </server>
  </servers>

  <proxies>
    <proxy>
      <id>myproxy</id>
      <protocol>http</protocol>
      <host>myproxy.mycompany.com</host>
      <port>80</port>
      <nonProxyHosts>*.mycompany.com</nonProxyHosts>
      <active>true</active>
    </proxy>
  </proxies>

  <mirrors>
    <mirror>
      <id>repo1</id>
      <name>repo1</name>
      <url>https://artifactory.mycompany.com/artifactory/repo1</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
</settings>

This example shows three common configuration settings that you may need to use:

Proxies: 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 organization's Maven repository manager as a mirror (cache) of Maven's central repository.

The Maven settings file can be used for other situations beyond the scope of this document. While some configuration can be placed in either settings.xml or the project's pom.xml files, Oracle recommends that all project-specific settings be placed in pom.xml and leave settings.xml for cross-project configuration. For more information, see https://maven.apache.org/settings.html.

Parent topic: Automating Application Builds With Maven

Populating the Maven Repository

Whether using your organization's Maven Repository Manager or simply using the local Maven repository, which is located by default in $HOME/.m2/repository, you must populate it with the Oracle FMW artifacts prior to trying to build FMW applications with Maven.

Oracle provides the Oracle Maven Synchronization plug-in that allows you to populate the Maven repository from an Oracle Home. When you install a Fusion Middleware product, the Maven archetypes, plug-ins, and POMs are installed with the product so that the Oracle Maven Synchronization plug-in can find them.

This section contains the following topics:

Parent topic: Automating Application Builds With Maven

Introduction to the Maven Synchronization Plug-In

Oracle Fusion Middleware provides the Oracle 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 the same at the binary level, ensuring that all patched files reflect accurately in the Maven repository.

Oracle homes contain plugins/maven directories which contain Maven POMs for the 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

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 a shared internal repository in your organization's Maven Repository Manager, if you have one.

The plug-in is located in your Oracle WebLogic Server 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/14.1.2/oracle-maven-sync-14.1.2.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/14.1.2/oracle-maven-sync-14.1.2.jar

Install and deploy the plug-in.

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/14.1.2 directory:
```
mvn install:install-file -DpomFile=oracle-maven-sync-14.1.2.pom -Dfile=oracle-maven-sync-14.1.2.jar
```
To deploy the plug-in, use one of the following methods:
- The simplest way to 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 and POM files 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/14.1.2 directory:
```
mvn deploy:deploy-file -DpomFile=oracle-maven-sync-14.1.2.pom -Dfile=oraclemaven-sync-14.1.2.jar -Durl=http://servername/artifactory/repositories/internal -DrepositoryId=internal
```
  To use the deploy plug-in, 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, 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.

Parent topic: Populating the Maven Repository

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 1-1 describes the parameters.

Table 1-1 Push Goal Parameters and Description

Parameter	Description
`dryRun`	A parameter to control whether the plug-in attempts to publish the artifacts to the repository. If you set this to `true`, then the push goal finds all of your POM files and prints out details of what would have been done if this was set to `false`. However, it does not publish any artifacts or make any change to the system.
`failOnError`	If you set this property to `false` and the plug-in fails to process a resource, it continues to process all other resources. Failures are logged as warnings, but the process completes successfully. If you set this property to `true`, when it encounters the first problem, the plug-in immediately exits with an error. This is the default.
`oracleHome`	The path to the Oracle home from which you want to populate the Maven repository.
`overwriteParent`	If you set this property to `true`, the plug-in overwrites POM artifacts with ancestry to oracle-common if they exist in the target repository. The default value of false prevents automatic overwrite of customized POM contents. If any such POMs are encountered during plug-in execution, an error is thrown and handled according to the `failOnError` flag value. To carry over changes, save the existing POMs, run the push goal with `overwriteParent=true`, and manually transfer the changes to the newly pushed POMs.
`pushDuplicates`	If you set this property to `true`, then the plug-in pushes all duplicate locations. That is, if multiple POMs with different Maven coordinates (GAV) are assigned to the same location path, the plug-in pushes them all to the destination repository.
`retryFailedDeploymentCount`	Parameter used to control how many times a failed deployment will be retried before giving up and failing. If a value outside the range 0-10 is specified, then it will be pulled to the nearest value within the range 0-10. If set to 0, there will be no retries. If the artifact being deployed to the remote server has both a POM and a binary file, then the retry count will be reset between deploying the POM and deploying the binary file. This parameter is ignored when pushing to a local repository.
`serverId`	The ID of 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` file should provide the remote artifact repository's deployment information, such as URL, user name, and password.

Parent topic: Populating the Maven Repository

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. See your Maven Repository Manager documentation for how to change this setting.

Parent topic: Populating the Maven Repository

Populating Your Maven Repository

To populate your repository, you must use the push goal. You can specify the parameters given in Table 1-1 on the command line or in your POM file.

This section contains the following topics:

Parent topic: Populating the Maven Repository

About Running the Push Goal

When you run the push goal, it takes the following actions:

Checks the Oracle home that 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 an 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 include the following:
- Client API classes
- Compilation, packaging, and deployment utilities, for example 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

Parent topic: Populating Your Maven Repository

Populating a Local Repository

To populate a local repository, you must specify oracleHome on the command line. For example:

mvn com.oracle.maven:oracle-maven-sync:push -DoracleHome=path_to_oracleHome

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=alternate_path

To specify the parameters in your POM file, you must add a plug-in entry similar to the following:

<plugin>
    <groupId>com.oracle.maven</groupId>
    <artifactId>oracle-maven-sync</artifactId>
    <version>14.1.2-0-0</version>
    <configuration>
        <oracleHome>path_to_oracleHome</oracleHome>
    </configuration>
</plugin>

After adding the plug-in, run Maven with the following command:

mvn com.oracle.maven:oracle-maven-sync:push

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, then 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>
        <id>internal</id>
        <name>Team Internal Repository</name>
        <url>http://some.host/maven/repo/internal</url>
        <layout>default</layout>
        <releases>
          <enabled>true</enabled>
          <updatePolicy>always</updatePolicy>
          <checksumPolicy>warn</checksumPolicy>
        </releases>
        <snapshots>
          <enabled>true</enabled>
          <updatePolicy>never</updatePolicy>
          <checksumPolicy>fail</checksumPolicy>
        </snapshots>
      </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: https://maven.apache.org/guides/mini/guide-encryption.html#How_to_encrypt_server_passwords.

To specify the parameters in your POM file, you must add a plug-in entry similar to the following:

<plugin>
  <groupId>com.oracle.maven</groupId>
  <artifactId>oracle-maven-sync</artifactId>
  <version>14.1.2-0-0</version>
  <configuration>
    <serverId>internal</serverId>
    <oracleHome>path_to_oracleHome</oracleHome>
  </configuration>
</plugin>

After adding the plug-in, run Maven with 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, then you need to specify the extra parameter -DoverwriteParent=true on the push goal.

Parent topic: Populating the Maven Repository

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 the 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.

Parent topic: Populating the Maven Repository

Oracle Approach to Patching

If any problems are found after a release of Oracle Fusion Middleware (for example, 14.1.1) into production, a one-off patch is created to fix that problem. Between any two releases, for example 14.1.1 and 14.1.2, 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 arise 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 match 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 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, run a command similar to the following:

mvn archetype:crawl -Dcatalog=$HOME/.m2/archetype-catalog.xml

Parent topic: Populating the Maven Repository