Tue, 11 Dec 2012 15:05:55 -0800
8004828: refactor init of *DocImpl classes
Reviewed-by: darcy
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.JavaFileManager;
31 import javax.tools.JavaFileObject;
32 import javax.tools.StandardJavaFileManager;
34 import com.sun.javadoc.*;
36 import com.sun.tools.javac.tree.JCTree.JCClassDecl;
37 import com.sun.tools.javac.util.List;
38 import com.sun.tools.javac.util.ListBuffer;
39 import com.sun.tools.javac.util.Position;
41 /**
42 * This class holds the information from one run of javadoc.
43 * Particularly the packages, classes and options specified
44 * by the user.
45 *
46 * <p><b>This is NOT part of any supported API.
47 * If you write code that depends on this, you do so at your own risk.
48 * This code and its internal interfaces are subject to change or
49 * deletion without notice.</b>
50 *
51 * @since 1.2
52 * @author Robert Field
53 * @author Atul M Dambalkar
54 * @author Neal Gafter (rewrite)
55 */
56 public class RootDocImpl extends DocImpl implements RootDoc {
58 /**
59 * list of classes specified on the command line.
60 */
61 private List<ClassDocImpl> cmdLineClasses;
63 /**
64 * list of packages specified on the command line.
65 */
66 private List<PackageDocImpl> cmdLinePackages;
68 /**
69 * a collection of all options.
70 */
71 private List<String[]> options;
73 /**
74 * Constructor used when reading source files.
75 *
76 * @param env the documentation environment, state for this javadoc run
77 * @param classes list of classes specified on the commandline
78 * @param packages list of package names specified on the commandline
79 * @param options list of options
80 */
81 public RootDocImpl(DocEnv env, List<JCClassDecl> classes, List<String> packages, List<String[]> options) {
82 super(env, null);
83 this.options = options;
84 setPackages(env, packages);
85 setClasses(env, classes);
86 }
88 /**
89 * Constructor used when reading class files.
90 *
91 * @param env the documentation environment, state for this javadoc run
92 * @param classes list of class names specified on the commandline
93 * @param options list of options
94 */
95 public RootDocImpl(DocEnv env, List<String> classes, List<String[]> options) {
96 super(env, null);
97 this.options = options;
98 cmdLinePackages = List.nil();
99 ListBuffer<ClassDocImpl> classList = new ListBuffer<ClassDocImpl>();
100 for (String className : classes) {
101 ClassDocImpl c = env.loadClass(className);
102 if (c == null)
103 env.error(null, "javadoc.class_not_found", className);
104 else
105 classList = classList.append(c);
106 }
107 cmdLineClasses = classList.toList();
108 }
110 /**
111 * Initialize classes information. Those classes are input from
112 * command line.
113 *
114 * @param env the compilation environment
115 * @param classes a list of ClassDeclaration
116 */
117 private void setClasses(DocEnv env, List<JCClassDecl> classes) {
118 ListBuffer<ClassDocImpl> result = new ListBuffer<ClassDocImpl>();
119 for (JCClassDecl def : classes) {
120 //### Do we want modifier check here?
121 if (env.shouldDocument(def.sym)) {
122 ClassDocImpl cd = env.getClassDoc(def.sym);
123 if (cd != null) {
124 cd.isIncluded = true;
125 result.append(cd);
126 } //else System.out.println(" (classdoc is null)");//DEBUG
127 } //else System.out.println(" (env.shouldDocument() returned false)");//DEBUG
128 }
129 cmdLineClasses = result.toList();
130 }
132 /**
133 * Initialize packages information.
134 *
135 * @param env the compilation environment
136 * @param packages a list of package names (String)
137 */
138 private void setPackages(DocEnv env, List<String> packages) {
139 ListBuffer<PackageDocImpl> packlist = new ListBuffer<PackageDocImpl>();
140 for (String name : packages) {
141 PackageDocImpl pkg = env.lookupPackage(name);
142 if (pkg != null) {
143 pkg.isIncluded = true;
144 packlist.append(pkg);
145 } else {
146 env.warning(null, "main.no_source_files_for_package", name);
147 }
148 }
149 cmdLinePackages = packlist.toList();
150 }
152 /**
153 * Command line options.
154 *
155 * <pre>
156 * For example, given:
157 * javadoc -foo this that -bar other ...
158 *
159 * This method will return:
160 * options()[0][0] = "-foo"
161 * options()[0][1] = "this"
162 * options()[0][2] = "that"
163 * options()[1][0] = "-bar"
164 * options()[1][1] = "other"
165 * </pre>
166 *
167 * @return an array of arrays of String.
168 */
169 public String[][] options() {
170 return options.toArray(new String[options.length()][]);
171 }
173 /**
174 * Packages specified on the command line.
175 */
176 public PackageDoc[] specifiedPackages() {
177 return (PackageDoc[])cmdLinePackages
178 .toArray(new PackageDocImpl[cmdLinePackages.length()]);
179 }
181 /**
182 * Classes and interfaces specified on the command line.
183 */
184 public ClassDoc[] specifiedClasses() {
185 ListBuffer<ClassDocImpl> classesToDocument = new ListBuffer<ClassDocImpl>();
186 for (ClassDocImpl cd : cmdLineClasses) {
187 cd.addAllClasses(classesToDocument, true);
188 }
189 return (ClassDoc[])classesToDocument.toArray(new ClassDocImpl[classesToDocument.length()]);
190 }
192 /**
193 * Return all classes and interfaces (including those inside
194 * packages) to be documented.
195 */
196 public ClassDoc[] classes() {
197 ListBuffer<ClassDocImpl> classesToDocument = new ListBuffer<ClassDocImpl>();
198 for (ClassDocImpl cd : cmdLineClasses) {
199 cd.addAllClasses(classesToDocument, true);
200 }
201 for (PackageDocImpl pd : cmdLinePackages) {
202 pd.addAllClassesTo(classesToDocument);
203 }
204 return classesToDocument.toArray(new ClassDocImpl[classesToDocument.length()]);
205 }
207 /**
208 * Return a ClassDoc for the specified class/interface name
209 *
210 * @param qualifiedName qualified class name
211 * (i.e. includes package name).
212 *
213 * @return a ClassDocImpl holding the specified class, null if
214 * this class is not referenced.
215 */
216 public ClassDoc classNamed(String qualifiedName) {
217 return env.lookupClass(qualifiedName);
218 }
220 /**
221 * Return a PackageDoc for the specified package name
222 *
223 * @param name package name
224 *
225 * @return a PackageDoc holding the specified package, null if
226 * this package is not referenced.
227 */
228 public PackageDoc packageNamed(String name) {
229 return env.lookupPackage(name);
230 }
232 /**
233 * Return the name of this Doc item.
234 *
235 * @return the string <code>"*RootDocImpl*"</code>.
236 */
237 public String name() {
238 return "*RootDocImpl*";
239 }
241 /**
242 * Return the name of this Doc item.
243 *
244 * @return the string <code>"*RootDocImpl*"</code>.
245 */
246 public String qualifiedName() {
247 return "*RootDocImpl*";
248 }
250 /**
251 * Return true if this Doc is include in the active set.
252 * RootDocImpl isn't even a program entity so it is always false.
253 */
254 public boolean isIncluded() {
255 return false;
256 }
258 /**
259 * Print error message, increment error count.
260 *
261 * @param msg message to print
262 */
263 public void printError(String msg) {
264 env.printError(msg);
265 }
267 /**
268 * Print error message, increment error count.
269 *
270 * @param msg message to print
271 */
272 public void printError(SourcePosition pos, String msg) {
273 env.printError(pos, msg);
274 }
276 /**
277 * Print warning message, increment warning count.
278 *
279 * @param msg message to print
280 */
281 public void printWarning(String msg) {
282 env.printWarning(msg);
283 }
285 /**
286 * Print warning message, increment warning count.
287 *
288 * @param msg message to print
289 */
290 public void printWarning(SourcePosition pos, String msg) {
291 env.printWarning(pos, msg);
292 }
294 /**
295 * Print a message.
296 *
297 * @param msg message to print
298 */
299 public void printNotice(String msg) {
300 env.printNotice(msg);
301 }
303 /**
304 * Print a message.
305 *
306 * @param msg message to print
307 */
308 public void printNotice(SourcePosition pos, String msg) {
309 env.printNotice(pos, msg);
310 }
312 /**
313 * Return the path of the overview file and null if it does not exist.
314 * @return the path of the overview file and null if it does not exist.
315 */
316 private JavaFileObject getOverviewPath() {
317 for (String[] opt : options) {
318 if (opt[0].equals("-overview")) {
319 if (env.fileManager instanceof StandardJavaFileManager) {
320 StandardJavaFileManager fm = (StandardJavaFileManager) env.fileManager;
321 return fm.getJavaFileObjects(opt[1]).iterator().next();
322 }
323 }
324 }
325 return null;
326 }
328 /**
329 * Do lazy initialization of "documentation" string.
330 */
331 @Override
332 protected String documentation() {
333 if (documentation == null) {
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 }
372 /**
373 * Return the current file manager.
374 */
375 public JavaFileManager getFileManager() {
376 return env.fileManager;
377 }
378 }