Tue, 15 Jul 2008 19:22:51 -0700
6657907: javadoc has unchecked warnings
Reviewed-by: bpatel
1 /*
2 * Copyright 1998-2005 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
26 package com.sun.tools.doclets.formats.html;
28 import com.sun.tools.doclets.internal.toolkit.*;
29 import com.sun.tools.doclets.internal.toolkit.util.*;
31 import com.sun.javadoc.*;
32 import java.util.*;
33 import java.io.*;
35 /**
36 * Configure the output based on the command line options.
37 * <p>
38 * Also determine the length of the command line option. For example,
39 * for a option "-header" there will be a string argument associated, then the
40 * the length of option "-header" is two. But for option "-nohelp" no argument
41 * is needed so it's length is 1.
42 * </p>
43 * <p>
44 * Also do the error checking on the options used. For example it is illegal to
45 * use "-helpfile" option when already "-nohelp" option is used.
46 * </p>
47 *
48 * @author Robert Field.
49 * @author Atul Dambalkar.
50 * @author Jamie Ho
51 */
52 public class ConfigurationImpl extends Configuration {
54 private static final ConfigurationImpl instance = new ConfigurationImpl();
56 /**
57 * The build date. Note: For now, we will use
58 * a version number instead of a date.
59 */
60 public static final String BUILD_DATE = System.getProperty("java.version");
62 /**
63 * The name of the constant values file.
64 */
65 public static final String CONSTANTS_FILE_NAME = "constant-values.html";
67 /**
68 * Argument for command line option "-header".
69 */
70 public String header = "";
72 /**
73 * Argument for command line option "-packagesheader".
74 */
75 public String packagesheader = "";
77 /**
78 * Argument for command line option "-footer".
79 */
80 public String footer = "";
82 /**
83 * Argument for command line option "-doctitle".
84 */
85 public String doctitle = "";
87 /**
88 * Argument for command line option "-windowtitle".
89 */
90 public String windowtitle = "";
92 /**
93 * Argument for command line option "-top".
94 */
95 public String top = "";
97 /**
98 * Argument for command line option "-bottom".
99 */
100 public String bottom = "";
102 /**
103 * Argument for command line option "-helpfile".
104 */
105 public String helpfile = "";
107 /**
108 * Argument for command line option "-stylesheetfile".
109 */
110 public String stylesheetfile = "";
112 /**
113 * True if command line option "-nohelp" is used. Default value is false.
114 */
115 public boolean nohelp = false;
117 /**
118 * True if command line option "-splitindex" is used. Default value is
119 * false.
120 */
121 public boolean splitindex = false;
123 /**
124 * False if command line option "-noindex" is used. Default value is true.
125 */
126 public boolean createindex = true;
128 /**
129 * True if command line option "-use" is used. Default value is false.
130 */
131 public boolean classuse = false;
133 /**
134 * False if command line option "-notree" is used. Default value is true.
135 */
136 public boolean createtree = true;
138 /**
139 * True if command line option "-nodeprecated" is used. Default value is
140 * false.
141 */
142 public boolean nodeprecatedlist = false;
144 /**
145 * True if command line option "-nonavbar" is used. Default value is false.
146 */
147 public boolean nonavbar = false;
149 /**
150 * True if command line option "-nooverview" is used. Default value is
151 * false
152 */
153 private boolean nooverview = false;
155 /**
156 * True if command line option "-overview" is used. Default value is false.
157 */
158 public boolean overview = false;
160 /**
161 * This is true if option "-overview" is used or option "-overview" is not
162 * used and number of packages is more than one.
163 */
164 public boolean createoverview = false;
166 /**
167 * Unique Resource Handler for this package.
168 */
169 public final MessageRetriever standardmessage;
171 /**
172 * First file to appear in the right-hand frame in the generated
173 * documentation.
174 */
175 public String topFile = "";
177 /**
178 * The classdoc for the class file getting generated.
179 */
180 public ClassDoc currentcd = null; // Set this classdoc in the
181 // ClassWriter.
183 /**
184 * Constructor. Initialises resource for the
185 * {@link com.sun.tools.doclets.MessageRetriever}.
186 */
187 private ConfigurationImpl() {
188 standardmessage = new MessageRetriever(this,
189 "com.sun.tools.doclets.formats.html.resources.standard");
190 }
192 public static ConfigurationImpl getInstance() {
193 return instance;
194 }
196 /**
197 * Return the build date for the doclet.
198 */
199 public String getDocletSpecificBuildDate() {
200 return BUILD_DATE;
201 }
203 /**
204 * Depending upon the command line options provided by the user, set
205 * configure the output generation environment.
206 *
207 * @param options The array of option names and values.
208 */
209 public void setSpecificDocletOptions(String[][] options) {
210 for (int oi = 0; oi < options.length; ++oi) {
211 String[] os = options[oi];
212 String opt = os[0].toLowerCase();
213 if (opt.equals("-footer")) {
214 footer = os[1];
215 } else if (opt.equals("-header")) {
216 header = os[1];
217 } else if (opt.equals("-packagesheader")) {
218 packagesheader = os[1];
219 } else if (opt.equals("-doctitle")) {
220 doctitle = os[1];
221 } else if (opt.equals("-windowtitle")) {
222 windowtitle = os[1];
223 } else if (opt.equals("-top")) {
224 top = os[1];
225 } else if (opt.equals("-bottom")) {
226 bottom = os[1];
227 } else if (opt.equals("-helpfile")) {
228 helpfile = os[1];
229 } else if (opt.equals("-stylesheetfile")) {
230 stylesheetfile = os[1];
231 } else if (opt.equals("-charset")) {
232 charset = os[1];
233 } else if (opt.equals("-nohelp")) {
234 nohelp = true;
235 } else if (opt.equals("-splitindex")) {
236 splitindex = true;
237 } else if (opt.equals("-noindex")) {
238 createindex = false;
239 } else if (opt.equals("-use")) {
240 classuse = true;
241 } else if (opt.equals("-notree")) {
242 createtree = false;
243 } else if (opt.equals("-nodeprecatedlist")) {
244 nodeprecatedlist = true;
245 } else if (opt.equals("-nosince")) {
246 nosince = true;
247 } else if (opt.equals("-nonavbar")) {
248 nonavbar = true;
249 } else if (opt.equals("-nooverview")) {
250 nooverview = true;
251 } else if (opt.equals("-overview")) {
252 overview = true;
253 }
254 }
255 if (root.specifiedClasses().length > 0) {
256 Map<String,PackageDoc> map = new HashMap<String,PackageDoc>();
257 PackageDoc pd;
258 ClassDoc[] classes = root.classes();
259 for (int i = 0; i < classes.length; i++) {
260 pd = classes[i].containingPackage();
261 if(! map.containsKey(pd.name())) {
262 map.put(pd.name(), pd);
263 }
264 }
265 }
266 setCreateOverview();
267 setTopFile(root);
268 }
270 /**
271 * Returns the "length" of a given option. If an option takes no
272 * arguments, its length is one. If it takes one argument, it's
273 * length is two, and so on. This method is called by JavaDoc to
274 * parse the options it does not recognize. It then calls
275 * {@link #validOptions(String[][], DocErrorReporter)} to
276 * validate them.
277 * <b>Note:</b><br>
278 * The options arrive as case-sensitive strings. For options that
279 * are not case-sensitive, use toLowerCase() on the option string
280 * before comparing it.
281 * </blockquote>
282 *
283 * @return number of arguments + 1 for a option. Zero return means
284 * option not known. Negative value means error occurred.
285 */
286 public int optionLength(String option) {
287 int result = -1;
288 if ((result = super.optionLength(option)) > 0) {
289 return result;
290 }
291 // otherwise look for the options we have added
292 option = option.toLowerCase();
293 if (option.equals("-nodeprecatedlist") ||
294 option.equals("-noindex") ||
295 option.equals("-notree") ||
296 option.equals("-nohelp") ||
297 option.equals("-splitindex") ||
298 option.equals("-serialwarn") ||
299 option.equals("-use") ||
300 option.equals("-nonavbar") ||
301 option.equals("-nooverview")) {
302 return 1;
303 } else if (option.equals("-help")) {
304 System.out.println(getText("doclet.usage"));
305 return 1;
306 } else if (option.equals("-footer") ||
307 option.equals("-header") ||
308 option.equals("-packagesheader") ||
309 option.equals("-doctitle") ||
310 option.equals("-windowtitle") ||
311 option.equals("-top") ||
312 option.equals("-bottom") ||
313 option.equals("-helpfile") ||
314 option.equals("-stylesheetfile") ||
315 option.equals("-charset") ||
316 option.equals("-overview")) {
317 return 2;
318 } else {
319 return 0;
320 }
321 }
323 /**
324 * {@inheritDoc}
325 */
326 public boolean validOptions(String options[][],
327 DocErrorReporter reporter) {
328 boolean helpfile = false;
329 boolean nohelp = false;
330 boolean overview = false;
331 boolean nooverview = false;
332 boolean splitindex = false;
333 boolean noindex = false;
334 // check shared options
335 if (!generalValidOptions(options, reporter)) {
336 return false;
337 }
338 // otherwise look at our options
339 for (int oi = 0; oi < options.length; ++oi) {
340 String[] os = options[oi];
341 String opt = os[0].toLowerCase();
342 if (opt.equals("-helpfile")) {
343 if (nohelp == true) {
344 reporter.printError(getText("doclet.Option_conflict",
345 "-helpfile", "-nohelp"));
346 return false;
347 }
348 if (helpfile == true) {
349 reporter.printError(getText("doclet.Option_reuse",
350 "-helpfile"));
351 return false;
352 }
353 File help = new File(os[1]);
354 if (!help.exists()) {
355 reporter.printError(getText("doclet.File_not_found", os[1]));
356 return false;
357 }
358 helpfile = true;
359 } else if (opt.equals("-nohelp")) {
360 if (helpfile == true) {
361 reporter.printError(getText("doclet.Option_conflict",
362 "-nohelp", "-helpfile"));
363 return false;
364 }
365 nohelp = true;
366 } else if (opt.equals("-overview")) {
367 if (nooverview == true) {
368 reporter.printError(getText("doclet.Option_conflict",
369 "-overview", "-nooverview"));
370 return false;
371 }
372 if (overview == true) {
373 reporter.printError(getText("doclet.Option_reuse",
374 "-overview"));
375 return false;
376 }
377 overview = true;
378 } else if (opt.equals("-nooverview")) {
379 if (overview == true) {
380 reporter.printError(getText("doclet.Option_conflict",
381 "-nooverview", "-overview"));
382 return false;
383 }
384 nooverview = true;
385 } else if (opt.equals("-splitindex")) {
386 if (noindex == true) {
387 reporter.printError(getText("doclet.Option_conflict",
388 "-splitindex", "-noindex"));
389 return false;
390 }
391 splitindex = true;
392 } else if (opt.equals("-noindex")) {
393 if (splitindex == true) {
394 reporter.printError(getText("doclet.Option_conflict",
395 "-noindex", "-splitindex"));
396 return false;
397 }
398 noindex = true;
399 }
400 }
401 return true;
402 }
404 /**
405 * {@inheritDoc}
406 */
407 public MessageRetriever getDocletSpecificMsg() {
408 return standardmessage;
409 }
411 /**
412 * Decide the page which will appear first in the right-hand frame. It will
413 * be "overview-summary.html" if "-overview" option is used or no
414 * "-overview" but the number of packages is more than one. It will be
415 * "package-summary.html" of the respective package if there is only one
416 * package to document. It will be a class page(first in the sorted order),
417 * if only classes are provided on the command line.
418 *
419 * @param root Root of the program structure.
420 */
421 protected void setTopFile(RootDoc root) {
422 if (!checkForDeprecation(root)) {
423 return;
424 }
425 if (createoverview) {
426 topFile = "overview-summary.html";
427 } else {
428 if (packages.length == 1 && packages[0].name().equals("")) {
429 if (root.classes().length > 0) {
430 ClassDoc[] classarr = root.classes();
431 Arrays.sort(classarr);
432 ClassDoc cd = getValidClass(classarr);
433 topFile = DirectoryManager.getPathToClass(cd);
434 }
435 } else {
436 topFile = DirectoryManager.getPathToPackage(packages[0],
437 "package-summary.html");
438 }
439 }
440 }
442 protected ClassDoc getValidClass(ClassDoc[] classarr) {
443 if (!nodeprecated) {
444 return classarr[0];
445 }
446 for (int i = 0; i < classarr.length; i++) {
447 if (classarr[i].tags("deprecated").length == 0) {
448 return classarr[i];
449 }
450 }
451 return null;
452 }
454 protected boolean checkForDeprecation(RootDoc root) {
455 ClassDoc[] classarr = root.classes();
456 for (int i = 0; i < classarr.length; i++) {
457 if (isGeneratedDoc(classarr[i])) {
458 return true;
459 }
460 }
461 return false;
462 }
464 /**
465 * Generate "overview.html" page if option "-overview" is used or number of
466 * packages is more than one. Sets {@link #createoverview} field to true.
467 */
468 protected void setCreateOverview() {
469 if ((overview || packages.length > 1) && !nooverview) {
470 createoverview = true;
471 }
472 }
474 /**
475 * {@inheritDoc}
476 */
477 public WriterFactory getWriterFactory() {
478 return WriterFactoryImpl.getInstance();
479 }
481 /**
482 * {@inheritDoc}
483 */
484 public Comparator<ProgramElementDoc> getMemberComparator() {
485 return null;
486 }
487 }