Maven Concepts

External

• https://maven.apache.org/guides/introduction/introduction-to-repositories.html

Internal

• Maven

Maven Coordinates

groupId:artifactId:version is the minimum amount of information to fully and unequivocally identify an artifact, and constitute an address and a timestamp. This information is referred to as maven coordinates. More details about each component below.

Group ID

The group ID is an unique identifier (ideally, globally) for a project. It is specified as <groupId> at the top of the POM file or inside a <dependency><groupId> element when a dependency is declared.

Conventionally uses a dot notation, but it does not have to. When it does use the dot notation, the groupId does NOT have to correspond to the package structure of the project it designates; it is, though, a good practice to follow. When stored within a repository, the dots are replaced by OS specific directory separators, which becomes a relative directory structure from the base repository.

Group ID and Parent-Children Module Relationship

The group ID namespace and the parent-chidren module namespace are completely independent: the children modules can belong to totally different groups than their parents - the parent's groupId and the children's groupIds may not overlap at all, yet Maven enforces the coordinated parent/children build cycles and places the artifacts on completely un-related locations in the repository. For more details on module and module naming, see:

Module Names

Artifact ID

The artifact ID is generally the name that the project is known by. It is specified as <artifactId> at the top of the POM file or inside a <dependency><artifactId> element when a dependency is declared. The artifact ID, along with the group ID, create a key that ideally separates this project from every other project in the world.

Under particular circumstances, the artifact ID may contain version information. For example, if the project is an extension for JBoss DataGrid 7 (and only works with JBoss DataGrid version 7), it is fine to use the following artifact ID: "jboss-datgrid-7.0". The project will have its own versioning scheme, independent of "7.0", and a project artifact will be named similarly to "jboss-datagrid-7.0-1.0.0-SNAPSHOT-1.jar"

Artifact Name

The artifactId is used to generate the project's artifact name, according to the pattern artifactId-version.packaging.

The name of the artifact file generated in the target directory of the project can be overridden using the finalName element. However, the name of the artifact published to repository ignores finalName.

Version

The version represents a timestamp for a specific incarnation of the project's artifact, in the history of the project. The information is used within an artifact's repository to separate versions from each other. It is specified as <version> at the top of the POM file or inside a <dependency><version> element when a dependency is declared.

For more details on a project's module version management, see "Modules and Versions" section.

Stable Versions and Snapshots

Stable Version

A stable version is guaranteed not to change in the repository.

Snapshots

https://maven.apache.org/guides/getting-started/index.html#What_is_a_SNAPSHOT_version

A snapshot is a version of a Maven artifact that has not been officially released. Maven treats the "-SNAPSHOT" qualifier differently from a regular version literal. If a version number is followed by "-SNAPSHOT", that means "the latest not-yet-released version associated with the major.minor.increment to which "-SNAPSHOT" was appended. For example 1.0.0-SNAPSHOT refers to a version that may become 1.0.0 or that may be overwritten by one or more updates until it becomes 1.0.0, so using

<version>1.0.0-SNAPSHOT</version> 

in the definition of a dependency means that you should be prepared to deal with a different version of the artifact every time a build is run and in consequence, the latest version is pulled from the artifact server. A remote repository may accumulate several actual snapshot versions that correspond to a *-SNAPSHOT, and the resolution is done by Maven by pulling the remote maven-metadata.xml that corresponds to the snapshot and looking up the latest actual version of the file, which is written in that file. Once downloaded, maven-metadata.xml is written as maven-metadata-*.xml in the local repository, with the exact name depending on the name of the remote repository.

Handling snapshots is different from handling stable versions, in that Maven may connect to the remote repository in an attempt to pull the latest version of a SNAPSHOT, even if there's a version of that SNAPSHOT in the local repository. The actual behavior is given by the configuration of the corresponding repository:

<repository>
   <id>...</id>
   <snapshots>
       <enabled>true</enabled>
       <updatePolicy>always|daily|interval:<interval-in-mins>|never</updatePolicy>
   </snapshots>
</repository>

With a <updatePolicy> of "never", SNAPSHOT will be handled as a stable version, in that it will pulled only if it does not exist in the local repository, and then, once cached, it will never be updated, even if newer snapshots appear in the remote repository.

For more details on the <repository> element syntax, see:

Maven Repositories

Packaging

The packaging represents the project's artifact type. It is specified as <packaging> at the top of the POM file.

When no packaging is declared, Maven assumes the artifact is, by default, a "jar". The valid types are Plexus role-hints of the component role org.apache.maven.lifecycle.mapping.LifecycleMapping. The current core packaging values are: "pom" (for an example see multi-module projects), "jar", "maven-plugin", "ejb", "war", "ear", "rar" and "par". The packaging value defines the default list of goals to be bound to phases associated with that particular package structure.

Some packaging types are available only if a particular plugin was declared in <build> and the <extensions> was turned on to true for that plugin.

If you need to specify packaging in the Maven coordinates of a project, it is specified after artifact ID: groupId:artifactId:packaging:version.

Classifier

The classifier allows to distinguish artifacts that were built from the same POM but differ in their content. It is some optional and arbitrary string that - if present - is appended to the artifact name just after the version number.

A common use case for classifiers is the need to attach secondary artifacts to the project's main artifact (for example, javadocs or sources).

The default value for the classifier, when not specified, is null.

It is specified as <classifier> at the top of the POM file. If you need to specify the classifier in the Maven coordinates of a project, it is specified after packaging: groupId:artifactId:packaging:classifier:version.

Classifiers are also used by the assembly plugin.

Type

Represents the type of a dependency. While it usually represents the extension on the filename of the dependency, that is not always the case. A type can be mapped to a different extension and a classifier. The type often corresponds to the packaging used, though this is also not always the case. Some examples are:

• "pom"
• "jar"
• "maven-plugin"
• "ejb"
• "war"
• "ear"
• "rar"
• "java-source"
• "javadoc"
• "ejb-client"
• "test-jar".

For more details see:

http://maven.apache.org/ref/3.5.2/maven-core/artifact-handlers.html

New types can be defined by plugins that set "extensions" to "true", so this is not a complete list.

The type may be specified when declaring a dependency, as <dependency><type>. The minimal set of information for matching a dependency reference against a <dependencyManagement> section is {groupId, artifactId, type, classifier}. In many cases, these dependencies will refer to jar artifacts with no classifier, because the default value for type is "jar" and the default value for classifier is "null".

Also see

Download Sources with the Class JAR Files

Name

It is specified as <name> at the top of the POM file.

Parent

See Project Inheritance and POM <parent>.

Lifecycle

For details on the Maven lifecycles and phases, see:

Maven Lifecycle

Project Inheritance

Project inheritance is a Maven feature that allows specification of various project elements across a POM file hierarchy. The hierarchy is established using the <parent> element of the POM. In a POM hierarchy, the following elements are merged:

• dependencies
• developers and contributors
• plugin lists - see <pluginManagement>
• plugin executions with matching IDs
• plugin configuration
• resources

Project inheritance is useful when a set of related projects share the same set of dependency libraries. In that case, the set of dependencies is specified in the parent POM, and the project POMs inherit it. For those dependency libraries specified in the parent POM, we do not have to specify a version in the children POM, as it will be inherited from the parent. However, we need to specify the groupId and the artifactId, to "select" the dependency for use in the child project.

TODO Project Inheritance vs. Aggregation: https://maven.apache.org/guides/introduction/introduction-to-the-pom.html#Project_Inheritance_vs_Project_Aggregation

Project Aggregation

TODO: https://maven.apache.org/guides/introduction/introduction-to-the-pom.html#Project_Aggregation

POM

pom.xml

Profile

Maven Profile

Plugin

A Maven plugin are pieces of functionality that provide goals. A plugin has one or more goals, and each goal represents a capability of that plugin. Available Plugins:

Maven Plugin List

Plugins can be used independently from command line, or their goals can be executed as part of a project release sequence.

In order to insure that a plugin is used in a project release sequence, the plugin must be declared in the <plugins> container element. If POM inheritance is used, the plugins to be used by a hierarchy of projects can be declared in a <pluginManagement> element at the top of the hierarchy. For more details on how <plugins> compares with <pluginManagement>, see "<pluginManagement>" section in the POM reference.

Plugin Execution

Declaring the plugins in POM is a pre-requisite for execution as part of the project lifecycle. In order to be actually executed, their goals must be linked to a specific phase of the project. For some plugins and some phases, this association is done automatically.

If the association is needed to be declared explicitly, this is how it's done:

<plugin>
    ...
   <executions>
       <execution>
           <id>attach-sources</id>
           <phase>package</phase>
           <goals>
               <goal>jar</goal>
           </goals>
       </execution>
    </executions>
</plugin>

Command Line Execution

Plugins' goals can be executed from command line, as shown below. The plugin configuration parameters can be passed with -D<param-name>=<param-value> convention.

mvn dependency:build-classpath -Dsilent=true

Plugin Registry

$HOME/.m2/plugin-registry.xml contains the plugin versions.

Configured in settings.xml

Variables

Maven configuration files support variables, which are of five different types:

TODO: Project interpolation and variables: https://maven.apache.org/guides/introduction/introduction-to-the-pom.html#Project_Interpolation

Environment Variables

Maven and Environment Variables

Project Properties

A dot (.) notated path in the POM prefixed with project. will contain the corresponding POM element value. For example:

<project>
   <version>...</version>
</project>

is accessible as ${project.version}.

More details about project properties are available here:

Maven Standard System Properties

Settings Properties

A dot (.) notated path in the POM prefixed with settings. will contain the corresponding settings.xml value. For example:

<settings>
   <offline>...</offline>
</settings >

is accessible as ${settings.offline}.

Also see:

settings.xml

System Properties

These are the Java system properties. These are the properties accessible with java.lang.system.getProperties(), and can be used as pom.xml variables (example: ${java.home}).

Set in the <properties> Elements

Properties can also be declared and exposed to the build in the <properties> section of a pom.xml or of a <profile>:

pom.xml <properties>

<profile><properties>

TODO: Maven Standard System Properties

Dependencies

Maven Dependencies

BOM

Maven Dependencies - BOM

Repositories

Maven Repositories

Servers

A server is a configuration element allowing to specify sensitive information such as the username and the password for the URLs used by repositories or mirrors, in a location different than the publicly shared pom.xml. A server is identified by its "id" element and it is declared in settings.xml. The server's "id" matches the "id" element of the repository or mirror Maven tries to connect to.

Mirror

Configured in settings.xml

Proxy

Configured in settings.xml

Multi-Module Maven Projects

Multi-Module Maven Projects

Fileset

Maven FileSets

Resources

The concept of "resource" is used by the "resources" plugin. See Maven Resources Plugin - The "Resources" section.

Interactive Mode

Maven attempts to interact with the user for input in interactive mode. Configured in settings.xml.

Offline Mode

Configured in settings.xml.