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 super JavaFileObject> diagnosticListener,
aoqi@0: Class> docletClass,
aoqi@0: Iterable 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 super JavaFileObject> 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