aoqi@0: /* aoqi@0: * Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved. aoqi@0: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. aoqi@0: * aoqi@0: * This code is free software; you can redistribute it and/or modify it aoqi@0: * under the terms of the GNU General Public License version 2 only, as aoqi@0: * published by the Free Software Foundation. Oracle designates this aoqi@0: * particular file as subject to the "Classpath" exception as provided aoqi@0: * by Oracle in the LICENSE file that accompanied this code. aoqi@0: * aoqi@0: * This code is distributed in the hope that it will be useful, but WITHOUT aoqi@0: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or aoqi@0: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License aoqi@0: * version 2 for more details (a copy is included in the LICENSE file that aoqi@0: * accompanied this code). aoqi@0: * aoqi@0: * You should have received a copy of the GNU General Public License version aoqi@0: * 2 along with this work; if not, write to the Free Software Foundation, aoqi@0: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. aoqi@0: * aoqi@0: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA aoqi@0: * or visit www.oracle.com if you need additional information or have any aoqi@0: * questions. aoqi@0: */ aoqi@0: package javax.tools; aoqi@0: aoqi@0: import java.io.Writer; aoqi@0: import java.nio.charset.Charset; aoqi@0: import java.util.Locale; aoqi@0: import java.util.concurrent.Callable; aoqi@0: aoqi@0: /** aoqi@0: * Interface to invoke Java™ programming language documentation tools from aoqi@0: * programs. aoqi@0: */ aoqi@0: public interface DocumentationTool extends Tool, OptionChecker { aoqi@0: /** aoqi@0: * Creates a future for a documentation task with the given aoqi@0: * components and arguments. The task might not have aoqi@0: * completed as described in the DocumentationTask interface. aoqi@0: * aoqi@0: *

If a file manager is provided, it must be able to handle all aoqi@0: * locations defined in {@link DocumentationTool.Location}, aoqi@0: * as well as aoqi@0: * {@link StandardLocation#SOURCE_PATH}, aoqi@0: * {@link StandardLocation#CLASS_PATH}, and aoqi@0: * {@link StandardLocation#PLATFORM_CLASS_PATH}. aoqi@0: * aoqi@0: * @param out a Writer for additional output from the tool; aoqi@0: * use {@code System.err} if {@code null} aoqi@0: * aoqi@0: * @param fileManager a file manager; if {@code null} use the aoqi@0: * tool's standard filemanager aoqi@0: * aoqi@0: * @param diagnosticListener a diagnostic listener; if {@code null} aoqi@0: * use the tool's default method for reporting diagnostics aoqi@0: * aoqi@0: * @param docletClass a class providing the necessary methods required aoqi@0: * of a doclet aoqi@0: * aoqi@0: * @param options documentation tool options and doclet options, aoqi@0: * {@code null} means no options aoqi@0: * aoqi@0: * @param compilationUnits the compilation units to compile, {@code aoqi@0: * null} means no compilation units aoqi@0: * aoqi@0: * @return an object representing the compilation aoqi@0: * aoqi@0: * @throws RuntimeException if an unrecoverable error aoqi@0: * occurred in a user supplied component. The aoqi@0: * {@linkplain Throwable#getCause() cause} will be the error in aoqi@0: * user code. aoqi@0: * aoqi@0: * @throws IllegalArgumentException if any of the given aoqi@0: * compilation units are of other kind than aoqi@0: * {@linkplain JavaFileObject.Kind#SOURCE source} aoqi@0: */ aoqi@0: DocumentationTask getTask(Writer out, aoqi@0: JavaFileManager fileManager, aoqi@0: DiagnosticListener diagnosticListener, aoqi@0: Class docletClass, aoqi@0: Iterable options, aoqi@0: Iterable compilationUnits); aoqi@0: aoqi@0: /** aoqi@0: * Gets a new instance of the standard file manager implementation aoqi@0: * for this tool. The file manager will use the given diagnostic aoqi@0: * listener for producing any non-fatal diagnostics. Fatal errors aoqi@0: * will be signaled with the appropriate exceptions. aoqi@0: * aoqi@0: *

The standard file manager will be automatically reopened if aoqi@0: * it is accessed after calls to {@code flush} or {@code close}. aoqi@0: * The standard file manager must be usable with other tools. aoqi@0: * aoqi@0: * @param diagnosticListener a diagnostic listener for non-fatal aoqi@0: * diagnostics; if {@code null} use the compiler's default method aoqi@0: * for reporting diagnostics aoqi@0: * aoqi@0: * @param locale the locale to apply when formatting diagnostics; aoqi@0: * {@code null} means the {@linkplain Locale#getDefault() default locale}. aoqi@0: * aoqi@0: * @param charset the character set used for decoding bytes; if aoqi@0: * {@code null} use the platform default aoqi@0: * aoqi@0: * @return the standard file manager aoqi@0: */ aoqi@0: StandardJavaFileManager getStandardFileManager( aoqi@0: DiagnosticListener diagnosticListener, aoqi@0: Locale locale, aoqi@0: Charset charset); aoqi@0: aoqi@0: /** aoqi@0: * Interface representing a future for a documentation task. The aoqi@0: * task has not yet started. To start the task, call aoqi@0: * the {@linkplain #call call} method. aoqi@0: * aoqi@0: *

Before calling the call method, additional aspects of the aoqi@0: * task can be configured, for example, by calling the aoqi@0: * {@linkplain #setLocale setLocale} method. aoqi@0: */ aoqi@0: interface DocumentationTask extends Callable { aoqi@0: /** aoqi@0: * Set the locale to be applied when formatting diagnostics and aoqi@0: * other localized data. aoqi@0: * aoqi@0: * @param locale the locale to apply; {@code null} means apply no aoqi@0: * locale aoqi@0: * @throws IllegalStateException if the task has started aoqi@0: */ aoqi@0: void setLocale(Locale locale); aoqi@0: aoqi@0: /** aoqi@0: * Performs this documentation task. The task may only aoqi@0: * be performed once. Subsequent calls to this method throw aoqi@0: * IllegalStateException. aoqi@0: * aoqi@0: * @return true if and only all the files were processed without errors; aoqi@0: * false otherwise aoqi@0: * aoqi@0: * @throws RuntimeException if an unrecoverable error occurred aoqi@0: * in a user-supplied component. The aoqi@0: * {@linkplain Throwable#getCause() cause} will be the error aoqi@0: * in user code. aoqi@0: * aoqi@0: * @throws IllegalStateException if called more than once aoqi@0: */ aoqi@0: Boolean call(); aoqi@0: } aoqi@0: aoqi@0: /** aoqi@0: * Locations specific to {@link DocumentationTool}. aoqi@0: * aoqi@0: * @see StandardLocation aoqi@0: */ aoqi@0: enum Location implements JavaFileManager.Location { aoqi@0: /** aoqi@0: * Location of new documentation files. aoqi@0: */ aoqi@0: DOCUMENTATION_OUTPUT, aoqi@0: aoqi@0: /** aoqi@0: * Location to search for doclets. aoqi@0: */ aoqi@0: DOCLET_PATH, aoqi@0: aoqi@0: /** aoqi@0: * Location to search for taglets. aoqi@0: */ aoqi@0: TAGLET_PATH; aoqi@0: aoqi@0: public String getName() { return name(); } aoqi@0: aoqi@0: public boolean isOutputLocation() { aoqi@0: switch (this) { aoqi@0: case DOCUMENTATION_OUTPUT: aoqi@0: return true; aoqi@0: default: aoqi@0: return false; aoqi@0: } aoqi@0: } aoqi@0: } aoqi@0: aoqi@0: }