This is an automated email from the ASF dual-hosted git repository.
cstamas pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git
The following commit(s) were added to refs/heads/master by this push:
new a6df0ec0 [MNGSITE-492] Maven Repositories documentation (#287)
a6df0ec0 is described below
commit a6df0ec06c78309b14df015e89c604013f69b325
Author: Tamas Cservenak <[email protected]>
AuthorDate: Tue Sep 27 08:11:13 2022 +0200
[MNGSITE-492] Maven Repositories documentation (#287)
Long missing documentation about Maven Artifact Repositories.
---
content/markdown/repositories/artifacts.md | 169 +++++++++++++++++++++
content/markdown/repositories/index.md | 55 +++++++
content/markdown/repositories/layout.md | 75 +++++++++
content/markdown/repositories/local.md | 43 ++++++
content/markdown/repositories/metadata.md | 94 ++++++++++++
content/markdown/repositories/remote.md | 74 +++++++++
.../repository/maven-central-repository.png | Bin 0 -> 80363 bytes
.../resources/repository/maven-repositories.png | Bin 80904 -> 62867 bytes
content/site.xml | 21 ++-
content/xdoc/repository/index.xml | 10 +-
.../xdoc/repository/maven-central-repository.odg | Bin 0 -> 18258 bytes
content/xdoc/repository/maven-repositories.odg | Bin 20373 -> 16327 bytes
12 files changed, 525 insertions(+), 16 deletions(-)
diff --git a/content/markdown/repositories/artifacts.md
b/content/markdown/repositories/artifacts.md
new file mode 100644
index 00000000..871570a4
--- /dev/null
+++ b/content/markdown/repositories/artifacts.md
@@ -0,0 +1,169 @@
+# Maven Artifacts
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+An Artifact is "anything" (any file) that can be addressed using its
coordinates, and Maven downloads, installs or
+deploys for you. Most of them are POMs and JARs but
+an artifact can be really anything. A very important thing about artifacts is
that they have coordinates,
+so they are not "just files", but they are files that are in some way
addressable by Maven.
+
+Artifact coordinates, are most often represented as
`groupId:artifactId:version`, or GAV in short or when
+informally used (please note that Artifact coordinates has more fields, but
for brevity we still call the
+coordinates "GAV", not "GAVCE"). The artifact coordinates uniquely describe
the artifact you are referring to,
+but does not tell anything about its source (or origin). It is up to Maven to
figure out (or you to tell Maven
+how to figure it out).
+
+A word about uniqueness: as stated above, GAV coordinates uniquely identifies
artifact, but only **within one repository**.
+It is clearly possible (but discouraged) to have multiple repositories with
overlapping content (so R1 and R2 both
+contain artifact with same GAV). If those files are not-identical (truly, ie.
hash wise), it may cause severe
+issues without you noticing it. In short, these cases should be avoided.
+
+While Maven internally uses the notion of "artifact" thoroughly (just look at
sources!), end users may never hit this term.
+That's due the fact, that while for Maven, "everything is artifact"
(internally), Maven end users actually speak about
+"projects", "parent projects", "dependencies", "build plugins", "reporting
plugins", "build extensions" and so on.
+
+## Artifact Properties
+
+The artifacts that Maven (internally) uses has following (for our topic
related) properties:
+
+| Name | Description |
+|-------------|---------------------------------------------------|
+| groupId | The artifact group |
+| artifactId | The artifact id |
+| version | The artifact version (linked w/ baseVersion) |
+| baseVersion | The artifact base version (linked w/ version) |
+| classifier | The artifact distinguishing classifier (optional) |
+| extension | The artifact extension (default: "jar") |
+
+One property worth explaining is a bit of special one: `baseVersion` that is
actually derived/linked to
+`version` (or the other way around, depending on the context): for release
artifacts, it holds the same value as
+`version`, whereas for snapshot artifacts, it holds the "non-timestamped
snapshot version". For example,
+for snapshot version "1.0-20220119.164608-1", the `baseVersion` would have the
value "1.0-SNAPSHOT".
+So, `version` and `baseVersion` are linked, derived from each other, but
**they have different values only in
+case of snapshots**.
+
+Important note about Artifacts: the fact is an artifact a snapshot or not,
should be queried with method
+`Artifact#isSnapshot()`.
+
+## But where do I set Artifact extension?
+
+In short, nowhere. Or maybe "you rarely have to". Maven POM (where you declare
your project, parent project,
+dependencies, plugins and other), maps those elements onto artifact
coordinates with some extra logic.
+
+In case of "project" and "parent project" aka POMs (after POM made into
effective POM, ie. parent values inherited):
+
+| Artifact Property | Project POM (pom.xml) | POM Artifact |
+|-------------------|-----------------------|----------------|
+| groupId | `project/groupId` | -> groupId |
+| artifactId | `project/artifactId` | -> artifactId |
+| version | `project/version` | -> version |
+| classifier | - | "" (always) |
+| extension | - | `pom` (always) |
+
+In case of "build plugins" and "build extensions", as they are JARs, this is
how corresponding elements are mapped
+(for build extension change the XML path prefix to
`project/build/extensions/extension[x]`):
+
+| Artifact Property | Plugin in Project POM |
Plugin/Extension Artifact |
+|-------------------|----------------------------------------------|---------------------------|
+| groupId | `project/build/plugins/plugin[x]/groupId` | ->
groupId |
+| artifactId | `project/build/plugins/plugin[x]/artifactId` | ->
artifactId |
+| version | `project/build/plugins/plugin[x]/version` | ->
version |
+| classifier | - | -> ""
(always) |
+| extension | - | -> `jar`
(always) |
+
+And finally, in case of "dependencies", this is the mapping (no, scope is NOT
part of artifact coordinates):
+
+| Artifact Property | Dependency in Project POM |
Dependency Artifact |
+|-------------------|-------------------------------------------------|-------------------------------------------|
+| groupId | `project/dependencies/dependency[x]/groupId` | ->
groupId |
+| artifactId | `project/dependencies/dependency[x]/artifactId` | ->
artifactId |
+| version | `project/dependencies/dependency[x]/version` | ->
version |
+| classifier | `project/dependencies/dependency[x]/classifier` | ->
classifier |
+| extension | `project/dependencies/dependency[x]/type` | ->
type handler provided, or same as type |
+
+Here, we need to make a short detour to explain "type" (of a dependency) and
how it becomes artifact extension.
+
+Maven for dependencies defines "type", that describes what that dependency is
(should it be added to classpath and
+many other things). Plugins and extensions may define new types, that is
usually a must for plugins introducing
+a "packaging" (lifecycle mapping) by providing `ArtifactHandler` components
with name corresponding to type name.
+
+Maven Core out of the box defines following "types" (handled by same named
`ArtifactHandler` components):
+
+| Type Name | Extension | Classifier |
+|--------------|-----------|--------------|
+| pom | `pom` | |
+| jar | `jar` | |
+| maven-plugin | `jar` | |
+| ear | `ear` | |
+| ejb | `jar` | |
+| ejb-client | `jar` | `ejb-client` |
+| javadoc | `jar` | `javadoc` |
+| java-source | `jar` | `sources` |
+| rar | `rar` | |
+| test-jar | `jar` | `tests` |
+| war | `war` | |
+| **any** | any | |
+
+From table above, we can see that if we define the dependency type as "war",
we will hit the "war" handler, that will
+result in using the `war` extension (which may not be obvious, as the type and
extension we end up with are the same, but internally this
+indirection does happen). The "test-jar" is more obvious, as it translates to
`jar` extension. Finally, the **any**
+last row will be used if none above matches, hence in that case your "type" is
used just as "extension", for example
+you can write `<type>tar.gz</type>` for dependency, and you will end up with
extension `tar.gz` (all this happens
+because as there is no artifact handler named "tar.gz" in table above). Still,
you should be aware that this table
+above may be extended by various plugins and extensions you use in your build!
+
+Also, this has "interesting" consequences, consider for example following
Artifact:
+`org.project:reusable-test-support:1.0:tests:jar`. With type handlers above,
maybe surprisingly, the dependency to
+this very same artifact can be described in two ways:
+
+```
+<dependency>
+ <groupId>org.project</groupId>
+ <artifactId>reusable-test-support</artifactId>
+ <version>1.0</version>
+ <classifier>tests</classifier>
+</dependency>
+```
+
+and the equivalent dependency would be:
+
+```
+<dependency>
+ <groupId>org.project</groupId>
+ <artifactId>reusable-test-support</artifactId>
+ <version>1.0</version>
+ <type>test-jar</type>
+</dependency>
+```
+
+Obvious difference is presence of `classifier` in first case, while in second
lack of it but presence of `type` "test-jar",
+that in the other hand, implies classifier of "tests". In both cases,
extension is "jar" (in first it uses the default
+value for this property, while in second type defines it).
+
+Note: In this very case, using the first way is somewhat "explicit", and is
recommended way. Not so for the
+cases when type handler carries some important extra information (like some
custom packaging), where using `type`
+is more appropriate. Simply put, in this case the type "test-jar" is like an
alias for ordinary JARs with "tests"
+classifier.
+
+## Summary
+
+In short, this is how various Maven bits like "project", "parent project",
"plugin", "extension" and "dependency"
+have artifact coordinates mapped from POM elements. Using this knowledge, we
can always deduce the artifact coordinate
+of these POM elements.
diff --git a/content/markdown/repositories/index.md
b/content/markdown/repositories/index.md
new file mode 100644
index 00000000..4bc6aa8c
--- /dev/null
+++ b/content/markdown/repositories/index.md
@@ -0,0 +1,55 @@
+# Maven Repositories
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+Apache Maven uses repositories to store artifacts. Your dependencies are being
downloaded from repositories,
+and artifacts you build are being stored (installed, uploaded) into
repositories as well. This is one of the
+fundamental concepts of Maven since its inception: Maven command line tool and
Maven Repositories were mold together
+and developed since the beginning of Maven project itself.
+
+<p align="center">
+<img src="../repository/maven-repositories.png" border="0" usemap="#map" />
+
+<map name="map">
+ <area shape="rect" coords="596,326,666,363" alt="JBoss"
href="http://repository.jboss.org/maven2/"; />
+ <area shape="rect" coords="0,184,460,421" alt="central (default)"
href="../repository/index.html" />
+ <area shape="rect" coords="187,593,277,629" alt="Maven"
href="/what-is-maven.html" />
+ <area shape="rect" coords="280,628,403,649" alt="local repository"
href="/guides/mini/guide-configuring-maven.html" />
+ <area shape="rect" coords="364,498,570,534" alt="Repository Manager"
href="/repository-management.html" />
+ <area shape="rect" coords="303,545,451,584" alt="settings.xml
<mirrorOf>" href="/guides/mini/guide-mirror-settings.html" />
+ <area shape="rect" coords="407,589,628,653" alt="pom.xml <repository>"
href="/guides/mini/guide-multiple-repositories.html" />
+</map>
+
+</p>
+
+See also the [Introduction to
Repositories](/guides/introduction/introduction-to-repositories.html) and
[Repository Layout](../repository/layout.html).
+
+As you may know, Maven addresses artifacts using artifact coordinates. The
artifact coordinates uniquely describe the artifact
+you are referring to, but does not tell anything about its source (or origin).
This is where
+Maven Repositories come into picture, that holds the artifacts laid out
(published) according to Maven Repository
+Layout. And this is where the circle closes: artifacts, being laid out in
defined layout, consumed and published
+by Maven.
+
+Sections:
+* [Artifacts](artifacts.md)
+* [Metadata](metadata.md)
+* [Layout](layout.md)
+* [Local Repositories](local.md)
+* [Remote Repositories](remote.md)
diff --git a/content/markdown/repositories/layout.md
b/content/markdown/repositories/layout.md
new file mode 100644
index 00000000..ed0336c4
--- /dev/null
+++ b/content/markdown/repositories/layout.md
@@ -0,0 +1,75 @@
+# Maven Repository Layout
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+The layout is responsible for translating the [artifact
coordinates](artifacts.md) into generic paths, that is later used to construct
some
+URI (file path, URL, it depends on context). Obviously, since Maven inception
in 2002 the layout evolved as well.
+For simplicity, we will cover current layout (aka "maven2" or "default"), as
since Maven 3.x release, the deprecated
+"Maven1 layout" (aka "legacy") is not supported anymore.
+
+This above implies following: if the repository contains a file that is "not
on layout" (does not obey layout
+transformation rules discussed below), that file is "not addressable" by Maven
coordinates, you cannot address that file
+in Maven nor make it to download it using GAV coordinates!
+
+The original premise of layout was simplicity: from historical perspective, a
remote repository was expected to be run
+by some computer with file storage (where artifacts were laid down) and served
by a HTTP server, essentially publishing
+the files on file paths for consumption (mainly for HTTP GET requests).
+
+The transformation rule is quite simple for that matter: consider artifact
properties below:
+
+| Name | Transformation |
Result example |
+|-------------|---------------------------------------------------------|------------------------------------------|
+| groupId | Replace "." (dot) characters with "/" (slash) character |
`org.apache.maven` -> `org/apache/maven` |
+| artifactId | none |
`apache-maven` -> `apache-maven` |
+| version | none |
`3.8.4` -> `3.8.4` |
+| baseVersion | none | (in
this example same as version) |
+| classifier | none |
`bin` -> `bin` |
+| extension | none |
`tar.gz` -> `tar.gz` |
+
+And using these properties transformed as above we can construct following
path (if classifier not present):
+
+```
+${groupId}/${artifactId}/${baseVersion}/${artifactId}-${version}.${extension}
+```
+
+or if classifier present:
+
+```
+${groupId}/${artifactId}/${baseVersion}/${artifactId}-${version}-${classifier}.${extension}
+```
+
+So the example artifact above noted as GAV:
+
+```
+org.apache.maven:apache-maven:3.8.4:bin:tar.gz
+```
+
+is translated to path as:
+
+```
+org/apache/maven/apache-maven/3.8.4/apache-maven-3.8.4-bin.tar.gz
+```
+
+And that is it! By applying this "algorithm" above to ANY Artifact we can
build up the path segment that
+artifact is expected to be.
+
+Important note: in case of locally installed artifacts (those you built
locally and invoked `mvn install`) will use
+Artifact baseVersion property instead of version. The full-blown "timestamped"
versions are used only in
+remote repositories, when the artifact is deployed.
diff --git a/content/markdown/repositories/local.md
b/content/markdown/repositories/local.md
new file mode 100644
index 00000000..6b39ae25
--- /dev/null
+++ b/content/markdown/repositories/local.md
@@ -0,0 +1,43 @@
+# Maven Local Repositories
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+The local repository is a mixed bag, in sense, that it serves two purposes: it
caches downloaded artifacts from
+remote repositories along with locally built and installed ones.
+
+While the local repository does reside on local filesystem, users should
**never** reach for its contents directly
+using plain file operations, but use the provided API instead. Reason for this
strict expectation is that even
+today different implementations of local repository exists. Hence, "reverse
engineering" the layout and direct
+access to locally cached or installed files may not only break in the future,
but may also circumvent important
+aspects like locking and synchronization, and so forth. Latest resolver even
implements "split" local repository,
+where user may configure local repository to split the installed and cached
artifacts, hence to make them physically
+split from each other.
+
+All these underlying changes remain hidden from code using local repository
API, and hence, the code will
+be more robust and time proof.
+
+## The `baseVersion` Artifact Property
+
+As noted in [Layout](layout.md) page, locally built and installed (implies "to
local repository") artifacts will use
+`baseVersion` while calculating layout. Hence, in this case both,
`baseVersion` and `version` of them will both
+contain same value, the one ending with "SNAPSHOT" constant string, no
transformation is applied to file name.
+
+Snapshots pulled from remote and cached in local repository will have
timestamped `version` property instead, hence
+they will have the full-blown timestamped version applied to file name.
diff --git a/content/markdown/repositories/metadata.md
b/content/markdown/repositories/metadata.md
new file mode 100644
index 00000000..0f2e2aed
--- /dev/null
+++ b/content/markdown/repositories/metadata.md
@@ -0,0 +1,94 @@
+# Maven Metadata
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+Repositories contain metadata (aka "repository metadata") files as well, that
enables several "discovery" and "resolution"-like operations
+for Maven. These metadata files are **not** Artifacts, and hence, are not
addressable by Maven users. They are instead
+transparently operated and handled by Maven itself in automatic manner. These
files are XML files named as
+`maven-metadata.xml` (are deployed with checksums just like artifacts are).
+
+Links:
+* [XML Schema](/xsd/repository-metadata-1.1.0.xsd)
+* [Modello
model](https://gitbox.apache.org/repos/asf?p=maven.git;a=blob_plain;f=maven-repository-metadata/src/main/mdo/metadata.mdo;hb=HEAD)
+
+We distinguish 3 different kinds of metadata files (using GAV coordinates):
+* G level metadata
+* A level metadata
+* V level metadata
+
+These metadata XML files share same XML schema (model), and the reason of that
is simple: one XML file may carry multiple
+kinds of metadata (for different Artifacts)! Consider these two artifacts:
`org.foo:bar:1.0` and `org.foo.bar:baz:1.0`.
+With default layout, the repository path `org/foo/bar` is once A level for
first, and G level for second artifact.
+Note: this is extreme example, and such artifact naming should be avoided!
+
+## The G Level Metadata
+
+| What | How |
+|----------------------------|-------------------------------|
+| Location | Path corresponding to groupId |
+| Repositories containing it | Release and Snapshots |
+| Artifacts related to them | Only `maven-plugin` packaged |
+
+The group level metadata (found in directory of groupId) serves purpose only
in case of Maven Plugins
+(POM packaging: maven-plugin). This metadata contains mapping of `plugin
prefix` to `artifactId`, and the XML bit
+considered for this kind of metadata is `metadata/plugins/plugin[]` path only.
+
+Example:
https://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-metadata.xml
+
+When user uses some plugin prefix on CLI, Maven will go through registered
`pluginGroups` groupIds, download their
+G level metadata, and look for prefix. If found, Maven has obtained G (from
pluginGroups) and A (from metadata)
+coordinates of plugin, and will go for given version, or attempt to discover
"latest" version.
+
+## The A Level Metadata
+
+| What | How |
+|----------------------------|----------------------------------|
+| Location | Path corresponding to artifactId |
+| Repositories containing it | Release and Snapshots |
+| Artifacts related to them | All |
+
+The artifactId level metadata (found in directory of artifactId) serves
purpose of version discovery. This metadata
+contains list of versions of given GA coordinates. The XML bit considered for
this kind of metadata are only:
+* `metadata/groupId`
+* `metadata/artifactId`
+* `metadata/versionining/latest`
+* `metadata/versionining/release`
+* `metadata/versionining/versions/*`
+* `metadata/versionining/lastUpdated`
+
+Example:
https://repo.maven.apache.org/maven2/org/apache/maven/plugins/maven-jar-plugin/maven-metadata.xml
+
+## The V Level Metadata
+
+| What | How |
+|----------------------------|-----------------------------------|
+| Location | Path corresponding to baseVersion |
+| Repositories containing it | Snapshots only |
+| Artifacts related to them | Only Snapshots |
+
+Exists only in Snapshot Remote repositories. The version level metadata (found
in directory of baseVersion) serves the
+purpose of snapshot timestamped version resolution. This metadata contains
mapping of all artifacts in this baseVersion
+directory with corresponding timestamps. The XML bit considered for this kind
of metadata are only:
+* `metadata/groupId`
+* `metadata/artifactId`
+* `metadata/versionining/snapshot/*`
+* `metadata/versionining/snapshotVersions/*`
+
+Example:
https://repository.apache.org/content/repositories/snapshots/org/apache/maven/plugins/maven-jar-plugin/3.3.0-SNAPSHOT/maven-metadata.xml
diff --git a/content/markdown/repositories/remote.md
b/content/markdown/repositories/remote.md
new file mode 100644
index 00000000..c64e835e
--- /dev/null
+++ b/content/markdown/repositories/remote.md
@@ -0,0 +1,74 @@
+# Maven Remote Repositories
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+Remote repositories usually refer to repositories like [Maven Central
Repository](/repository/index.html). These
+repositories are holding the artifacts to be consumed by Maven builds.
+
+The two most important properties of remote repositories are:
+* baseURL
+* repository policy
+
+In essence, Maven using [Layout](layout.md) produces relative paths for
[Artifacts](artifacts.md), that in turn are
+resolved against baseURL of Remote Repositories ending in absolute URLs. The
policy decides should a release or snapshot
+artifact looked for in given repository.
+
+## The `baseVersion` Artifact Property
+
+In case of snapshot artifacts (hence Snapshot Remote Repositories implied) we
already hinted that some
+sort of "version transformation" happens. We can distinguish two cases:
+
+### Deploying Snapshot Artifact
+
+Your POM locally usually contains snapshot versions in a form of a string that
ends with "SNAPSHOT" constant string
+(for example "1.0-SNAPSHOT"). But, in case of deploy, this version is being
transformed to a "timestamped snapshot"
+on the fly (by Maven) and when you check the deployed result, you will see
that artifact file does not end up with
+"SNAPSHOT" anymore, but a timestamp and build number. Also, during deploy,
Maven will deploy required Maven V Level Metadata
+as well that will describe for consumers of this snapshot how to "reverse"
this process.
+
+So, in case of snapshot deploy, version transformation happens in form of:
+```
+1.0-SNAPSHOT -> Maven (on the fly) -> 1.0-${YYYYMMDD.HHMMSS}-${counter}
+```
+Where the date in `Etc/UTC` timezone (used in `YYYYMMDD.HHMMSS` format) is
constant across deploy from same session (is time when Maven
+Session was created), and counter is increased counter from previously
deployed metadata (or if no
+remote metadata exists, is initialized with 1).
+
+### Consuming Snapshot Artifacts
+
+If your project depends on SNAPSHOT dependencies, the POM of your project
usually contains `version` value that ends
+with "SNAPSHOT" (for example "1.0-SNAPSHOT"), still, as we see above, remote
repositories do NOT contain such versions,
+but only timestamped ones. Maven snapshots are "moving targets", hence,
during resolution Maven
+will use the deployed metadata first, to figure out `baseVersion` -> `version`
(timestamped) mapping, and only then
+will fetch the required files.
+
+In case of consuming snapshot, the following transformation happens:
+```
+1.0-SNAPSHOT -> Remote V Level Repository Metadata -> 1.0-YYYYMMDD.HHMMS-X
+```
+
+Due this indirection (the real filename of artifact, the version part) is
figured from deployed maven repository metadata,
+the snapshot artifacts are "moving target": each snapshot deploy as above will
deploy new and new metadata, hence, will
+alter this transformation here (Maven will download different and different
snapshot artifact).
+
+Note: it is possible to "lock down" snapshot artifacts, by using timestamped
version in version field of a dependency,
+and it will ensure Maven downloads always same artifact (is not "moving
target" anymore), but **Maven will still consider
+that dependency as snapshot**, and all the fine print applies (for example,
release plugin will refuse to release such
+a project).
diff --git a/content/resources/repository/maven-central-repository.png
b/content/resources/repository/maven-central-repository.png
new file mode 100644
index 00000000..9cc719da
Binary files /dev/null and
b/content/resources/repository/maven-central-repository.png differ
diff --git a/content/resources/repository/maven-repositories.png
b/content/resources/repository/maven-repositories.png
index 6c4ad189..73573aca 100644
Binary files a/content/resources/repository/maven-repositories.png and
b/content/resources/repository/maven-repositories.png differ
diff --git a/content/site.xml b/content/site.xml
index 718c02a7..b2e33af2 100644
--- a/content/site.xml
+++ b/content/site.xml
@@ -64,7 +64,7 @@ under the License.
<menu name="Documentation">
<item name="Maven Plugins" href="/plugins/index.html" />
- <item name="Maven Extensions" href="/extensions/index.html" />
+ <item name="Maven Extensions" href="/extensions/index.html" />
<item name="Index (category)" href="/guides/index.html" />
<item name="User Centre" href="/users/index.html" collapse="true">
@@ -144,12 +144,19 @@ under the License.
<item name="Plexus Javadoc to Plexus Annotations"
href="/plugin-developers/cookbook/plexus-plugin-upgrade.html" />
<item name="Using JSR-330" href="/maven-jsr330.html" />
</item>
- <item name="Maven Central Repository" href="/repository/index.html"
collapse="true">
- <item name="Maintaining your Metadata" href="/project-faq.html" />
- <item name="Guide to Uploading Artifacts"
href="/repository/guide-central-repository-upload.html" />
- <item name="Fixing Metadata" href="/repository/central-metadata.html"
/>
- <item name="Central Index" href="/repository/central-index.html" />
- <item name="Repository Layout" href="/repository/layout.html" />
+ <item name="Maven Repository Centre" href="/repositories/index.html"
collapse="true">
+ <item name="Maven Central Repository" href="/repository/index.html"
collapse="true">
+ <item name="Maintaining your Metadata" href="/project-faq.html" />
+ <item name="Guide to Uploading Artifacts"
href="/repository/guide-central-repository-upload.html" />
+ <item name="Fixing Metadata"
href="/repository/central-metadata.html" />
+ <item name="Central Index" href="/repository/central-index.html" />
+ <item name="Repository Layout" href="/repository/layout.html" />
+ </item>
+ <item name="Maven Artifacts" href="/repositories/artifacts.html" />
+ <item name="Maven Metadata" href="/repositories/metadata.html" />
+ <item name="Maven Layout" href="/repositories/layout.html" />
+ <item name="Maven Local Repository" href="/repositories/local.html" />
+ <item name="Maven Remote Repositories"
href="/repositories/remote.html" />
</item>
<item name="Maven Developer Centre" href="/developers/index.html"
collapse="true">
<item name="Guide to Helping with Maven"
href="/guides/development/guide-helping.html" />
diff --git a/content/xdoc/repository/index.xml
b/content/xdoc/repository/index.xml
index dd464896..e883021e 100644
--- a/content/xdoc/repository/index.xml
+++ b/content/xdoc/repository/index.xml
@@ -49,29 +49,21 @@
<!-- TODO: more documents to link to here. Use the navigation cues (how to
upload, how to mirror, etc). -->
<p align="center">
- <img src="maven-repositories.png" width="764" height="654" border="0"
usemap="#map" />
+ <img src="maven-central-repository.png" border="0" usemap="#map" />
<map name="map">
<area shape="rect" coords="0,0,189,128" alt="standalone public
artifact repositories"
href="/guides/introduction/introduction-to-repositories.html" />
<area shape="rect" coords="264,76,354,111" alt="Apache"
href="https://repository.apache.org/content/groups/public/"; />
<area shape="rect" coords="378,76,468,111" alt="OSSRH"
href="https://central.sonatype.org/pages/ossrh-guide.html"; />
<area shape="rect" coords="490,75,520,111" alt="Producers"
href="https://central.sonatype.org/pages/producers.html"; />
- <area shape="rect" coords="596,326,666,363" alt="JBoss"
href="http://repository.jboss.org/maven2/"; />
<area shape="rect" coords="329,274,426,312" alt="central index"
href="./central-index.html" />
<area shape="rect" coords="39,274,205,314" alt="archetype"
href="/archetype/archetype-models/archetype-catalog/archetype-catalog.html" />
<area shape="rect" coords="65,348,205,383" alt="repo"
href="https://repo.maven.apache.org/maven2/"; />
<area shape="rect" coords="292,356,365,391" alt="ibiblio"
href="http://mirrors.ibiblio.org/pub/mirrors/maven2/"; />
<area shape="rect" coords="373,356,447,391" alt="Google"
href="https://storage-download.googleapis.com/maven-central/index.html"; />
<area shape="rect" coords="100,126,424,239" alt="Central Upload"
href="./guide-central-repository-upload.html" />
- <area shape="rect" coords="0,184,460,421" alt="central (default)"
href="/guides/introduction/introduction-to-the-pom.html" />
- <area shape="rect" coords="187,593,277,629" alt="Maven"
href="/what-is-maven.html" />
- <area shape="rect" coords="280,628,403,649" alt="local repository"
href="/guides/mini/guide-configuring-maven.html" />
- <area shape="rect" coords="364,498,570,534" alt="Repository Manager"
href="/repository-management.html" />
- <area shape="rect" coords="303,545,451,584" alt="settings.xml
<mirrorOf>" href="/guides/mini/guide-mirror-settings.html" />
- <area shape="rect" coords="407,589,628,653" alt="pom.xml
<repository>" href="/guides/mini/guide-multiple-repositories.html" />
</map>
</p>
- <p>See also the <a
href="/guides/introduction/introduction-to-repositories.html">Introduction to
Repositories</a> and <a href="./layout.html">Repository Layout</a>.</p>
</section>
</body>
</document>
diff --git a/content/xdoc/repository/maven-central-repository.odg
b/content/xdoc/repository/maven-central-repository.odg
new file mode 100644
index 00000000..e97f6ac7
Binary files /dev/null and
b/content/xdoc/repository/maven-central-repository.odg differ
diff --git a/content/xdoc/repository/maven-repositories.odg
b/content/xdoc/repository/maven-repositories.odg
index 9df0526e..75b01d09 100644
Binary files a/content/xdoc/repository/maven-repositories.odg and
b/content/xdoc/repository/maven-repositories.odg differ
