Maven2 Repository Layout

Maven2 repository layout format is the default layout used since Maven 2 (see Repository Layout- Final in Maven 2.0 Design Documents), superceding old Maven 1 layout:

Repository root
`-- ${groupId as directory}/
    |-- maven-metadata.xml
    |--                   .${checksums}
    `-- ${artifactId}/
        |-- maven-metadata.xml
        |--                   .${checksums}
        `-- ${version}/
            |-- ${artifactId}-${version}.pom
            |--                             .asc
            |--                             .${checksums}
            |-- ${artifactId}-${version}.${extension}
            |--                                     .asc
            |--                                     .${checksums}
            |-- ${artifactId}-${version}-${classifier}.${extension}
            |--                                                    .asc
            `--                                                    .${checksums}

where:

  • ${groupId as directory} is the groupId with . replaced by /, for example org/apache/maven,
  • ${artifactId} is the artifactId,
  • ${version} is the version, with some additional possibilities on a SNAPSHOT, see SNAPSHOT paragraph,
  • ${extension} is the file extension, for example zip or tar.gz,
  • ${classifier} is the artifact classifier (when available),
  • ${checksums} is a list of checksums algorithms, md5 and sha1 by default.

maven-metadata.xml file format is defined in Maven Repository Metadata Model.

.asc file is optional (may be required in some repositories, like Central Repository) and is a PGP detached signature file.

Obviously, ${groupId}, ${artifactId} and ${version} are defined in pom.xml. But what about ${classifier} and ${extension}, how are they defined?

Classifier and extension definition is completely different at artifact publication and usage times:

  • At artifact publication time: Extension and classifier are defined by plugins that create the artifacts and attach them for publication.
    Some plugins provide configuration parameters to be able to override default values. For example, Maven JAR Plugin's jar:jar goal produces by default an artifact with jar extension and empty classifier. The classifier goal parameter can be used to define a classifier (there is no parameter to override extension).

  • At artifact usage time: Extension and classifier are defined by <dependency>'s <type> and <classifier> definition in pom.xml:

    • <type> (jar by default) defines the extension and default classifier:
      see default artifact handlers to see default types and corresponding extension and default classifier.
    • <classifier> is optional, to override default classifier defined by the dependency type.

SNAPSHOT

In case of a SNAPSHOT version, version directory uses base version, i.e. version ending in -SNAPSHOT, for example 3.8.4-SNAPSHOT.

For artifact files, there are 2 options available:

  1. unique SNAPSHOT artifacts, using the same base version,
  2. multiple SNAPSHOT artifacts for one base version, each deployment will have an effective version where SNAPSHOT is replaced with YYYYMMDD.HHMMSS-${counter}.

Protocol

Repository can be accessed through many file-oriented protocols, both for read and write: most classical are file://, http:// and https:// (GET and PUT). Older (now generally unused) protocols are FTP(S), SCP, SSH,

HTTP/HTTPS protocol have 2 specific characteristics:

  1. there is no directory listing feature: Maven does not need to list files in a directory, a remote directory does have not provide any directory listing feature,

  2. HTTP/1.1 Reason-Phrase is used to provide extended message when artifact access is rejected by remote repository. This usage of Reason-Phrase is nowadays legacy and is removed in HTTP/2, MNG-6795 is open to create a replacement.