Issue20/add import resolver

.gitignore

@@ -15,7 +15,7 @@ hs_err_pid*
 *.ipr
 *.iml
 .idea
-/therapi-runtime-javadoc-scribe/build
-/therapi-runtime-javadoc/build
+out
+build
 
-.gradle
+.gradle

acceptance-tests/build.gradle

@@ -0,0 +1,8 @@
+
+dependencies {
+    compile project(':therapi-runtime-javadoc')
+    compile project(':therapi-runtime-javadoc-scribe')
+
+    annotationProcessor project(':therapi-runtime-javadoc')
+    annotationProcessor project(':therapi-runtime-javadoc-scribe')
+}

acceptance-tests/gradle.properties

@@ -0,0 +1 @@
+description = End to end tests that demonstrate capturing and accessing javadocs

acceptance-tests/src/main/java/com/therapi/javadoc/acctests/Example.java

@@ -0,0 +1,19 @@
+package com.therapi.javadoc.acctests;
+
+import  java.util.HashMap;
+import  java.util.Map ;
+
+
+/**
+ * Class java doc.
+ */
+public class Example {
+    /**
+     *
+     * @see Map
+     * @throws RuntimeException Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt.
+     */
+    public Map<String,String> method() {
+        return new HashMap<>();
+    }
+}

acceptance-tests/src/test/java/com/therapi/javadoc/acctests/ExampleTest.java

@@ -0,0 +1,51 @@
+package com.therapi.javadoc.acctests;
+
+import com.github.therapi.runtimejavadoc.ClassJavadoc;
+import com.github.therapi.runtimejavadoc.Comment;
+import com.github.therapi.runtimejavadoc.CommentElement;
+import com.github.therapi.runtimejavadoc.CommentText;
+import com.github.therapi.runtimejavadoc.Link;
+import com.github.therapi.runtimejavadoc.RuntimeJavadoc;
+import com.github.therapi.runtimejavadoc.SeeAlsoJavadoc;
+import com.github.therapi.runtimejavadoc.ThrowsJavadoc;
+import org.junit.Test;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+import static org.junit.Assert.assertEquals;
+
+
+public class ExampleTest {
+    @Test
+    public void givenRelativeClassNameInSeeTag_expectClassNameToBeResolved() {
+        ClassJavadoc         classJavadoc = RuntimeJavadoc.getJavadoc(Example.class);
+        List<SeeAlsoJavadoc> expected     = Collections.singletonList( new SeeAlsoJavadoc( new Link( "Map", "java.util.Map", null, Collections.<String>emptyList() ) ) );
+        List<SeeAlsoJavadoc> actual       = classJavadoc.getMethod( "method" ).getSeeAlso();
+
+        assertEquals( expected, actual );
+    }
+
+    @Test
+    public void givenRelativeExceptionInThrowsTag_expectExceptionClassNameToBeResolved() {
+        ClassJavadoc classJavadoc = RuntimeJavadoc.getJavadoc(Example.class);
+
+        List<ThrowsJavadoc> expected = Collections.singletonList(
+            new ThrowsJavadoc(
+                "java.lang.RuntimeException",
+                new Comment(
+                    Collections.<CommentElement>singletonList(
+                        new CommentText(
+                            "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt."
+                        )
+                    )
+                )
+            )
+        );
+
+        List<ThrowsJavadoc> actual = classJavadoc.getMethod( "method" ).getThrows();
+
+        assertEquals( expected, actual );
+    }
+}

settings.gradle

@@ -2,5 +2,6 @@ rootProject.name = 'therapi-runtime-javadoc'
 
 include 'therapi-runtime-javadoc'
 include 'therapi-runtime-javadoc-scribe'
+include 'acceptance-tests'
 
 enableFeaturePreview('STABLE_PUBLISHING')

therapi-runtime-javadoc-scribe/build.gradle

@@ -39,4 +39,4 @@ publishing {
             }
         }
     }
-}
+}

therapi-runtime-javadoc-scribe/src/main/java/com/github/therapi/runtimejavadoc/internal/JavacImportAccessor.java

@@ -1,15 +1,15 @@
 package com.github.therapi.runtimejavadoc.internal;
 
-import static java.util.Collections.emptySet;
+import com.sun.source.tree.ImportTree;
+import com.sun.source.util.TreePath;
+import com.sun.source.util.Trees;
 
 import javax.annotation.processing.ProcessingEnvironment;
 import javax.lang.model.element.Element;
 import java.util.HashSet;
 import java.util.Set;
 
-import com.sun.source.tree.ImportTree;
-import com.sun.source.util.TreePath;
-import com.sun.source.util.Trees;
+import static java.util.Collections.emptySet;
 
 /**
  * Implementation in separate class file so it fails gracefully in case
@@ -31,7 +31,7 @@ public Set<String> getImports(Element element) {
         }
         Set<String> imports = new HashSet<>();
         for (ImportTree importTree : path.getCompilationUnit().getImports()) {
-            imports.add(importTree.getQualifiedIdentifier().toString());
+            imports.add(importTree.toString().trim());
         }
         return imports;
     }

therapi-runtime-javadoc-scribe/src/main/java/com/github/therapi/runtimejavadoc/internal/JsonJavadocBuilder.java

@@ -17,12 +17,14 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 
 import static com.github.therapi.runtimejavadoc.internal.RuntimeJavadocHelper.constructorsFieldName;
 import static com.github.therapi.runtimejavadoc.internal.RuntimeJavadocHelper.elementDocFieldName;
 import static com.github.therapi.runtimejavadoc.internal.RuntimeJavadocHelper.elementNameFieldName;
 import static com.github.therapi.runtimejavadoc.internal.RuntimeJavadocHelper.enumConstantsFieldName;
 import static com.github.therapi.runtimejavadoc.internal.RuntimeJavadocHelper.fieldsFieldName;
+import static com.github.therapi.runtimejavadoc.internal.RuntimeJavadocHelper.importsFieldName;
 import static com.github.therapi.runtimejavadoc.internal.RuntimeJavadocHelper.isBlank;
 import static com.github.therapi.runtimejavadoc.internal.RuntimeJavadocHelper.methodsFieldName;
 import static com.github.therapi.runtimejavadoc.internal.RuntimeJavadocHelper.paramTypesFieldName;
@@ -55,11 +57,13 @@ JsonObject getClassJavadocAsJsonOrNull(TypeElement classElement) {
         }
 
         final List<Element> emptyList = Collections.emptyList();
+        Set<String>   imports = ImportUtils.getImports( classElement, processingEnv );
         List<Element> enclosedFields = defaultIfNull(children.get(FIELD), emptyList);
         List<Element> enclosedEnumConstants = defaultIfNull(children.get(ENUM_CONSTANT), emptyList);
         List<Element> enclosedMethods = defaultIfNull(children.get(METHOD), emptyList);
         List<Element> encolsedConstructors = defaultIfNull(children.get(CONSTRUCTOR), emptyList);
 
+        JsonArray importsJson = asJsonArray(imports);
         JsonArray fieldDocs = getJavadocsAsJson(enclosedFields, new FieldJavadocAsJson());
         JsonArray enumConstantDocs = getJavadocsAsJson(enclosedEnumConstants, new FieldJavadocAsJson());
         JsonArray methodDocs = getJavadocsAsJson(enclosedMethods, new MethodJavadocAsJson());
@@ -70,6 +74,7 @@ JsonObject getClassJavadocAsJsonOrNull(TypeElement classElement) {
         }
 
         JsonObject json = new JsonObject();
+        json.add(importsFieldName(), importsJson);
         json.add(elementDocFieldName(), classDoc);
         json.add(fieldsFieldName(), fieldDocs);
         json.add(enumConstantsFieldName(), enumConstantDocs);
@@ -78,6 +83,16 @@ JsonObject getClassJavadocAsJsonOrNull(TypeElement classElement) {
         return json;
     }
 
+    private JsonArray asJsonArray( Set<String> imports ) {
+        JsonArray jsonArray = new JsonArray();
+
+        for ( String imp : imports ) {
+            jsonArray.add(imp);
+        }
+
+        return jsonArray;
+    }
+
     private static JsonArray getJavadocsAsJson(List<Element> elements, ElementToJsonFunction createDoc) {
         JsonArray jsonArray = new JsonArray();
         for (Element e : elements) {

therapi-runtime-javadoc/src/main/java/com/github/therapi/runtimejavadoc/ClassJavadoc.java

@@ -45,6 +45,16 @@ public List<MethodJavadoc> getConstructors() {
         return constructors;
     }
 
+    public MethodJavadoc getMethod(String methodName) {
+        for ( MethodJavadoc m : methods ) {
+            if ( m.getName().equals(methodName) ) {
+                return m;
+            }
+        }
+
+        return null;
+    }
+
     @Override
     public String toString() {
         return "ClassJavadoc{" +

therapi-runtime-javadoc/src/main/java/com/github/therapi/runtimejavadoc/ClassResolver.java

@@ -0,0 +1,175 @@
+package com.github.therapi.runtimejavadoc;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+
+
+/**
+ * Searches a list of imports for a specified class.
+ */
+public abstract class ClassResolver implements Comparable<ClassResolver> {
+
+    public static ClassResolver createClassResolverFor( String sourcePackage, Import...imports ) {
+        return createClassResolverFor( sourcePackage, Arrays.asList(imports) );
+    }
+
+    public static ClassResolver createClassResolverFor( String sourcePackage, List<Import> imports ) {
+        return new CompositeClassResolver( createClassResolversFor(sourcePackage,imports) );
+    }
+
+
+    private final int comparisonOrder;
+
+    protected ClassResolver( int comparisonOrder ) {
+        this.comparisonOrder = comparisonOrder;
+    }
+
+    /**
+     * Do ones best to convert classRef into an instance of java.lang.Class.
+     *
+     * @return null if no match was found.
+     */
+    public abstract Class resolveClass( String classRef );
+
+
+    public int compareTo( ClassResolver o ) {
+        return Integer.compare( this.comparisonOrder, o.comparisonOrder );
+    }
+
+
+    private static Class fetchClass( String fqn ) {
+        try {
+            return Class.forName( fqn );
+        } catch ( ClassNotFoundException e ) {
+            return null;
+        }
+    }
+
+
+    private static List<ClassResolver> createClassResolversFor( String sourcePackage, List<Import> imports ) {
+        List<ClassResolver> classResolvers = new ArrayList<>();
+
+        classResolvers.add( new FQNResolver() );
+        classResolvers.add( new FullPackageResolver(sourcePackage) );
+        classResolvers.add( new FullPackageResolver("java.lang") );
+
+        for ( Import declaredImport : imports ) {
+            ClassResolver newResolver = createClassResolverFor( declaredImport );
+
+            if ( newResolver != null ) {
+                classResolvers.add( newResolver );
+            }
+        }
+
+        // ensure that the fully qualified comparators appear ahead of the 'all in package' imports
+        Collections.sort(classResolvers);
+
+        return classResolvers;
+    }
+
+    private static ClassResolver createClassResolverFor( Import declaredImport ) {
+        if ( declaredImport.getStaticMember() == null ) {
+            if ( "*".equals(declaredImport.getClassName()) ) {
+                return new FullPackageResolver(declaredImport.getPkg());
+            } else {
+                Class importedClass = fetchClass( declaredImport.getFullyQualifiedClass() );
+
+                if ( importedClass != null ) {
+                    return new ExactClassResolver(declaredImport.getClassName(), importedClass);
+                }
+            }
+        }
+
+        return null;
+    }
+
+    public String resolveRef( String classRef ) {
+        Class resolvedClass = resolveClass( classRef );
+
+        return resolvedClass == null ? classRef : resolvedClass.getName();
+    }
+
+
+    /**
+     * Given a list of ClassResolvers, return the result of the first one that returns a non-null
+     * result.
+     */
+    private static class CompositeClassResolver extends ClassResolver {
+        private List<ClassResolver> classResolvers;
+
+        private CompositeClassResolver( List<ClassResolver> classResolvers ) {
+            super(0);
+
+            this.classResolvers = classResolvers;
+        }
+
+        public Class resolveClass( String classRef ) {
+            for ( ClassResolver resolver : classResolvers ) {
+                Class resolvedClass = resolver.resolveClass( classRef );
+
+                if ( resolvedClass != null ) {
+                    return resolvedClass;
+                }
+            }
+
+            return null;
+        }
+    }
+
+    /**
+     * Resolves absolute class refs (eg x.y.Z).
+     */
+    private static class FQNResolver extends ClassResolver {
+        public FQNResolver() {
+            super(1);
+        }
+
+        public Class resolveClass( String ref ) {
+            return fetchClass(ref);
+        }
+    }
+
+    /**
+     * Given 'import x.y.Z', match relative class refs that equal 'Z' and return the class
+     * for x.y.Z.
+     */
+    private static class ExactClassResolver extends ClassResolver {
+        private String targetRelativeRef;
+        private Class  explicitClass;
+
+        private ExactClassResolver( String targetRelativeRef, Class matchingClass ) {
+            super(2);
+
+            this.targetRelativeRef = targetRelativeRef;
+            this.explicitClass     = matchingClass;
+        }
+
+        public Class resolveClass( String ref ) {
+            if ( !Objects.equals(targetRelativeRef, ref) ) {
+                return null;
+            }
+
+            return explicitClass;
+        }
+    }
+    /**
+     * Given 'import x.y.*', attempt to load any class ref as though it is within package x.y.
+     */
+    private static class FullPackageResolver extends ClassResolver {
+
+        private String basePackage;
+
+        private FullPackageResolver( String basePackage ) {
+            super(3);
+
+            this.basePackage = basePackage;
+        }
+        public Class resolveClass( String ref ) {
+            return fetchClass(basePackage + "." + ref);
+        }
+
+    }
+}