DocletEnvironment.java revision 3595:81692f730015 
1/*
2 * Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package jdk.javadoc.doclet;
27
28import java.util.List;
29import java.util.Set;
30
31import javax.lang.model.SourceVersion;
32import javax.lang.model.element.Element;
33import javax.lang.model.element.ModuleElement;
34import javax.lang.model.element.PackageElement;
35import javax.lang.model.element.TypeElement;
36import javax.lang.model.util.Elements;
37import javax.lang.model.util.Types;
38import javax.tools.JavaFileManager;
39
40import com.sun.source.util.DocTrees;
41
42/**
43 * Represents the operating environment of a single invocation
44 * of the doclet. This object can be used to access the program
45 * structures, various utilities and the user specified elements
46 * on the command line.
47 *
48 * @since 9
49 */
50public interface DocletEnvironment {
51    /**
52     * Returns the <a href="package-summary.html#included">included</a>
53     * modules.
54     *
55     * @return a set of included module elements
56     */
57    Set<ModuleElement> getIncludedModuleElements();
58
59    /**
60     * Returns the <a href="package-summary.html#included">included</a>
61     * annotation types, classes, interfaces and enums in all packages.
62     *
63     * @return a set of included type elements
64     */
65    Set<TypeElement> getIncludedTypeElements();
66
67    /**
68     * Returns the <a href="package-summary.html#included">included</a>
69     * packages.
70     *
71     * @return a set of included package elements
72     */
73    Set<PackageElement> getIncludedPackageElements();
74
75    /**
76     * Returns an instance of the {@code DocTrees} utility class.
77     * This class provides methods to access {@code TreePath}s, {@code DocCommentTree}s
78     * and so on.
79     *
80     * @return a utility class to operate on doc trees
81     */
82    DocTrees getDocTrees();
83
84    /**
85     * Returns an instance of the {@code Elements} utility class.
86     * This class provides methods for operating on
87     * {@link javax.lang.model.element.Element elements}.
88     *
89     * @return a utility class to operate on elements
90     */
91    Elements getElementUtils();
92
93    /**
94     * Returns the <a href="package-summary.html#included">selected</a>
95     * elements that can be documented.
96     *
97     * @param elements those that need to be checked
98     * @return elements selected, an empty list if none
99     */
100    List<Element> getSelectedElements(List<? extends Element> elements);
101
102    /**
103     * Returns the elements <a href="package-summary.html#specified">specified</a>
104     * on the command line, usually module elements, package elements and type elements.
105     * If {@code -subpackages} and {@code -exclude} options
106     * are used, return all the non-excluded packages.
107     *
108     * @return elements specified on the command line.
109     */
110    Set<Element> getSpecifiedElements();
111
112    /**
113     * Returns an instance of the {@code Types} utility class.
114     * This class provides methods for operating on
115     * {@link javax.lang.model.type.TypeMirror type mirrors}.
116     *
117     * @return a utility class to operate on type mirrors
118     */
119    Types getTypeUtils();
120
121    /**
122     * Indicates if an element is <a href="package-summary.html#included">included</a>.
123     *
124     * @param e the Element in question
125     * @return true if included, false otherwise
126     */
127    boolean isIncluded(Element e);
128
129    /**
130     * Returns the file manager used to read and write files.
131     *
132     * @return the file manager used to read and write files
133     */
134    JavaFileManager getJavaFileManager();
135
136    /**
137     * Returns the source version of the source files that were read.
138     *
139     * @return the source version
140     */
141    SourceVersion getSourceVersion();
142
143    /**
144     * Returns the required level of module documentation.
145     *
146     * @return the required level of module documentation
147     */
148    public ModuleMode getModuleMode();
149
150    enum ModuleMode {
151        /** Indicate API level documentation is required */
152        API,
153        /** Indicate Detailed documentation is required */
154        ALL
155    }
156}
157