This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Documentation

This site are is “work in progress” and will remain as such for a long time. As our time allows.

This section is where the user documentation for our project lives - all the information You need to understand and successfully use our projects.

1 - Overview

Maveniverse projects are here to help and guide you

All the Maveniverse projects were built with well-defined purpose and goal: to help and guide Apache Maven users.

Maveniverse umbrella started as a “laboratory” for fast-paced prototyping and experimenting, but also to host projects that Apache Maven project felt as inadequate to host at project itself.

The idea of Maveniverse is to serve as “skunk works” around Maven with quick turnaround and prototyping, but at the same provide clear passage for projects from Apache Maven to here, but other way around as well (once community deems project as “mature”). Given most of us are Apache Maven committers, or Apache Maven PMC members, we want Apache Maven to prosper.

2 - Contribution Guidelines

How to contribute

We are open for contributions! All our projects are open, feel free to fork them and provide Pull Requests.

3 - MIMA

Use Resolver everywhere!

Maveniverse MIMA is very first project of ours.

MIMA (“MIni MAven”) is a Java 8 library that makes it easy to use Maven Resolver as a library, both inside and outside of Maven. Resolver alone is incomplete: model classes and several components are provided by Maven, and outside of Maven one also needs to apply user configuration like settings.xml. MIMA provides all this, and lets the same code run unchanged in a Maven plugin or in a standalone application.

Code is written against the MIMA context artifact, and at runtime one or more runtimes are provided: embedded-maven (when running inside Maven, it reuses the repository system and session Maven already set up), standalone-sisu (boots Eclipse Sisu, so Resolver can be extended with components from the classpath) or standalone-static (no DI, manual wiring). Standalone runtimes are also available as “uber” JARs.

In every case the context supports all recent Resolver features and configuration properties, like split local repository, extensible checksums, transport configuration, repository filtering and locking. Many other Maveniverse projects, like Toolbox and Huginn, are built on MIMA.

Sources: https://github.com/maveniverse/mima

3.1 - What is it?

Where it all started

Maveniverse MIMA (MIni MAven) is a library that makes you able to use Resolver wherever you are, inside or outside of Maven.

4 - MASE

Maven Search

Maven Search done simple.

MASE (“Maven Search”) is a fork of the Maven Indexer Search API, and a drop-in replacement for it: switching requires only changing the groupId and version. The Search API offers a simple Java API to search Maven Central and other repositories, using various backends.

The fork existed to allow faster prototyping. All its changes have since been merged back, and as of Maven Indexer 7.1.2 and MASE 1.0.1 the two are equivalent; the Search API from Maven Indexer is the recommended one to use.

Sources: https://github.com/maveniverse/mase

5 - Nisse

Inject properties to your build

Nisse was a response to “finish” CI Friendly implementation in Maven 3, but turned out to be more.

Nisse is a suite of a core extension and a plugin for Maven 3 and Maven 4 (and a Gradle plugin) that collects properties from “property sources” and publishes them to the build. Sources available out of the box are: properties files, Git data via Eclipse JGit, Maven version, and OS information; new sources can be added. Property keys can be renamed when published, for example to revision.

In Maven 3 it also fixes CI Friendly versions, which by default can result in deploying POMs with unresolved version expressions. Combined with the JGit source, the project version can be derived from Git tags and history, removing hardcoded versions from POMs.

Nisse can also replace the discontinued OS Detector plugin: with -Dnisse.compat.osDetector it emits the same properties. To see what Nisse injects, use mvn validate -N -Dnisse.dump.

Sources: https://github.com/maveniverse/nisse

5.1 - What is it?

A small helper for big tasks

Maveniverse Nisse is a suite of extensions and plugins for Maven 3 and Maven 4. In essence, it provides a set of “property sources” that are injected into your build. For Maven 3 it also redoes the “CI Friendly versioning” feature that is in vanilla Maven 3 incomplete.

6 - Toolbox

Swiss knife in your pocket

Toolbox was started as a “showcase” project of Maveniverse MIMA combined into plugin goals and CLI commands, that never stopped growing.

Toolbox is a Maven plugin, a CLI (also runnable via JBang as jbang toolbox@maveniverse), a Maven 4 mvnsh extension and an MCP server, all exposing the same set of commands. It started as a replacement for the MIMA CLI and as a showcase of how MIMA lets the same Resolver code run inside Maven and standalone.

Commands cover resolving artifacts and classpaths, dependency trees, searching and listing versions, copying and deploying artifacts, and more. It offers a similar subset of goals as maven-dependency-plugin. Toolbox also served for experiments: the Resolver 2.x ScopeManager was born here, and Toolbox carries a Resolver 1.x workaround for it, supporting Maven 3.6.3+. Requires Java 17+.

If you consider the Maven Plugin documentation below, you will notice there are two types of goals: those with gav- prefix and those without it. The differences are:

  • The gav- prefixed goals do not require project and same code is exposed via CLI as well. For example mvn toolbox:gav-search and jbang toolbox@maveniverse search runs essentially the same code.
  • The gav- prefix-less goals do require Maven project and hence are not exposed via CLI.

Sources: https://github.com/maveniverse/toolbox

Maven generated plugin documentation

Many goals accept *Spec parameters (matchers, selectors, sources, sinks…); their syntax is described in Spec languages.

6.1 - What is it?

A showcase of MIMA + Mojo + Picocli that grew

Maveniverse Toolbox serves manifold purpose.

It is a real tool, that gives you Swiss Knife for every situation. Toolbox is a Maven Plugin but also a CLI tool (and a Maven 4 mvnsh extension) that provides useful commands.

Is also a showcase of Maveniverse MIMA.

Finally, is here to educate or help: the shared module is reusable library that can be easily embedded into Mojo or any standalone application.

6.2 - Spec languages

Matcher, selector, mapper, source and sink expressions used by Toolbox

Many Toolbox commands accept a spec string (options like --artifactVersionMatcherSpec, --sinkSpec, or the source/sink parameters of gav-copy). Every spec is parsed by the same tiny parser (eu.maveniverse.maven.toolbox.shared.internal.SpecParser) and then interpreted by a class-specific builder. This page documents the common syntax and every “language” built on top of it.

LanguageProducesExample
Artifact version matcherPredicate<Version>and(noSnapshotsAndPreviews(), constraint('[,4)'))
Artifact version selectorversion stringcontextualSnapshotsAndPreviews(last())
Artifact matcherPredicate<Artifact>and(artifact(org.apache.maven*), not(snapshot()))
Dependency matcherPredicate<Dependency>and(scopeIncluded(compile,runtime), optional(false))
Artifact name mapperString from artifactcompose(fixed(libs/), AbVE())
Artifact mapperArtifact → Artifactcompose(omitClassifier(), baseVersion())
Dependency mapperDependency → Dependencycompose(scope(compile), optional(false))
Artifact key factorykey StringversionlessId()
Artifact differentiatorkey StringmajorVersion()
Artifact sourcestream of artifactsresolveTransitive(gav(g:a:1.0), test)
Artifact sinkconsumer of artifactsmatching(not(snapshot()), flat(target/libs))
Dependency sinkconsumer of dependenciesmatching(scopeIncluded(test), counting())

Common syntax

A spec is a tree of operations and literals:

spec    := op
op      := name '(' [ arg ( ',' arg )* ] ')'
arg     := op | literal
literal := bare | quoted
  • The root of a spec must be an operation: any() is a spec, any is not.
  • Operation names are case-sensitive. An operation without arguments still needs ().
  • Bare literals may contain letters, digits and the characters * : . - / \ $ { } [ ]. Whitespace outside of quotes is ignored (also inside bare literals: a b is the same as ab).
  • Quoted literals are enclosed in single quotes and may contain any character except ' (there is no escaping). Whitespace is preserved. Use them whenever a value contains (, ), ,, +, _, @, spaces, etc., for example version ranges: constraint('[,32.1)'). '' is the empty string.
  • Property references: a literal that is exactly ${name} is replaced by the value of property name (the resolver session config properties, which include Java system and user properties). Unknown properties become the empty string. Partial interpolation (foo-${name}) is not supported. Note: a few operations read some arguments raw, without interpolation; these are marked with (raw) below.
  • Syntax errors (bad characters, unbalanced parentheses, dangling commas, unterminated quote) and unknown operations fail with an “Invalid … spec” error.

Some operations take another language as argument; e.g. matching(...) in a sink takes an artifact matcher as first argument and a sink as second. This is noted in the argument descriptions below.

Known quirks

  • Variadic arguments (X...) are collected in reverse order. For and/or/tee this rarely matters, but compose(...) of artifact and dependency mappers applies its arguments right to left.

Notation in the tables: str is a literal, bool is a literal true/false (anything else is false), X... means zero or more arguments of type X, [x] means optional.


Artifact version matcher

ArtifactVersionMatcher — a predicate over versions. Used for filtering available versions (e.g. options --artifactVersionMatcherSpec, default usually noSnapshotsAndPreviews(), and --parentVersionMatcherSpec). Versions are parsed using the session version scheme.

OperationMatches
any()every version
snapshot()snapshot versions (-SNAPSHOT or timestamped)
preview()“preview” versions: contains alpha, beta, milestone, rc or cr, or a/b/m immediately followed by a digit (case-insensitive)
noSnapshots()shorthand for not(snapshot())
noPreviews()shorthand for not(preview())
noSnapshotsAndPreviews()shorthand for and(noSnapshots(), noPreviews())
eq(str)versions equal to given version
gt(str) / gte(str)versions greater than / greater or equal to given version
lt(str) / lte(str)versions less than / less or equal to given version
range(str)versions contained in given version range, e.g. range('[1.0,2.0)')
constraint(str)versions contained in given version constraint (a range, or a plain version), e.g. constraint('[,32.1)')
not(matcher)negation
and(matcher...)all matchers match
or(matcher...)any matcher matches

Examples:

noSnapshotsAndPreviews()
and(noSnapshotsAndPreviews(), lt(4.0.0))
and(noPreviews(), constraint('[3.9,4)'))
or(eq(1.0), eq(2.0))

Artifact version selector

ArtifactVersionSelector — given an artifact and the ascending sorted list of its available versions, selects one version. Used by options --artifactVersionSelectorSpec (default usually contextualSnapshotsAndPreviews()). Every selector falls back to the artifact’s own version when it cannot select anything (e.g. empty list).

OperationSelects
identity()the artifact’s current version
first()the first (lowest) version
last()the last (highest) version
prev()the highest version lower than the current one
next()the lowest version higher than the current one
major()the last version with the same major (prefix up to first .) as the current one; if the current version has no major part, does last()
minor()the last version with the same major.minor (prefix up to second .); if the current version has no minor part, does major()
filtered(versionMatcher, selector)applies selector to versions accepted by the version matcher
noSnapshots(selector)selector applied to non-snapshot versions
noPreviews(selector)selector applied to non-preview versions
noSnapshotsAndPreviews(selector)selector applied to versions that are neither snapshots nor previews
contextualSnapshotsAndPreviews([selector])filtering depends on current version: if it is a snapshot, no filtering; if it is a preview, snapshots are filtered out; otherwise both snapshots and previews are filtered out. Then selector is applied (default major())

Examples:

last()
contextualSnapshotsAndPreviews(last())
filtered(lt(4.0.0), noSnapshotsAndPreviews(last()))

Artifact matcher

ArtifactMatcher — a predicate over artifacts.

OperationMatches
any()every artifact
none()no artifact
snapshot()snapshot artifacts
withoutClassifier()artifacts with no (or blank) classifier
artifact(str)artifacts matching a coordinate pattern, see below
unique()stateful: matches an artifact only the first time it is seen (keyed by full coordinates)
uniqueBy(nameMapper)stateful: like unique(), keyed by the given artifact name mapper, e.g. uniqueBy(GAKey())
not(matcher)negation
and(matcher...)all match
or(matcher...)any matches

Coordinate patterns for artifact(...); missing parts mean *:

Pattern formExample
groupIdorg.apache.maven
groupId:artifactIdorg.apache.maven:maven-core
groupId:artifactId:versionorg.slf4j:*:2*
groupId:artifactId:extension:version*:*:pom:*
groupId:artifactId:classifier:extension:version*:*:sources:jar:*

Each part is matched with a simple glob: * (anything), foo* (starts with), *foo (ends with), *foo* (contains), otherwise exact match. Note that the 5-part form is classifier before extension.

Examples:

artifact(org.apache.maven*)
and(artifact(org.slf4j), not(snapshot()))
and(withoutClassifier(), uniqueBy(GAKey()))

Dependency matcher

DependencyMatcher — a predicate over dependencies (artifact + scope + optional flag). Used by tree-related commands (e.g. gav-tree) and by dependency sinks.

OperationMatches
any()every dependency
none()no dependency
scopeIncluded(str...)dependencies whose scope is one of the given scopes
scopeExcluded(str...)dependencies whose scope is none of the given scopes
optional(bool)dependencies whose optional flag equals the given value
artifact(str)dependencies whose artifact matches the coordinate pattern (same as artifact(...) of artifact matcher)
not(matcher)negation
and(matcher...)all match
or(matcher...)any matches

Examples:

scopeExcluded(test,provided)
and(scopeIncluded(compile,runtime), optional(false), not(artifact(org.slf4j)))

Artifact name mapper

ArtifactNameMapper — maps an artifact to a string; used for file names (flat(...), unpack(...) sinks) and keys (uniqueBy(...)). Letters stand for GroupId, ArtifactId, Version, bV (base version, i.e. 1.0-SNAPSHOT instead of 1.0-20240101.123456-1), Classifier and Extension.

Single fields:

OperationResult
G() A() V() bV() C() E()the corresponding single field
P(key, default)artifact property key, or default if absent

Keys (colon separated):

OperationResult
GAKey()g:a
GAVKey()g:a:v
GAbVKey()g:a:bV
GACEVKey()full artifact string g:a:e[:c]:v

File names (classifier part including its - is omitted when the classifier is empty):

OperationResultOperationResult
GACVE()g.a[-c]-v.eACVE()a[-c]-v.e
GACbVE()g.a[-c]-bV.eACbVE()a[-c]-bV.e
GACE()g.a[-c].eAVCE()a-v[-c].e
GAVE()g.a-v.eAbVCE()a-bV[-c].e
GAbVE()g.a-bV.eACE()a[-c].e
GAE()g.a.eAVE()a-v.e
AbVE()a-bV.e
AE()a.e

Others:

OperationResult
repositoryDefault()Maven repository layout path, using the OS file separator
repository(str)Maven repository layout path, using given separator (e.g. repository(/))
empty()empty string
fixed(str)the given (non-blank) string
optionalPrefix(str, mapper)str + mapper result, or empty string if the mapper result is blank
optionalSuffix(str, mapper)mapper result + str, or empty string if the mapper result is blank
compose(mapper...)concatenation of all mapper results, in order

Examples:

AbVCE()
compose(G(), fixed(/), AVE())
compose(A(), optionalPrefix(-, C()), fixed(.), E())

Artifact mapper

ArtifactMapper — transforms an artifact into another artifact. Used by mapping(...) sources/sinks.

OperationResult
identity()artifact unchanged
baseVersion()version replaced with base version (timestamped snapshot → -SNAPSHOT)
versionSuffix(str)version + str
baseVersionSuffix(str)base version + str
omitClassifier()classifier removed
rename(g, a, v)groupId, artifactId and version replaced; * keeps the original value
compose(mapper...)applies mappers one after another

Note: compose(...) currently applies its arguments right to left (the last argument first), so compose(versionSuffix(-x), rename(*,*,2)) turns a:x:1 into a:x:2-x.

Examples:

omitClassifier()
rename(org.example,*,1.0.0)
rename(${groupId},*,*)

Dependency mapper

DependencyMapper — transforms a dependency. Only reachable as the first argument of the mapping(...) dependency sink.

OperationResult
identity()dependency unchanged
scope(str)scope set to str
optional(bool)optional flag set
exclusion(str...)exclusions replaced with given ones; each is groupId:artifactId[:extension[:classifier]] (wildcards like *:* allowed)
compose(mapper...)applies mappers one after another (currently right to left, like the artifact mapper)

Example: compose(scope(compile), exclusion(*:*))

Artifact key factory

ArtifactKeyFactory — computes a key used to group artifacts (e.g. --keyFactorySpec of conflict-listing commands, default versionlessId()).

OperationKey
id()g:a:e[:c]:v
baseId()g:a:e[:c]:bV
versionlessId()g:a:e[:c]
ga()g:a

Artifact differentiator

ArtifactDifferentiator — computes a value that tells artifacts within the same key group apart; a group with more than one distinct value is a conflict (e.g. --artifactDifferentiatorSpec, default majorVersion()).

OperationValue
majorVersion()version up to first . (whole version if there is no dot)
minorVersion()version up to second . (whole version if there is none)
baseVersion()base version
version()version

Artifact source

Artifacts.Source — supplies a stream of artifacts (e.g. first parameter of gav-copy). Relative paths are resolved against the current base directory.

OperationSupplies
null()nothing
gav(str)a single artifact g:a[:e[:c]]:v (not resolved)
gavs(str)artifacts from a comma separated list of GAVs, or from a file containing one GAV per line
directory(str)all artifacts found in the given directory
localRepository(str)all artifacts installed in the local repository at given path
sessionLocalRepository()all artifacts installed in the session’s local repository
recorder()artifacts recorded during this session (see gav-copy-recorded)
concat(source...)concatenation of all sources
resolve(source)artifacts of source resolved (unresolvable ones are skipped with a warning)
resolveTransitive(source[, scope])each artifact of source resolved with its transitive dependencies, in given resolution scope (raw): none, compile, compile_plus_runtime, runtime (default), runtime_plus_system, test (case-insensitive; names with _ must be quoted)
matching(artifactMatcher, source)artifacts of source accepted by the artifact matcher
mapping(artifactMapper, source)artifacts of source transformed by the artifact mapper

Examples:

gav(org.slf4j:slf4j-api:2.0.13)
resolveTransitive(gavs(gavs.txt), 'runtime_plus_system')
matching(not(snapshot()), sessionLocalRepository())

Artifact sink

Artifacts.Sink — consumes artifacts (e.g. --sinkSpec, last parameter of gav-copy; default often null()). Relative paths are resolved against the current base directory. Sinks that modify something honor dry-run mode.

OperationDoes
null()discards everything
counting()counts artifacts
sizing()sums artifact file sizes
logging()prints each artifact
stat([[list,] details])prints statistics; stat() = stat(true,true), stat(x) = stat(true,x); details add module descriptor, checksums, origin URI and PURL info
artifactUri([bool])collects origin repository URIs of artifacts and prints them on close if bool (default true)
moduleDescriptor()extracts JPMS module descriptors
modules(file[, classifier]) (raw)writes a module=uri#SIZE=..&SHA-1=.. properties file for modular resolved JARs (optionally only of given classifier)
flat(dir[, nameMapper]) (raw dir)copies files into directory dir, named by the artifact name mapper (default AbVCE()); does not overwrite
repository(dir)copies files into directory dir using Maven repository layout (release artifacts only)
unpack(dir[, nameMapper]) (raw dir)unpacks archives into dir, each into a subdirectory named by the name mapper (default ACVE()); fixed(.) overlays all into dir
install([localRepoDir])installs into the session local repository, or into the local repository at given path
deploy(remoteRepo)deploys into given remote repository
purge(remoteRepo...)purges whole GAVs from the session local repository, considering given remote repositories
tee(sink...)passes artifacts to all sinks
nonClosing(sink)delegates but never closes sink
matching(artifactMatcher, sink)passes on only artifacts accepted by the artifact matcher
mapping(artifactMapper, sink)passes on artifacts transformed by the artifact mapper

Remote repositories are given as url, id::url or id::layout::url; as URLs contain : and /, they work unquoted, but quoting is safer.

Examples:

flat(target/libs)
flat(target/libs, compose(G(), fixed(/), AVE()))
tee(stat(), matching(withoutClassifier(), install(target/local-repo)))
deploy('myrepo::https://repo.example.com/releases/')

Dependency sink

Dependencies.Sink — consumes dependencies.

OperationDoes
null()discards everything
counting()counts dependencies
tee(sink...)passes dependencies to all sinks
nonClosing(sink)delegates but never closes sink
matching(dependencyMatcher, sink)passes on only dependencies accepted by the dependency matcher
mapping(dependencyMapper, sink)passes on dependencies transformed by the dependency mapper

7 - BOM Builder Maven Plugin

A tool for generating BOMs

A Maven Plugin for BOMs to build according to your own taste.

BOM Builder is a Maven 3 plugin that generates a dependency management POM (a “BOM”, bill of materials) from the dependencies of the current project. The generated POM contains a dependencyManagement section listing the configured set of artifacts: only the modules of the reactor, or the full stack including transitive dependencies.

The plugin does not take a stance on what a BOM should contain. Maven team calls the reactor-only kind “skinny” and the full-stack kind “fat”; both are possible, and the content can be tuned with exclusions, dependency exclusions (with wildcards) and the option to express versions via properties. The BOM can be attached with a classifier (consumable by Maven 4 only), or it can replace the pom.xml of a dedicated pom packaging module, which makes it consumable by Maven 3 as well.

Sources: https://github.com/maveniverse/bom-builder-maven-plugin

Maven generated plugin documentation

7.1 - What is it?

A tool for building BOMs

The Maveniverse bom-builder-maven-plugin is a Maven Plugin for generating BOMs. The idea is following: you manage your dependencies “as usual”, and then use the plugin to generate BOM or even multiple BOMs as you like them: reactor only or full bill of materials.

8 - Mímir

The Maven workstation and LAN cache

Maveniverse Mímir started as solution of my own problem: workstation hopping, and a LOT of download when picking up where I left on.

Mímir is a Maven 3.9+/4 core extension that adds a system-wide cache layer between Resolver and the transport. As it sits “above” the local repository, it works regardless of where the local repository is or of its layout (enhanced, split, etc.). The cache, by default in ~/.mimir/local, is shared by all builds on the workstation and consulted before going remote, which makes deleting the local repository cheap.

By default only release artifacts from Maven Central are cached, but the set of cached repositories is configurable. Snapshots are never cached. On local caching hard links are used where possible to avoid duplicating content.

Mímir can also share caches across the LAN: a daemon discovers other Mímir nodes and serves cached content to them, on the assumption that a LAN neighbour is faster than the real remote. It can also log every artifact resolution (CSV or JSON Lines), recording where each artifact came from and whether it was served from cache.

Sources: https://github.com/maveniverse/mimir

8.1 - What is it?

The Maven workstation and LAN cache

Mímir is a Maven 3 and Maven 4 extension that offers global caching on workstations. More precisely, Mímir is a Resolver 1.x and 2.x extension (is a RepositoryConnector) that is loaded via Maven extensions mechanism and extends Resolver.

As you may know, Maven historically uses “local repository” as mixed bag, to store cached artifacts fetched from remote along with locally build and installed artifacts. Hence, your local repository usually contains both kind of artifacts.

Mímir alleviates this, by introducing a new workstation wide read-through cache (by default in ~/.mimir/local) and placing hardlinks in Maven local repository pointing to Mímir cache entries. This implies several important things:

  • you have separated pure cache (of immutable artifacts; Mimir handles release artifacts only), unlike existing local repository, that is a mixed bag on your disk.
  • because of hardlinks, ideally you have only one copy of any cached artifact on your disk (as opposed to as many, as many local repositories you use).
  • is more compatible than “split local repository” as it is in reality “invisible” for Maven and Maven goals.

Also some consequences are:

  • you can easily adhere to “best practices” and delete your local repository often, as you still have it all locally (in Mímir caches). You will not lose you precious time by waiting to populate local repository.
  • backup or caching (like in CI case) is simple also: instead of tip-toeing and doing trickery with your local repository, just store and restore Mímir caches instead, you may forget local repository.

Advanced features of Mímir is LAN-wide cache sharing, so if you hop from workstation to workstation on same LAN, you don’t need to pull everything again, as your build will get it from the workstation that already has it. Nowadays with Gigabit LANs combined with modern WiFi networks, doing this is usually faster, than going to Maven Central.

Architecture

Mimir is composed of multiple components, and works in the following way:

classDiagram
    Node <|-- LocalNode
    Node <|-- RemoteNode
    LocalNode <|-- SystemNode

    class Node{
      locate(URI)
    }

    class LocalNode{
      store(Path)
    }

    class SystemNode{
      store(Entry)
    }

Where node name represents the content “locality”: local node is “local” to the user workstation, and hence, has access to OS filesystem. Remote node on the other hand, needs to retrieve the content from somewhere else (remote).

In other words: every node is able to “locate”, but local node is able to “store” local filesystem backed content, and system node is able to “store” Entry instances, usually originating from other Node instances.

One peculiarity of system nodes is that they can be “published” as well. Mimir supports two LAN publishers out of the box: http that uses Java built in HTTP server and socket that uses plain ServerSocket.

Most important Node implementations are (note: there are more, but they are usually aggregating nodes):

Node nameLocalNodeSystemNodeRemoteNodeDescription
fileyesyesnoUses OS filesystem
minioyesyesnoUses S3 storage
bundleyesnonoRead-only local node, backed by “bundle” ZIP files
daemonyesnonoCommunicates via UDS to Mimir Daemon process
jgroupsnonoyesUses JGroups messaging w/ publishers to LAN share cache content
ipfsnonoyesUses IPFS to WAN share cache content (not implemented yet)

Mimir Session

MimirSession (sharing lifecycle with MavenSession; lives within Maven process) requires one LocalNode and exposes two methods: locate(RemoteRepository, Artifact) and store(RemoteRepository, Artifact) (where Artifact must be resolved, hence backing file set).

Using MimirSession, the MimirConnector, that wraps original RepositoryConnector resolver would use, implements caching: it asks MimirSession to locate the required artifact. If local node has the artifact, the request is “short-circuited” and artifact with content is returned to resolver. If not, the MimirConnector falls back to original connector, and if the artifact is successfully retrieved, it is stored/cached for future use and then returned to resolver.

Out of local nodes, the interesting one is DaemonNode: this node in reality starts (unless not already running) a Mímir Daemon process, and uses Unix Domain Sockets to communicate with it. On workstation, there is only one Mímir Daemon running, and it is shared by all Maven processes (DaemonNodes in each separate Maven sessions).

Mimir Daemon process

Mímir Daemon requires one SystemNode and zero or more RemoteNodes. It implements “round-robin” strategy to locate the requested artifact: it first tries to locate it in SystemNode (which is local to the workstation), and if not found, it tries to locate it in RemoteNodes (which are remote, hence on LAN or WAN). If artifact is found in RemoteNode, it is retrieved and cached in SystemNode for future use.

Mimir without daemon process

In case of CI usage, daemon is usually unwanted overhead, as usually there is only one Maven process, hence one “client” of Mimir cache. In such cases, Mimir session can be configured to use other local node than DaemonNode is. In this case, a ~/.mimir/session.properties with content of mimir.session.localNode=<node name> can be used, for example file (remember, SystemNode extends LocalNode).

Mimir LAN cache sharing

It is currently implemented using JGroups cluster messaging. In short, when JGroups backed RemoteNode is asked for URI, a message is broadcasted in cluster. Receiving cluster nodes will respond do they have the wanted content or not. If one or more node has it, it will create once-usable “token”, and access URI and send back as response. Finally, the originator will fetch the wanted content identified by “token” from the received URI from randomly chosen node that responded positively.

Mimir WAN cache sharing

Not implemented yet

Most probably will use IPFS.

8.2 - Why would I use it?

The Maven workstation and LAN cache

In short: you want to use it for proper local repository maintenance, but it also helps with disk space usage as well, and real workstation wide caching, irrelevant of how many local repositories you use.

Finally, if you workstation-hop a lot (like I do) on same LAN, it makes pretty much sense to pick up on the new workstation where you left off on old workstation.

On CI-like setups it also simplifies caching between jobs, as all you need is to store Mímir cache after job finishes, and on subsequent job runs just restore it.

8.3 - How to use it?

The Maven workstation and LAN cache

Simplest way to use Mímir is with Maven 4, it supports user wide extensions. Just create ~/.m2/extensions.xml with following content (adjust Mímir version as needed):

<?xml version="1.0" encoding="UTF-8"?>
<extensions>
    <extension>
        <groupId>eu.maveniverse.maven.mimir</groupId>
        <artifactId>extension3</artifactId>
        <version>${mimirVersion}</version>
    </extension>
</extensions>

You can add it to your (parent) POM as well, as build extension:

    <extensions>
      <extension>
        <groupId>eu.maveniverse.maven.mimir</groupId>
        <artifactId>extension3</artifactId>
        <version>${mimirVersion}</version>
      </extension>
    </extensions>

Using it with Maven 3 is also possible and completely fine and compatible, but there you will need to set up per-project extensions in .mvn/extensions.xml file instead of one user-wide one.

One extra step is needed, in case you have non-trivial networking (like Docker, Tailscale or alike): you need to “help” Mimir a bit to figure out which networking interface belongs to your LAN. To achieve that, you need to create ~/.mimir/daemon.properties file with following content (use your LAN IP address):

mimir.localHostHint=match-address\:192.168.1.*

This will help JGroups and Mimir system node publishers to properly bind to interface that is used on your LAN.

With these, you are fully set up. Now just go and fire up a Maven or Maven Daemon build.

8.4 - Use case: Maven CI

The Maven workstation and LAN cache

TBD: explain how is Mímir used in Maven GH CI

9 - Mason

If you dislike XML

A new project that makes POMs written in YAML, JSON, HOCON and TOML possible with all the whistle and bells.

Mason is a Maven 4 core extension that provides alternative model readers, making it possible to write POMs in YAML, JSON5, TOML or HOCON instead of XML. It requires Maven 4.0.0-rc-3 or later and Java 17; it does not work with Maven 3.

To use it, register the extension in the project root .mvn/extensions.xml and replace pom.xml with a pom.yaml, pom.json, pom.toml or pom.conf file; child modules inherit the extension. Besides the format, the model can be written in a more compact form, for example coordinates as single groupId:artifactId:version strings and dependency scope given as a suffix (@test).

YAML and JSON are fully supported. TOML and HOCON support is limited: HOCON substitutions, includes and object merging are not supported, and TOML files do not report line numbers in errors.

Sources: https://github.com/maveniverse/mason

9.1 - What is it?

If you dislike XML

Maveniverse Mason is a Maven 4 extension that allows you to author POMs in YAML, JSON, HOCON and TOML with all the “whistle and bells” (ie. location tracking).

10 - Njord (Njörðr)

Local staging, Artifact publishing and more!

Njord is an attempt to bring simple “publishing” (new term, is not “deploying with a twist”) to Maven 3 and Maven 4 with some extras like “local staging”.

Where and how artifacts are published changes over time, and publishing services often require project changes like extra profiles or their own plugins. Njord is a Maven 3.9+/4 extension and plugin that separates publishing from the build: the project is deployed as usual, into a local “staging” store, and the store is then published to the chosen service, without changes to the POMs.

Supported publishers include Sonatype Central Portal, Apache RAO, generic Sonatype Nexus 2 and 3 instances, plain install and deploy, and JReleaser. Staged content can be listed, inspected and validated before publishing. As publisher and authentication are configured in settings.xml, one needs only one server entry per publishing service, instead of one per project.

Njord is used by Maveniverse itself and by other projects like MojoHaus, Codehaus Plexus and Quarkus.

Sources: https://github.com/maveniverse/njord

Maven generated plugin documentation

10.1 - What is it?

Publish where you want (and more)!

Njord is a Maven 3 and Maven 4 extension that offers local staging, repository operations and repository publishing and a njord-maven-plugin optional plugin. More precisely, Njord is a Resolver 1.x and 2.x extension (is RepositoryConnector) that is loaded via Maven extensions mechanism and extends Resolver. Njord does not mingle with your build at all.

Njord supports “templates”, that define repository properties. Based on template, a local staging repository (“artifact store” in Njord lingo) is created. And those local staging repositories can be merged, redeployed, dropped, validated or published (and more coming) through a Maven plugin. Also, based on chosen template, Resolver is configured to create mandatory checksums for you. On the other hand, mandatory signatures are NOT generated, it is you who must provide them as part of your build.

In short, Njord keeps things “as before” (as without it): user never had to worry about checksums (Resolver did generate them always), while the signatures are usually provided by a plugin enabled in “release profile”. Njord goes step forward, and IF user selects any “SCA” template
(“SCA” stands for “Stronger Checksum Algorithms”, see Resolver Checksums) it will configure Resolver, and it will implicitly generate required stronger checksums without any user intervention required.

For now, templates supported out of the box are:

NameModeChecksums CreatedSignature CheckedRedeploy allowed?
releaseRELEASESHA-1, MD5GPG (Sigstore optional)no
release-scaRELEASESHA-512, SHA-256, SHA-1, MD5GPG (Sigstore optional)no
release-redeployRELEASESHA-1, MD5GPG (Sigstore optional)yes
release-redeploy-scaRELEASESHA-512, SHA-256, SHA-1, MD5GPG (Sigstore optional)yes
snapshotSNAPSHOTSHA-1, MD5GPG (Sigstore optional)no
snapshot-scaSNAPSHOTSHA-512, SHA-256, SHA-1, MD5GPG (Sigstore optional)no

The njord: URI

Njord can be considered also as new transport for Maven. It defines the njord: URI prefix and supports several forms:

  • njord: URI is a shorthand for njord:release-sca (default template), see below.
  • njord:<TEMPLATE> is equivalent to njord:template:<TEMPLATE>, see below.
  • njord:template:<TEMPLATE> URI when deployed to, will create new store using given template.
  • njord:store:<STORE> URI when deployed to, will try to deploy to given store that already must exist (will not be created).

Similarly, to use Njord URIs in cases like maven-deploy-plugin parameter for alternate deployment repository, the format accepts id::uri formatted string, so Njord URIs looks like id::njord: or id::njord:template:release-sca with one important detail: the id repository ID is there only to fulfil syntactical requirements, is unused otherwise. Store name will be determined at the moment of creation.

Example URIs:

  • njord: - means “use default template (that is release-sca) and create a new store”.
  • njord:snapshot - means “use template by name snapshot and create a new store”.
  • njord:store:release-00001 - means “select existing store release-00001 and use that”.

Basically by setting up your POM with distribution release repository using URL njord: and snapshot repository using URL njord:snapshot you are ready to use Njord. But, Njord is not intrusive, you can still use it by doing nothing in your project and just deploying with -DaltDeploymentRepository=id::njord: as well.

Hints:

The njord base directory

By default, Njord uses user-wide base directory (~/.njord/njord.properties). This is where Njord global configuration and also staged contents are.

This directory is not bound to any project, hence, you are free to go to one project, stage it locally, then go over another project, and stage that one as well, and so on.

Moreover, many Njord plugin goals does not require project, hence you can operate on staged contents outside of any project. Projects merely serve as “configuration source”, but you can always publish a staged store from outside it, by properly configuring publish goal.

The njord bundles

Njord by default produces two kinds of “bundles”. They are very similar, as essentially both are ZIP files with contents being artifacts laid down on Maven layout. But, there are subtle differences between the two:

The goal write-bundle will write out “bundle” file, that is a ZIP file and it will contain only the artifacts laid down on Maven layout. This is the same file format used for publishing for example on Maven Central.

The goal export will write out “transportable bundle” (NTB, “Njord Transportable Bundle”), that is very similar to “bundle”, but contains also Njord metadata, and can be imported by Njord too. This means you can carry staged content from one workstation to another workstation, like it was locally staged on another workstation. Export and Import combined with “install” publisher (that installs into local repository) can be also used in use cases like preparing some testing.

Differences are:

Use casebundle ZIPtransportable bundle ZIP
Can be published to Maven Central PortalYesNo (probably, unsure whar will Portal do with metadata)
Can be imported on another workstationNoYes
Can be “mounted” as Remote Repository by Resolver 2.xYesYes
Can be “overlaid” by MimirYesYes

Notes:

  • Resolver 2.x file transport supports `bundle:" protocol, see here.
  • Mimir supports “overlay” functionality, where it is able to overlay ZIP content over contents of remote repository caches, see this Mimir IT.

The njord attachments

Njord is able to add “attachments” to bundles. Those are opaque file-like contents added to stores. Store attachments are handled with following goals:

  • attachment-from-tile adds store attachment from file user points at
  • attachment-to-file writes out store attachment to the file user points at
  • attachment-delete deletes a store attachment
  • attachment-list lists all store attachments

Attachments are meant to carry some “orthogonal” information to store (artifacts), like some metadata collected during the build and similar. Attachments may be handled by publisher, if it wants to. Currently no publisher handles attachments.

Hence, attachments are simply lost, for example when using sonatype-cp publisher, or when exporting store as “bundle”. It is only the “transportable bundle” that carries over attachments.

10.2 - Using it

Using Njord!

Short explanation how to use Njord. It is totally non-invasive, but still you can integrate it as well with your project. To prove it, there is example at end of this page.

There is only one required thing: the extension must be loaded when publishing. Still, the extension is non-invasive, and remains fully dormant, does not interfere with your build at all, merely defines the njord: transport.

Setting it up

Maveniverse Njord is a suite of a Maven (core or build; works both ways) extension and a Maven Plugin. You should keep the versions of extension and plugin aligned. Simplest way to achieve this is to:

  • create a property like version.njord in your parent POM carrying Njord version.
  • adding a build/pluginManagement section with Njord plugin and previous version property.
  • adding a build/extensions section with Njord extension and previous version property.

Depending on your needs, Njord can be defined in parent POMs but can also be “sideloaded” as user or project extension, maybe even only when you are about to publish (so not all the time).

If you want to add Njord to your parent POM, the recommended way is this:

  <properties>
    <version.njord>VERSION</version.njord>
  </properties>

  <build>
    <extensions>
      <extension>
        <groupId>eu.maveniverse.maven.njord</groupId>
        <artifactId>extension3</artifactId>
        <version>${version.njord}</version>
      </extension>
    </extensions>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>eu.maveniverse.maven.plugins</groupId>
          <artifactId>njord</artifactId>
          <version>${version.njord}</version>
        </plugin>
      </plugins>
    </pluginManagement>

Alternatively, with Maven 3 create project-wide, or with Maven 4+ create user-wide ~/.m2/extensions.xml like this:

<?xml version="1.0" encoding="UTF-8"?>
<extensions>
    <extension>
        <groupId>eu.maveniverse.maven.njord</groupId>
        <artifactId>extension3</artifactId>
        <version>${currentVersion}</version>
    </extension>
</extensions>

It is recommended (but not mandatory) to add this stanza to your settings.xml as well if you don’t have it already (to not type whole groupId of plugin):

  <pluginGroups>
    <pluginGroup>eu.maveniverse.maven.plugins</pluginGroup>
  </pluginGroups>

Next, set up authentication. Different publishers require different server, for example the recommended entry for Sonatype Central Portal publishing service is following stanza in your settings.xml (assuming you enabled snapshots on your namespace, and you wish directly to deploy to it, not locally stage them):

  <servers>
    <server>
      <id>sonatype-central-portal</id>
      <username>$TOKEN1</username>
      <password>$TOKEN2</password>
      <configuration>
        <njord.publisher>sonatype-cp</njord.publisher>
        <njord.releaseUrl>njord:template:release-sca</njord.releaseUrl>
      </configuration>
    </server>
  </servers>

Njord publishers

Supported publishers are:

Publisher (publisher ID)server.idWhat is needed
Black Hole (black-hole)-Like /dev/null; mainly for testing.
Resolver Installer (install)-Utilizes Maven Resolver Installer.
Resolver Deployer (deploy)-Utilizes Maven Resolver Deployer.
Sonatype Central Portal (sonatype-cp)-Obtain tokens for publishing by following this documentation.
Apache RAO on https://repository.apache.org/ (apache-rao)apache.releases.httpsObtain a token by logging in to https://repository.apache.org/#profile;User%20Token. See also the Nexus 2 Documentation.
Sonatype Nx2 “generic” (sonatype-nx2)-To be used by “private” Sonatype Nexus 2 instances; user must configure URLs at least for this publisher to be usable. See also the Nexus 2 Documentation.
Sonatype Nx3 “generic” (sonatype-nx3)-To be used by “private” Sonatype Nexus 3 instances; user must configure URLs at least for this publisher to be usable. See also the Nexus 3 Documentation.

Make sure your settings.xml contains token associated with proper server.id corresponding to the publishing service you want to use.

In case you are about to publish a project you cannot alter distribution management for some reason, and assuming Central Portal publishing is enabled for it, just add this stanza in your settings.xml:

     <server>
       <id>the-project-releases</id>
       <configuration>
         <njord.serviceRedirect>sonatype-central-portal</njord.serviceRedirect>
       </configuration>
     </server>

This basically redirects the server the-project-release (in POM that you are unable to change) to your defined sonatype-central-portal entry.

That’s all! No project change needed at all.

Using it

Next, let’s see an example of Apache Maven project (I used maven-shared-jar https://github.com/apache/maven-shared-jar/):

  1. For example’s sake, I took last release of the project (hence am simulating release deploy): git checkout maven-shared-jar-3.2.0
  2. Deploy it (locally stage): mvn -P apache-release deploy -DaltDeploymentRepository=id::njord: (The id is really unused, is there just to fulfil deploy plugin syntax requirement. The URL njord: will use “default” store template that is RELEASE. You can target other templates by using, and is equivalent of this njord:release. You can stage locally snapshots as well with URL njord:snapshot. Finally, you can target existing store with njord:store:storename-xxx).
  3. Check staged store names: mvn njord:list
  4. Optionally, check locally staged content: mvn njord:list-content -Dstore=release-xxx (use store name from above)
  5. Optionally, validate locally staged content: mvn njord:validate -Ddetails -Dstore=release-xxx (use store name from above)
  6. Publish it to ASF: mvn njord:publish -Dstore=release-xxx -Dtarget=apache-rao (use store name from above)
  7. From now on, the repository is staged on RAO, so you can close it, vote, and on vote pass, release it. All the usual fluff as before.
  8. Drop locally staged store: mvn njord:drop -Dstore=release-xxx (use store name from above)

Check out Maven generated plugin documentation for more goals.

10.3 - Configuring it

Using Njord!

Njord uses existing Maven infrastructure to get the configuration, still a bit more explanation is needed for some bits.

For start, user interacts with Njord via njord: URI using vanilla Maven plugins like maven-deploy-plugin is, and also using njord-maven-plugin goals. All the goals do not require projects to be run (and are also aggregator goals). Still, IF goals are invoked with Maven Project present (ie in a checkout where pom.xml is present, and Maven loads it) the Project will be used as “extra contextual source” for some operations.

Njord basedir

By default, Njord uses ~/.njord directory (in user home) directory as basedir. All the stores (locally staged artifacts) are here. This directory may also contain a plain Java properties file njord.properties to define some workstation-wide Njord configuration (usually not needed). The file full path is ~/.njord/njord.properties.

Njord properties

Njord merges properties from the following sources to calculate effective (configuration) properties:

  1. Maven system properties (from Java system properties and environment variables)
  2. Njord system-wide properties (from ~/.njord/njord.properties)
  3. Server configuration, only for some properties which are annotated below (from effective server with the given server id in settings.xml)
  4. Maven project properties (if present)
  5. Maven user properties

This implies, that if you want to define for example njord.dryRun property, you can achieve it in multiple ways: it is possible even to have it in (effective) Project properties set by some profile. But be warned: in this example case, the property will be defined ONLY if you invoke Njord goals in this very same project using very same active profiles! Basic Maven stuff.

Of course, the recommended way to set this very property from example is Maven user property like mvn -Dnjord.dryRun ....

Njord Server Configurations

Some properties may be added to the Maven [settings.xml] like this

    <server>
      <id>sonatype-central-portal</id>
      <username>$TOKEN1</username>
      <password>$TOKEN2</password>
      <configuration>
        <njord.publisher>sonatype-cp</njord.publisher>
        <njord.releaseUrl>njord:template:release-sca</njord.releaseUrl>
        <njord.snapshotUrl>njord:template:snapshot-sca</njord.snapshotUrl>
      </configuration>
    </server>

The server id used for the lookup is determined from project.distributionManagement.repository.id / project.distributionManagement.snapshotRepository.id.

In addition the used server can be redirected with njord.serviceRedirect (or if not set with njord.authRedirect, the latter only effective for credentials). The redirect properties (njord.serviceRedirect and njord.authRedirect) must be used exclusively inside the server configuration of settings.xml and lead to only leveraging the configuration/authentication from the server id contained in the redirect property.

Global properties

The following properties are applicable irrespective of the actual publisher being used.

NameDescriptionDefault ValueMandatoryOptionally sourced from settings.xml
njord.enabledBoolean flag determining whether Njord should be active at all.truenono
njord.dryRunBoolean flag determining whether Njord should prevent actual publishing.falsenono
njord.autoPublishBoolean flag determining whether publication should happen automatically at the end of the session.falsenono
njord.autoDropBoolean flag determining whether a local staging should be automatically dropped after publishing.truenono
njord.prefixThe prefix to use for local Njord stores/staging repositories.Determined from <top level project>.artifactIdnono
njord.publisherThe publisher to use with this repository. Supported publisher ids listed in Using it.not setyesyes
njord.releaseUrlThe url identifying the local Njord store/staging repository for release artifacts. Must always start with njord:. For details on the URI format refer to What is it.Determined from project.distributionManagement.repository.urlyesyes
njord.snapshotUrlThe url identifying the local Njord store/staging repository for SNAPSHOT artifacts. Must always start with njord:. For details on the URI format refer to What is it.Determined from project.distributionManagement.snapshotRepository.urlyes (only if Njord should be used with Snapshots, one can continue to use maven-deploy-plugin for SNAPSHOTs)yes
njord.authRedirectId of the server from which to retrieve the credentials from Maven’s settings.xml instead of the one determined by project.distributionManagement.repository.id / project.distributionManagement.snapshotRepository.id. Only used if njord.serviceRedirect is not set.-noexclusively
njord.serviceRedirectId of the server from which to retrieve Njord properties from Maven’s settings.xml instead of the one determined by project.distributionManagement.repository.id / project.distributionManagement.snapshotRepository.id.-noexclusively

Publisher specific properties

There are some properties only evaluated with certain publishers. The most relevant ones are listed below. None of them are mandatory though. For the full list look at the source code.

Sonatype Central Portal Publisher

NameAliasDescriptionDefault Value
njord.publisher.sonatype-cp.publishingTypenjord.publishingTypeEither automatic or user_managed. See https://central.sonatype.org/publish/publish-portal-api/#uploading-a-deployment-bundle for details.user_managed
njord.publisher.sonatype-cp.waitForStatesnjord.waitForStatesBoolean flag determining whether publishing should block until deployment reached the final state. Makes the publishing fail in case the final state is an error state.false

Project

Njord goals do not require project, and they can be invoked without any. But, in that case all the “heuristics” will be unavailable, and you will need to provide all the required input to goals explicitly. For example, assuming you have locally staged myproject-00001, you can still publish it by explicitly configuring publish goal from a directory where no project exists:

$ mvn njord:publish -Dstore=myproject=00001 -Dpublisher=sonatype-cp

Naturally, your user wide settings.xml should be configured for this: authentication tokens should be set for server sonatype-cp.

When project is present, it implies several things:

First, “prefix” is known (top level project artifactId), in this example case, it would be myproject. When prefix is known, Njord will use simple heuristics, and will implicitly use last (newest) store prefixed with this prefix (so if you have myproject-00001 and myproject-00002 the latter would be selected).

Second, if project is present, and if distributionManagement is configured (usually is for projects being deployed), then Njord can deduce the publisher using the server.id from POM and the server configuration present in your settings.xml.

10.4 - Migrating projects

Using Njord!

Here will try to explain required steps to migrate your project to Njord. Assuming Maven basic knowledge, and some experience about existing publishing to Central, using phased out services like Sonatype OSS or Sonatype S01 are. Also, assuming you do have a project already, set up and probably published used via these legacy services.

Setup your namespace on Sonatype portal

Not much to say here, just follow the guide. Do not forget to enable SNAPSHOTS for namespace, if you intend to use them.

Edit your settings.xml and add your tokens to it. One of the main goals of Njord is to prevent copy-paste happening in your Maven Settings. Users publishing one namespace may not experience this, but users publishing multiple namespaces are currently forced to copy-paste their auth tokens, as each project usually “invent” their own distribution management server IDs (exception is ASF, where ASF parent POM contains “well known” server ID).

Hence, Njord recommends to name and store your tokens only once in your Maven Settings (this example is for Sonatype Central Portal):

    <server>
      <id>sonatype-central-portal</id>
      <username>$TOKEN1</username>
      <password>$TOKEN2</password>
    </server>

Next, we will add a bit of Njord configuration: what publisher we want to use with this server, and what templates. Edit the server entry above to contain something like this:

    <server>
      <id>sonatype-central-portal</id>
      <username>$TOKEN1</username>
      <password>$TOKEN2</password>
      <configuration>
        <!-- Sonatype Central Portal publisher -->
        <njord.publisher>sonatype-cp</njord.publisher>
        <!-- Releases are staged locally (if omitted, would go directly to URL as per POM) -->
        <njord.releaseUrl>njord:template:release-sca</njord.releaseUrl>
        <!-- Only if you want snapshots locally staged (if omitted, would go directly to URL as per POM) -->
        <njord.snapshotUrl>njord:template:snapshot-sca</njord.snapshotUrl>
      </configuration>
    </server>

One more nit, for simplicity sake:

  <pluginGroups>
    <pluginGroup>eu.maveniverse.maven.plugins</pluginGroup>
  </pluginGroups>

To not have to type plugin groupId on each invocation (this is not mandatory, but makes life easier).

And that’s it! Your settings.xml now contains auth for Sonatype Central Portal, and also tells Njord which publisher to use with this server (it is sonatype-cp), and which templates to use.

Note: if you want to use Central Portal Snapshots feature, then don’t forget to first enable these on Portal Web UI. Next, in that case you can remove the njord.snapshotUrl element, and enjoy “direct deploy” (so Njord does not meddle, or stage snapshots). Maven will go directly for Central Portal Snapshot endpoint. Any service that supports SNAPSHOT deploy and accepts maven-deploy-plugin direct file deploy requests may be left without njord.snapshotUrl configuration as in that case that good old deploy plugin can do the job as well, no Njord needed.

Setup your project

As your project was already published to Central, the POM may contain distribution management like this:

  <distributionManagement>
    <snapshotRepository>
      <id>myproject-snapshots</id>
      <name>My Project Snapshots</name>
      <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
    </snapshotRepository>
    <repository>
      <id>myproject-releases</id>
      <name>My Project Releases</name>
      <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
    </repository>
  </distributionManagement>

You do not have to change anything!. But, it is worth to change it. For start, the URLs for releases here are “fake”, and some tools like SBOM engines cannot use them as intended, as the URL is not “where artifacts are published” (where they’ll be available for download), it is “service used to publish” instead. It is recommended to change this POM section into something like this:

  <distributionManagement>
    <snapshotRepository>
      <id>sonatype-central-portal</id>
      <name>My Project Snapshots</name>
      <url>https://central.sonatype.com/repository/maven-snapshots</url>
    </snapshotRepository>
    <repository>
      <id>sonatype-central-portal</id>
      <name>My Project Releases</name>
      <url>https://repo.maven.apache.org/maven2</url>
    </repository>
</distributionManagement>

Yes, you see it right: POM now says the truth: “we publish to Central” and “we use Sonatype Central Portal” service. Also, there is no need to distinguish server id for “release” and “snapshot”.

Finally, IF you have some existing plugin that did the job before, just remove, and undo all the hoops and loops that the plugin or tool required (like adding some properties, profiles, whatnot).

And you are done!

Extension

Finally, you need to make sure that Njord extension is loaded as extension. Ideally as POM project/build/extensions:

    <properties>
      <version.njord>VERSION</version.njord>
    </properties>

    <build>
      <extensions>
        <extension>
          <groupId>eu.maveniverse.maven.njord</groupId>
          <artifactId>extension3</artifactId>
          <version>${version.njord}</version>
        </extension>
      </extensions>
      <pluginManagement>
        <plugins>
          <plugin>
            <groupId>eu.maveniverse.maven.plugins</groupId>
            <artifactId>njord</artifactId>
            <version>${version.njord}</version>
          </plugin>
        </plugins>
      </pluginManagement>
    </build>

But you can do it as core extension, in .mvn/extensions.xml or Maven 4 user wide ~/.m2/extensions.xml:

<?xml version="1.0" encoding="UTF-8"?>
<extensions>
    <extension>
        <groupId>eu.maveniverse.maven.njord</groupId>
        <artifactId>extension3</artifactId>
        <version>VERSION</version>
    </extension>
</extensions>

Summary

To get summary, invoke mvn njord:status.

Note: this line above will work for you as-is IF you added pluginGroup to your settings.xml.

It will tell you all publishing related information about your project, even is the auth present or not (ie you may have a typo in server.id in POM or your settings.xml).

With this setup as above, one should see output like this (example is from BOM builder plugin), with added right hand “annotated explanations”:

[cstamas@angeleyes bom-builder-maven-plugin (master)]$ mvn njord:status
[INFO] Scanning for projects...
[INFO] Njord 0.6.0 session created
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO] 
[INFO] eu.maveniverse.maven.bom-builder:bom-builder                       [pom]
[INFO] eu.maveniverse.maven.plugins:bom-builder3                 [maven-plugin]
[INFO] eu.maveniverse.maven.bom-builder:it3                               [pom]
[INFO] 
[INFO] ------------< eu.maveniverse.maven.bom-builder:bom-builder >------------
[INFO] Building eu.maveniverse.maven.bom-builder:bom-builder 1.1.1-SNAPSHOT [1/3]
[INFO]   from pom.xml
[INFO] --------------------------------[ pom ]---------------------------------
[INFO] 
[INFO] --- njord:0.6.0:status (default-cli) @ bom-builder ---
[INFO] Project deployment:
[INFO]   Store prefix: bom-builder  <------------------------------------------------ store prefix, build-builder-00001, etc
[INFO] * Release
[INFO]   Repository Id: sonatype-central-portal
[INFO]   Repository Auth: Present  <------------------------------------------------- auth is present
[INFO]   POM URL: https://repo.maven.apache.org/maven2/  <--------------------------- POM "truth", once published, artifacts are here
[INFO]   Effective URL: njord:template:release-sca  <-------------------------------- The Njord URL we use when deploy releases
[INFO] - release-sca  <-------------------------------------------------------------- The template we set, detailed
[INFO]     Default prefix: 'bom-builder'
[INFO]     Allow redeploy: false
[INFO]     Checksum Factories: [SHA-512, SHA-256, SHA-1, MD5]
[INFO]     Omit checksums for: [.asc, .sigstore, .sigstore.json]
[INFO] * Snapshot
[INFO]   Repository Id: sonatype-central-portal
[INFO]   Repository Auth: Present
[INFO]   POM URL: https://central.sonatype.com/repository/maven-snapshots/  <-------- Snapshots do not use Njord, mvn deploy deploys directly Portal
[INFO] 
[INFO] No candidate artifact stores found  <----------------------------------------- Nothing has been locally staged yet
[INFO] 
[INFO] Project publishing:
[INFO] - 'sonatype-cp' -> Publishes to Sonatype Central Portal  <-------------------- The publishing service we set, detailed
[INFO]   Checksums:
[INFO]     Mandatory: SHA-1, MD5
[INFO]     Supported: SHA-512, SHA-256
[INFO]   Signatures:
[INFO]     Mandatory: GPG
[INFO]     Supported: Sigstore
[INFO]   Published artifacts will be available from:
[INFO]     RELEASES:  central @ https://repo.maven.apache.org/maven2/
[INFO]     SNAPSHOTS: sonatype-central-portal @ https://central.sonatype.com/repository/maven-snapshots
[INFO]   Service endpoints:
[INFO]     RELEASES:  sonatype-central-portal @ https://central.sonatype.com/api/v1/publisher/upload
[INFO]     SNAPSHOTS: sonatype-central-portal @ https://central.sonatype.com/repository/maven-snapshots
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary for eu.maveniverse.maven.bom-builder:bom-builder 1.1.1-SNAPSHOT:
[INFO] 
[INFO] eu.maveniverse.maven.bom-builder:bom-builder ....... SUCCESS [  0.037 s]
[INFO] eu.maveniverse.maven.plugins:bom-builder3 .......... SKIPPED
[INFO] eu.maveniverse.maven.bom-builder:it3 ............... SKIPPED
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  0.329 s
[INFO] Finished at: 2025-05-24T22:49:03+02:00
[INFO] ------------------------------------------------------------------------
[INFO] Njord session closed
[cstamas@angeleyes bom-builder-maven-plugin (master)]$ 

Publish it!

With this setup, you just perform mvn deploy as you did before. If your checkout is snapshot, you will deploy to Central Portal Snapshots. If your checkout is a release, it will be locally staged once Maven finishes.

To publish, just use mvn njord:publish, or just do mvn deploy -Dnjord.autoPublish.

Once Maven returns, your project is being validated at https://central.sonatype.com/publishing

Check out Maven generated plugin documentation for more goals.

What if don’t want (or cannot) change the POM?

In this case Njord can still be used, but the “inconvenience” is that you need to hand over all info to Njord.

The maven user settings change is mandatory, you need to have tokens set in your settings.xml.

The presence of Njord extension is mandatory as well, You can load it as user-wide extension (~/m2/extensions.xml) if you use Maven 4 or you can create (or edit if exists) project .mvn/extensions.xml.

Below I assume you work with a release checkout (ie you checked out a tag, also the “release profile” in this example follow ASF convention):

$ mvn -P apache-release deploy \                                                     1)
         -DaltDeploymentRepository=id::njord: \                                      2)
         -Dnjord.autoPublish \                                                       3)
         -Dnjord.publisher=sonatype-cp \                                             4)
         -Dnjord.publisher.sonatype-cp.releaseRepositoryId=sonatype-central-portal   5)

So what happens here? We invoke “deploy for release” (1), but using “alternate deployment repository” (2), that will create an artifact store from default template. Note that id::url form is standard format accepted by maven-deploy-plugin but the id is in fact unused, as store ID will be known only after it is created. At session end (3) the created store with deployed artifacts will be published, using specified publisher service (4) and auth material from specified server (5) in user settings.xml.

11 - Zippy

Small extension for ZIP files

Zippy is small extension for simpler working with ZIP files.

Zippy is a Maven 3.9+ extension and plugin suite for working with ZIP files as dependencies and as build output.

It provides a zip-classpath artifact handler, so dependencies of type=zip-classpath are added to the classpath. It also provides a zip handler that behaves like plain Maven (not adding ZIPs to classpath), unless the maveniverse.zippy.zip.classpath=true system property is set; for new projects the explicit zip-classpath type is recommended. Finally, it provides a zip packaging that produces a ZIP file from (optionally filtered) resources, based on maven-jar-plugin and accepting mostly the same options.

Sources: https://github.com/maveniverse/zippy

11.1 - What is it?

Embrace ZIPs

By Java spec, classpath may contain JARs, ZIPs and directories (with .class files). Maven is “not conformant” in this respect, as while it adds JAR dependencies to classpath, ZIPs are not added.

Zippy helps here.

Zippy extension provides:

  • Dependency type zip-classpath, similar to type=zip, but ZIP declared with this type is added to classpath.
  • Dependency type zip, that by default makes Maven behave same as before. But, IF you define Java System Property maveniverse.zippy.zip.classpath=true, then all dependencies of type=zip will be added to classpath. Not recommended for new projects, this is more like a hack.
  • Packaging zip, where one can create POM with <packaging>zip</packaging> and unfiltered (and filtered if configured as usual) resources from project will be just zipped up as main artifact.

To use it, just add following bits to your project .mvn/extensions.xml:

<?xml version="1.0" encoding="UTF-8"?>
<extensions>
    <extension>
        <groupId>eu.maveniverse.maven.zippy</groupId>
        <artifactId>extension3</artifactId>
        <version>${version.zippy}</version>
    </extension>
</extensions>

Naturally, this extension applies locally to project only, so it will modify ZIP file handling in situ only.

You can still produce libraries and JARs for downstream consumption that expect same behaviour, but then your consumers must use Zippy as well.

12 - DOMTrip

The lossless XML editing library for Java

Round-trip editing is a programmatic changing/editing an XML document, like for example a Maven POM is, while preserving all the formatting of the original document.

DOMTrip is a Java 8+ library for lossless XML editing. A document parsed with DOMTrip and written back out is identical to the input: comments, whitespace, entity encoding, attribute order and quote styles are all preserved. When the document is modified, only the changed parts are reformatted, following the style of the surrounding content.

The API offers fluent builders, stream-based navigation, namespace support, a built-in mini XPath (full XPath 1.0 via the domtrip-jaxen module), an XML-aware structural diff, and SAX output for interoperation with JAXP. The domtrip-maven module adds utilities specific to editing Maven POMs.

Typical use is tooling that changes human-maintained XML files, like POMs or other configuration files, where reformatting the whole file is not acceptable. Other Maveniverse projects, like Pilot, use it for POM editing.

Sources: https://github.com/maveniverse/domtrip

Site: https://maveniverse.github.io/domtrip/

13 - Maven BOMs

Generating the missing BOMs

Generating the missing BOMs for Maven versions.

Apache Maven does not publish BOMs for its own artifacts, which makes aligning versions harder when building plugins, extensions or other tools against a given Maven version. Maven BOMs generates and publishes them, per Maven version.

Three BOMs are generated for each Maven version: “skinny” (the Maven core artifacts only), “fat” (everything the Maven distribution contains, including transitive dependencies), and “plugin” (meant for plugin development, with artifacts that should not be used by plugins excluded). The BOMs are produced with BOM Builder Maven Plugin, and the build uses Nisse to drive versions from a single file containing the target Maven version.

Sources: https://github.com/maveniverse/maven-boms

14 - Maven@IPFS

Maven suite to use IPFS

Maven suite to use IPFS.

Maven@IPFS is a core extension that adds an IPFS transport to Maven Resolver. With it loaded, remote repositories can be declared with URLs of the form ipfs:/name[/subpath], where name is a CID or any IPNS-resolvable name (a key hash or a DNSLink-enabled domain).

The transport talks to an IPFS node, by default one running on localhost (for example IPFS Desktop). Consuming requires nothing more than a running node. Deploying requires the node to have a key with the same name as used in the repository URL; publishing under that name is only possible with the private key, while DNSLink gives a human-friendly domain -> IPNS -> CID indirection.

The same content is also reachable via public IPFS HTTP gateways using the plain HTTP transport, but running an own node is recommended. Requires Java 11+ and Maven 3.9+.

Sources: https://github.com/maveniverse/ipfs

15 - Scalpel

Surgical tool to speed up builds

Maven extension that detects which modules in a multi-module reactor are affected by a git changeset. Analyzes POM changes semantically — tracking property indirection, managed dependencies, plugins, and resource filtering — to avoid unnecessary rebuilds.

Scalpel is a Maven 3.9+ core extension that, given a Git changeset, determines which modules of a multi-module reactor are affected. It finds the merge base against a base branch, maps changed files to modules, and analyzes POM changes semantically, following property indirection, managed dependencies, plugins, import-scoped BOMs and resource filtering, instead of treating any POM change as a change to everything.

The result is applied according to the mode: trim (default) builds only the affected modules and their upstream and downstream dependencies, skip-tests builds everything but runs tests only in affected modules, and report writes a JSON report for CI scripts without changing the build. The shadow mode runs a full build and records what trimming would have done, to evaluate it on a given project before adopting it.

Scalpel works on CI (including shallow clones) and locally, and has a migration guide for users of gitflow-incremental-builder.

Sources: https://github.com/maveniverse/scalpel

16 - Pilot

The TUI for Maven

Interactive TUI for Maven – search, browse, and manage dependencies from the terminal.

Pilot is a Maven plugin and a standalone CLI providing interactive, keyboard-driven terminal UIs for working with Maven projects. The pilot:pilot goal opens a shell with the reactor module tree and tabs for each tool, while individual tools are also available as goals.

Tools include: Maven Central search, dependency tree browsing with conflict highlighting, raw and effective POM viewer with origin tracking, bytecode-based analysis of used and unused dependencies, dependency and plugin update checks, version conflict resolution, license and vulnerability audit (via OSV.dev), and alignment of dependency conventions across POMs. Changes to POMs are made using DOMTrip, preserving formatting and comments.

Most goals also have non-interactive report, check and fix actions for use in CI. The standalone CLI (runnable via JBang) embeds Maven 4 Resolver and does not need mvn. Requires Java 17+ and Maven 3.6.3+.

Sources: https://github.com/maveniverse/pilot

17 - Toolrunner

Toolrunner

Provides means to detect, provision and execute (via own or Java ToolProvider SPI) various tools.

Toolrunner is a library and a Maven plugin for running CLI tools as part of a build, optionally provisioning them first. Supported tools are Ant, Cosign, Gradle, isx, JBang, Maven, Minisign and the tools of the running JDK.

The core library is built on MIMA and provides a ToolManager to discover, provision and invoke tools. Tools are implemented as ToolProviders and discovered using the Java ServiceLoader. The Maven plugin itself is minimal: the tools needed are added as plugin dependencies, and are discovered dynamically.

Requires Java 8+ and, for the plugin, Maven 3.6+.

Sources: https://github.com/maveniverse/toolrunner

18 - Checksum Suite

Checksums powers to Maven!

Checksum Suite empowers Maven 3.9/Resolver 1.9 (and requires too at runtime) by adding a nearly trivial plugin to perform usual “checksum related stuff”, and an extension that provides modern cryptographically strong checksums.

Since Maven 3.9 (Resolver 1.9) checksum algorithms are pluggable via an SPI, and SHA-256 and SHA-512 are supported out of the box, but the defaults remained SHA-1 and MD5. Checksum Suite consists of a Maven plugin and a core extension, both small and without dependencies, and usable independently of each other.

The plugin lists supported checksum algorithms and calculates checksums for any file or for project artifacts, without changing Maven or Resolver configuration. The original motivation was the ASF release process, where all artifacts use the default checksums, but the source release ZIP needs a SHA-512 one.

The extension hooks into the Resolver checksum SPI and exposes every MessageDigest algorithm available in the JVM as a checksum algorithm, so newer ones like SHA-3 variants become usable. Optionally it registers the BouncyCastle provider as well, making algorithms like BLAKE2 available.

Sources: https://github.com/maveniverse/checksum

Maven generated plugin documentation

19 - MWM

Maven Workspace Manager

Maven Workspace Manager

MWM is a Maven 3.10+ core extension that makes Maven aware of “workspaces”. It inspects the Git checkout (using Nisse JGit support, but without requiring the Nisse extension), and derives a workspace ID from the remote, host, owner, repository name and current branch. Project artifacts are then installed into a workspace specific directory (by default .mwm/$workspaceId within the local repository), while the local repository itself is used as cache only.

As the workspace follows the current branch, switching branches or Git worktrees also switches the set of locally installed artifacts. After the first full mvn install on a branch, one can move between branches and run partial builds (using -f or -rf) without picking up artifacts built from another branch.

MWM steps aside if it detects advanced setups like a chained local repository. It works well combined with Mímir. See the introduction blog post for more.

Sources: https://github.com/maveniverse/mwm

20 - Muninn

Maven core extension producing compact JSON reports, for coding agents

Maven core extension producing compact JSON reports, for coding agents

Muninn is a Maven core extension for coding agents: it replaces Maven console output with a single compact JSON report at the end of the build. The full console log is still written to target/muninn-output/build.log, and the report points to it. It is inactive unless switched on, by -Dmuninn.output=json (or ndjson), the MUNINN_OUTPUT environment variable, or automatically when an agent environment is detected.

The report contains per-module results, and recognizes compile errors (with file, line and column), test failures (from Surefire and Failsafe reports), dependency resolution failures (with the repositories tried and the reason), Javadoc errors and POM problems. It also contains a resume command to continue the build from the failed module. This typically reduces output size several times compared to console output.

Muninn works with Maven 3.9 and 3.10, has no dependencies, and is recommended to be installed as user-wide extension.

Sources: https://github.com/maveniverse/muninn

21 - Huginn

Project-aware MCP server for Maven, for coding agents

Project-aware MCP server for Maven, for coding agents

Huginn is an MCP server for coding agents that answers questions about the Maven build the agent is working on: the reactor’s effective models, the repositories in use, and the resolved dependency graph, including dependencyManagement, BOMs, profiles and CI-friendly versions from .mvn/maven.config. Reactor modules that were never installed are resolved from the working tree, the same way Maven does.

It provides seven read-only tools: describe (modules or a module’s effective model), dependencies (resolved tree with conflicts), why (every path bringing an artifact in), versions (upgrade candidates from the project’s own repositories), search (Maven Central), sources (sources of a dependency) and extensions (declared core extensions, and which useful ones are missing). The number of tools is kept low on purpose, as each tool description costs agent context. Running builds is left to Maven itself, together with Muninn.

Huginn is built on MIMA and MASE, requires Java 17, and is run via JBang (jbang huginn-mcp@maveniverse).

Sources: https://github.com/maveniverse/huginn