[MRM-1329] Start to revise Javadoc of APIs

- additionally, add projectVersion to the ArtifactMetadata so that the full coordinate is available.

git-svn-id: https://svn.apache.org/repos/asf/archiva/trunk@923520 13f79535-47bb-0310-9956-ffa450edef68

7 files changed, 191 insertions, 20 deletions

diff --git a/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/ArtifactMetadata.java b/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/ArtifactMetadata.java
index b5b7307cd..6d408726d 100644
--- a/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/ArtifactMetadata.java
+++ b/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/ArtifactMetadata.java
@@ -21,28 +21,80 @@ package org.apache.archiva.metadata.model;
 
 import java.util.Date;
 
+/**
+ * Metadata stored in the content repository for a particular artifact. Information that is shared between different
+ * artifacts of a given project version can be found in the
+ * {@link org.apache.archiva.metadata.model.ProjectVersionMetadata} class. The metadata is faceted to store information
+ * about particular types of artifacts, for example Maven 2.x artifact specific information.
+ * For more information, see the
+ * <a href="{@docRoot}/../metadata-content-model.html" target="_top">Metadata Content Model</a>.
+ */
 public class ArtifactMetadata
     extends FacetedMetadata
 {
+    /**
+     * The artifact ID uniquely identifies an artifact within a given namespace, project and project version. For
+     * example, <tt>archiva-1.4-20100201.345612-2.jar</tt>
+     */
     private String id;
-    
-    private long size;
 
+    /**
+     * The repository that the artifact is stored in within the content repository.
+     */
+    private String repositoryId;
+
+    /**
+     * The namespace of the project within the repository.
+     *
+     * @see org.apache.archiva.metadata.model.ProjectMetadata#namespace
+     */
+    private String namespace;
+
+    /**
+     * The identifier of the project within the repository and namespace.
+     *
+     * @see org.apache.archiva.metadata.model.ProjectMetadata#id
+     */
+    private String project;
+
+    /**
+     * The version of the project. This may be more generalised than @{link #version}.
+     *
+     * @see org.apache.archiva.metadata.model.ProjectVersionMetadata#id
+     */
+    private String projectVersion;
+
+    /**
+     * The artifact version, if different from the project version. Note that the metadata does not do any calculation
+     * of this based on the project version - the calling code must be sure to set and check it appropriately if
+     * <tt>null</tt>.
+     */
     private String version;
 
+    /**
+     * The last modified date of the artifact file, if known.
+     */
     private Date fileLastModified;
 
-    private Date whenGathered;
+    /**
+     * The file size of the artifact, if known.
+     */
+    private long size;
 
+    /**
+     * The MD5 checksum of the artifact, if calculated.
+     */
     private String md5;
 
+    /**
+     * The SHA-1 checksum of the artifact, if calculated.
+     */
     private String sha1;
 
-    private String namespace;
-
-    private String project;
-
-    private String repositoryId;
+    /**
+     * When the artifact was found in the repository storage and added to the metadata content repository.
+     */
+    private Date whenGathered;
 
     public String getId()
     {
@@ -74,6 +126,16 @@ public class ArtifactMetadata
         this.version = version;
     }
 
+    public String getProjectVersion()
+    {
+        return projectVersion;
+    }
+
+    public void setProjectVersion( String projectVersion )
+    {
+        this.projectVersion = projectVersion;
+    }
+
     public void setFileLastModified( long fileLastModified )
     {
         this.fileLastModified = new Date( fileLastModified );
@@ -163,7 +225,9 @@ public class ArtifactMetadata
         {
             return false;
         }
-        if ( !fileLastModified.equals( that.fileLastModified ) )
+        if ( fileLastModified != null
+            ? !fileLastModified.equals( that.fileLastModified )
+            : that.fileLastModified != null )
         {
             return false;
         }
@@ -183,7 +247,11 @@ public class ArtifactMetadata
         {
             return false;
         }
-        if ( repositoryId != null ? !repositoryId.equals( that.repositoryId ) : that.repositoryId != null )
+        if ( projectVersion != null ? !projectVersion.equals( that.projectVersion ) : that.projectVersion != null )
+        {
+            return false;
+        }
+        if ( !repositoryId.equals( that.repositoryId ) )
         {
             return false;
         }
@@ -191,11 +259,11 @@ public class ArtifactMetadata
         {
             return false;
         }
-        if ( !version.equals( that.version ) )
+        if ( version != null ? !version.equals( that.version ) : that.version != null )
         {
             return false;
         }
-        if ( !whenGathered.equals( that.whenGathered ) )
+        if ( whenGathered != null ? !whenGathered.equals( that.whenGathered ) : that.whenGathered != null )
         {
             return false;
         }
@@ -209,6 +277,6 @@ public class ArtifactMetadata
         return "ArtifactMetadata{" + "id='" + id + '\'' + ", size=" + size + ", version='" + version + '\'' +
             ", fileLastModified=" + fileLastModified + ", whenGathered=" + whenGathered + ", md5='" + md5 + '\'' +
             ", sha1='" + sha1 + '\'' + ", namespace='" + namespace + '\'' + ", project='" + project + '\'' +
-            ", repositoryId='" + repositoryId + '\'' + '}';
+            ", projectVersion='" + projectVersion + '\'' + ", repositoryId='" + repositoryId + '\'' + '}';
     }
 }
diff --git a/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/CiManagement.java b/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/CiManagement.java
index bb0bc7c1b..bbee4efcf 100644
--- a/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/CiManagement.java
+++ b/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/CiManagement.java
@@ -19,10 +19,21 @@ package org.apache.archiva.metadata.model;
  * under the License.
  */
 
+/**
+ * Information about the CI system used by the project.
+ *
+ * @todo considering moving this to a facet - avoid referring to it externally
+ */
 public class CiManagement
 {
+    /**
+     * A simple identifier for the type of CI server used, eg <tt>continuum</tt>, <tt>bamboo</tt>, <tt>hudson</tt>, etc.
+     */
     private String system;
 
+    /**
+     * The base URL of the CI system.
+     */
     private String url;
 
     public String getUrl()
diff --git a/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/Dependency.java b/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/Dependency.java
index 034bce463..a2658769d 100644
--- a/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/Dependency.java
+++ b/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/Dependency.java
@@ -20,24 +20,51 @@ package org.apache.archiva.metadata.model;
  */
 
 /**
- * TODO: review what is appropriate for the base here - rest should be in a maven dependency facet
+ * Information about a dependency that this project has on another project or artifact.
+ *
+ * @todo will be reviewing what is appropriate for the base here - rest should be in a maven dependency facet - avoid details on it externally
  */
 public class Dependency
 {
+    /**
+     * The Maven classifier of the dependency.
+     */
     private String classifier;
 
+    /**
+     * Whether the dependency is optional or required.
+     */
     private boolean optional;
 
+    /**
+     * The Maven scope of the dependency - <tt>compile</tt> (default), <tt>runtime</tt>, etc.
+     */
     private String scope;
 
+    /**
+     * The system path of the file of the dependency artifact to use.
+     */
     private String systemPath;
 
+    /**
+     * The Maven type of the dependency.
+     */
     private String type;
 
+    /**
+     * The Maven artifact ID of the dependency.
+     */
     private String artifactId;
 
+    /**
+     * The Maven group ID of the dependency.
+     */
     private String groupId;
 
+    /**
+     * The version of the artifact to depend on. If this refers to a project version then the repository implementation
+     * may choose the most appropriate artifact version to use.
+     */
     private String version;
 
     public void setClassifier( String classifier )
diff --git a/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/FacetedMetadata.java b/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/FacetedMetadata.java
index a3df5e339..3024512f3 100644
--- a/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/FacetedMetadata.java
+++ b/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/FacetedMetadata.java
@@ -23,30 +23,52 @@ import java.util.Collection;
 import java.util.HashMap;
 import java.util.Map;
 
-public class FacetedMetadata
+/**
+ * Base class for metadata that is contains facets for storing extensions by various plugins.
+ */
+public abstract class FacetedMetadata
 {
+    /**
+     * The facets to store, keyed by the {@linkplain MetadataFacet#getFacetId() Facet ID} of the metadata.
+     */
     private Map<String, MetadataFacet> facets = new HashMap<String, MetadataFacet>();
 
+    /**
+     * Add a new facet to the metadata. If it already exists, it will be replaced.
+     *
+     * @param metadataFacet the facet to add
+     */
     public void addFacet( MetadataFacet metadataFacet )
     {
         this.facets.put( metadataFacet.getFacetId(), metadataFacet );
     }
 
+    /**
+     * Get a particular facet of metadata.
+     *
+     * @param facetId the facet ID
+     * @return the facet of the metadata.
+     */
     public MetadataFacet getFacet( String facetId )
     {
         return this.facets.get( facetId );
     }
 
-    public Map<String, MetadataFacet> getFacets()
-    {
-        return facets;
-    }
-
+    /**
+     * Get all the facets available on this metadata.
+     *
+     * @return the facets of the metadata
+     */
     public Collection<MetadataFacet> getFacetList()
     {
         return this.facets.values();
     }
 
+    /**
+     * Get all the keys of the facets available on this metadata.
+     *
+     * @return the collection of facet IDs.
+     */
     public Collection<String> getFacetIds()
     {
         return this.facets.keySet();
diff --git a/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/IssueManagement.java b/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/IssueManagement.java
index 22f7290be..83eecda0d 100644
--- a/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/IssueManagement.java
+++ b/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/IssueManagement.java
@@ -19,10 +19,21 @@ package org.apache.archiva.metadata.model;
  * under the License.
  */
 
+/**
+ * Information about the issue management system used by the project.
+ *
+ * @todo considering moving this to a facet - avoid referring to it externally
+ */
 public class IssueManagement
 {
+    /**
+     * A simple identifier for the type of issue management server used, eg <tt>jira</tt>, <tt>bugzilla</tt>, etc.
+     */
     private String system;
 
+    /**
+     * The base URL of the issue management system.
+     */
     private String url;
 
     public String getUrl()
diff --git a/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/License.java b/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/License.java
index 2f5a141f8..b1ce93b77 100644
--- a/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/License.java
+++ b/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/License.java
@@ -19,10 +19,19 @@ package org.apache.archiva.metadata.model;
  * under the License.
  */
 
+/**
+ * A description of a particular license used by a project.
+ */
 public class License
 {
+    /**
+     * The name of the license.
+     */
     private String name;
 
+    /**
+     * The URL of the license text.
+     */
     private String url;
 
     public License( String name, String url )
diff --git a/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/MailingList.java b/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/MailingList.java
index a9530b79d..129358d4a 100644
--- a/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/MailingList.java
+++ b/archiva-modules/metadata/metadata-model/src/main/java/org/apache/archiva/metadata/model/MailingList.java
@@ -21,18 +21,41 @@ import java.util.List;
  * under the License.
  */
 
+/**
+ * Information about the available mailing lists for communicating with the project.
+ *
+ * @todo considering moving this to a facet - avoid referring to it externally
+ */
 public class MailingList
 {
+    /**
+     * The primary archive URL for this mailing list.
+     */
     private String mainArchiveUrl;
 
+    /**
+     * A list of other URLs to archives of the mailing list.
+     */
     private List<String> otherArchives;
 
+    /**
+     * The name of the mailing list, eg. <i>Archiva Developers List</i>.
+     */
     private String name;
 
+    /**
+     * The email address to post a new message to the mailing list, if applicable.
+     */
     private String postAddress;
 
+    /**
+     * The email address to send a message to to subscribe to the mailing list, if applicable.
+     */
     private String subscribeAddress;
 
+    /**
+     * The email address to send a message to to unsubscribe from the mailing list, if applicable.
+     */
     private String unsubscribeAddress;
 
     public void setMainArchiveUrl( String mainArchiveUrl )