Java Code Examples for javax.tools.DocumentationTool.DocumentationTask#call()

/**
 * Verify that expected output files are written via the file manager,
 * for a source file read from the file system with StandardJavaFileManager.
 */
@Test
public void testStandardFileObject() throws Exception {
    File testSrc = new File(System.getProperty("test.src"));
    File srcFile = new File(testSrc, "pkg/C.java");
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    StandardJavaFileManager fm = tool.getStandardFileManager(null, null, null);
    File outDir = getOutDir();
    fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
    Iterable<? extends JavaFileObject> files = fm.getJavaFileObjects(srcFile);
    DocumentationTask t = tool.getTask(null, fm, null, null, null, files);
    if (t.call()) {
        System.err.println("task succeeded");
        checkFiles(outDir, standardExpectFiles);
    } else {
        throw new Exception("task failed");
    }
}
 

/**
 * Verify that exceptions from a doclet are thrown as expected.
 */
@Test
public void testBadDoclet() throws Exception {
    JavaFileObject srcFile = createSimpleJavaFileObject();
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    StandardJavaFileManager fm = tool.getStandardFileManager(null, null, null);
    File outDir = getOutDir();
    fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
    Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
    DocumentationTask t = tool.getTask(null, fm, null, BadDoclet.class, null, files);
    try {
        t.call();
        error("call completed without exception");
    } catch (RuntimeException e) {
        Throwable c = e.getCause();
        if (c.getClass() == UnexpectedError.class)
            System.err.println("exception caught as expected: " + c);
        else
            throw e;
    }
}
 

/**
 * Verify that expected output files are written via the file manager,
 * for an in-memory file object.
 */
@Test
public void testMemoryFileObject() throws Exception {
    JavaFileObject srcFile = createSimpleJavaFileObject();
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    StandardJavaFileManager fm = tool.getStandardFileManager(null, null, null);
    File outDir = getOutDir();
    fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
    Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
    DocumentationTask t = tool.getTask(null, fm, null, null, null, files);
    if (t.call()) {
        System.err.println("task succeeded");
        checkFiles(outDir, standardExpectFiles);
    } else {
        throw new Exception("task failed");
    }
}
 

/**
 * Verify that exceptions from a doclet are thrown as expected.
 */
@Test
public void testBadDoclet() throws Exception {
    JavaFileObject srcFile = createSimpleJavaFileObject();
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    try (StandardJavaFileManager fm = tool.getStandardFileManager(null, null, null)) {
        File outDir = getOutDir();
        fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
        Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
        DocumentationTask t = tool.getTask(null, fm, null, BadDoclet.class, null, files);
        try {
            t.call();
            error("call completed without exception");
        } catch (RuntimeException e) {
            Throwable c = e.getCause();
            if (c.getClass() == UnexpectedError.class)
                System.err.println("exception caught as expected: " + c);
            else
                throw e;
        }
    }
}
 

/**
 * Verify that an alternate doclet can be specified.
 *
 * There is no standard interface or superclass for a doclet;
 * the only requirement is that it provides static methods that
 * can be invoked via reflection. So, for now, the doclet is
 * specified as a class.
 * Because we cannot create and use a unique instance of the class,
 * we verify that the doclet has been called by having it record
 * (in a static field!) the comment from the last time it was invoked,
 * which is randomly generated each time the test is run.
 */
@Test
public void testDoclet() throws Exception {
    Random r = new Random();
    int key = r.nextInt();
    JavaFileObject srcFile = createSimpleJavaFileObject(
            "pkg/C",
            "package pkg; /** " + key + "*/ public class C { }");
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    try (StandardJavaFileManager fm = tool.getStandardFileManager(null, null, null)) {
        File outDir = getOutDir();
        fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
        Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
        DocumentationTask t = tool.getTask(null, fm, null, TestDoclet.class, null, files);
        if (t.call()) {
            System.err.println("task succeeded");
            if (TestDoclet.lastCaller.equals(String.valueOf(key)))
                System.err.println("found expected key: " + key);
            else
                error("Expected key not found");
            checkFiles(outDir, Collections.<String>emptySet());
        } else {
            throw new Exception("task failed");
        }
    }
}
 

/**
 * Verify that an alternate file manager can be specified:
 * in this case, a PathFileManager.
 */
@Test
public void testFileManager() throws Exception {
    JavaFileObject srcFile = createSimpleJavaFileObject();
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    PathFileManager fm = new JavacPathFileManager(new Context(), false, null);
    Path outDir = getOutDir().toPath();
    fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
    Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
    DocumentationTask t = tool.getTask(null, fm, null, null, null, files);
    if (t.call()) {
        System.err.println("task succeeded");
        checkFiles(outDir, standardExpectFiles);
    } else {
        throw new Exception("task failed");
    }
}
 

/**
 * Verify that an alternate file manager can be specified:
 * in this case, a TestFileManager.
 */
@Test
public void testFileManager() throws Exception {
    JavaFileObject srcFile = createSimpleJavaFileObject();
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    StandardJavaFileManager fm = new TestFileManager();
    File outDir = getOutDir();
    fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
    Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
    DocumentationTask t = tool.getTask(null, fm, null, null, Arrays.asList("-verbose"), files);
    if (t.call()) {
        System.err.println("task succeeded");
        checkFiles(outDir, standardExpectFiles);
    } else {
        throw new Exception("task failed");
    }
}
 

/**
 * Verify that exceptions from a doclet are thrown as expected.
 */
@Test
public void testBadDoclet() throws Exception {
    JavaFileObject srcFile = createSimpleJavaFileObject();
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    StandardJavaFileManager fm = tool.getStandardFileManager(null, null, null);
    File outDir = getOutDir();
    fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
    Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
    DocumentationTask t = tool.getTask(null, fm, null, BadDoclet.class, null, files);
    try {
        t.call();
        error("call completed without exception");
    } catch (RuntimeException e) {
        Throwable c = e.getCause();
        if (c.getClass() == UnexpectedError.class)
            System.err.println("exception caught as expected: " + c);
        else
            throw e;
    }
}
 

/**
 * Verify that expected output files are written via the file manager,
 * for an in-memory file object.
 */
@Test
public void testMemoryFileObject() throws Exception {
    JavaFileObject srcFile = createSimpleJavaFileObject();
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    StandardJavaFileManager fm = tool.getStandardFileManager(null, null, null);
    File outDir = getOutDir();
    fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
    Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
    DocumentationTask t = tool.getTask(null, fm, null, null, null, files);
    if (t.call()) {
        System.err.println("task succeeded");
        checkFiles(outDir, standardExpectFiles);
    } else {
        throw new Exception("task failed");
    }
}
 

@Test
public void testDirectAccess1() throws Exception {
    JavaFileObject srcFile = createSimpleJavaFileObject();
    Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
    Context c = new Context();
    Messager.preRegister(c, "javadoc");
    StandardJavaFileManager fm = new JavacFileManager(c, true, null);
    File outDir = getOutDir();
    fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
    DocumentationTask t = new JavadocTaskImpl(c, null, null, files);
    if (t.call()) {
        System.err.println("task succeeded");
    } else {
        throw new Exception("task failed");
    }
}
 

/**
 * Verify that expected output files are written via the file manager,
 * for a source file read from the file system with StandardJavaFileManager.
 */
@Test
public void testStandardFileObject() throws Exception {
    File testSrc = new File(System.getProperty("test.src"));
    File srcFile = new File(testSrc, "pkg/C.java");
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    StandardJavaFileManager fm = tool.getStandardFileManager(null, null, null);
    File outDir = getOutDir();
    fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
    Iterable<? extends JavaFileObject> files = fm.getJavaFileObjects(srcFile);
    DocumentationTask t = tool.getTask(null, fm, null, null, null, files);
    if (t.call()) {
        System.err.println("task succeeded");
        checkFiles(outDir, standardExpectFiles);
    } else {
        throw new Exception("task failed");
    }
}
 

/**
 * Verify that a writer can be provided.
 */
@Test
public void testWriter() throws Exception {
    JavaFileObject srcFile = createSimpleJavaFileObject();
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    StandardJavaFileManager fm = tool.getStandardFileManager(null, null, null);
    File outDir = getOutDir();
    fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
    Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
    StringWriter sw = new StringWriter();
    PrintWriter pw = new PrintWriter(sw);
    DocumentationTask t = tool.getTask(pw, fm, null, null, null, files);
    if (t.call()) {
        System.err.println("task succeeded");
        checkFiles(outDir, standardExpectFiles);
        String out = sw.toString();
        System.err.println(">>" + out + "<<");
        for (String f: standardExpectFiles) {
            String f1 = f.replace('/', File.separatorChar);
            if (f1.endsWith(".html") && !out.contains(f1))
                throw new Exception("expected string not found: " + f1);
        }
    } else {
        throw new Exception("task failed");
    }
}
 

/**
 * Verify that an alternate doclet can be specified.
 *
 * There is no standard interface or superclass for a doclet;
 * the only requirement is that it provides static methods that
 * can be invoked via reflection. So, for now, the doclet is
 * specified as a class.
 * Because we cannot create and use a unique instance of the class,
 * we verify that the doclet has been called by having it record
 * (in a static field!) the comment from the last time it was invoked,
 * which is randomly generated each time the test is run.
 */
@Test
public void testDoclet() throws Exception {
    Random r = new Random();
    int key = r.nextInt();
    JavaFileObject srcFile = createSimpleJavaFileObject(
            "pkg/C",
            "package pkg; /** " + key + "*/ public class C { }");
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    StandardJavaFileManager fm = tool.getStandardFileManager(null, null, null);
    File outDir = getOutDir();
    fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
    Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
    DocumentationTask t = tool.getTask(null, fm, null, TestDoclet.class, null, files);
    if (t.call()) {
        System.err.println("task succeeded");
        if (TestDoclet.lastCaller.equals(String.valueOf(key)))
            System.err.println("found expected key: " + key);
        else
            error("Expected key not found");
        checkFiles(outDir, Collections.<String>emptySet());
    } else {
        throw new Exception("task failed");
    }
}
 

/**
 * Verify that a writer can be provided.
 */
@Test
public void testWriter() throws Exception {
    JavaFileObject srcFile = createSimpleJavaFileObject();
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    try (StandardJavaFileManager fm = tool.getStandardFileManager(null, null, null)) {
        File outDir = getOutDir();
        fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
        Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
        StringWriter sw = new StringWriter();
        PrintWriter pw = new PrintWriter(sw);
        DocumentationTask t = tool.getTask(pw, fm, null, null, null, files);
        if (t.call()) {
            System.err.println("task succeeded");
            checkFiles(outDir, standardExpectFiles);
            String out = sw.toString();
            System.err.println(">>" + out + "<<");
            for (String f: standardExpectFiles) {
                String f1 = f.replace('/', File.separatorChar);
                if (f1.endsWith(".html") && !out.contains(f1))
                    throw new Exception("expected string not found: " + f1);
            }
        } else {
            throw new Exception("task failed");
        }
    }
}
 

/**
 * Verify that exceptions from a bad file manager are thrown as expected.
 */
@Test
public void testBadFileManager() throws Exception {
    JavaFileObject srcFile = createSimpleJavaFileObject();
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    PathFileManager fm = new JavacPathFileManager(new Context(), false, null) {
        @Override
        public Iterable<JavaFileObject> list(Location location,
                String packageName,
                Set<Kind> kinds,
                boolean recurse)
                throws IOException {
            throw new UnexpectedError();
        }
    };
    Path outDir = getOutDir().toPath();
    fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
    Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
    DocumentationTask t = tool.getTask(null, fm, null, null, null, files);
    try {
        t.call();
        error("call completed without exception");
    } catch (RuntimeException e) {
        Throwable c = e.getCause();
        if (c.getClass() == UnexpectedError.class)
            System.err.println("exception caught as expected: " + c);
        else
            throw e;
    }
}
 

private DocumentationTask getAndRunTask() throws Exception {
    JavaFileObject srcFile = createSimpleJavaFileObject();
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    StandardJavaFileManager fm = tool.getStandardFileManager(null, null, null);
    File outDir = getOutDir();
    fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
    Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
    DocumentationTask t = tool.getTask(null, fm, null, null, null, files);
    if (t.call()) {
        System.err.println("task succeeded");
        return t;
    } else {
        throw new Exception("task failed");
    }
}
 

/**
 * Verify that an alternate doclet can be specified, and located via
 * the file manager's DOCLET_PATH.
 */
@Test
public void testDocletPath() throws Exception {
    JavaFileObject docletSrc =
            createSimpleJavaFileObject("DocletOnDocletPath", docletSrcText);
    File docletDir = getOutDir("classes");
    JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
    StandardJavaFileManager cfm = compiler.getStandardFileManager(null, null, null);
    cfm.setLocation(StandardLocation.CLASS_OUTPUT, Arrays.asList(docletDir));
    Iterable<? extends JavaFileObject> cfiles = Arrays.asList(docletSrc);
    if (!compiler.getTask(null, cfm, null, null, null, cfiles).call())
        throw new Exception("cannot compile doclet");

    JavaFileObject srcFile = createSimpleJavaFileObject();
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    StandardJavaFileManager fm = tool.getStandardFileManager(null, null, null);
    File outDir = getOutDir("api");
    fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
    fm.setLocation(DocumentationTool.Location.DOCLET_PATH, Arrays.asList(docletDir));
    Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
    Iterable<String> options = Arrays.asList("-doclet", "DocletOnDocletPath");
    StringWriter sw = new StringWriter();
    PrintWriter pw = new PrintWriter(sw);
    DocumentationTask t = tool.getTask(pw, fm, null, null, options, files);
    boolean ok = t.call();
    String out = sw.toString();
    System.err.println(">>" + out + "<<");
    if (ok) {
        if (out.contains(TEST_STRING)) {
            System.err.println("doclet executed as expected");
        } else {
            error("test string not found in doclet output");
        }
    } else {
        error("task failed");
    }
}
 

/**
 * Verify that call can only be called once.
 */
@Test
public void testReuse() throws Exception {
    DocumentationTask t = getAndRunTask();
    try {
        t.call();
        error("task was reused without exception");
    } catch (IllegalStateException e) {
        System.err.println("caught exception " + e);
    }
}
 

/**
 * Verify that exceptions from a bad file manager are thrown as expected.
 */
@Test
public void testBadFileManager() throws Exception {
    JavaFileObject srcFile = createSimpleJavaFileObject();
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    PathFileManager fm = new JavacPathFileManager(new Context(), false, null) {
        @Override
        public Iterable<JavaFileObject> list(Location location,
                String packageName,
                Set<Kind> kinds,
                boolean recurse)
                throws IOException {
            throw new UnexpectedError();
        }
    };
    Path outDir = getOutDir().toPath();
    fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
    Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
    DocumentationTask t = tool.getTask(null, fm, null, null, null, files);
    try {
        t.call();
        error("call completed without exception");
    } catch (RuntimeException e) {
        Throwable c = e.getCause();
        if (c.getClass() == UnexpectedError.class)
            System.err.println("exception caught as expected: " + c);
        else
            throw e;
    }
}
 

/**
 * Verify that a taglet can be specified, and located via
 * the file manager's TAGLET_PATH.
 */
@Test
public void testTagletPath() throws Exception {
    File testSrc = new File(System.getProperty("test.src"));
    File tagletSrcFile = new File(testSrc, "taglets/UnderlineTaglet.java");
    File tagletDir = getOutDir("classes");
    JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
    StandardJavaFileManager cfm = compiler.getStandardFileManager(null, null, null);
    cfm.setLocation(StandardLocation.CLASS_OUTPUT, Arrays.asList(tagletDir));
    Iterable<? extends JavaFileObject> cfiles = cfm.getJavaFileObjects(tagletSrcFile);
    if (!compiler.getTask(null, cfm, null, null, null, cfiles).call())
        throw new Exception("cannot compile taglet");

    JavaFileObject srcFile = createSimpleJavaFileObject("pkg/C", testSrcText);
    DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
    StandardJavaFileManager fm = tool.getStandardFileManager(null, null, null);
    File outDir = getOutDir("api");
    fm.setLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(outDir));
    fm.setLocation(DocumentationTool.Location.TAGLET_PATH, Arrays.asList(tagletDir));
    Iterable<? extends JavaFileObject> files = Arrays.asList(srcFile);
    Iterable<String> options = Arrays.asList("-taglet", "UnderlineTaglet");
    StringWriter sw = new StringWriter();
    PrintWriter pw = new PrintWriter(sw);
    DocumentationTask t = tool.getTask(pw, fm, null, null, options, files);
    boolean ok = t.call();
    String out = sw.toString();
    System.err.println(">>" + out + "<<");
    if (ok) {
        File f = new File(outDir, "pkg/C.html");
        List<String> doc = Files.readAllLines(f.toPath(), Charset.defaultCharset());
        for (String line: doc) {
            if (line.contains("<u>" + TEST_STRING + "</u>")) {
                System.err.println("taglet executed as expected");
                return;
            }
        }
        error("expected text not found in output " + f);
    } else {
        error("task failed");
    }
}