/*
* Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.tools;
import java.io.Writer;
import java.nio.charset.Charset;
import java.util.Locale;
import java.util.concurrent.Callable;
/**
* Interface to invoke Java™ programming language documentation tools from
* programs.
*/
public interface DocumentationTool extends Tool, OptionChecker {
/**
* Creates a future for a documentation task with the given
* components and arguments. The task might not have
* completed as described in the DocumentationTask interface.
*
* <p>If a file manager is provided, it must be able to handle all
* locations defined in {@link DocumentationTool.Location},
* as well as
* {@link StandardLocation#SOURCE_PATH},
* {@link StandardLocation#CLASS_PATH}, and
* {@link StandardLocation#PLATFORM_CLASS_PATH}.
*
* @param out a Writer for additional output from the tool;
* use {@code System.err} if {@code null}
*
* @param fileManager a file manager; if {@code null} use the
* tool's standard filemanager
*
* @param diagnosticListener a diagnostic listener; if {@code null}
* use the tool's default method for reporting diagnostics
*
* @param docletClass a class providing the necessary methods required
* of a doclet; a value of {@code null} means to use the standard doclet.
*
* @param options documentation tool options and doclet options,
* {@code null} means no options
*
* @param compilationUnits the compilation units to compile, {@code
* null} means no compilation units
*
* @return an object representing the compilation
*
* @throws RuntimeException if an unrecoverable error
* occurred in a user supplied component. The
* {@linkplain Throwable#getCause() cause} will be the error in
* user code.
*
* @throws IllegalArgumentException if any of the given
* compilation units are of other kind than
* {@linkplain JavaFileObject.Kind#SOURCE source}
*/
DocumentationTask getTask(Writer out,
JavaFileManager fileManager,
DiagnosticListener<? super JavaFileObject> diagnosticListener,
Class<?> docletClass,
Iterable<String> options,
Iterable<? extends JavaFileObject> compilationUnits);
/**
* Returns a new instance of the standard file manager implementation
* for this tool. The file manager will use the given diagnostic
* listener for producing any non-fatal diagnostics. Fatal errors
* will be signaled with the appropriate exceptions.
*
* <p>The standard file manager will be automatically reopened if
* it is accessed after calls to {@code flush} or {@code close}.
* The standard file manager must be usable with other tools.
*
* @param diagnosticListener a diagnostic listener for non-fatal
* diagnostics; if {@code null} use the compiler's default method
* for reporting diagnostics
*
* @param locale the locale to apply when formatting diagnostics;
* {@code null} means the {@linkplain Locale#getDefault() default locale}.
*
* @param charset the character set used for decoding bytes; if
* {@code null} use the platform default
*
* @return the standard file manager
*/
StandardJavaFileManager getStandardFileManager(
DiagnosticListener<? super JavaFileObject> diagnosticListener,
Locale locale,
Charset charset);
/**
* Interface representing a future for a documentation task. The
* task has not yet started. To start the task, call
* the {@linkplain #call call} method.
*
* <p>Before calling the call method, additional aspects of the
* task can be configured, for example, by calling the
* {@linkplain #setLocale setLocale} method.
*/
interface DocumentationTask extends Callable<Boolean> {
/**
* Set the locale to be applied when formatting diagnostics and
* other localized data.
*
* @param locale the locale to apply; {@code null} means apply no
* locale
* @throws IllegalStateException if the task has started
*/
void setLocale(Locale locale);
/**
* Performs this documentation task. The task may only
* be performed once. Subsequent calls to this method throw
* IllegalStateException.
*
* @return true if and only all the files were processed without errors;
* false otherwise
*
* @throws RuntimeException if an unrecoverable error occurred
* in a user-supplied component. The
* {@linkplain Throwable#getCause() cause} will be the error
* in user code.
*
* @throws IllegalStateException if called more than once
*/
Boolean call();
}
/**
* Locations specific to {@link DocumentationTool}.
*
* @see StandardLocation
*/
enum Location implements JavaFileManager.Location {
/**
* Location of new documentation files.
*/
DOCUMENTATION_OUTPUT,
/**
* Location to search for doclets.
*/
DOCLET_PATH,
/**
* Location to search for taglets.
*/
TAGLET_PATH;
public String getName() { return name(); }
public boolean isOutputLocation() {
switch (this) {
case DOCUMENTATION_OUTPUT:
return true;
default:
return false;
}
}
}
}