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.
This is the multi-page printable view of this section. Click here to print.
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.
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.
We are open for contributions! All our projects are open, feel free to fork them and provide Pull Requests.
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
Maveniverse MIMA (MIni MAven) is a library that makes you able to use Resolver wherever you are, inside or outside of Maven.
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
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
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.
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:
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.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.
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.
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.
| Language | Produces | Example |
|---|---|---|
| Artifact version matcher | Predicate<Version> | and(noSnapshotsAndPreviews(), constraint('[,4)')) |
| Artifact version selector | version string | contextualSnapshotsAndPreviews(last()) |
| Artifact matcher | Predicate<Artifact> | and(artifact(org.apache.maven*), not(snapshot())) |
| Dependency matcher | Predicate<Dependency> | and(scopeIncluded(compile,runtime), optional(false)) |
| Artifact name mapper | String from artifact | compose(fixed(libs/), AbVE()) |
| Artifact mapper | Artifact → Artifact | compose(omitClassifier(), baseVersion()) |
| Dependency mapper | Dependency → Dependency | compose(scope(compile), optional(false)) |
| Artifact key factory | key String | versionlessId() |
| Artifact differentiator | key String | majorVersion() |
| Artifact source | stream of artifacts | resolveTransitive(gav(g:a:1.0), test) |
| Artifact sink | consumer of artifacts | matching(not(snapshot()), flat(target/libs)) |
| Dependency sink | consumer of dependencies | matching(scopeIncluded(test), counting()) |
A spec is a tree of operations and literals:
spec := op
op := name '(' [ arg ( ',' arg )* ] ')'
arg := op | literal
literal := bare | quoted
any() is a spec, any is not.().* : . - / \ $ { } [ ]. Whitespace outside of
quotes is ignored (also inside bare literals: a b is the same as ab).' (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.${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.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.
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.
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.
| Operation | Matches |
|---|---|
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))
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).
| Operation | Selects |
|---|---|
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()))
ArtifactMatcher — a predicate over artifacts.
| Operation | Matches |
|---|---|
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 form | Example |
|---|---|
groupId | org.apache.maven |
groupId:artifactId | org.apache.maven:maven-core |
groupId:artifactId:version | org.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()))
DependencyMatcher — a predicate over dependencies (artifact + scope + optional flag). Used by tree-related commands
(e.g. gav-tree) and by dependency sinks.
| Operation | Matches |
|---|---|
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)))
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:
| Operation | Result |
|---|---|
G() A() V() bV() C() E() | the corresponding single field |
P(key, default) | artifact property key, or default if absent |
Keys (colon separated):
| Operation | Result |
|---|---|
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):
| Operation | Result | Operation | Result |
|---|---|---|---|
GACVE() | g.a[-c]-v.e | ACVE() | a[-c]-v.e |
GACbVE() | g.a[-c]-bV.e | ACbVE() | a[-c]-bV.e |
GACE() | g.a[-c].e | AVCE() | a-v[-c].e |
GAVE() | g.a-v.e | AbVCE() | a-bV[-c].e |
GAbVE() | g.a-bV.e | ACE() | a[-c].e |
GAE() | g.a.e | AVE() | a-v.e |
AbVE() | a-bV.e | ||
AE() | a.e |
Others:
| Operation | Result |
|---|---|
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())
ArtifactMapper — transforms an artifact into another artifact. Used by mapping(...) sources/sinks.
| Operation | Result |
|---|---|
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},*,*)
DependencyMapper — transforms a dependency. Only reachable as the first argument of the mapping(...)
dependency sink.
| Operation | Result |
|---|---|
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(*:*))
ArtifactKeyFactory — computes a key used to group artifacts (e.g. --keyFactorySpec of conflict-listing commands,
default versionlessId()).
| Operation | Key |
|---|---|
id() | g:a:e[:c]:v |
baseId() | g:a:e[:c]:bV |
versionlessId() | g:a:e[:c] |
ga() | g:a |
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()).
| Operation | Value |
|---|---|
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 |
Artifacts.Source — supplies a stream of artifacts (e.g. first parameter of gav-copy). Relative paths are resolved
against the current base directory.
| Operation | Supplies |
|---|---|
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())
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.
| Operation | Does |
|---|---|
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/')
Dependencies.Sink — consumes dependencies.
| Operation | Does |
|---|---|
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 |
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
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.
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
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:
Also some consequences are:
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.
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 name | LocalNode | SystemNode | RemoteNode | Description |
|---|---|---|---|---|
file | yes | yes | no | Uses OS filesystem |
minio | yes | yes | no | Uses S3 storage |
bundle | yes | no | no | Read-only local node, backed by “bundle” ZIP files |
daemon | yes | no | no | Communicates via UDS to Mimir Daemon process |
jgroups | no | no | yes | Uses JGroups messaging w/ publishers to LAN share cache content |
ipfs | no | no | yes | Uses IPFS to WAN share cache content (not implemented yet) |
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).
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.
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).
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.
Not implemented yet
Most probably will use IPFS.
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.
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.
On hosts where there is running Docker, Tailscale etc. it may be impossible to “figure out” which interface and which address correspond to LAN address, if any. Hence, one can give Mimir a “hint” that is globally applied at Mimir level (like publishers or LAN sharing is). Accepted hints are:
match-interface:valuematch-address:valueIn both cases “value” may end with “*” (asterisk). If no asterisk, value equality is checked, if it ends with asterisk, then “starts with value” is checked.
Examples: match-interface:enp* (means “use interface whose name starts with enp”) or match-address:192.168.1.10 (means “use address that equals to 192.168.1.10”)
These hints may still produce wrong address selection, so one should check logs to ensure about them.
For the full documentation of mimir.localHostHint configuration is in Javadoc.
With these, you are fully set up. Now just go and fire up a Maven or Maven Daemon build.
TBD: explain how is Mímir used in Maven GH CI
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
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).
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
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:
| Name | Mode | Checksums Created | Signature Checked | Redeploy allowed? |
|---|---|---|---|---|
release | RELEASE | SHA-1, MD5 | GPG (Sigstore optional) | no |
release-sca | RELEASE | SHA-512, SHA-256, SHA-1, MD5 | GPG (Sigstore optional) | no |
release-redeploy | RELEASE | SHA-1, MD5 | GPG (Sigstore optional) | yes |
release-redeploy-sca | RELEASE | SHA-512, SHA-256, SHA-1, MD5 | GPG (Sigstore optional) | yes |
snapshot | SNAPSHOT | SHA-1, MD5 | GPG (Sigstore optional) | no |
snapshot-sca | SNAPSHOT | SHA-512, SHA-256, SHA-1, MD5 | GPG (Sigstore optional) | no |
njord: URINjord 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:
mvn njord:list to list existing stores, see list goalmvn njord:list-templates to list existing templates, see list-templates goalnjord base directoryBy 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.
njord bundlesNjord 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 case | bundle ZIP | transportable bundle ZIP |
|---|---|---|
| Can be published to Maven Central Portal | Yes | No (probably, unsure whar will Portal do with metadata) |
| Can be imported on another workstation | No | Yes |
| Can be “mounted” as Remote Repository by Resolver 2.x | Yes | Yes |
| Can be “overlaid” by Mimir | Yes | Yes |
Notes:
file transport supports `bundle:" protocol, see here.njord attachmentsNjord 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 atattachment-to-file writes out store attachment to the file user points atattachment-delete deletes a store attachmentattachment-list lists all store attachmentsAttachments 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.
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.
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:
version.njord in your parent POM carrying Njord version.build/pluginManagement section with Njord plugin and previous version property.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>
Supported publishers are:
| Publisher (publisher ID) | server.id | What 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.https | Obtain 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.
Next, let’s see an example of Apache Maven project (I used maven-shared-jar https://github.com/apache/maven-shared-jar/):
git checkout maven-shared-jar-3.2.0mvn -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).mvn njord:listmvn njord:list-content -Dstore=release-xxx (use store name from above)mvn njord:validate -Ddetails -Dstore=release-xxx (use store name from above)mvn njord:publish -Dstore=release-xxx -Dtarget=apache-rao (use store name from above)mvn njord:drop -Dstore=release-xxx (use store name from above)Check out Maven generated plugin documentation for more goals.
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.
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 merges properties from the following sources to calculate effective (configuration) properties:
~/.njord/njord.properties)settings.xml)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 ....
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.
The following properties are applicable irrespective of the actual publisher being used.
| Name | Description | Default Value | Mandatory | Optionally sourced from settings.xml |
|---|---|---|---|---|
njord.enabled | Boolean flag determining whether Njord should be active at all. | true | no | no |
njord.dryRun | Boolean flag determining whether Njord should prevent actual publishing. | false | no | no |
njord.autoPublish | Boolean flag determining whether publication should happen automatically at the end of the session. | false | no | no |
njord.autoDrop | Boolean flag determining whether a local staging should be automatically dropped after publishing. | true | no | no |
njord.prefix | The prefix to use for local Njord stores/staging repositories. | Determined from <top level project>.artifactId | no | no |
njord.publisher | The publisher to use with this repository. Supported publisher ids listed in Using it. | not set | yes | yes |
njord.releaseUrl | The 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.url | yes | yes |
njord.snapshotUrl | The 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.url | yes (only if Njord should be used with Snapshots, one can continue to use maven-deploy-plugin for SNAPSHOTs) | yes |
njord.authRedirect | Id 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. | - | no | exclusively |
njord.serviceRedirect | Id 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. | - | no | exclusively |
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.
| Name | Alias | Description | Default Value |
|---|---|---|---|
njord.publisher.sonatype-cp.publishingType | njord.publishingType | Either 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.waitForStates | njord.waitForStates | Boolean 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 |
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.
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.
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.
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!
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>
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)]$
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.
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.
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
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:
zip-classpath, similar to type=zip, but ZIP declared with this type is added to classpath.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.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.
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.
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.
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
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.
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
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+.
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.
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
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.
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).