Apache
/
maven
mirror of https://github.com/apache/maven.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[MNG-7385] improve repository metadata documentation

This commit is contained in:
Hervé Boutemy 2022-01-09 19:22:55 +01:00
parent 76452c7269
commit 1af8513fa7
3 changed files with 65 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
maven-artifact/src/main/java/org/apache/maven/repository/legacy/metadata/ArtifactMetadata.java
View File

@ -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 )

69
maven-repository-metadata/src/main/mdo/metadata.mdo
View File

@ -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>

36
maven-repository-metadata/src/site/apt/index.apt
View File

@ -27,16 +27,6 @@ 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,
[[2]] a snapshot artifact: it gives precise information on the snapshot,
[[3]] a group containing Maven plugins artifacts: it gives informations on plugins available in this group.
[]
The metadata file name is:
* <<<maven-metadata.xml>>> in a remote repository,
@ -45,8 +35,30 @@ Maven Repository Metadata Model
[]
Depending on what the directory represents ("groupId", "groupId/artifactId" or "groupId/artifactId/version"),
the Maven Repository Metadata file contains 3 different sets of metadata:
[[1]] in a "groupId" directory: a "groupId" directory may contain Maven plugins artifacts, which are described in metadata's <<<plugins>>> element,
[[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