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 <[email protected]> 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:[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 { @@ -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)
