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/01/09 18:23:04 UTC
[maven] 01/01: [MNG-7385] improve repository metadata documentation
This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch MNG-7385
in repository https://gitbox.apache.org/repos/asf/maven.git
commit a01a42c81362eceadd18f6f039931463bea02f62
Author: Hervé Boutemy <hb...@apache.org>
AuthorDate: Sun Jan 9 19:22:55 2022 +0100
[MNG-7385] improve repository metadata documentation
---
.../legacy/metadata/ArtifactMetadata.java | 8 +--
.../src/main/mdo/metadata.mdo | 69 ++++++++++++----------
maven-repository-metadata/src/site/apt/index.apt | 26 ++++----
3 files changed, 57 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 45207b1..136ab44 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:brett@apache.org">Brett Porter</a>
* TODO merge with artifactmetadatasource
* TODO retrieval exception not appropriate for store
+ *
+ * @author <a href="mailto:brett@apache.org">Brett Porter</a>
*/
public interface ArtifactMetadata
{
@@ -70,19 +70,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
* @throws RepositoryMetadataStoreException in case of issue
- * TODO this should only be needed on the repository metadata
*/
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..ab14502 100644
--- a/maven-repository-metadata/src/site/apt/index.apt
+++ b/maven-repository-metadata/src/site/apt/index.apt
@@ -27,26 +27,32 @@ 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, ie 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 (perhaps 4)