Merged in the branch "nexus-indexer-docs": mostly Javadoc updates, an…

…d retionalization of the code.

git-svn-id: file:///opt/svn/repositories/sonatype.org/nexus/trunk/nexus-indexer@3478 2aa8b3fc-8ebb-4439-a84f-95066eaea8ab

pom.xml

@@ -133,7 +133,7 @@
           <forkMode>never</forkMode>
         </configuration>
       </plugin>
-
+      
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-shade-plugin</artifactId>
@@ -205,6 +205,14 @@
           -->
         </configuration>
       </plugin>
+
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <configuration>
+          <overview>/src/main/java/overview-summary.html</overview>
+        </configuration>
+      </plugin>
     </plugins>
   </build>
 

src/main/java/org/sonatype/nexus/artifact/AbstractGavCalculator.java

@@ -6,9 +6,10 @@
  */
 package org.sonatype.nexus.artifact;
 
-import org.sonatype.nexus.DefaultNexusEnforcer;
-import org.sonatype.nexus.NexusEnforcer;
 
+/**
+ * An abstract <code>GavCalculator</code> base class.
+ */
 public abstract class AbstractGavCalculator
     implements GavCalculator
 {

src/main/java/org/sonatype/nexus/DefaultNexusEnforcer.java → src/main/java/org/sonatype/nexus/artifact/DefaultNexusEnforcer.java

@@ -4,9 +4,10 @@
  * This program and the accompanying materials are made available under the terms of the Eclipse Public License Version 1.0,
  * which accompanies this distribution and is available at http://www.eclipse.org/legal/epl-v10.html.
  */
-package org.sonatype.nexus;
+package org.sonatype.nexus.artifact;
 
 import org.codehaus.plexus.component.annotations.Component;
+import org.sonatype.nexus.artifact.NexusEnforcer;
 
 /**
  * The Default Nexus Enforcer.  At some piont this can all be config based, but for now

src/main/java/org/sonatype/nexus/artifact/Gav.java

@@ -6,18 +6,23 @@
  */
 package org.sonatype.nexus.artifact;
 
-import org.sonatype.nexus.DefaultNexusEnforcer;
 
 /**
  * A value class representing unique artifact coordinates
  */
 public class Gav
 {
+    /**
+     * Enumeration representing Maven artifact hash types
+     */
     public enum HashType
     {
         sha1, md5
     }
 
+    /**
+     * Enumeration representing Maven artifact signature types
+     */
     public enum SignatureType
     {
         gpg;

src/main/java/org/sonatype/nexus/artifact/M1ArtifactRecognizer.java

@@ -6,6 +6,9 @@
  */
 package org.sonatype.nexus.artifact;
 
+/**
+ * Utility methods for basic "detection" of artifact kind in M1 repository.
+ */
 public class M1ArtifactRecognizer {
 	/**
 	 * Is this item M1 Checksum?

src/main/java/org/sonatype/nexus/artifact/M1GavCalculator.java

@@ -12,7 +12,7 @@
 import org.codehaus.plexus.component.annotations.Component;
 
 /**
- * The M1 GAV Calculator.
+ * An M1 <code>GavCalculator</code>.
  * 
  * @author Jason van Zyl
  * @author Tamas Cservenak

src/main/java/org/sonatype/nexus/artifact/M2ArtifactRecognizer.java

@@ -7,7 +7,7 @@
 package org.sonatype.nexus.artifact;
 
 /**
- * A simple class for some very basic "detection" of the kind of path.
+ * Utility methods for basic "detection" of artifact kind in M2 repository.
  */
 public class M2ArtifactRecognizer
 {

src/main/java/org/sonatype/nexus/artifact/M2GavCalculator.java

@@ -12,7 +12,7 @@
 import org.codehaus.plexus.component.annotations.Component;
 
 /**
- * The M2 GAV Calculator.
+ * An M2 <code>GavCalculator</code>.
  * 
  * @author Jason van Zyl
  * @author Tamas Cservenak

src/main/java/org/sonatype/nexus/NexusEnforcer.java → src/main/java/org/sonatype/nexus/artifact/NexusEnforcer.java

@@ -4,7 +4,7 @@
  * This program and the accompanying materials are made available under the terms of the Eclipse Public License Version 1.0,
  * which accompanies this distribution and is available at http://www.eclipse.org/legal/epl-v10.html.
  */
-package org.sonatype.nexus;
+package org.sonatype.nexus.artifact;
 
 public interface NexusEnforcer
 {

src/main/java/org/sonatype/nexus/artifact/VersionUtils.java

@@ -9,9 +9,10 @@
 import java.util.regex.Pattern;
 
 import org.apache.maven.artifact.Artifact;
-import org.sonatype.nexus.DefaultNexusEnforcer;
-import org.sonatype.nexus.NexusEnforcer;
 
+/**
+ * Utility methods for working with artifact version strings
+ */
 public class VersionUtils
 {
     private static NexusEnforcer enforcer = new DefaultNexusEnforcer();

src/main/java/org/sonatype/nexus/artifact/package.html

@@ -0,0 +1,11 @@
+<html>
+<!--
+ Copyright (c) 2007-2008 Sonatype, Inc. All rights reserved.
+
+ This program and the accompanying materials are made available under the terms of the Eclipse Public License Version 1.0,
+ which accompanies this distribution and is available at http://www.eclipse.org/legal/epl-v10.html.
+-->
+<body>
+Provides functionality to work with artifacts, their versions and paths in Maven 1 and Maven 2 repositories.
+</body>
+</html>

src/main/java/org/sonatype/nexus/index/ArtifactAvailablility.java

@@ -6,6 +6,9 @@
  */
 package org.sonatype.nexus.index;
 
+/**
+ * Enumeration provides values indicating artifact availability
+ */
 public enum ArtifactAvailablility
 {
     /**

src/main/java/org/sonatype/nexus/index/ArtifactContext.java

@@ -7,13 +7,25 @@
 package org.sonatype.nexus.index;
 
 import java.io.File;
+import java.io.IOException;
 import java.util.ArrayList;
 import java.util.List;
 
+import org.apache.lucene.document.Document;
+import org.apache.lucene.document.Field;
+import org.apache.lucene.document.Field.Index;
+import org.apache.lucene.document.Field.Store;
 import org.sonatype.nexus.artifact.Gav;
+import org.sonatype.nexus.index.context.IndexCreator;
+import org.sonatype.nexus.index.context.IndexingContext;
 
 /**
- * The context of an artifact.
+ * An artifact context used to provide information about artifact during
+ * scanning. It is passed to the {@link IndexCreator}, which can populate
+ * {@link ArtifactInfo} for the given artifact.
+ * 
+ * @see IndexCreator#populateArtifactInfo(ArtifactContext)
+ * @see NexusIndexer#scan(IndexingContext)
  * 
  * @author Jason van Zyl
  * @author Tamas Cservenak
@@ -80,4 +92,39 @@ public void addError(Exception e)
     {
         errors.add( e );
     }
+
+    /**
+     * Creates Lucene Document using {@link IndexCreator}s from the given {@link IndexingContext}.
+     */
+    public Document createDocument( IndexingContext context )
+    {
+        Document doc = new Document();
+
+        // unique key
+        doc.add( new Field( ArtifactInfo.UINFO, getArtifactInfo().getUinfo(),
+            Store.YES, Index.UN_TOKENIZED ) );
+
+        doc.add( new Field( ArtifactInfo.LAST_MODIFIED, //
+            Long.toString( System.currentTimeMillis() ), Store.YES, Index.NO ) );
+
+        for ( IndexCreator indexCreator : context.getIndexCreators() )
+        {
+            try 
+            {
+                indexCreator.populateArtifactInfo( this );
+            } 
+            catch ( IOException ex ) 
+            {
+                addError( ex );
+            }
+        }
+
+        // need a second pass in case index creators updated document attributes
+        for ( IndexCreator indexCreator : context.getIndexCreators() )
+        {
+            indexCreator.updateDocument( getArtifactInfo(), doc );
+        }
+
+        return doc;
+    }
 }

src/main/java/org/sonatype/nexus/index/ArtifactContextProducer.java

@@ -11,9 +11,9 @@
 import org.sonatype.nexus.index.context.IndexingContext;
 
 /**
- * A producer that creates ArtifactContext from POM (and possibly other available files).
+ * A producer that creates {@link ArtifactContext} from POM and from other available files.
  * 
- * @author cstamas
+ * @author Tamas Cservenak
  */
 public interface ArtifactContextProducer
 {

src/main/java/org/sonatype/nexus/index/ArtifactDiscoveryListener.java

@@ -7,7 +7,7 @@
 package org.sonatype.nexus.index;
 
 /**
- * Listener triggered on artifact discovery.
+ * A listener notified upon artifact discovery.
  * 
  * @author Tamas Cservenak
  */

src/main/java/org/sonatype/nexus/index/ArtifactInfo.java

@@ -7,14 +7,17 @@
 package org.sonatype.nexus.index;
 
 import java.io.Serializable;
+import java.util.Arrays;
+import java.util.Collection;
 import java.util.Comparator;
 import java.util.List;
+import java.util.regex.Pattern;
 
 import org.apache.maven.artifact.versioning.ArtifactVersion;
 import org.apache.maven.artifact.versioning.DefaultArtifactVersion;
+import org.codehaus.plexus.util.StringUtils;
 import org.sonatype.nexus.artifact.Gav;
 import org.sonatype.nexus.artifact.VersionUtils;
-import org.sonatype.nexus.index.creator.AbstractIndexCreator;
 
 /**
  * ArtifactInfo holds the values known about an repository artifact. This is a simple Value Object kind of stuff.
@@ -27,6 +30,14 @@ public class ArtifactInfo
 {
     private static final long serialVersionUID = 6028843453477511104L;
 
+    /** Field separator */
+    public static final String FS = "|";
+
+    public static final Pattern FS_PATTERN = Pattern.compile( Pattern.quote( FS ) );
+
+    /** Non available value */
+    public static final String NA = "NA";
+
     public static final String ROOT_GROUPS = "rootGroups";
 
     public static final String ROOT_GROUPS_VALUE = "rootGroups";
@@ -128,9 +139,9 @@ public class ArtifactInfo
      */
     public static final String DELETED = "del";
 
-    public static final VersionComparator VERSION_COMPARATOR = new VersionComparator();
+    public static final Comparator<ArtifactInfo> VERSION_COMPARATOR = new VersionComparator();
 
-    public static final VersionComparator REPOSITORY_VERSION_COMPARATOR = new RepositoryVersionComparator();
+    public static final Comparator<ArtifactInfo> REPOSITORY_VERSION_COMPARATOR = new RepositoryVersionComparator();
 
     public String fname;
 
@@ -243,17 +254,28 @@ public String getUinfo()
     {
         if( uinfo == null )
         {
-            uinfo = AbstractIndexCreator.getGAV( //
-              groupId, //
-              artifactId, //
-              version, //
-              classifier, //
-              packaging );  // extension is stored in the packaging field when classifier is not used
+            uinfo = new StringBuilder() //
+            .append( groupId ).append( FS ) //
+            .append( artifactId ).append( FS ) //
+            .append( version ).append( FS ) //
+            .append( nvl( classifier ) ) //
+            .append( StringUtils.isEmpty( classifier ) || StringUtils.isEmpty( packaging ) ? "" : FS + packaging ) //
+            .toString();  // extension is stored in the packaging field when classifier is not used
         }
 
         return uinfo;    
     }
 
+    public String getRootGroup()
+    {
+        int n = groupId.indexOf( '.' );
+        if ( n > -1 )
+        {
+            return groupId.substring( 0, n );
+        }
+        return groupId;
+    }
+
     public Gav calculateGav() 
     {
         return new Gav( 
@@ -286,7 +308,35 @@ public String toString()
     // Utils
     // ----------------------------------------------------------------------------
 
-    public static class VersionComparator
+    public static String nvl( String v )
+    {
+        return v == null ? NA : v;
+    }
+
+    public static String renvl( String v )
+    {
+        return NA.equals( v ) ? null : v;
+    }
+
+    public static String lst2str( Collection<String> list )
+    {
+        StringBuilder sb = new StringBuilder();
+        for ( String s : list )
+        {
+            sb.append( s ).append( ArtifactInfo.FS );
+        }
+        return sb.length()==0 ? sb.toString() : sb.substring( 0, sb.length() - 1 );
+    }
+
+    public static List<String> str2lst( String str )
+    {
+        return Arrays.asList( ArtifactInfo.FS_PATTERN.split( str ) );
+    }
+
+    /**
+     * A version comparator
+     */
+    static class VersionComparator
         implements Comparator<ArtifactInfo>
     {
         @SuppressWarnings( "unchecked" )
@@ -350,7 +400,10 @@ public int compare( ArtifactInfo f1, ArtifactInfo f2 )
         }
     }
 
-    public static class RepositoryVersionComparator
+    /**
+     * A repository and version comparator
+     */
+    static class RepositoryVersionComparator
         extends VersionComparator
     {
         @Override