This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch maven-3.8.x
in repository https://gitbox.apache.org/repos/asf/maven.git
The following commit(s) were added to refs/heads/maven-3.8.x by this push:
new 2775512 [MNG-7385] improve repository metadata documentation
2775512 is described below
commit 27755123e30d46a73ede29cef5b4c340fcdc3fab
Author: Hervé Boutemy <[email protected]>
AuthorDate: Sun Jan 9 19:22:55 2022 +0100
[MNG-7385] improve repository metadata documentation
---
.../legacy/metadata/ArtifactMetadata.java | 9 +--
.../src/main/mdo/metadata.mdo | 69 ++++++++++++----------
maven-repository-metadata/src/site/apt/index.apt | 32 ++++++----
3 files changed, 64 insertions(+), 46 deletions(-)
diff --git
a/maven-artifact/src/main/java/org/apache/maven/repository/legacy/metadata/ArtifactMetadata.java
b/maven-artifact/src/main/java/org/apache/maven/repository/legacy/metadata/ArtifactMetadata.java
index 7abdfbb..c97b4e7 100644
---
a/maven-artifact/src/main/java/org/apache/maven/repository/legacy/metadata/ArtifactMetadata.java
+++
b/maven-artifact/src/main/java/org/apache/maven/repository/legacy/metadata/ArtifactMetadata.java
@@ -24,10 +24,10 @@ import
org.apache.maven.artifact.repository.metadata.RepositoryMetadataStoreExce
/**
* Contains metadata about an artifact, and methods to retrieve/store it from
an artifact repository.
- *
- * @author <a href="mailto:[email protected]";>Brett Porter</a>
* TODO merge with artifactmetadatasource
* TODO retrieval exception not appropriate for store
+ *
+ * @author <a href="mailto:[email protected]";>Brett Porter</a>
*/
public interface ArtifactMetadata
{
@@ -62,18 +62,19 @@ public interface ArtifactMetadata
/**
* Merge a new metadata set into this piece of metadata.
+ * TODO this should only be needed on the repository metadata {@link
org.apache.maven.artifact.metadata.ArtifactMetadata}
*
* @param metadata the new metadata
- * TODO this should only be needed on the repository metadata
*/
void merge( ArtifactMetadata metadata );
/**
* Store the metadata in the local repository.
+ * TODO this should only be needed on the repository metadata {@link
org.apache.maven.artifact.metadata.ArtifactMetadata}
*
* @param localRepository the local repository
* @param remoteRepository the remote repository it came from
- * TODO this should only be needed on the repository metadata
+ * @throws RepositoryMetadataStoreException in case of issue
*/
void storeInLocalRepository( ArtifactRepository localRepository,
ArtifactRepository remoteRepository )
diff --git a/maven-repository-metadata/src/main/mdo/metadata.mdo
b/maven-repository-metadata/src/main/mdo/metadata.mdo
index a6f5299..ddaeb0a 100644
--- a/maven-repository-metadata/src/main/mdo/metadata.mdo
+++ b/maven-repository-metadata/src/main/mdo/metadata.mdo
@@ -24,11 +24,9 @@ under the License.
<id>repository-metadata</id>
<name>Metadata</name>
<description><![CDATA[
- <p>Per-directory repository metadata, for directories representing
un-versioned artifact, snapshot artifact
- or a group containing Maven plugins.</p>
- <p>Notice that most metadata content has a meaning when the directory
represents
- an artifact (<code>groupId</code>, <code>artifactId</code>,
<code>versioning</code>), but
- <code>plugins</code> is used when the directory represents a group.</p>]]>
+ <p>Per-directory repository metadata
<code>repository-metadata.xml</code>.</p>
+ <p>A directory may represent 3 types of content: "groupId",
"groupId/artifactId" or "groupId/artifactId/version".</p>
+ <p>Most metadata content has a meaning when the directory represents a
"groupId/artifactId" (<code>groupId</code>, <code>artifactId</code>,
<code>versioning</code>)<p>]]>
</description>
<defaults>
<default>
@@ -51,19 +49,13 @@ under the License.
<name>groupId</name>
<version>1.0.0+</version>
<type>String</type>
- <description>The groupId that this directory represents, if
any.</description>
+ <description>The groupId when this directory represents
"groupId/artifactId" or "groupId/artifactId/version".</description>
</field>
<field>
<name>artifactId</name>
<version>1.0.0+</version>
<type>String</type>
- <description>The artifactId that this directory represents, if
any.</description>
- </field>
- <field>
- <name>version</name>
- <version>1.0.0+</version>
- <type>String</type>
- <description>The version that this directory represents, if any. It
is used for artifact snapshots only.</description>
+ <description>The artifactId when this directory represents
"groupId/artifactId" or "groupId/artifactId/version".</description>
</field>
<field>
<name>versioning</name>
@@ -71,12 +63,21 @@ under the License.
<association>
<type>Versioning</type>
</association>
- <description>Versioning information for the artifact.</description>
+ <description>Versioning information when this directory represents
"groupId/artifactId" or "groupId/artifactId/version".</description>
+ </field>
+ <field>
+ <name>version</name>
+ <version>1.0.0+</version>
+ <type>String</type>
+ <description><![CDATA[The base version (ie. ending in
<code>-SNAPSHOT</code>) when this directory represents a
"groupId/artifactId/version" for a SNAPSHOT.]]></description>
</field>
<field xdoc.separator="blank">
<name>plugins</name>
<version>1.0.0+</version>
- <description>The set of plugin mappings for the group represented by
this directory</description>
+ <description>The set of plugins when this directory represents a
"groupId" (deprecated)</description>
+ <annotations>
+ <annotation>@Deprecated</annotation>
+ </annotations>
<association>
<type>Plugin</type>
<multiplicity>*</multiplicity>
@@ -213,42 +214,42 @@ under the License.
<class java.clone="deep">
<name>Versioning</name>
<version>1.0.0+</version>
- <description>Versioning information for an artifact (un-versioned or
snapshot)</description>
+ <description>Versioning information for "groupId/artifactId" or
"groupId/artifactId/version" SNAPSHOT</description>
<fields>
<field>
<name>latest</name>
<version>1.0.0+</version>
<type>String</type>
- <description>What the latest version in the directory is, including
snapshots</description>
+ <description>What the last version added to the directory is,
including both releases and snapshots ("groupId/artifactId" directory
only)</description>
</field>
<field>
<name>release</name>
<version>1.0.0+</version>
<type>String</type>
- <description>What the latest version in the directory is, of the
releases only</description>
- </field>
- <field>
- <name>snapshot</name>
- <version>1.0.0+</version>
- <association>
- <type>Snapshot</type>
- </association>
- <description>The current snapshot data in use for this version
(artifact snapshots only)</description>
+ <description>What the last version added to the directory is, for
the releases only ("groupId/artifactId" directory only)</description>
</field>
<field>
<name>versions</name>
<version>1.0.0+</version>
- <description>Versions available of the artifact (both releases and
snapshots)</description>
+ <description>Versions available of the artifact (both releases and
snapshots) ("groupId/artifactId" directory only)</description>
<association>
<type>String</type>
<multiplicity>*</multiplicity>
</association>
</field>
- <field>
+ <field xdoc.separator="blank">
<name>lastUpdated</name>
<version>1.0.0+</version>
<type>String</type>
- <description>When the metadata was last updated</description>
+ <description>When the metadata was last updated (both
"groupId/artifactId" and "groupId/artifactId/version" directories)</description>
+ </field>
+ <field xdoc.separator="blank">
+ <name>snapshot</name>
+ <version>1.0.0+</version>
+ <association>
+ <type>Snapshot</type>
+ </association>
+ <description>The current snapshot data in use for this version
("groupId/artifactId/version" only)</description>
</field>
<field>
<name>snapshotVersions</name>
@@ -283,7 +284,7 @@ under the License.
<class java.clone="deep">
<name>Snapshot</name>
<version>1.0.0+</version>
- <description>Snapshot data for the current artifact version</description>
+ <description>Snapshot data for the last artifact corresponding to the
SNAPSHOT base version</description>
<fields>
<field>
<name>timestamp</name>
@@ -322,7 +323,7 @@ under the License.
<name>extension</name>
<version>1.1.0+</version>
<type>String</type>
- <description>The file extension of thesub-artifact.</description>
+ <description>The file extension of the sub-artifact.</description>
</field>
<field xml.tagName="value">
<name>version</name>
@@ -338,10 +339,14 @@ under the License.
</field>
</fields>
</class>
+
<class java.clone="deep">
<name>Plugin</name>
<version>1.0.0+</version>
- <description>Mapping information for a single plugin within this
group</description>
+ <description>Mapping information for a single plugin within this group
(deprecated).</description>
+ <annotations>
+ <annotation>@Deprecated</annotation>
+ </annotations>
<comment>NOTE: plugin version is _NOT_ included here, since it is
resolved using a separate algorithm in plugins' artifact.</comment>
<fields>
<field>
diff --git a/maven-repository-metadata/src/site/apt/index.apt
b/maven-repository-metadata/src/site/apt/index.apt
index ed2bff9..1a484f9 100644
--- a/maven-repository-metadata/src/site/apt/index.apt
+++ b/maven-repository-metadata/src/site/apt/index.apt
@@ -27,26 +27,38 @@ Maven Repository Metadata Model
This is strictly the model for Maven Repository Metadata, so really just
plain objects.
- Maven Repository Metadata is available in directories representing:
-
- [[1]] an un-versioned artifact: it gives informations about available
versions of the artifact,
+ The metadata file name is:
- [[2]] a snapshot artifact: it gives precise information on the snapshot,
+ * <<<maven-metadata.xml>>> in a remote repository,
- [[3]] a group containing Maven plugins artifacts: it gives informations on
plugins available in this group.
+ * <<<maven-metadata-\<repo-id>.xml>>> in a local repository, for metadata
from a repository with <<<repo-id>>> identifier.
[]
- The metadata file name is:
+ Depending on what the directory represents ("groupId", "groupId/artifactId"
or "groupId/artifactId/version"),
+ the Maven Repository Metadata file contains 3 different sets of metadata:
- * <<<maven-metadata.xml>>> in a remote repository,
+ [[1]] in a "groupId" directory: a "groupId" directory may contain Maven
plugins artifacts, which are described in metadata's <<<plugins>>> element,
- * <<<maven-metadata-\<repo-id>.xml>>> in a local repository, for metadata
from a repository with <<<repo-id>>> identifier.
+ [[2]] in a "groupId/artifactId" directory: metadata describes <<<groupId>>>,
<<<artifactId>>> and <<<versioning>>> element that
+ gives data about available versions (<<<latest>>>, <<<release>>>,
<<<versions>>> list and <<<lastUpdated>>>),
+
+ [[3]] in a "groupId/artifactId/version" snapshot artifact directory: metadata
describes <<<groupId>>>, <<<artifactId>>>, <<<version>>> (base version, i.e.
ending in <<<-SNAPSHOT>>>) and
+ <<<versioning>>> element that gives data about snaphot (<<<snapshot>>>,
<<<lastUpdated>>> and <<<snapshotVersions>>> list). Notice that a
+ release artifact directory is not expected to provide metadata.
[]
The following are generated from this model:
- * {{{./apidocs/index.html}Java sources}} with Reader and Writers for the
Xpp3 XML parser, to read and write <<<maven-metadata(-*).xml>>> files
+ * {{{./apidocs/index.html}Java sources}} with Reader and Writers for the
Xpp3 XML parser, to read and write <<<maven-metadata(-*).xml>>> files,
- * A {{{./repository-metadata.html}Descriptor Reference}}
+ * a {{{./repository-metadata.html}Descriptor Reference}}.
+
+ Notice: data about plugins in a directory representing a groupId is
deprecated and will be removed in a future Maven version.
+~~ logic behind this:
+~~ 1. MNG-7266: maven-compat will be removed from future Maven version
+~~ 2. this will remove the code that updates plugins data: see
MNG-7375/MPLUGIN-384
https://maven.apache.org/ref/3.8.4/maven-compat/apidocs/org/apache/maven/artifact/repository/metadata/GroupRepositoryMetadata.html
+~~ 3. this will lead to inconsistent data: removing it will be safer/more clear
+~~ but this logic still remains to be confirmed by clear consensus of the
whole team
+
\ No newline at end of file
