Red Hat Training

A Red Hat training course is available for Red Hat JBoss Developer Studio

Chapter 2. Configuring Maven Basics

In the context of application development, Maven provides a standardized build system for projects. One of the main benefits of using Maven with your project is that it facilitates fetching dependencies from one or more repositories. This article serves as an introduction to using Maven with the IDE.

Root Maven projects can serve as aggregators for multiple Maven modules, also known as sub-projects. For each module that is part of a maven project, a <module> entry is added to the project’s pom.xml file. A pom.xml that contains <module> entries is often referred to as an aggregator pom.

When modules are included into a project it is possible to execute Maven goals across all of the modules by a single command issued from the parent project directory.

Note

The provided instructions pertain to the creation of a parent+module project structure. If you prefer to create a simple project, simply start with an archetype or don’t use the pom packaging in step 2.i of the Section 2.1, “Creating a New Maven Project” section.

2.1. Creating a New Maven Project

Use the following instructions to create the parent project of a multi-module Maven project. The instructions provided ensure that the packaging option is set to pom, which is a requirement for multi-module Maven projects. Alternately, to create a standalone Maven project instead, set the packaging option to an option other than pom.

To create a new Maven project:

  1. In the workspace, click File > New > Other.
  2. In the Filter field, type maven and then click Maven Project from the search results.
  3. Click Next to continue.

  4. Enter the initial project details:

    1. Click the Create a simple project (skip archetype selection) check box. If this check box is selected, the Select an Archetype step of the wizard is skipped and the project type is set to pom, which is required to create a Maven Module based on this Maven project. Alternately, to create a standalone project, clear the Create a simple project (skip archetype selection) check box and follow the instructions in the wizard.
    2. Ensure that the Use default Workspace location check box is clear and specify a non-default location for your workspace files using the Browse button. Using a non-default workspace location is recommended because this allows other tools to access the workspace location easily.
    3. Optional, click the Add project(s) to working set check box to add the newly created projects to a working set.

    4. Optional, click Advanced to view additional optional advanced configuration for the new Maven project, such as:

      1. Resolve Workspace projects: Dependencies opened as workspace projects will be resolved without having to install them to your local Maven repository first. This way, any changes made to one of these dependencies will have an immediate effect on other projects consuming it (compilation, refactoring, etc.). When Resolve Workspace projects is disabled, dependencies existing in the workspace must be installed to your local Maven repository after any change (by running mvn install), in order to see effects in projects consuming them.
      2. Profiles: Select a set of Maven profiles to activate or deactivate in the workspace. Profiles are defined in the project pom.xml, or inherited from a parent pom.xml, or defined in the relevant settings.xml.

      3. Name templates: Allows you to disambiguate project names in the workspace by prepending or appending the group ID or SCM branch names to the default artifact ID.

        Figure 2.1. Create a New Maven Project

        Create a New Maven Project
    5. When the configuration is complete, click Next to continue.

  5. To configure the project details:

    1. In the Group Id field, enter the desired group ID, which is similar to an organization namespace (for example, com.company.businessunit.project).
    2. In the Artifact Id field, enter the desired artifact ID value, which is the name for your project. This value must not include any spaces and the only special characters allowed are periods ('.'), underscores ('_'), and dashes ('-').
    3. In the Version list, click 0.0.1-SNAPSHOT or a similar value. For details about the appropriate version build numbers, see Project Versions
    4. In the Packaging list, click pom.
    5. Optionally, in the Name field, add a name for your project.

    6. Optionally, in the Description field, add a description for your project.

      Figure 2.2. Configure Project Details

      Configure Project Details
    7. Click Finish to conclude the new Maven project creation. Your new Maven project is created and appears in the Project Explorer view.

2.2. Creating a New Maven Module

Each Maven project with a packaging pom can include multiple Maven modules. Follow the instructions here to create your first Maven module.

Prerequisites

To create a new Maven module:

  1. In the Project Explorer view, right-click the recently created pom project and click New > Project.
  2. In the New Project wizard, expand Maven and click Maven Module.
  3. Click Next to continue.

  4. To enter the initial module details:

    1. Ensure that the Create a simple project (skip archetype selection) check box is clear. If this check box is clicked, the Select an Archetype step of the wizard is skipped.
    2. In the Module Name field, enter the desired module name. This value corresponds to the Maven project’s Project ID.
    3. Use the Browse button to locate the desired parent project and select it.
    4. Optionally, clikc the Add project(s) to working set check box to add the newly created projects to a working set.

    5. Optionally, click Advanced to view additional optional advanced configuration for the new Maven project, such as:

      1. Resolve Workspace projects: Dependencies opened as workspace projects will be resolved without having to install them to your local Maven repository first. This way, any changes made to one of these dependencies will have an immediate effect on other projects consuming it (compilation, refactoring, etc.). When Resolve Workspace projects is disabled, dependencies existing in the workspace must be installed to your local Maven repository after any change (by running mvn install), in order to see effects in projects consuming them.
      2. Profiles: Select a set of Maven profiles to activate or deactivate in the workspace. Profiles are defined in the project pom.xml, or inherited from a parent pom.xml, or defined in the relevant settings.xml.

      3. Name templates: Allows you to disambiguate projects names in the workspace by prepending or appending the group ID or SCM branch names to the default artifact ID.

        Figure 2.3. Set the Module Name and Parent

        Set the Module Name and Parent
    6. When the configuration is complete, click Next to continue.

  5. To enter the module archetype information:

    1. Ensure that the Show the last version of Archetype only check box is clicked. This ensures that only the latest version of each archetype displays.

    2. Select an archetype based on the purpose of the project you are creating. Use the keyword maven-archetype-quickstart in the Filter field to locate a sample Maven project archetype.

      Figure 2.4. Select a Module Archetype

      Select a Module Archetype
    3. Click Next to continue.

  6. To enter the module details:

    1. In the Group Id field, add the same group ID value that was used for the Maven project.
    2. In the Version field, add the desired version number. For details about the appropriate version build numbers, see Project Versions

    3. The Artefact Id and Package fields are automatically populated based on the parent project details. Click Finish to conclude setting up the Maven module.

      Figure 2.5. Configure the Module Archetype Parameters

      Configure the Module Archetype Parameters

  7. Optionally, to change the settings for the created Maven module, expand the module name in the Project Explorer view and double click pom.xml from the expanded list. An Overview tab appears for you to chnage the settings if you wish to.

    Figure 2.6. Change the Module Settings from the Overview View

    Change the Module Settings from the Overview View

    Your new Maven module is created and appears in the Project Explorer view. Additionally, a hierarchical view of the nested projects is now available in the Project Explorer view as well (see Nested/Hierarchical view of projects).

2.3. Adding Maven Support to an Existing Non-Maven Project

For an existing application that was not created with Maven support, use the following instructions to add Maven support to the non-Maven project:

  1. In the Project Explorer view, right-click the project name and click Configure > Convert to Maven Project.

  2. To configure details for the new pom file:

    1. The basic fields for the new pom file are prepopulated based on the project details. If required, edit the existing values:
    2. Optionally, in the Name field, add a name for the new project.

    3. Optionally, in the Description field, add a brief description for the project.

      Figure 2.7. Create a New Pom Descriptor

      Create a New Pom Descriptor
    4. Click Finish to finalize the pom information.
  3. If the project references java dependencies, a wizard appears displaying all these dependencies and a green check mark when each dependency is identified. Learn more about dependency identification in the Troubleshooting section.

  4. Check the Delete original references from project check box to avoid retaining duplicate or stale dependencies in your project.

    Figure 2.8. Identify Maven Dependencies

    Identify Maven Dependencies
  5. Click Finish when all dependencies are converted. The existing project is now configured for Maven support.

2.4. Troubleshooting

2.4.1. Unidentifiable Dependency

Figure 2.9. Unidentifiable Dependency

Unidentifiable Dependency

Issue:

Either:

  1. The jar file is corrupted/invalid.
  2. The jar file is valid but does not contain any metadata used for identification.

Resolution:

  1. Ensure that jar exists as a Maven artifact. If needed, you can install it to your local repository and then click Identify dependencies.
  2. Double-click the dependency, or click Edit and set the expected maven coordinates.

2.4.2. Some selected dependencies can not be resolved. Click here to configure repositories in your settings.xml.

Figure 2.10. Dependencies Can Not Be Resolved Error

Dependencies Can Not Be Resolved Error

Issue: This error displays when a dependency can be identified (that is, whether it contains the pom properties or other metadata) but the dependency is not available in any repository defined in your settings.xml file.

Resolution: Click the here link in the error message and compare the old and new settings for the dependency and add a new and correct repository. Users may choose to use one of the predefined repositories from Red Hat.

Additional Resources

  • The wizard used to convert a non-Maven project to a Maven project attempts to identify all the project’s classpath entries and their equivalent Maven dependencies. From the list of identified dependencies, users can select which ones will be added to the generated Maven pom.xml file. When identifying dependencies, one of several strategies may be used:

    • Checking if the jar contains the relevant maven metadata.
    • Identify the dependency using the Nexus indexer.
    • Identify the dependency using the JBoss Nexus instance REST API (if we are online) via a SHA1 search.
    • Identify the dependency using the search.maven.org REST API (if we are online) via a SHA1 search.
  • All unchecked dependencies will be ignored and are not added to the generated pom.xml. However, some of these can be added as transitive dependencies to your project. For instance, if you add jsp-api but remove servlet-api, the latter appears in the project classpath, as it is a dependency of jsp-api.
  • You can double-click on a dependency from a list (or click the Edit button) to edit its Maven coordinates or scope. Selecting several dependencies (ctrl+click) and clicking the Edit button allows batch editing of their scope.