Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

2.3. Use the Maven Repository

2.3.1. Configure the JBoss EAP Maven 6 Repository

Overview

There are two approaches to direct Maven to use the JBoss EAP 6 Maven Repository in your project:

  • You can configure the repositories in the Maven global or user settings.
  • You can configure the repositories in the project's POM file.

Procedure 2.5. Configure Maven Settings to Use the JBoss EAP 6 Maven Repository

  1. Configure the Maven repository using Maven settings

    This is the recommended approach. Maven settings used with a repository manager or repository on a shared server provide better control and manageability of projects. Settings also provide the ability to use an alternative mirror to redirect all lookup requests for a specific repository to your repository manager without changing the project files. For more information about mirrors, see http://maven.apache.org/guides/mini/guide-mirror-settings.html.
    This method of configuration applies across all Maven projects, as long as the project POM file does not contain repository configuration.
    Section 2.3.2, “Configure the JBoss EAP 6 Maven Repository Using the Maven Settings”.

  2. Configure the Maven repository using the project POM

    This method of configuration is generally not recommended. If you decide to configure repositories in your project POM file, plan carefully and be aware that it can slow down your build and you may even end up with artifacts that are not from the expected repository.

    Note

    In an Enterprise environment, where a repository manager is usually used, Maven should query all artifacts for all projects using this manager. Because Maven uses all declared repositories to find missing artifacts, if it can't find what it's looking for, it will try and look for it in the repository central (defined in the built-in parent POM). To override this central location, you can add a definition with central so that the default repository central is now your repository manager as well. This works well for established projects, but for clean or 'new' projects it causes a problem as it creates a cyclic dependency.
    Transitively included POMs are also an issue with this type of configuration. Maven has to query these external repositories for missing artifacts. This not only slows down your build, it also causes you to lose control over where your artifacts are coming from and likely to cause broken builds.
    This method of configuration overrides the global and user Maven settings for the configured project.
    Section 2.3.4, “Configure the JBoss EAP 6 Maven Repository Using the Project POM”.
Report a bug

2.3.2. Configure the JBoss EAP 6 Maven Repository Using the Maven Settings

There are two approaches to direct Maven to use the JBoss EAP 6 Maven Repository in your project:
  • You can modify the Maven settings. This directs Maven to use the configuration across all projects.
  • You can configure the project's POM file. This limits the configuration to the specific project.
This topic shows you how to direct Maven to use the JBoss EAP 6 Maven Repository across all projects using the Maven settings. This is the recommended approach.
You can configure Maven to use either the online or a locally installed JBoss EAP 6 repository. If you choose to use the online repository, you can use a preconfigured settings file or add the JBoss EAP 6 Maven profiles to the existing settings file. To use a local repository, you must download the repository and configure the settings to point to your locally installed repository. The following procedures describe how to configure Maven for JBoss EAP 6.

Note

The URL of the repository will depend on where the repository is located; on the filesystem, or web server. For information on how to install the repository, see Section 2.2.2, “Install the JBoss EAP 6 Maven Repository”. The following are examples for each of the installation options:
File System
file:///path/to/repo/jboss-eap-6.x-maven-repository
Apache Web Server
http://intranet.acme.com/jboss-eap-6.x-maven-repository/
Nexus Repository Manager
https://intranet.acme.com/nexus/content/repositories/jboss-eap-6.x-maven-repository
You can configure Maven using either the Maven install global settings or the user install settings. These instructions configure the user install settings as this is the most common configuration.

Procedure 2.6. Configure Maven Using the Settings Shipped with the Quickstart Examples

The JBoss EAP 6 Quickstarts ship with a settings.xml file that is configured to use the online JBoss EAP 6 Maven repository. This is the simplest approach.
  1. This procedure overwrites the existing Maven settings file, so you must back up the existing Maven settings.xml file.
    1. Locate the Maven install directory for your operating system. It is usually installed in USER_HOME/.m2/ directory.
      • For Linux or Mac, this is: ~/.m2/
      • For Windows, this is: \Documents and Settings\USER_NAME\.m2\ or \Users\USER_NAME\.m2\
    2. If you have an existing USER_HOME/.m2/settings.xml file, rename it or make a backup copy so you can restore it later.
  2. Download and unzip the quickstart examples that ship with JBoss EAP 6. For more information, see Section 1.4.1.1, “Access the Quickstarts”
  3. Copy the QUICKSTART_HOME/settings.xml file to the USER_HOME/.m2/ directory.
  4. If you modify the settings.xml file while Red Hat JBoss Developer Studio is running, follow the procedure below entitled Procedure 2.9, “Refresh the Red Hat JBoss Developer Studio User Settings”.

Procedure 2.7. Manually Edit and Configure the Maven Settings To Use the Online JBoss EAP 6 Maven Repository

You can manually add the JBoss EAP 6 profiles to an existing Maven settings file.
  1. Locate the Maven install directory for your operating system. It is usually installed in USER_HOME/.m2/ directory.
    • For Linux or Mac, this is ~/.m2/
    • For Windows, this is \Documents and Settings\USER_NAME\.m2\ or \Users\USER_NAME\.m2\
  2. If you do not find a settings.xml file, copy the settings.xml file from the USER_HOME/.m2/conf/ directory into the USER_HOME/.m2/ directory.
  3. Copy the following XML into the <profiles> element of the file. 
    <!-- Configure the JBoss GA Maven repository -->
<profile>
  <id>jboss-ga-repository</id>
  <repositories>
    <repository>
      <id>jboss-ga-repository</id>
      <url>http://maven.repository.redhat.com/techpreview/all</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
  </repositories>
  <pluginRepositories>
    <pluginRepository>
      <id>jboss-ga-plugin-repository</id>
      <url>http://maven.repository.redhat.com/techpreview/all</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </pluginRepository>
  </pluginRepositories>
</profile>
<!-- Configure the JBoss Early Access Maven repository -->
<profile>
  <id>jboss-earlyaccess-repository</id>
  <repositories>
    <repository>
      <id>jboss-earlyaccess-repository</id>
      <url>http://maven.repository.redhat.com/earlyaccess/all/</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
  </repositories>
  <pluginRepositories>
    <pluginRepository>
      <id>jboss-earlyaccess-plugin-repository</id>
      <url>http://maven.repository.redhat.com/earlyaccess/all/</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </pluginRepository>
  </pluginRepositories>
</profile>
    Copy the following XML into the <activeProfiles> element of the settings.xml file. 
    <activeProfile>jboss-ga-repository</activeProfile>
<activeProfile>jboss-earlyaccess-repository</activeProfile>
  4. If you modify the settings.xml file while Red Hat JBoss Developer Studio is running, follow the procedure below entitled Procedure 2.9, “Refresh the Red Hat JBoss Developer Studio User Settings”.

Procedure 2.8. Configure the Settings to Use a Locally Installed JBoss EAP Repository

You can modify the settings to use the JBoss EAP 6 repository installed on the local file system.
  1. Locate the Maven install directory for your operating system. It is usually installed in USER_HOME/.m2/ directory.
    • For Linux or Mac, this is ~/.m2/
    • For Windows, this is \Documents and Settings\USER_NAME\.m2\ or \Users\USER_NAME\.m2\
  2. If you do not find a settings.xml file, copy the settings.xml file from the USER_HOME/.m2/conf/ directory into the USER_HOME/.m2/ directory.
  3. Copy the following XML into the <profiles> element of the settings.xml file. Be sure to change the <url> to the actual repository location. 
    <profile>
  <id>jboss-eap-repository</id>
  <repositories>
    <repository>
      <id>jboss-eap-repository</id>
      <name>JBoss EAP Maven Repository</name>
      <url>file:///path/to/repo/jboss-eap-6.x-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-eap-repository-group</id>
      <name>JBoss EAP Maven Repository</name>
      <url>
      file:///path/to/repo/jboss-eap-6.x-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>
    Copy the following XML into the <activeProfiles> element of the settings.xml file. 
    <activeProfile>jboss-eap-repository</activeProfile>
  4. If you modify the settings.xml file while Red Hat JBoss Developer Studio is running, follow the procedure below entitled Procedure 2.9, “Refresh the Red Hat JBoss Developer Studio User Settings”.

Procedure 2.9. Refresh the Red Hat JBoss Developer Studio User Settings

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

    Figure 2.1. Update Maven User Settings

Important

If your Maven repository contains outdated artifacts, you may encounter one of the following Maven error messages 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 version of your local repository to force a download of the latest Maven artifacts. The cached repository is located in your ~/.m2/repository/ subdirectory on Linux, or the %SystemDrive%\Users\USERNAME\.m2\repository\ subdirectory on Windows.
Report a bug

2.3.3. Configure Maven for Use with Red Hat JBoss Developer Studio

The artifacts and dependencies needed to build and deploy applications to Red Hat JBoss Enterprise Application Platform are hosted on a public repository. You must direct Maven to use this repository when you build your applications. This topic covers the steps to configure Maven if you plan to build and deploy applications using Red Hat JBoss Developer Studio.
Maven is distributed with Red Hat JBoss Developer Studio, so it is not necessary to install it separately. However, you must configure Maven for use by the Java EE Web Project wizard for deployments to JBoss EAP. The procedure below demonstrates how to configure Maven for use with JBoss EAP by editing the Maven configuration file from within Red Hat JBoss Developer Studio.

Procedure 2.10. Configure Maven in Red Hat JBoss Developer Studio

  1. Click Window→Preferences, expand JBoss Tools and select JBoss Maven Integration.
    Click Window→Preferences, expand JBoss Tools and select JBoss Maven Integration.

    Figure 2.2. JBoss Maven Integration Pane in the Preferences Window

  2. Click Configure Maven Repositories.
  3. Click Add Repository to configure the JBoss GA Tech Preview Maven repository. Complete the Add Maven Repository dialog as follows:
    1. Set the Profile ID, Repository ID, and Repository Name values to jboss-ga-repository.
    2. Set the Repository URL value to http://maven.repository.redhat.com/techpreview/all.
    3. Click the Active by default checkbox to enable the Maven repository.
    4. Click OK
    Enter Maven profile and repository values.

    Figure 2.3. Add Maven Repository - JBoss Tech Preview

  4. Click Add Repository to configure the JBoss Early Access Maven repository. Complete the Add Maven Repository dialog as follows:
    1. Set the Profile ID, Repository ID, and Repository Name values to jboss-earlyaccess-repository.
    2. Set the Repository URL value to http://maven.repository.redhat.com/earlyaccess/all/.
    3. Click the Active by default checkbox to enable the Maven repository.
    4. Click OK
    Enter Maven profile and repository values.

    Figure 2.4. Add Maven Repository - JBoss Early Access

  5. Review the repositories and click Finish.
    Review Maven profile and repository values.

    Figure 2.5. Review Maven Repositories

  6. You are prompted with the message "Are you sure you want to update the file 'MAVEN_HOME/settings.xml'?". Click Yes to update the settings. Click OK to close the dialog.
    The JBoss EAP Maven repository is now configured for use with Red Hat JBoss Developer Studio.
Report a bug

2.3.4. Configure the JBoss EAP 6 Maven Repository Using the Project POM

There are two approaches to direct Maven to use the JBoss EAP 6 Maven Repository in your project:
  • You can modify the Maven settings.
  • You can configure the project's POM file.
This task shows you how to configure a specific project to use the JBoss EAP 6 Maven Repository by adding repository information to the project pom.xml. This configuration method supercedes and overrides the global and user settings configurations.
This method of configuration is generally not recommended. If you decide to configure repositories in your project POM file, plan carefully and be aware that it can slow down your build and you may even end up with artifacts that are not from the expected repository.

Note

In an Enterprise environment, where a repository manager is usually used, Maven should query all artifacts for all projects using this manager. Because Maven uses all declared repositories to find missing artifacts, if it can't find what it's looking for, it will try and look for it in the repository central (defined in the built-in parent POM). To override this central location, you can add a definition with central so that the default repository central is now your repository manager as well. This works well for established projects, but for clean or 'new' projects it causes a problem as it creates a cyclic dependency.
Transitively included POMs are also an issue with this type of configuration. Maven has to query these external repositories for missing artifacts. This not only slows down your build, it also causes you to lose control over where your artifacts are coming from and likely to cause broken builds.

Note

The URL of the repository will depend on where the repository is located; on the filesystem, or web server. For information on how to install the repository, see: Section 2.2.2, “Install the JBoss EAP 6 Maven Repository”. The following are examples for each of the installation options:
File System
file:///path/to/repo/jboss-eap-6.x-maven-repository
Apache Web Server
http://intranet.acme.com/jboss-eap-6.x-maven-repository/
Nexus Repository Manager
https://intranet.acme.com/nexus/content/repositories/jboss-eap-6.x-maven-repository
  1. Open your project's pom.xml file in a text editor.
  2. Add the following repository configuration. If there is already a <repositories> configuration in the file, then add the <repository> element to it. Be sure to change the <url> to the actual repository location. 
    <repositories>
   <repository>
      <id>jboss-eap-repository-group</id>
      <name>JBoss EAP Maven Repository</name>
      <url>file:///path/to/repo/jboss-eap-6.x.0-maven-repository/</url>
      <layout>default</layout>
      <releases>
         <enabled>true</enabled>
         <updatePolicy>never</updatePolicy>
      </releases>
      <snapshots>
         <enabled>true</enabled>
         <updatePolicy>never</updatePolicy>
      </snapshots>
   </repository>
</repositories>
  3. Add the following plug-in repository configuration. If there is already a <pluginRepositories> configuration in the file, then add the <pluginRepository> element to it. 
    <pluginRepositories>
   <pluginRepository>
      <id>jboss-eap-repository-group</id>
      <name>JBoss EAP Maven Repository</name>
      <url>file:///path/to/repo/jboss-eap-6.x.0-maven-repository/</url>
      <releases>
         <enabled>true</enabled>
      </releases>
      <snapshots>
         <enabled>true</enabled>
      </snapshots>
   </pluginRepository>
</pluginRepositories>
Report a bug

2.3.5. Manage Project Dependencies

This topic describes the usage of Bill of Materials (BOM) POMs for Red Hat JBoss Enterprise Application Platform 6.
A BOM is a Maven pom.xml (POM) file that specifies the versions of all runtime dependencies for a given module. Version dependencies are listed in the dependency management section of the file.
A project uses a BOM by adding its groupId:artifactId:version (GAV) to the dependency management section of the project pom.xml file and specifying the <scope>import</scope> and <type>pom</type> element values.

Note

In many cases, dependencies in project POM files use the provided scope. This is because these classes are provided by the application server at runtime and it is not necessary to package them with the user application.

Supported Maven Artifacts

As part of the product build process, all runtime components of JBoss EAP are built from source in a controlled environment. This helps to ensure that the binary artifacts do not contain any malicious code, and that they can be supported for the life of the product. These artifacts can be easily identified by the -redhat version qualifier, for example 1.0.0-redhat-1.
Adding a supported artifact to the build configuration pom.xml file ensures that the build is using the correct binary artifact for local building and testing. Note that an artifact with a -redhat version is not necessarily part of the supported public API, and may change in future revisions. For information about the public supported API, see the JavaDoc documentation included in the release.
For example, to use the supported version of hibernate, add something similar to the following to your build configuration. 
<dependency>
  <groupId>org.hibernate</groupId>
  <artifactId>hibernate-core</artifactId>
  <version>4.2.16.Final-redhat-1</version>
  <scope>provided</scope>
</dependency>
Notice that the above example includes a value for the <version/> field. However, it is recommended to use Maven dependency management for configuring dependency versions.

Dependency Management

Maven includes a mechanism for managing the versions of direct and transitive dependencies throughout the build. For general information about using dependency management, see the Apache Maven Project Introduction to the Dependency Mechanism.
Using one or more supported JBoss dependencies directly in your build does not guarantee that all transitive dependencies of the build will be fully supported JBoss artifacts. It is common for Maven builds to use a mix of artifact sources from the Maven central repository, the JBoss.org Maven repository, and other Maven repositories.
Included with the JBoss EAP Maven repository is a dependency management BOM, which specifies all supported JBoss EAP binary artifacts. This BOM can be used in a build to ensure that Maven will prioritize supported JBoss EAP dependencies for all direct and transitive dependencies in the build. In other words, transitive dependencies will be managed to the correct supported dependency version where applicable. The version of this BOM matches the version of the JBoss EAP release. 
<dependencyManagement>
  <dependencies>
    ...
    <dependency>
      <groupId>org.jboss.bom</groupId>
      <artifactId>eap6-supported-artifacts</artifactId>
      <version>6.4.0.GA</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    ...
  </dependencies>
</dependencyManagement>

JBoss JavaEE Specs Bom

The jboss-javaee-6.0 BOM contains the Java EE Specification API JARs used by JBoss EAP.
To use this BOM in a project, add a dependency for the GAV that contains the version of the JSP and Servlet API JARs needed to build and deploy the application.
The following example uses the 3.0.2.Final-redhat-x version of the jboss-javaee-6.0 BOM. 
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.jboss.spec</groupId>
      <artifactId>jboss-javaee-6.0</artifactId>
      <version>3.0.2.Final-redhat-x</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    ...
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>org.jboss.spec.javax.servlet</groupId>
    <artifactId>jboss-servlet-api_3.0_spec</artifactId>
    <scope>provided</scope>
  </dependency>
  <dependency>
    <groupId>org.jboss.spec.javax.servlet.jsp</groupId>
    <artifactId>jboss-jsp-api_2.2_spec</artifactId>
    <scope>provided</scope>
  </dependency>
  ...
</dependencies>

JBoss EAP BOMs and Quickstarts

The JBoss BOMs are located in the jboss-bom project at https://github.com/jboss-developer/jboss-eap-boms.
The quickstarts provide the primary use case examples for the Maven repository. The following table lists the Maven BOMs used by the quickstarts.

Table 2.1. JBoss BOMs Used by the Quickstarts

Maven artifactId Description
jboss-javaee-6.0-with-hibernate This BOM builds on the Java EE full profile BOM, adding Hibernate Community projects including Hibernate ORM, Hibernate Search and Hibernate Validator. It also provides tool projects such as Hibernate JPA Model Gen and Hibernate Validator Annotation Processor.
jboss-javaee-6.0-with-hibernate3 This BOM builds on the Java EE full profile BOM, adding Hibernate Community projects including Hibernate 3 ORM, Hibernate Entity Manager (JPA 1.0) and Hibernate Validator.
jboss-javaee-6.0-with-logging This BOM builds on the Java EE full profile BOM, adding the JBoss Logging Tools and Log4j framework.
jboss-javaee-6.0-with-osgi This BOM builds on the Java EE full profile BOM, adding OSGI.
jboss-javaee-6.0-with-resteasy This BOM builds on the Java EE full profile BOM, adding RESTEasy
jboss-javaee-6.0-with-security This BOM builds on the Java EE full profile BOM, adding Picketlink.
jboss-javaee-6.0-with-tools This BOM builds on the Java EE full profile BOM, adding Arquillian to the mix. It also provides a version of JUnit and TestNG recommended for use with Arquillian.
jboss-javaee-6.0-with-transactions This BOM includes a world class transaction manager. Use the JBossTS APIs to access its full capabilities.
The following example uses the 6.4.0.GA version of the jboss-javaee-6.0-with-hibernate BOM. 
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.jboss.bom.eap</groupId>
      <artifactId>jboss-javaee-6.0-with-hibernate</artifactId>
      <version>6.4.0.GA</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    ...
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-core</artifactId>
    <scope>provided</scope>
  </dependency>
  ...
</dependencies>

JBoss Client BOMs

The JBoss EAP server build includes two client BOMs: jboss-as-ejb-client-bom and jboss-as-jms-client-bom.
The client BOMs do not create a dependency management section or define dependencies. Instead, they are an aggregate of other BOMs and are used to package the set of dependencies necessary for a remote client use case.
The following example uses the 7.4.0.Final-redhat-x version of the jboss-as-ejb-client-bom client BOM. 
<dependencies>
  <dependency>
    <groupId>org.jboss.as</groupId>
    <artifactId>jboss-as-ejb-client-bom</artifactId>
    <version>7.5.0.Final-redhat-x</version>
    <type>pom</type>
  </dependency>
  ...l
</dependencies>
This example uses the 7.4.0.Final-redhat-x version of the jboss-as-jms-client-bom client BOM. 
<dependencies>
  <dependency>
    <groupId>org.jboss.as</groupId>
    <artifactId>jboss-as-jms-client-bom</artifactId>
    <version>7.4.0.Final-redhat-x</version>
    <type>pom</type>
  </dependency>
  ...
</dependencies>
For more information about Maven Dependencies and BOM POM files, see Apache Maven Project - Introduction to the Dependency Mechanism.
Report a bug