Thu, 15 Nov 2012 09:18:36 -0800
8000800: javadoc uses static non-final fields
Reviewed-by: bpatel
1 /*
2 * Copyright (c) 1997, 2012, 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 */
26 package com.sun.tools.javadoc;
28 import java.io.IOException;
29 import java.util.Locale;
30 import javax.tools.JavaFileObject;
31 import javax.tools.StandardJavaFileManager;
33 import com.sun.javadoc.*;
35 import com.sun.tools.javac.tree.JCTree.JCClassDecl;
36 import com.sun.tools.javac.util.List;
37 import com.sun.tools.javac.util.ListBuffer;
38 import com.sun.tools.javac.util.Position;
40 /**
41 * This class holds the information from one run of javadoc.
42 * Particularly the packages, classes and options specified
43 * by the user.
44 *
45 * <p><b>This is NOT part of any supported API.
46 * If you write code that depends on this, you do so at your own risk.
47 * This code and its internal interfaces are subject to change or
48 * deletion without notice.</b>
49 *
50 * @since 1.2
51 * @author Robert Field
52 * @author Atul M Dambalkar
53 * @author Neal Gafter (rewrite)
54 */
55 public class RootDocImpl extends DocImpl implements RootDoc {
57 /**
58 * list of classes specified on the command line.
59 */
60 private List<ClassDocImpl> cmdLineClasses;
62 /**
63 * list of packages specified on the command line.
64 */
65 private List<PackageDocImpl> cmdLinePackages;
67 /**
68 * a collection of all options.
69 */
70 private List<String[]> options;
72 /**
73 * Constructor used when reading source files.
74 *
75 * @param env the documentation environment, state for this javadoc run
76 * @param classes list of classes specified on the commandline
77 * @param packages list of package names specified on the commandline
78 * @param options list of options
79 */
80 public RootDocImpl(DocEnv env, List<JCClassDecl> classes, List<String> packages, List<String[]> options) {
81 super(env, null);
82 this.options = options;
83 setPackages(env, packages);
84 setClasses(env, classes);
85 }
87 /**
88 * Constructor used when reading class files.
89 *
90 * @param env the documentation environment, state for this javadoc run
91 * @param classes list of class names specified on the commandline
92 * @param options list of options
93 */
94 public RootDocImpl(DocEnv env, List<String> classes, List<String[]> options) {
95 super(env, null);
96 this.options = options;
97 cmdLinePackages = List.nil();
98 ListBuffer<ClassDocImpl> classList = new ListBuffer<ClassDocImpl>();
99 for (String className : classes) {
100 ClassDocImpl c = env.loadClass(className);
101 if (c == null)
102 env.error(null, "javadoc.class_not_found", className);
103 else
104 classList = classList.append(c);
105 }
106 cmdLineClasses = classList.toList();
107 }
109 /**
110 * Initialize classes information. Those classes are input from
111 * command line.
112 *
113 * @param env the compilation environment
114 * @param classes a list of ClassDeclaration
115 */
116 private void setClasses(DocEnv env, List<JCClassDecl> classes) {
117 ListBuffer<ClassDocImpl> result = new ListBuffer<ClassDocImpl>();
118 for (JCClassDecl def : classes) {
119 //### Do we want modifier check here?
120 if (env.shouldDocument(def.sym)) {
121 ClassDocImpl cd = env.getClassDoc(def.sym);
122 if (cd != null) {
123 cd.isIncluded = true;
124 result.append(cd);
125 } //else System.out.println(" (classdoc is null)");//DEBUG
126 } //else System.out.println(" (env.shouldDocument() returned false)");//DEBUG
127 }
128 cmdLineClasses = result.toList();
129 }
131 /**
132 * Initialize packages information.
133 *
134 * @param env the compilation environment
135 * @param packages a list of package names (String)
136 */
137 private void setPackages(DocEnv env, List<String> packages) {
138 ListBuffer<PackageDocImpl> packlist = new ListBuffer<PackageDocImpl>();
139 for (String name : packages) {
140 PackageDocImpl pkg = env.lookupPackage(name);
141 if (pkg != null) {
142 pkg.isIncluded = true;
143 packlist.append(pkg);
144 } else {
145 env.warning(null, "main.no_source_files_for_package", name);
146 }
147 }
148 cmdLinePackages = packlist.toList();
149 }
151 /**
152 * Command line options.
153 *
154 * <pre>
155 * For example, given:
156 * javadoc -foo this that -bar other ...
157 *
158 * This method will return:
159 * options()[0][0] = "-foo"
160 * options()[0][1] = "this"
161 * options()[0][2] = "that"
162 * options()[1][0] = "-bar"
163 * options()[1][1] = "other"
164 * </pre>
165 *
166 * @return an array of arrays of String.
167 */
168 public String[][] options() {
169 return options.toArray(new String[options.length()][]);
170 }
172 /**
173 * Packages specified on the command line.
174 */
175 public PackageDoc[] specifiedPackages() {
176 return (PackageDoc[])cmdLinePackages
177 .toArray(new PackageDocImpl[cmdLinePackages.length()]);
178 }
180 /**
181 * Classes and interfaces specified on the command line.
182 */
183 public ClassDoc[] specifiedClasses() {
184 ListBuffer<ClassDocImpl> classesToDocument = new ListBuffer<ClassDocImpl>();
185 for (ClassDocImpl cd : cmdLineClasses) {
186 cd.addAllClasses(classesToDocument, true);
187 }
188 return (ClassDoc[])classesToDocument.toArray(new ClassDocImpl[classesToDocument.length()]);
189 }
191 /**
192 * Return all classes and interfaces (including those inside
193 * packages) to be documented.
194 */
195 public ClassDoc[] classes() {
196 ListBuffer<ClassDocImpl> classesToDocument = new ListBuffer<ClassDocImpl>();
197 for (ClassDocImpl cd : cmdLineClasses) {
198 cd.addAllClasses(classesToDocument, true);
199 }
200 for (PackageDocImpl pd : cmdLinePackages) {
201 pd.addAllClassesTo(classesToDocument);
202 }
203 return classesToDocument.toArray(new ClassDocImpl[classesToDocument.length()]);
204 }
206 /**
207 * Return a ClassDoc for the specified class/interface name
208 *
209 * @param qualifiedName qualified class name
210 * (i.e. includes package name).
211 *
212 * @return a ClassDocImpl holding the specified class, null if
213 * this class is not referenced.
214 */
215 public ClassDoc classNamed(String qualifiedName) {
216 return env.lookupClass(qualifiedName);
217 }
219 /**
220 * Return a PackageDoc for the specified package name
221 *
222 * @param name package name
223 *
224 * @return a PackageDoc holding the specified package, null if
225 * this package is not referenced.
226 */
227 public PackageDoc packageNamed(String name) {
228 return env.lookupPackage(name);
229 }
231 /**
232 * Return the name of this Doc item.
233 *
234 * @return the string <code>"*RootDocImpl*"</code>.
235 */
236 public String name() {
237 return "*RootDocImpl*";
238 }
240 /**
241 * Return the name of this Doc item.
242 *
243 * @return the string <code>"*RootDocImpl*"</code>.
244 */
245 public String qualifiedName() {
246 return "*RootDocImpl*";
247 }
249 /**
250 * Return true if this Doc is include in the active set.
251 * RootDocImpl isn't even a program entity so it is always false.
252 */
253 public boolean isIncluded() {
254 return false;
255 }
257 /**
258 * Print error message, increment error count.
259 *
260 * @param msg message to print
261 */
262 public void printError(String msg) {
263 env.printError(msg);
264 }
266 /**
267 * Print error message, increment error count.
268 *
269 * @param msg message to print
270 */
271 public void printError(SourcePosition pos, String msg) {
272 env.printError(pos, msg);
273 }
275 /**
276 * Print warning message, increment warning count.
277 *
278 * @param msg message to print
279 */
280 public void printWarning(String msg) {
281 env.printWarning(msg);
282 }
284 /**
285 * Print warning message, increment warning count.
286 *
287 * @param msg message to print
288 */
289 public void printWarning(SourcePosition pos, String msg) {
290 env.printWarning(pos, msg);
291 }
293 /**
294 * Print a message.
295 *
296 * @param msg message to print
297 */
298 public void printNotice(String msg) {
299 env.printNotice(msg);
300 }
302 /**
303 * Print a message.
304 *
305 * @param msg message to print
306 */
307 public void printNotice(SourcePosition pos, String msg) {
308 env.printNotice(pos, msg);
309 }
311 /**
312 * Return the path of the overview file and null if it does not exist.
313 * @return the path of the overview file and null if it does not exist.
314 */
315 private JavaFileObject getOverviewPath() {
316 for (String[] opt : options) {
317 if (opt[0].equals("-overview")) {
318 if (env.fileManager instanceof StandardJavaFileManager) {
319 StandardJavaFileManager fm = (StandardJavaFileManager) env.fileManager;
320 return fm.getJavaFileObjects(opt[1]).iterator().next();
321 }
322 }
323 }
324 return null;
325 }
327 /**
328 * Do lazy initialization of "documentation" string.
329 */
330 @Override
331 protected String documentation() {
332 if (documentation == null) {
333 int cnt = options.length();
334 JavaFileObject overviewPath = getOverviewPath();
335 if (overviewPath == null) {
336 // no doc file to be had
337 documentation = "";
338 } else {
339 // read from file
340 try {
341 documentation = readHTMLDocumentation(
342 overviewPath.openInputStream(),
343 overviewPath);
344 } catch (IOException exc) {
345 documentation = "";
346 env.error(null, "javadoc.File_Read_Error", overviewPath.getName());
347 }
348 }
349 }
350 return documentation;
351 }
353 /**
354 * Return the source position of the entity, or null if
355 * no position is available.
356 */
357 @Override
358 public SourcePosition position() {
359 JavaFileObject path;
360 return ((path = getOverviewPath()) == null) ?
361 null :
362 SourcePositionImpl.make(path, Position.NOPOS, null);
363 }
365 /**
366 * Return the locale provided by the user or the default locale value.
367 */
368 public Locale getLocale() {
369 return env.doclocale.locale;
370 }
371 }