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.Set;
29
30import javax.lang.model.SourceVersion;
31import javax.lang.model.element.Element;
32import javax.lang.model.element.TypeElement;
33import javax.lang.model.util.Elements;
34import javax.lang.model.util.Types;
35import javax.tools.JavaFileManager;
36import javax.tools.JavaFileObject.Kind;
37
38import com.sun.source.util.DocTrees;
39
40/**
41 * Represents the operating environment of a single invocation
42 * of the doclet. This object can be used to access the program
43 * structures, various utilities and the user specified elements
44 * on the command line.
45 *
46 * @since 9
47 */
48public interface DocletEnvironment {
49
50    /**
51     * Returns the elements <a href="package-summary.html#specified">specified</a>
52     * when the tool is invoked.
53     *
54     * @return the set of specified elements
55     */
56    Set<? extends Element> getSpecifiedElements();
57
58    /**
59     * Returns the module, package and type elements that should be
60     * <a href="package-summary.html#included">included</a> in the
61     * documentation.
62     *
63     * @return the set of included elements
64     */
65    Set<? extends Element> getIncludedElements();
66
67    /**
68     * Returns an instance of the {@code DocTrees} utility class.
69     * This class provides methods to access {@code TreePath}s, {@code DocCommentTree}s
70     * and so on.
71     *
72     * @return a utility class to operate on doc trees
73     */
74    DocTrees getDocTrees();
75
76    /**
77     * Returns an instance of the {@code Elements} utility class.
78     * This class provides methods for operating on
79     * {@link javax.lang.model.element.Element elements}.
80     *
81     * @return a utility class to operate on elements
82     */
83    Elements getElementUtils();
84
85    /**
86     * Returns an instance of the {@code Types} utility class.
87     * This class provides methods for operating on
88     * {@link javax.lang.model.type.TypeMirror type mirrors}.
89     *
90     * @return a utility class to operate on type mirrors
91     */
92    Types getTypeUtils();
93
94    /**
95     * Returns true if an element should be
96     * <a href="package-summary.html#included">included</a> in the
97     * documentation.
98     *
99     * @param e the element
100     * @return true if included, false otherwise
101     */
102    boolean isIncluded(Element e);
103
104    /**
105     * Returns true if the element is <a href="package-summary.html#selected">selected</a>.
106     *
107     * @param e the element
108     * @return true if selected, false otherwise
109     */
110    boolean isSelected(Element e);
111
112    /**
113     * Returns the file manager used to read and write files.
114     *
115     * @return the file manager used to read and write files
116     */
117    JavaFileManager getJavaFileManager();
118
119    /**
120     * Returns the source version of the source files that were read.
121     *
122     * @return the source version
123     */
124    SourceVersion getSourceVersion();
125
126    /**
127     * Returns the required level of module documentation.
128     *
129     * @return the required level of module documentation
130     */
131    ModuleMode getModuleMode();
132
133    /**
134     * Returns the file kind of a type element.
135     *
136     * @param type the type element
137     * @return the file kind
138     */
139    Kind getFileKind(TypeElement type);
140
141    enum ModuleMode {
142        /** Indicate API level documentation is required */
143        API,
144        /** Indicate Detailed documentation is required */
145        ALL
146    }
147}
148