You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by hb...@apache.org on 2022/02/03 07:09:43 UTC
[maven-site] branch maven-repository-layout updated (8be0394 -> 0bbb3d3)
This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a change to branch maven-repository-layout
in repository https://gitbox.apache.org/repos/asf/maven-site.git.
omit 8be0394 Add examples, note about locally installed snapshots
omit 75ec89b WIP
omit 728e395 WIP
omit 093a4a4 WIP
omit dd4561b WIP
omit fa407ff WIP
omit cd556f8 Initial draft layout
add b9e4e4c replace <x> with ${x} to avoid confusion with XML element
add 22f23df section about extensions and classifiers
add 022bb4b HTTP(S) specific support
add a25fcd2 Git commit timestamp strategy
add 4405359 Release maven-dependency-analyzer 1.12.0
add f887c28 improve remote repository layout documentation
add f890944 center image
new 1df2dad Initial draft layout
new 6bf4d8b WIP
new 4ef74cc WIP
new cc5d3ac WIP
new f3e4dea WIP
new d345620 WIP
new 0bbb3d3 Add examples, note about locally installed snapshots
This update added new revisions after undoing existing revisions.
That is to say, some revisions that were in the old version of the
branch are not in the new version. This situation occurs
when a user --force pushes a change and generates a repository
containing something like this:
* -- * -- B -- O -- O -- O (8be0394)
\
N -- N -- N refs/heads/maven-repository-layout (0bbb3d3)
You should already have received notification emails for all of the O
revisions, and so the following emails describe only the N revisions
from the common base, B.
Any revisions marked "omit" are not gone; other references still
refer to them. Any revisions marked "discard" are gone forever.
The 7 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.../apt/guides/mini/guide-reproducible-builds.apt | 6 +-
content/apt/shared/index.apt | 2 +-
content/markdown/repository/layout.md | 65 ++++++++++++++--------
content/xdoc/repository/index.xml | 4 +-
4 files changed, 50 insertions(+), 27 deletions(-)
[maven-site] 07/07: Add examples, note about locally installed snapshots
Posted by hb...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch maven-repository-layout
in repository https://gitbox.apache.org/repos/asf/maven-site.git
commit 0bbb3d39cb7fae856bce8a1b7191a4e4d15522d4
Author: Tamas Cservenak <ta...@cservenak.net>
AuthorDate: Wed Feb 2 10:42:36 2022 +0100
Add examples, note about locally installed snapshots
---
content/markdown/repositories/layout.md | 7 ++++++
content/markdown/repositories/local.md | 4 ++++
content/markdown/repositories/remote.md | 39 ++++++++++++++++++++++++++++++++-
3 files changed, 49 insertions(+), 1 deletion(-)
diff --git a/content/markdown/repositories/layout.md b/content/markdown/repositories/layout.md
index 19dae2f..00b5529 100644
--- a/content/markdown/repositories/layout.md
+++ b/content/markdown/repositories/layout.md
@@ -71,6 +71,10 @@ 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, 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.
+
# A word about Maven1 layout
Maven1 aka "legacy" layout **is unsupported since Maven 3.x** (Maven 2.x supported it to ease transition from 1.x to
@@ -105,3 +109,6 @@ is translated to path:
```
org.apache.maven/poms/apache-maven-3.8.4.pom
```
+
+Easy to spot, that `org.apache.maven/poms` directory will become a file system issue, as that directory
+may potentially contain way too much files.
\ No newline at end of file
diff --git a/content/markdown/repositories/local.md b/content/markdown/repositories/local.md
index 597238c..345805b 100644
--- a/content/markdown/repositories/local.md
+++ b/content/markdown/repositories/local.md
@@ -21,3 +21,7 @@ under the License.
The local repository is mixed bag, in sense, that it serves two purposes: it caches downloaded artifacts from
remote repositories along with locally built and installed ones.
+
+As noted on [Layout](layout.md) page, locally built and installed artifacts with use baseVersion while calculating
+layout. Snapshots pulled from remote will use version property instead, hence they will have the full-blown
+"timestamped" version format applied.
diff --git a/content/markdown/repositories/remote.md b/content/markdown/repositories/remote.md
index beaa4c4..d1438a7 100644
--- a/content/markdown/repositories/remote.md
+++ b/content/markdown/repositories/remote.md
@@ -19,5 +19,42 @@ specific language governing permissions and limitations
under the License.
-->
-Remote repositories usually referrers to repositories like [Maven Central Repository](/repository/index.html) is. These
+Remote repositories usually refers to repositories like [Maven Central Repository](/repository/index.html) is. These
repositories are holding the artifacts to be consumed by Maven builds.
+
+## Example
+
+Let's determine the full URL of following dependency:
+
+```
+ <dependency>
+ <groupId>org.apache.maven</groupId>
+ <artifactId>maven-plugin-api</artifactId>
+ <version>3.8.1</version>
+ <scope>provided</scope>
+ </dependency>
+```
+
+As we have seen, if no type given for dependency, it defaults to "jar", and also scope does not takes part in layout,
+hence we have the following artifact properties:
+
+| Project | Artifact |
+|------------|-----------------------|
+| groupId | -> "org.apache.maven" |
+| artifactId | -> "maven-plugin-api" |
+| version | -> "3.8.1" |
+| classifier | -> "" (none) |
+| extension | -> "jar" (defaulted) |
+
+Applying layout, we end up with following path:
+
+```
+org/apache/maven/maven-plugin-api/3.8.1/maven-plugin-api-3.8.1.jar
+```
+
+And finally, by prepending remote repository baseUrl (as defined in repository POM section) we can calculate the
+final absolute URL that this JAR can be pulled from:
+
+https://repo.maven.apache.org/maven2/org/apache/maven/maven-plugin-api/3.8.1/maven-plugin-api-3.8.1.jar
+
+
[maven-site] 05/07: WIP
Posted by hb...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch maven-repository-layout
in repository https://gitbox.apache.org/repos/asf/maven-site.git
commit f3e4deac204cf6e22f7fb86ff4611f50293f9d71
Author: Tamas Cservenak <ta...@cservenak.net>
AuthorDate: Wed Jan 19 17:09:37 2022 +0100
WIP
---
content/markdown/repositories/index.md | 22 +++++++++++-----------
1 file changed, 11 insertions(+), 11 deletions(-)
diff --git a/content/markdown/repositories/index.md b/content/markdown/repositories/index.md
index 66c3b9e..848be72 100644
--- a/content/markdown/repositories/index.md
+++ b/content/markdown/repositories/index.md
@@ -62,8 +62,8 @@ of "project" and "parent project" (aka POMs):
| groupId | -> groupId |
| artifactId | -> artifactId |
| version | -> version |
-| classifier | empty |
-| extension | "pom" |
+| classifier | -> empty |
+| extension | -> "pom" |
In case of "build plugins" and "build extensions", as they are JARs, this is how corresponding elements are mapped:
@@ -72,17 +72,17 @@ In case of "build plugins" and "build extensions", as they are JARs, this is how
| groupId | -> groupId |
| artifactId | -> artifactId |
| version | -> version |
-| classifier | empty |
-| extension | "jar" |
+| classifier | -> empty |
+| extension | -> "jar" |
And finally, in case of "dependencies", this is the mapping:
-| Dependency | Artifact |
-|------------|------------------------------------------|
-| groupId | -> groupId |
-| artifactId | -> artifactId |
-| version | -> version |
-| classifier | -> classifier |
-| type | -> type handler provided or same as type |
+| Dependency | Artifact |
+|------------|-------------------------------------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> classifier |
+| type | -> type handler provided, or same as type |
Here, we need to make a short turn to explain "type" (of a dependency) and how it becomes artifact extension.
[maven-site] 01/07: Initial draft layout
Posted by hb...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch maven-repository-layout
in repository https://gitbox.apache.org/repos/asf/maven-site.git
commit 1df2dadda847df8e153e829eef7fd294a901e1dd
Author: Tamas Cservenak <ta...@cservenak.net>
AuthorDate: Wed Jan 19 15:10:37 2022 +0100
Initial draft layout
---
content/markdown/repositories/index.md | 32 ++++++++++++++++++++++++++++++++
content/markdown/repositories/layout.md | 31 +++++++++++++++++++++++++++++++
content/markdown/repositories/local.md | 23 +++++++++++++++++++++++
content/markdown/repositories/remote.md | 23 +++++++++++++++++++++++
content/site.xml | 7 ++++++-
5 files changed, 115 insertions(+), 1 deletion(-)
diff --git a/content/markdown/repositories/index.md b/content/markdown/repositories/index.md
new file mode 100644
index 0000000..451af35
--- /dev/null
+++ b/content/markdown/repositories/index.md
@@ -0,0 +1,32 @@
+# 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 build artifacts. Your dependencies are being downloaded from repositories,
+and your built artifacts are being stored (installed, uploaded) into repositories as well. This is one of the
+fundamental concept of Maven since its inception: Maven command line tool and Maven Repositories were mold together
+and developed since inception of Maven project itself.
+
+Maven addresses artifacts using coordinates, that are most often represented as `groupId`:`artifactId`:`version`,
+or GAV in short (or informally). The artifact coordinates uniquely describes the artifact you are referring to, but
+does not tells anything about its source (or origin). It is up to Maven to figure out (or you to tell Maven how
+to figure it out).
+
+Maven in general operates with one local repository and one or more remote repositories.
\ No newline at end of file
diff --git a/content/markdown/repositories/layout.md b/content/markdown/repositories/layout.md
new file mode 100644
index 0000000..3271098
--- /dev/null
+++ b/content/markdown/repositories/layout.md
@@ -0,0 +1,31 @@
+# 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 to translate the artifact coordinates into generic URI (path, URL, it depends on context).
+The transformation rule is quite simple for that matter:
+
+| Source coordinate | Trasformation | Result example |
+|-------------------|---------------|----------------|
+| Group ID | Replace "." (dot) characters with "/" (dash) character | `org.apache.maven` -> `org/apache/maven` |
+| Artifact ID | none | `apache-maven` -> `apache-maven` |
+| Version | none | `3.8.4` -> `3.8.4` |
+
+
diff --git a/content/markdown/repositories/local.md b/content/markdown/repositories/local.md
new file mode 100644
index 0000000..f58d06e
--- /dev/null
+++ b/content/markdown/repositories/local.md
@@ -0,0 +1,23 @@
+# 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 mixed bag, in sense, that it serves two purpose: it "caches" downloaded artifacts from
+remote repositories along with locally built and installed ones.
diff --git a/content/markdown/repositories/remote.md b/content/markdown/repositories/remote.md
new file mode 100644
index 0000000..beaa4c4
--- /dev/null
+++ b/content/markdown/repositories/remote.md
@@ -0,0 +1,23 @@
+# 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 referrers to repositories like [Maven Central Repository](/repository/index.html) is. These
+repositories are holding the artifacts to be consumed by Maven builds.
diff --git a/content/site.xml b/content/site.xml
index 0b8ebfe..eaca2a2 100644
--- a/content/site.xml
+++ b/content/site.xml
@@ -73,7 +73,12 @@ 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="Maven Repositories" href="/repositories/index.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="Index (category)" href="/guides/index.html" />
<item name="User Centre" href="/users/index.html" collapse="true">
[maven-site] 04/07: WIP
Posted by hb...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch maven-repository-layout
in repository https://gitbox.apache.org/repos/asf/maven-site.git
commit cc5d3acf0b5e01cd4d5792ba2eb389b0c57b2c57
Author: Tamas Cservenak <ta...@cservenak.net>
AuthorDate: Wed Jan 19 16:56:15 2022 +0100
WIP
---
content/markdown/repositories/index.md | 45 ++++++++++++++++++++++++++++-----
content/markdown/repositories/layout.md | 36 +++++++++++++++++++++-----
2 files changed, 69 insertions(+), 12 deletions(-)
diff --git a/content/markdown/repositories/index.md b/content/markdown/repositories/index.md
index 3352c46..66c3b9e 100644
--- a/content/markdown/repositories/index.md
+++ b/content/markdown/repositories/index.md
@@ -32,7 +32,7 @@ Maven to figure out (or you to tell Maven how to figure it out).
While Maven internally uses notion of "artifact" thoroughly (just look at sources!), end user may never hit this name.
That's due the fact, that while for Maven, "everything is artifact" (internally), the end users actually speak about
-"projects", "parent projects", "dependencies", "plugins", "extensions" and so on.
+"projects", "parent projects", "dependencies", "build plugins", "build extensions" and so on.
## Artifact properties
@@ -46,10 +46,43 @@ The artifacts that Maven (internally) uses has following (among many others, but
| classifier | The artifact distinguishing classifier |
| extension | The artifact extension |
-And some more, a bit of special ones:
+And some more, a bit of special one: `baseVersion` that is actually derived from version (or other way around,
+depends on context): for release artifacts holds same value as `version`, for snapshot artifacts holds "non-timestamped
+snapshot version". For example, for `version` "1.0-20220119.164608-1" value the `baseVersion` would have value
+"1.0-SNAPSHOT".
-| Name | Description |
-|------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| type | The "type" of the artifact, implies extension. |
-| baseVersion | Is actually derived from version (or other way around, depends on context): for release artifacts same as version, for snapshot artifacts this is always "non stamped snapshot version", for example "1.0-SNAPSHOT". |
+## 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 simple mapping. In case
+of "project" and "parent project" (aka POMs):
+
+| Project | Artifact |
+|------------|---------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | empty |
+| extension | "pom" |
+
+In case of "build plugins" and "build extensions", as they are JARs, this is how corresponding elements are mapped:
+
+| Plugin | Artifact |
+|------------|---------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | empty |
+| extension | "jar" |
+
+And finally, in case of "dependencies", this is the mapping:
+
+| Dependency | Artifact |
+|------------|------------------------------------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> classifier |
+| type | -> type handler provided or same as type |
+
+Here, we need to make a short turn to explain "type" (of a dependency) and how it becomes artifact extension.
diff --git a/content/markdown/repositories/layout.md b/content/markdown/repositories/layout.md
index aace610..98ba670 100644
--- a/content/markdown/repositories/layout.md
+++ b/content/markdown/repositories/layout.md
@@ -34,12 +34,36 @@ the files on file paths for consumption (mainly for HTTP GET requests). Actually
Maven1 and Maven2 (the today's "default") was exactly that: Maven1 layout was stressing the underlying file system
way too much, it was not scaling in this setup.
-The transformation rule is quite simple for that matter:
+The transformation rule is quite simple for that matter: consider artifact properties below:
-| Source coordinate | Transformation | Result example |
-|-------------------|---------------------------------------------------------|----------------|
-| Group ID | Replace "." (dot) characters with "/" (slash) character | `org.apache.maven` -> `org/apache/maven` |
-| Artifact ID | none | `apache-maven` -> `apache-maven` |
-| Version | none | `3.8.4` -> `3.8.4` |
+| 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` |
+| classifier | none | `bin` -> `bin` |
+| extension | none | `tar.gz` -> `tar.gz` |
+And using these properties transformed as above we can construct following layout (if classifier not present):
+```
+${groupId}/${artifactId}/${version}/${artifactId}-${version}.${extension}
+```
+
+or if classifier present:
+
+```
+${groupId}/${artifactId}/${version}/${artifactId}-${version}-${classifier}.${extension}
+```
+
+So the example artifact above:
+
+```
+org.apache.maven:apache-maven:3.8.4:bin:tar.gz
+```
+
+is translated to path:
+
+```
+org/apache/maven/apache-maven/3.8.4/apache-maven-3.8.4-bin.tar.gz
+```
[maven-site] 02/07: WIP
Posted by hb...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch maven-repository-layout
in repository https://gitbox.apache.org/repos/asf/maven-site.git
commit 6bf4d8bd12035034dc81bf979c97b9f95aed1444
Author: Tamas Cservenak <ta...@cservenak.net>
AuthorDate: Wed Jan 19 15:27:02 2022 +0100
WIP
---
content/markdown/repositories/index.md | 2 +-
content/markdown/repositories/layout.md | 12 +++++++++++-
2 files changed, 12 insertions(+), 2 deletions(-)
diff --git a/content/markdown/repositories/index.md b/content/markdown/repositories/index.md
index 451af35..1770a8f 100644
--- a/content/markdown/repositories/index.md
+++ b/content/markdown/repositories/index.md
@@ -26,7 +26,7 @@ and developed since inception of Maven project itself.
Maven addresses artifacts using coordinates, that are most often represented as `groupId`:`artifactId`:`version`,
or GAV in short (or informally). The artifact coordinates uniquely describes the artifact you are referring to, but
-does not tells anything about its source (or origin). It is up to Maven to figure out (or you to tell Maven how
+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).
Maven in general operates with one local repository and one or more remote repositories.
\ No newline at end of file
diff --git a/content/markdown/repositories/layout.md b/content/markdown/repositories/layout.md
index 3271098..1a8dd1f 100644
--- a/content/markdown/repositories/layout.md
+++ b/content/markdown/repositories/layout.md
@@ -19,7 +19,17 @@ specific language governing permissions and limitations
under the License.
-->
-The layout is responsible to translate the artifact coordinates into generic URI (path, URL, it depends on context).
+The layout is responsible to translate the artifact coordinates into generic path, 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.
+Due simplicity, we will cover current layout (aka "maven2" or "default"), as since Maven 3.x release, the deprecated
+"Maven1 layout" is not supported anymore.
+
+The original premise of layout was simplicity: from historical perspective, a remote repository was expected to be run
+by some compute 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). Actually, the reason of layout change between
+Maven1 and Maven2 (the today's "default") was exactly that: Maven1 layout was stressing the underlying file system
+way too much, it was not scaling in this setup.
+
The transformation rule is quite simple for that matter:
| Source coordinate | Trasformation | Result example |
[maven-site] 06/07: WIP
Posted by hb...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch maven-repository-layout
in repository https://gitbox.apache.org/repos/asf/maven-site.git
commit d345620d9fc188a420d54b567325fa3af829e4d8
Author: Tamas Cservenak <ta...@cservenak.net>
AuthorDate: Fri Jan 21 09:52:08 2022 +0100
WIP
---
content/markdown/repositories/artifacts.md | 122 +++++++++++++++++++++++++++++
content/markdown/repositories/index.md | 75 +++---------------
content/markdown/repositories/layout.md | 56 ++++++++++---
content/site.xml | 1 +
4 files changed, 182 insertions(+), 72 deletions(-)
diff --git a/content/markdown/repositories/artifacts.md b/content/markdown/repositories/artifacts.md
new file mode 100644
index 0000000..d2221ba
--- /dev/null
+++ b/content/markdown/repositories/artifacts.md
@@ -0,0 +1,122 @@
+# 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.
+-->
+
+Artifact is "anything" that Maven downloads, installs or deploys for you. Most of them are POMs and JARs but
+the 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 coordinate 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).
+
+While Maven internally uses notion of "artifact" thoroughly (just look at sources!), end user may never hit this name.
+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", "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 name |
+| version | The artifact version |
+| classifier | The artifact distinguishing classifier (optional) |
+| extension | The artifact extension |
+
+Some more properties worth mention, is a bit of special one: `baseVersion` that is actually derived from version
+(or other way around, depends on context): for release artifacts holds same value as `version`, for snapshot artifacts
+holds "non-timestamped snapshot version". For example, for snapshot `version` "1.0-20220119.164608-1" value of the
+`baseVersion` would have value "1.0-SNAPSHOT". So, `version` and `baseVersion` are linked, derived from each other,
+but they have different values only in case of snapshots.
+
+## 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:
+
+| Project | Artifact |
+|------------|---------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> |
+| extension | -> `pom` |
+
+In case of "build plugins" and "build extensions", as they are JARs, this is how corresponding elements are mapped:
+
+| Plugin | Artifact |
+|------------|---------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> |
+| extension | -> `jar` |
+
+And finally, in case of "dependencies", this is the mapping (no, scope is NOT part of artifact coordinates, is used in
+dependency resolution only):
+
+| Dependency | Artifact |
+|------------|-------------------------------------------|
+| groupId | -> groupId |
+| artifactId | -> artifactId |
+| version | -> version |
+| classifier | -> classifier |
+| 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 ArtifactHandlers components with name corresponding to type name.
+
+Maven Core out of the box defines following "types" (ArtifactHandlers):
+
+| 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 | |
+
+So, from table above, we can see that if we define dependency type as "war", we will hit the "war" handler, that will
+result in the `war` extension (may not be obvious, as type and extension we end up is same, but internally this
+indirection does happen). More obvious is type "test-jar", where we end up with extension `jar`. 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!
+
+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
index 848be72..807368e 100644
--- a/content/markdown/repositories/index.md
+++ b/content/markdown/repositories/index.md
@@ -20,69 +20,18 @@ under the License.
-->
Apache Maven uses repositories to store artifacts. Your dependencies are being downloaded from repositories,
-and your artifacts are being stored (installed, uploaded) into repositories as well. This is one of the
+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.
-As you may know, Maven addresses artifacts using coordinates, that 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 coordinate 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).
-
-While Maven internally uses notion of "artifact" thoroughly (just look at sources!), end user may never hit this name.
-That's due the fact, that while for Maven, "everything is artifact" (internally), the end users actually speak about
-"projects", "parent projects", "dependencies", "build plugins", "build extensions" and so on.
-
-## Artifact properties
-
-The artifacts that Maven (internally) uses has following (among many others, but for our topic related) properties:
-
-| Name | Description |
-|------------|-------------|
-| groupId | The artifact group name |
-| artifactId | The artifact name |
-| version | The artifact version |
-| classifier | The artifact distinguishing classifier |
-| extension | The artifact extension |
-
-And some more, a bit of special one: `baseVersion` that is actually derived from version (or other way around,
-depends on context): for release artifacts holds same value as `version`, for snapshot artifacts holds "non-timestamped
-snapshot version". For example, for `version` "1.0-20220119.164608-1" value the `baseVersion` would have value
-"1.0-SNAPSHOT".
-
-## 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 simple mapping. In case
-of "project" and "parent project" (aka POMs):
-
-| Project | Artifact |
-|------------|---------------|
-| groupId | -> groupId |
-| artifactId | -> artifactId |
-| version | -> version |
-| classifier | -> empty |
-| extension | -> "pom" |
-
-In case of "build plugins" and "build extensions", as they are JARs, this is how corresponding elements are mapped:
-
-| Plugin | Artifact |
-|------------|---------------|
-| groupId | -> groupId |
-| artifactId | -> artifactId |
-| version | -> version |
-| classifier | -> empty |
-| extension | -> "jar" |
-
-And finally, in case of "dependencies", this is the mapping:
-
-| Dependency | Artifact |
-|------------|-------------------------------------------|
-| groupId | -> groupId |
-| artifactId | -> artifactId |
-| version | -> version |
-| classifier | -> classifier |
-| type | -> type handler provided, or same as type |
-
-Here, we need to make a short turn to explain "type" (of a dependency) and how it becomes artifact extension.
+As you may know, Maven addresses artifacts using coordinates. The artifact coordinate 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)
+* [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
index 98ba670..19dae2f 100644
--- a/content/markdown/repositories/layout.md
+++ b/content/markdown/repositories/layout.md
@@ -21,8 +21,8 @@ under the License.
The layout is responsible to translate the artifact coordinates into generic paths, that is later used to construct some
URI (file path, URL, it depends on context). Obviously, since Maven;s inception in 2002 the layout evolved as well.
-Due simplicity, we will cover current layout (aka "maven2" or "default"), as since Maven 3.x release, the deprecated
-"Maven1 layout" is not supported anymore.
+For simplicity, we will cover current layout (aka "maven2", "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 make Maven
@@ -31,20 +31,20 @@ 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). Actually, the reason of layout change between
-Maven1 and Maven2 (the today's "default") was exactly that: Maven1 layout was stressing the underlying file system
-way too much, it was not scaling in this setup.
+Maven1 and current Maven was exactly that: Maven1 layout was stressing the underlying file system way too much, it
+was not scaling in this setup.
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` |
-| classifier | none | `bin` -> `bin` |
-| extension | none | `tar.gz` -> `tar.gz` |
+| artifactId | none | `apache-maven` -> `apache-maven` |
+| version | none | `3.8.4` -> `3.8.4` |
+| classifier | none | `bin` -> `bin` |
+| extension | none | `tar.gz` -> `tar.gz` |
-And using these properties transformed as above we can construct following layout (if classifier not present):
+And using these properties transformed as above we can construct following path (if classifier not present):
```
${groupId}/${artifactId}/${version}/${artifactId}-${version}.${extension}
@@ -67,3 +67,41 @@ is translated to path:
```
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, we can build up the path segment that
+artifact is expected to be.
+
+# A word about Maven1 layout
+
+Maven1 aka "legacy" layout **is unsupported since Maven 3.x** (Maven 2.x supported it to ease transition from 1.x to
+2.x), but is still worth a few words.
+
+The Maven1 layout was not applying groupId transformation (hence the path, if it had dots, still contained it), and
+used "type" in plural as second level directory. This is the reason why it caused FS stress, as these directories
+ended up containing a LOT of files (in case of many versions existed).
+
+| Name | Transformation | Result example |
+|------------|---------------------------------------|------------------------------------------|
+| groupId | none | `org.apache.maven` -> `org.apache.maven` |
+| artifactId | none | `apache-maven` -> `apache-maven` |
+| version | none | `3.8.4` -> `3.8.4` |
+| extension | none | `pom` -> `pom` |
+| type | derived by extension by appending 's' | `pom` -> `poms` |
+
+And using these properties transformed as above we can construct following path:
+
+```
+${groupId}/${type}/${artifactId}-${version}.${extension}
+```
+
+So the example artifact above:
+
+```
+org.apache.maven:apache-maven:3.8.4:pom
+```
+
+is translated to path:
+
+```
+org.apache.maven/poms/apache-maven-3.8.4.pom
+```
diff --git a/content/site.xml b/content/site.xml
index eaca2a2..c66fc03 100644
--- a/content/site.xml
+++ b/content/site.xml
@@ -75,6 +75,7 @@ under the License.
<item name="Maven Plugins" href="/plugins/index.html" />
<item name="Maven Extensions" href="/extensions/index.html" />
<item name="Maven Repositories" href="/repositories/index.html">
+ <item name="Maven Artifacts" href="/repositories/artifacts.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" />
[maven-site] 03/07: WIP
Posted by hb...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch maven-repository-layout
in repository https://gitbox.apache.org/repos/asf/maven-site.git
commit 4ef74cc88697d4fa1316013767e189aa1d95023d
Author: Tamas Cservenak <ta...@cservenak.net>
AuthorDate: Wed Jan 19 16:27:47 2022 +0100
WIP
---
content/markdown/repositories/index.md | 41 +++++++++++++++++++++++++--------
content/markdown/repositories/layout.md | 20 +++++++++-------
content/markdown/repositories/local.md | 2 +-
3 files changed, 45 insertions(+), 18 deletions(-)
diff --git a/content/markdown/repositories/index.md b/content/markdown/repositories/index.md
index 1770a8f..3352c46 100644
--- a/content/markdown/repositories/index.md
+++ b/content/markdown/repositories/index.md
@@ -19,14 +19,37 @@ specific language governing permissions and limitations
under the License.
-->
-Apache Maven uses repositories to store build artifacts. Your dependencies are being downloaded from repositories,
-and your built artifacts are being stored (installed, uploaded) into repositories as well. This is one of the
-fundamental concept of Maven since its inception: Maven command line tool and Maven Repositories were mold together
-and developed since inception of Maven project itself.
+Apache Maven uses repositories to store artifacts. Your dependencies are being downloaded from repositories,
+and your artifacts 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.
-Maven addresses artifacts using coordinates, that are most often represented as `groupId`:`artifactId`:`version`,
-or GAV in short (or informally). The artifact coordinates uniquely describes 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).
+As you may know, Maven addresses artifacts using coordinates, that 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 coordinate 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).
+
+While Maven internally uses notion of "artifact" thoroughly (just look at sources!), end user may never hit this name.
+That's due the fact, that while for Maven, "everything is artifact" (internally), the end users actually speak about
+"projects", "parent projects", "dependencies", "plugins", "extensions" and so on.
+
+## Artifact properties
+
+The artifacts that Maven (internally) uses has following (among many others, but for our topic related) properties:
+
+| Name | Description |
+|------------|-------------|
+| groupId | The artifact group name |
+| artifactId | The artifact name |
+| version | The artifact version |
+| classifier | The artifact distinguishing classifier |
+| extension | The artifact extension |
+
+And some more, a bit of special ones:
+
+| Name | Description |
+|------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| type | The "type" of the artifact, implies extension. |
+| baseVersion | Is actually derived from version (or other way around, depends on context): for release artifacts same as version, for snapshot artifacts this is always "non stamped snapshot version", for example "1.0-SNAPSHOT". |
-Maven in general operates with one local repository and one or more remote repositories.
\ No newline at end of file
diff --git a/content/markdown/repositories/layout.md b/content/markdown/repositories/layout.md
index 1a8dd1f..aace610 100644
--- a/content/markdown/repositories/layout.md
+++ b/content/markdown/repositories/layout.md
@@ -19,23 +19,27 @@ specific language governing permissions and limitations
under the License.
-->
-The layout is responsible to translate the artifact coordinates into generic path, 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.
+The layout is responsible to translate the artifact coordinates into generic paths, that is later used to construct some
+URI (file path, URL, it depends on context). Obviously, since Maven;s inception in 2002 the layout evolved as well.
Due simplicity, we will cover current layout (aka "maven2" or "default"), as since Maven 3.x release, the deprecated
"Maven1 layout" 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 make Maven
+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 compute with file storage (where artifacts were laid down) and served by a HTTP server, essentially publishing
+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). Actually, the reason of layout change between
Maven1 and Maven2 (the today's "default") was exactly that: Maven1 layout was stressing the underlying file system
way too much, it was not scaling in this setup.
The transformation rule is quite simple for that matter:
-| Source coordinate | Trasformation | Result example |
-|-------------------|---------------|----------------|
-| Group ID | Replace "." (dot) characters with "/" (dash) character | `org.apache.maven` -> `org/apache/maven` |
-| Artifact ID | none | `apache-maven` -> `apache-maven` |
-| Version | none | `3.8.4` -> `3.8.4` |
+| Source coordinate | Transformation | Result example |
+|-------------------|---------------------------------------------------------|----------------|
+| Group ID | Replace "." (dot) characters with "/" (slash) character | `org.apache.maven` -> `org/apache/maven` |
+| Artifact ID | none | `apache-maven` -> `apache-maven` |
+| Version | none | `3.8.4` -> `3.8.4` |
diff --git a/content/markdown/repositories/local.md b/content/markdown/repositories/local.md
index f58d06e..597238c 100644
--- a/content/markdown/repositories/local.md
+++ b/content/markdown/repositories/local.md
@@ -19,5 +19,5 @@ specific language governing permissions and limitations
under the License.
-->
-The local repository is mixed bag, in sense, that it serves two purpose: it "caches" downloaded artifacts from
+The local repository is mixed bag, in sense, that it serves two purposes: it caches downloaded artifacts from
remote repositories along with locally built and installed ones.