[maven-site] 07/07: Add examples, note about locally installed snapshots

[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
+
+