• file
• revisions
• annotate
• diff
• comparison
• raw

src/share/classes/javax/tools/DocumentationTool.java@93012e2a5d1d (annotated)

src/share/classes/javax/tools/DocumentationTool.java

Sat, 07 Nov 2020 10:30:02 +0800

author

aoqi

date

Sat, 07 Nov 2020 10:30:02 +0800

changeset 3938

93012e2a5d1d

parent 0

959103a6100f

permissions

-rw-r--r--

Added tag mips-jdk8u275-b01 for changeset eb6ee6a5f2fe

aoqi@0	1	/*
aoqi@0	2	* Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved.
aoqi@0	3	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
aoqi@0	4	*
aoqi@0	5	* This code is free software; you can redistribute it and/or modify it
aoqi@0	6	* under the terms of the GNU General Public License version 2 only, as
aoqi@0	7	* published by the Free Software Foundation. Oracle designates this
aoqi@0	8	* particular file as subject to the "Classpath" exception as provided
aoqi@0	9	* by Oracle in the LICENSE file that accompanied this code.
aoqi@0	10	*
aoqi@0	11	* This code is distributed in the hope that it will be useful, but WITHOUT
aoqi@0	12	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
aoqi@0	13	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
aoqi@0	14	* version 2 for more details (a copy is included in the LICENSE file that
aoqi@0	15	* accompanied this code).
aoqi@0	16	*
aoqi@0	17	* You should have received a copy of the GNU General Public License version
aoqi@0	18	* 2 along with this work; if not, write to the Free Software Foundation,
aoqi@0	19	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
aoqi@0	20	*
aoqi@0	21	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
aoqi@0	22	* or visit www.oracle.com if you need additional information or have any
aoqi@0	23	* questions.
aoqi@0	24	*/
aoqi@0	25	package javax.tools;
aoqi@0	26
aoqi@0	27	import java.io.Writer;
aoqi@0	28	import java.nio.charset.Charset;
aoqi@0	29	import java.util.Locale;
aoqi@0	30	import java.util.concurrent.Callable;
aoqi@0	31
aoqi@0	32	/**
aoqi@0	33	* Interface to invoke Java™ programming language documentation tools from
aoqi@0	34	* programs.
aoqi@0	35	*/
aoqi@0	36	public interface DocumentationTool extends Tool, OptionChecker {
aoqi@0	37	/**
aoqi@0	38	* Creates a future for a documentation task with the given
aoqi@0	39	* components and arguments. The task might not have
aoqi@0	40	* completed as described in the DocumentationTask interface.
aoqi@0	41	*
aoqi@0	42	* <p>If a file manager is provided, it must be able to handle all
aoqi@0	43	* locations defined in {@link DocumentationTool.Location},
aoqi@0	44	* as well as
aoqi@0	45	* {@link StandardLocation#SOURCE_PATH},
aoqi@0	46	* {@link StandardLocation#CLASS_PATH}, and
aoqi@0	47	* {@link StandardLocation#PLATFORM_CLASS_PATH}.
aoqi@0	48	*
aoqi@0	49	* @param out a Writer for additional output from the tool;
aoqi@0	50	* use {@code System.err} if {@code null}
aoqi@0	51	*
aoqi@0	52	* @param fileManager a file manager; if {@code null} use the
aoqi@0	53	* tool's standard filemanager
aoqi@0	54	*
aoqi@0	55	* @param diagnosticListener a diagnostic listener; if {@code null}
aoqi@0	56	* use the tool's default method for reporting diagnostics
aoqi@0	57	*
aoqi@0	58	* @param docletClass a class providing the necessary methods required
aoqi@0	59	* of a doclet
aoqi@0	60	*
aoqi@0	61	* @param options documentation tool options and doclet options,
aoqi@0	62	* {@code null} means no options
aoqi@0	63	*
aoqi@0	64	* @param compilationUnits the compilation units to compile, {@code
aoqi@0	65	* null} means no compilation units
aoqi@0	66	*
aoqi@0	67	* @return an object representing the compilation
aoqi@0	68	*
aoqi@0	69	* @throws RuntimeException if an unrecoverable error
aoqi@0	70	* occurred in a user supplied component. The
aoqi@0	71	* {@linkplain Throwable#getCause() cause} will be the error in
aoqi@0	72	* user code.
aoqi@0	73	*
aoqi@0	74	* @throws IllegalArgumentException if any of the given
aoqi@0	75	* compilation units are of other kind than
aoqi@0	76	* {@linkplain JavaFileObject.Kind#SOURCE source}
aoqi@0	77	*/
aoqi@0	78	DocumentationTask getTask(Writer out,
aoqi@0	79	JavaFileManager fileManager,
aoqi@0	80	DiagnosticListener<? super JavaFileObject> diagnosticListener,
aoqi@0	81	Class<?> docletClass,
aoqi@0	82	Iterable<String> options,
aoqi@0	83	Iterable<? extends JavaFileObject> compilationUnits);
aoqi@0	84
aoqi@0	85	/**
aoqi@0	86	* Gets a new instance of the standard file manager implementation
aoqi@0	87	* for this tool. The file manager will use the given diagnostic
aoqi@0	88	* listener for producing any non-fatal diagnostics. Fatal errors
aoqi@0	89	* will be signaled with the appropriate exceptions.
aoqi@0	90	*
aoqi@0	91	* <p>The standard file manager will be automatically reopened if
aoqi@0	92	* it is accessed after calls to {@code flush} or {@code close}.
aoqi@0	93	* The standard file manager must be usable with other tools.
aoqi@0	94	*
aoqi@0	95	* @param diagnosticListener a diagnostic listener for non-fatal
aoqi@0	96	* diagnostics; if {@code null} use the compiler's default method
aoqi@0	97	* for reporting diagnostics
aoqi@0	98	*
aoqi@0	99	* @param locale the locale to apply when formatting diagnostics;
aoqi@0	100	* {@code null} means the {@linkplain Locale#getDefault() default locale}.
aoqi@0	101	*
aoqi@0	102	* @param charset the character set used for decoding bytes; if
aoqi@0	103	* {@code null} use the platform default
aoqi@0	104	*
aoqi@0	105	* @return the standard file manager
aoqi@0	106	*/
aoqi@0	107	StandardJavaFileManager getStandardFileManager(
aoqi@0	108	DiagnosticListener<? super JavaFileObject> diagnosticListener,
aoqi@0	109	Locale locale,
aoqi@0	110	Charset charset);
aoqi@0	111
aoqi@0	112	/**
aoqi@0	113	* Interface representing a future for a documentation task. The
aoqi@0	114	* task has not yet started. To start the task, call
aoqi@0	115	* the {@linkplain #call call} method.
aoqi@0	116	*
aoqi@0	117	* <p>Before calling the call method, additional aspects of the
aoqi@0	118	* task can be configured, for example, by calling the
aoqi@0	119	* {@linkplain #setLocale setLocale} method.
aoqi@0	120	*/
aoqi@0	121	interface DocumentationTask extends Callable<Boolean> {
aoqi@0	122	/**
aoqi@0	123	* Set the locale to be applied when formatting diagnostics and
aoqi@0	124	* other localized data.
aoqi@0	125	*
aoqi@0	126	* @param locale the locale to apply; {@code null} means apply no
aoqi@0	127	* locale
aoqi@0	128	* @throws IllegalStateException if the task has started
aoqi@0	129	*/
aoqi@0	130	void setLocale(Locale locale);
aoqi@0	131
aoqi@0	132	/**
aoqi@0	133	* Performs this documentation task. The task may only
aoqi@0	134	* be performed once. Subsequent calls to this method throw
aoqi@0	135	* IllegalStateException.
aoqi@0	136	*
aoqi@0	137	* @return true if and only all the files were processed without errors;
aoqi@0	138	* false otherwise
aoqi@0	139	*
aoqi@0	140	* @throws RuntimeException if an unrecoverable error occurred
aoqi@0	141	* in a user-supplied component. The
aoqi@0	142	* {@linkplain Throwable#getCause() cause} will be the error
aoqi@0	143	* in user code.
aoqi@0	144	*
aoqi@0	145	* @throws IllegalStateException if called more than once
aoqi@0	146	*/
aoqi@0	147	Boolean call();
aoqi@0	148	}
aoqi@0	149
aoqi@0	150	/**
aoqi@0	151	* Locations specific to {@link DocumentationTool}.
aoqi@0	152	*
aoqi@0	153	* @see StandardLocation
aoqi@0	154	*/
aoqi@0	155	enum Location implements JavaFileManager.Location {
aoqi@0	156	/**
aoqi@0	157	* Location of new documentation files.
aoqi@0	158	*/
aoqi@0	159	DOCUMENTATION_OUTPUT,
aoqi@0	160
aoqi@0	161	/**
aoqi@0	162	* Location to search for doclets.
aoqi@0	163	*/
aoqi@0	164	DOCLET_PATH,
aoqi@0	165
aoqi@0	166	/**
aoqi@0	167	* Location to search for taglets.
aoqi@0	168	*/
aoqi@0	169	TAGLET_PATH;
aoqi@0	170
aoqi@0	171	public String getName() { return name(); }
aoqi@0	172
aoqi@0	173	public boolean isOutputLocation() {
aoqi@0	174	switch (this) {
aoqi@0	175	case DOCUMENTATION_OUTPUT:
aoqi@0	176	return true;
aoqi@0	177	default:
aoqi@0	178	return false;
aoqi@0	179	}
aoqi@0	180	}
aoqi@0	181	}
aoqi@0	182
aoqi@0	183	}