Chapter 6. Maven Repositories

6.1. About Maven

Apache Maven is a distributed build automation tool used in Java application development to build and manage software projects. Maven uses configuration XML files called POM (Project Object Model) to define project properties and manage the build process. POM files describe the project’s module and component dependencies, build order, and targets for the resulting project packaging and output. This ensures that projects are built in a correct and uniform manner.

Maven uses repositories to store Java libraries, plug-ins, and other build artifacts. Repositories can be either local or remote. A local repository is a download of artifacts from a remote repository cached on a local machine. A remote repository is any other repository accessed using common protocols, such as http:// when located on an HTTP server, or file:// when located on a file server. The default repository is the public remote Maven 2 Central Repository.

Configuration of Maven is performed by modifying the settings.xml file. You can either configure global Maven settings in the M2_HOME/conf/settings.xml file, or user-level settings in the USER_HOME/.m2/settings.xml file.

For more information about Maven, see the Welcome to Apache Maven page.

For more information about Maven repositories, see the Apache Maven Project — Introduction to Repositories article.

For more information about Maven POM files, see Apache Maven Project — POM Reference.

Note

Your Red Hat JBoss product has been built with Maven 3.0.x. Therefore, this is the recommended Maven version for building your own SwitchYard applications.

6.2. About Provided Maven Repositories

A set of repositories containing artifacts required to build applications based on Red Hat JBoss BPM Suite is provided with this release. Maven must be configured to use these repositories and the Maven Central Repository in order to provide correct build functionality.

Two interchangeable sets of repositories ensuring the same functionality are provided. The first set is available for download and storage in a local file system, the second set is hosted online for use as remote repositories.

Important

The set of online remote repositories is a technology preview source of components. As such, it is not in scope of patching and is supported only for use in development environment. Using the set of online repositories in production environment is a potential source of security vulnerabilities and is therefore not a supported use case. For more information, see the JBoss Enterprise Maven Repository.

6.3. Configuring Maven to Use File System Repositories

Overview

In situations where you cannot use the online repositories, you will have to download and configure the required repositories locally.

  1. Download the following ZIP archives containing the required repositories:

  2. Unzip the downloaded ZIP files into an arbitrary location in a local file system.

  3. Add entries for the unzipped repositories to Maven’s ~/.m2/settings.xml file. The following code sample contains a profile with the repositories, configuration of authentication for access to the repositories, and an activation entry for the profile: 

    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <localRepository/>
  <profiles>
  <!-- Profile with local repositories required by
       Red Hat JBoss BRMS/Red Hat JBoss BPM Suite -->
    <profile>
      <id>brms-bpms-local-profile</id>
      <repositories>
        <repository>
          <id>jboss-brms-bpmsuite-repository</id>
          <name>BRMS/BPMS 6.4.0 GA Repository</name>
          <url>
            <!-- path to the repository -->
            file:///jboss-brms-bpmsuite-6.4.0.GA-maven-repository/maven-repository
          </url>
          <layout>default</layout>
          <releases>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
          </releases>
          <snapshots>
            <enabled>false</enabled>
            <updatePolicy>never</updatePolicy>
          </snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>jboss-brms-bpmsuite-repository</id>
          <name>BRMS/BPMS 6.4.0.GA Repository</name>
          <url>
            <!-- path to the repository -->
            file:///jboss-brms-bpmsuite-6.4.0.GA-maven-repository/maven-repository
          </url>
          <layout>default</layout>
          <releases>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
          </releases>
          <snapshots>
            <enabled>false</enabled>
            <updatePolicy>never</updatePolicy>
          </snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>

  <servers>
    <!-- Configuring pre-emptive authentication for the repository server -->
    <server>
      <id>brms-bpms-m2-repo</id>
      <username>admin</username>
      <password>admin</password>
      <configuration>
        <wagonProvider>httpclient</wagonProvider>
        <httpConfiguration>
          <all>
            <usePreemptive>true</usePreemptive>
          </all>
        </httpConfiguration>
      </configuration>
    </server>

    <!-- Alternative to enabling pre-emptive authentication - configuring
         the Authorization HTTP header with Base64-encoded credentials
    <server>
      <id>brms-bpms-m2-repo</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <value>Basic YWRtaW46YWRtaW4=</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
    -->
  </servers>

  <activeProfiles>
    <!-- Activation of the Red Hat JBoss BRMS/Red Hat JBoss BPM Suite profile -->
    <activeProfile>brms-bpms-local-profile</activeProfile>
  </activeProfiles>
</settings>

Result

The Maven repositories are downloaded, unzipped in a local file system, registered in Maven’s ~/.m2/settings.xml file, and ready to be used when performing Maven builds.

Note

To use the Maven Central Repositories offline,perform a KJAR build in the Maven online environment, then copy the ~/.m2/repository folder to the offline environment.

6.3.1. Troubleshooting

6.3.1.1. Why do I still get errors when building or deploying my applications?

When you build or deploy a project, it fails with one or both of the following errors:

  • [ERROR] Failed to execute goal on project PROJECT_NAME
  • Could not find artifact ARTIFACT_NAME

Your cached local Maven repository might contain outdated artifacts.

To resolve the issue, delete the cached local repository — the ~/.m2/repository/ directory on Linux or the %SystemDrive%\Users\USERNAME\.m2\repository\ directory on Windows — and run mvn clean install -U. This will force Maven to download correct versions of required artifacts when performing the next build.

6.3.1.2. Why is Red Hat JBoss Developer Studio using my old Maven configuration?

You have updated your Maven configuration, but this configuration is not reflected in Red Hat JBoss Developer Studio.

If Red Hat JBoss Developer Studio is running when you modify your Maven settings.xml file, this configuration will not be reflected in Red Hat JBoss Developer Studio.

Refresh the Maven settings in the IDE. From the menu, choose Window → Preferences. In the Preferences window, expand Maven and choose User Settings. Click the Update Settings button to refresh the Maven user settings in Red Hat JBoss Developer Studio.

Updating Maven Settings

6.4. Configuring Maven to Use Online Repositories

The online repositories required for Red Hat JBoss BPM Suite applications are located at https://maven.repository.redhat.com/ga/.

It is possible to configure Maven to use online repositories using the project’s POM file, but this is not recommended.

Procedure: Configuring Maven to Use Online Repositories

  1. Add entries for the online repositories and configuration of authentication for accessing them to Maven’s settings.xml file as in the code sample below: 

    <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                              http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <profiles>
    <!-- Profile with online repositories required by BRMS/BPMS -->
    <profile>
      <id>brms-bpms-online-profile</id>
      <repositories>
        <repository>
          <id>jboss-ga-repository</id>
          <url>https://maven.repository.redhat.com/ga/</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>jboss-ga-plugin-repository</id>
          <url>https://maven.repository.redhat.com/ga/</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>

  <servers>
    <!-- Configuring pre-emptive authentication for the repository server -->
    <server>
      <id>brms-bpms-m2-repo</id>
      <username>admin</username>
      <password>admin</password>
      <configuration>
        <wagonProvider>httpclient</wagonProvider>
        <httpConfiguration>
          <all>
            <usePreemptive>true</usePreemptive>
          </all>
        </httpConfiguration>
      </configuration>
    </server>

    <!-- Alternative to enabling pre-emptive authentication - configuring
         the Authorization HTTP header with Base64-encoded credentials
    <server>
      <id>brms-bpms-m2-repo</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <value>Basic YWRtaW46YWRtaW4=</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
    -->
  </servers>

  <activeProfiles>
    <!-- Activation of the BRMS/BPMS profile -->
    <activeProfile>brms-bpms-online-profile</activeProfile>
  </activeProfiles>

</settings>

  2. If you modified the settings.xml file while Red Hat JBoss Developer Studio was running, you must refresh Maven settings in the IDE. From the menu, choose Window → Preferences. In the Preferences window, expand Maven and choose User Settings. Click the Update Settings button to refresh the Maven user settings in Red Hat JBoss Developer Studio.

    Figure 6.1. Update Maven User Settings

    128

Result

Maven has been configured to use the online repositories provided for your Red Hat JBoss product.

Important

If your cached local Maven repository contains outdated artifacts, you may encounter one of the following Maven errors when you build or deploy your project:

  • Missing artifact ARTIFACT_NAME
  • [ERROR] Failed to execute goal on project PROJECT_NAME; Could not resolve dependencies for PROJECT_NAME

To resolve the issue, delete the cached local repository — the ~/.m2/repository/ directory on Linux or the %SystemDrive%\Users\USERNAME\.m2\repository\ directory on Windows — and run mvn clean install -U. This will force Maven to download correct versions of required artifacts when performing the next build.

6.5. Dependency Management

In order to use the correct Maven dependencies in your Red Hat JBoss BPM Suite project, you must add relevant Bill Of Materials (BOM) files to the project’s pom.xml file. Adding the BOM files ensures that the correct versions of transitive dependencies from the provided Maven repositories are included in the project.

To use the Red Hat JBoss BPM Suite Maven artifacts, you need to configure one of the following:

The Maven Central online repository, which is also required, is configured by default in Maven. It has to be reachable for your project to function properly, even if you selected the local Maven repository.

Depending on your project requirements, declare one of the following the dependencies in your POM file in the dependencies section. For further information about the versions, see Section 1.3, “Supported Component Versions”.

  • org.jboss.bom.brms:jboss-brms-bpmsuite-platform-bom:$VERSION
  • org.jboss.bom.brms:jboss-brms-bpmsuite-bom:$VERSION