[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

archiva-modules/archiva-web/archiva-rss/src/test/java/org/apache/archiva/rss/processor/NewArtifactsRssFeedProcessorTest.java

@@ -19,14 +19,6 @@ package org.apache.archiva.rss.processor;
  * under the License.
  */
 
-import java.util.ArrayList;
-import java.util.Calendar;
-import java.util.Date;
-import java.util.HashMap;
-import java.util.List;
-import java.util.Map;
-import java.util.TimeZone;
-
 import com.sun.syndication.feed.synd.SyndEntry;
 import com.sun.syndication.feed.synd.SyndFeed;
 import org.apache.archiva.metadata.model.ArtifactMetadata;
@@ -35,6 +27,14 @@ import org.apache.archiva.rss.RssFeedGenerator;
 import org.codehaus.plexus.spring.PlexusInSpringTestCase;
 import org.easymock.MockControl;
 
+import java.util.ArrayList;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.TimeZone;
+
 public class NewArtifactsRssFeedProcessorTest
     extends PlexusInSpringTestCase
 {
@@ -111,6 +111,7 @@ public class NewArtifactsRssFeedProcessorTest
         artifact.setRepositoryId( TEST_REPO );
         artifact.setWhenGathered( whenGathered );
         artifact.setProject( artifactId );
+        artifact.setProjectVersion( version );
         artifact.setVersion( version );
         return artifact;
     }

archiva-modules/archiva-web/archiva-rss/src/test/java/org/apache/archiva/rss/processor/NewVersionsOfArtifactRssFeedProcessorTest.java

@@ -19,13 +19,6 @@ package org.apache.archiva.rss.processor;
  * under the License.
  */
 
-import java.util.Arrays;
-import java.util.Collections;
-import java.util.Date;
-import java.util.HashMap;
-import java.util.List;
-import java.util.Map;
-
 import com.sun.syndication.feed.synd.SyndEntry;
 import com.sun.syndication.feed.synd.SyndFeed;
 import org.apache.archiva.metadata.model.ArtifactMetadata;
@@ -34,6 +27,13 @@ import org.apache.archiva.rss.RssFeedGenerator;
 import org.codehaus.plexus.spring.PlexusInSpringTestCase;
 import org.easymock.MockControl;
 
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
 public class NewVersionsOfArtifactRssFeedProcessorTest
     extends PlexusInSpringTestCase
 {
@@ -124,6 +124,7 @@ public class NewVersionsOfArtifactRssFeedProcessorTest
         ArtifactMetadata artifact = new ArtifactMetadata();
         artifact.setNamespace( GROUP_ID );
         artifact.setProject( ARTIFACT_ID );
+        artifact.setProjectVersion( version );
         artifact.setVersion( version );
         artifact.setRepositoryId( TEST_REPO );
         artifact.setId( ARTIFACT_ID + "-" + version + ".jar" );

archiva-modules/archiva-web/archiva-webapp/src/test/java/org/apache/archiva/metadata/repository/memory/TestMetadataRepository.java

@@ -19,12 +19,6 @@ package org.apache.archiva.metadata.repository.memory;
  * under the License.
  */
 
-import java.util.ArrayList;
-import java.util.Collection;
-import java.util.Collections;
-import java.util.Date;
-import java.util.List;
-
 import org.apache.archiva.metadata.model.ArtifactMetadata;
 import org.apache.archiva.metadata.model.MetadataFacet;
 import org.apache.archiva.metadata.model.ProjectMetadata;
@@ -32,6 +26,12 @@ import org.apache.archiva.metadata.model.ProjectVersionMetadata;
 import org.apache.archiva.metadata.model.ProjectVersionReference;
 import org.apache.archiva.metadata.repository.MetadataRepository;
 
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.Date;
+import java.util.List;
+
 public class TestMetadataRepository
     implements MetadataRepository
 {
@@ -62,6 +62,7 @@ public class TestMetadataRepository
         ArtifactMetadata artifact = new ArtifactMetadata();
         artifact.setFileLastModified( System.currentTimeMillis() );
         artifact.setNamespace( TEST_NAMESPACE );
+        artifact.setProjectVersion( projectVersion );
         artifact.setVersion( projectVersion );
         artifact.setId( projectId + "-" + projectVersion + ".jar" );
         artifact.setProject( projectId );

archiva-modules/archiva-web/archiva-webapp/src/test/java/org/apache/maven/archiva/web/action/SearchActionTest.java

@@ -19,11 +19,6 @@ package org.apache.maven.archiva.web.action;
  * under the License.
  */
 
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.Collections;
-import java.util.List;
-
 import com.opensymphony.xwork2.Action;
 import org.apache.archiva.indexer.search.RepositorySearch;
 import org.apache.archiva.indexer.search.SearchFields;
@@ -38,6 +33,11 @@ import org.apache.maven.archiva.security.UserRepositories;
 import org.codehaus.plexus.spring.PlexusInSpringTestCase;
 import org.easymock.MockControl;
 
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
 /**
  *
  */
@@ -504,6 +504,7 @@ public class SearchActionTest
         ArtifactMetadata metadata = new ArtifactMetadata();
         metadata.setNamespace( "org.apache.archiva" );
         metadata.setProject( project );
+        metadata.setProjectVersion( version );
         metadata.setVersion( version );
         metadata.setRepositoryId( TEST_REPO );
         metadata.setId( project + "-" + version + ".jar" );

archiva-modules/archiva-web/archiva-webapp/src/test/java/org/apache/maven/archiva/web/action/ShowArtifactActionTest.java

@@ -27,6 +27,7 @@ import org.apache.archiva.metadata.model.ProjectVersionMetadata;
 import org.apache.archiva.metadata.model.ProjectVersionReference;
 import org.apache.archiva.metadata.repository.memory.TestMetadataResolver;
 import org.apache.archiva.metadata.repository.storage.maven2.MavenArtifactFacet;
+import org.apache.maven.archiva.common.utils.VersionUtil;
 import org.apache.maven.archiva.configuration.ManagedRepositoryConfiguration;
 import org.apache.maven.archiva.repository.ManagedRepositoryContent;
 import org.apache.maven.archiva.repository.RepositoryContentFactory;
@@ -402,6 +403,7 @@ public class ShowArtifactActionTest
         metadata.setNamespace( TEST_GROUP_ID );
         metadata.setRepositoryId( TEST_REPO );
         metadata.setSize( TEST_SIZE );
+        metadata.setProjectVersion( VersionUtil.getBaseVersion( version ) );
         metadata.setVersion( version );
 
         MavenArtifactFacet facet = new MavenArtifactFacet();

archiva-modules/archiva-web/archiva-xmlrpc/archiva-xmlrpc-services/src/test/java/org/apache/archiva/web/xmlrpc/services/AdministrationServiceImplTest.java

@@ -719,6 +719,7 @@ public class AdministrationServiceImplTest
         artifact.setId( "archiva-test-1.0.jar" );
         artifact.setProject( "archiva-test" );
         artifact.setVersion( "1.0" );
+        artifact.setProjectVersion( "1.0" );
         artifact.setNamespace( "org.apache.archiva" );
         artifact.setRepositoryId( "internal" );
         artifacts.add( artifact );

archiva-modules/archiva-web/archiva-xmlrpc/archiva-xmlrpc-services/src/test/java/org/apache/archiva/web/xmlrpc/services/SearchServiceImplTest.java

@@ -543,6 +543,7 @@ public class SearchServiceImplTest
         String version = "1.0";
         ArtifactMetadata artifactMetadata = new ArtifactMetadata();
         artifactMetadata.setVersion( version );
+        artifactMetadata.setProjectVersion( version );
         artifactMetadata.setId( ARCHIVA_TEST_ARTIFACT_ID + "-" + version + ".jar" );
         artifactMetadata.setProject( ARCHIVA_TEST_ARTIFACT_ID );
         artifactMetadata.setNamespace( ARCHIVA_TEST_GROUP_ID );

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 + '\'' + '}';
     }
 }

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

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 )

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();

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

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 )

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 )

archiva-modules/plugins/maven2-repository/src/main/java/org/apache/archiva/metadata/repository/storage/maven2/Maven2RepositoryPathTranslator.java

@@ -260,6 +260,7 @@ public class Maven2RepositoryPathTranslator
         metadata.setNamespace( namespace );
         metadata.setProject( projectId );
         metadata.setRepositoryId( repoId );
+        metadata.setProjectVersion( projectVersion );
         metadata.setVersion( version );
 
         facet.setClassifier( classifier );

archiva-modules/plugins/metadata-repository-file/src/main/java/org/apache/archiva/metadata/repository/file/FileMetadataRepository.java

@@ -437,6 +437,7 @@ public class FileMetadataRepository
                     artifact.setRepositoryId( repoId );
                     artifact.setNamespace( namespace );
                     artifact.setProject( projectId );
+                    artifact.setProjectVersion( projectVersion );
                     artifact.setVersion( projectVersion );
                     artifact.setId( id );
                     artifacts.put( id, artifact );

archiva-modules/plugins/metadata-repository-file/src/test/java/org/apache/archiva/metadata/repository/file/FileMetadataRepositoryTest.java

@@ -608,6 +608,7 @@ public class FileMetadataRepositoryTest
         artifact.setRepositoryId( TEST_REPO_ID );
         artifact.setFileLastModified( System.currentTimeMillis() );
         artifact.setVersion( TEST_PROJECT_VERSION );
+        artifact.setProjectVersion( TEST_PROJECT_VERSION );
         artifact.setMd5( TEST_MD5 );
         artifact.setSha1( TEST_SHA1 );
         return artifact;

archiva-modules/plugins/problem-reports/src/test/java/org/apache/archiva/reports/consumers/DuplicateArtifactsConsumerTest.java

@@ -208,6 +208,7 @@ public class DuplicateArtifactsConsumerTest
         artifact.setId( TEST_PROJECT + "-" + version + ".jar" );
         artifact.setNamespace( TEST_NAMESPACE );
         artifact.setProject( TEST_PROJECT );
+        artifact.setProjectVersion( version );
         artifact.setVersion( version );
         artifact.setRepositoryId( TEST_REPO );
         return artifact;

archiva-modules/plugins/repository-statistics/src/test/java/org/apache/archiva/metadata/repository/stats/RepositoryStatisticsManagerTest.java

@@ -437,6 +437,7 @@ public class RepositoryStatisticsManagerTest
         metadata.setId( projectId + "-" + projectVersion + "." + type );
         metadata.setProject( projectId );
         metadata.setSize( 12345L );
+        metadata.setProjectVersion( projectVersion );
         metadata.setVersion( projectVersion );
         metadata.setNamespace( namespace );
 

archiva-modules/pom.xml

@@ -142,6 +142,8 @@
             <link>http://jakarta.apache.org/regexp/apidocs/</link>
             <link>http://velocity.apache.org/engine/releases/velocity-1.5/apidocs/</link>
           </links>
+          <linksource>true</linksource>
+          <show>private</show>
           <tags>
             <tag>
               <name>plexus.component</name>