Maven 2 Repositories, Snapshots, Releases, Metadata, Checksums, and Maven Client Configuration: Concepts, Architecture, and Mental Model

1. The practical problem: one coordinate, several state machines

Chapter 05 separated Nexus database metadata from blob bytes. Maven adds another layer: the client does not ask for “a JAR somewhere.” It asks for an artifact identified by a groupId, artifactId, and version—usually shortened to GAV—plus optional packaging/type and classifier. Nexus must expose files at Maven-compatible paths, enforce repository policy, update Maven metadata, and return bytes whose identity the client can validate.

That means a successful mvn command crosses several distinct states: Maven's project model and local cache; the selected remote repository or mirror; Nexus authorization and repository topology; Maven metadata and component/asset records in the database; binary POM/JAR/checksum content in a blob store; and, for a proxy, the upstream Central repository. Debugging improves dramatically once those states are named instead of called “the Maven repository.”

2. GAV coordinates become deterministic paths

For com.example.academy:ch06-demo:1.0.0, Maven converts dots in the group ID to path separators, then nests artifact ID and version. The main JAR and POM therefore live beneath com/example/academy/ch06-demo/1.0.0/. A sources classifier would produce a sibling such as ch06-demo-1.0.0-sources.jar. Nexus commonly represents that logical version as one component with several assets.

3. Release and SNAPSHOT are different publication semantics

A release version such as 1.0.0 is intended to identify stable bytes. A snapshot version must end in -SNAPSHOT, for example 1.1.0-SNAPSHOT. Sonatype's current Maven documentation explains that repeated snapshot publications are represented by timestamped values plus a build counter while clients continue to request the logical -SNAPSHOT coordinate. The translation is carried by Maven metadata.

This is why “snapshot can change” does not mean “overwrite one JAR path and hope caches notice.” Maven and the repository manager cooperate through maven-metadata.xml. Release repositories should normally protect immutability with a write-once deployment policy; snapshot repositories deliberately support repeated development publications.

flowchart TD
M[Maven client] -->|GAV request| G[Maven group]
G --> H[Hosted releases/snapshots]
G --> P[Central proxy]
P --> U[Maven Central]
H --> D[(Nexus database metadata)]
P --> D
H --> B[(Blob store assets)]
P --> B
D --> R[Path + metadata decision]
B --> R
R -->|POM/JAR/checksum| M

The arrows are deliberately asymmetric. Maven reads through the group. Hosted repositories own internal publication. The proxy fetches from Central and caches results. Database metadata helps Nexus locate and describe content; blob storage carries repository file bytes. Neither the group nor the proxy should be treated as the authoritative publish target for ordinary Maven releases.

4. What maven-metadata.xml does—and does not do

Maven metadata is generated/maintained coordination state. At an artifact level it can describe available versions; inside a snapshot version directory it maps a logical snapshot to timestamped snapshot values. It is not the source code, not a signature, and not a vulnerability assessment. A metadata file can be internally consistent while the artifact is still unauthorized or vulnerable.

Nexus also keeps its own component and asset records for browsing, searching, authorization, cleanup, and API responses. Do not equate those database records with the Maven protocol metadata file even when both describe the same published component.

5. The recommended read/write topology

Sonatype currently recommends groups to expose aggregated Maven content. Member order matters, and hosted repositories placed ahead of proxies reduce unnecessary remote lookups and reduce the chance that a public artifact shadows an internal coordinate.

6. Maven settings.xml: routing and secrets belong to the client boundary

Maven settings are machine/user execution configuration, not project source. The file can define a local repository path, mirrors, credentials under <servers>, profiles, proxies, and other environment-specific values. A server's id is a lookup key: it must match the repository or mirror ID used when Maven connects. It is not the Nexus username.

<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0 https://maven.apache.org/xsd/settings-1.2.0.xsd">
  <localRepository>/replace/with/disposable/path</localRepository>
  <servers>
    <server>
      <id>academy-ch06-releases</id>
      <username>${env.NX_USER}</username>
      <password>${env.NX_PASS}</password>
    </server>
  </servers>
  <mirrors>
    <mirror>
      <id>academy-ch06-public</id>
      <mirrorOf>*</mirrorOf>
      <url>http://127.0.0.1:8081/repository/academy-ch06-public/</url>
    </mirror>
  </mirrors>
</settings>

The environment placeholders prevent the tutorial from embedding a credential into the file. In production, prefer your CI secret facility or Maven's supported password-encryption approach. Do not pass repository passwords as command-line arguments or commit settings.xml with plaintext secrets.

7. Read-only inspection before mutation

Before creating anything, record the server and client baseline. The goal is to prove which versions and endpoints you are about to change.

NX_URL=http://127.0.0.1:8081
mvn --version
curl -fsS "$NX_URL/service/rest/v1/status"
curl -fsS "$NX_URL/service/rest/v1/repositories" | tee repositories-before.json
# Also inspect Settings → System Information in the UI for Nexus version/runtime/database mode.

8. Checksums, signatures, authorization, and provenance answer different questions

A checksum answers “did these bytes change relative to this digest?” A signature can answer “did the holder of a trusted signing key sign these bytes?” Authorization answers “was this identity permitted to publish or read here?” Provenance answers questions about how a build was produced. Vulnerability intelligence evaluates known risk. None substitutes for the others.

Knowledge check

9. Summary

Maven turns coordinates into predictable paths and metadata operations. Nexus applies hosted/proxy/group semantics, authorization, policy, database records and blob storage to those requests. The next lesson builds this model with an isolated Maven client and disposable repositories.

Official references and version notes

• Nexus Repository Download and 3.95.x release notes — current self-hosted baseline.
• Sonatype: Maven Repositories — Maven version/layout policies, default repositories, grouping, settings and deployment examples.
• Configurable Repository Fields — hosted deployment policy, proxy caching, and group ordering.
• Components API and REST API Reference — supported component/asset inspection and upload boundaries.
• Apache Maven Download — current Maven 3 stable line.
• Apache Maven Settings Reference — localRepository, servers, mirrors, environment interpolation and profiles.
• Using Mirrors for Repositories — mirrorOf matching and single-repository patterns.
• Apache Maven Deploy Plugin — deployment goals and repository-id matching.

Version-sensitive statements were rechecked against Sonatype and Apache Maven primary documentation on 2026-08-26. The mandatory lab pins Nexus Repository Community Edition 3.95.2 and Apache Maven 3.9.16. Nexus 3.95.2 was released 2026-08-21; Maven 3.9.16 is the current recommended Maven 3 release. Nexus 3.87+ requires Java 21 when using an external JVM and official Nexus packages include a bundled Java 21 runtime. Re-check live support/download pages before executing these labs.