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 */
25
26 package com.sun.tools.doclets.internal.toolkit;
27
28 import java.io.*;
29 import java.util.*;
30
31 import com.sun.javadoc.*;
32 import com.sun.tools.doclets.internal.toolkit.builders.BuilderFactory;
33 import com.sun.tools.doclets.internal.toolkit.taglets.*;
34 import com.sun.tools.doclets.internal.toolkit.util.*;
35 import javax.tools.JavaFileManager;
36
37 /**
38 * Configure the output based on the options. Doclets should sub-class
39 * Configuration, to configure and add their own options. This class contains
40 * all user options which are supported by the 1.1 doclet and the standard
41 * doclet.
42 *
43 * <p><b>This is NOT part of any supported API.
44 * If you write code that depends on this, you do so at your own risk.
45 * This code and its internal interfaces are subject to change or
46 * deletion without notice.</b>
47 *
48 * @author Robert Field.
49 * @author Atul Dambalkar.
50 * @author Jamie Ho
51 */
171 * <code>showauthor</code> is set to true if -author option is used.
172 * Default is don't show author information.
173 */
174 public boolean showauthor = false;
175
176 /**
177 * Generate version specific information for the all the classes
178 * if @version tag is used in the doc comment and if -version option is
179 * used. <code>showversion</code> is set to true if -version option is
180 * used.Default is don't show version information.
181 */
182 public boolean showversion = false;
183
184 /**
185 * Sourcepath from where to read the source files. Default is classpath.
186 *
187 */
188 public String sourcepath = "";
189
190 /**
191 * Don't generate deprecated API information at all, if -nodeprecated
192 * option is used. <code>nodepracted</code> is set to true if
193 * -nodeprecated option is used. Default is generate deprected API
194 * information.
195 */
196 public boolean nodeprecated = false;
197
198 /**
199 * The catalog of classes specified on the command-line
200 */
201 public ClassDocCatalog classDocCatalog;
202
203 /**
204 * Message Retriever for the doclet, to retrieve message from the resource
205 * file for this Configuration, which is common for 1.1 and standard
206 * doclets.
207 *
208 * TODO: Make this private!!!
209 */
210 public MessageRetriever message = null;
230 */
231 public abstract String getDocletSpecificBuildDate();
232
233 /**
234 * This method should be defined in all those doclets(configurations),
235 * which want to derive themselves from this Configuration. This method
236 * can be used to set its own command line options.
237 *
238 * @param options The array of option names and values.
239 * @throws DocletAbortException
240 */
241 public abstract void setSpecificDocletOptions(String[][] options);
242
243 /**
244 * Return the doclet specific {@link MessageRetriever}
245 * @return the doclet specific MessageRetriever.
246 */
247 public abstract MessageRetriever getDocletSpecificMsg();
248
249 /**
250 * An array of the packages specified on the command-line merged
251 * with the array of packages that contain the classes specified on the
252 * command-line. The array is sorted.
253 */
254 public PackageDoc[] packages;
255
256 /**
257 * Constructor. Constructs the message retriever with resource file.
258 */
259 public Configuration() {
260 message =
261 new MessageRetriever(this,
262 "com.sun.tools.doclets.internal.toolkit.resources.doclets");
263 excludedDocFileDirs = new HashSet<String>();
264 excludedQualifiers = new HashSet<String>();
265 setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);
266 }
267
268 /**
269 * Return the builder factory for this doclet.
298 option.equals("-linksource") ||
299 option.equals("-nocomment") ||
300 option.equals("-nodeprecated") ||
301 option.equals("-nosince") ||
302 option.equals("-notimestamp") ||
303 option.equals("-quiet") ||
304 option.equals("-xnodate") ||
305 option.equals("-version")) {
306 return 1;
307 } else if (option.equals("-d") ||
308 option.equals("-docencoding") ||
309 option.equals("-encoding") ||
310 option.equals("-excludedocfilessubdir") ||
311 option.equals("-link") ||
312 option.equals("-sourcetab") ||
313 option.equals("-noqualifier") ||
314 option.equals("-output") ||
315 option.equals("-sourcepath") ||
316 option.equals("-tag") ||
317 option.equals("-taglet") ||
318 option.equals("-tagletpath")) {
319 return 2;
320 } else if (option.equals("-group") ||
321 option.equals("-linkoffline")) {
322 return 3;
323 } else {
324 return -1; // indicate we don't know about it
325 }
326 }
327
328 /**
329 * Perform error checking on the given options.
330 *
331 * @param options the given options to check.
332 * @param reporter the reporter used to report errors.
333 */
334 public abstract boolean validOptions(String options[][],
335 DocErrorReporter reporter);
336
337 private void initPackageArray() {
338 Set<PackageDoc> set = new HashSet<PackageDoc>(Arrays.asList(root.specifiedPackages()));
339 ClassDoc[] classes = root.specifiedClasses();
340 for (int i = 0; i < classes.length; i++) {
341 set.add(classes[i].containingPackage());
342 }
343 ArrayList<PackageDoc> results = new ArrayList<PackageDoc>(set);
344 Collections.sort(results);
345 packages = results.toArray(new PackageDoc[] {});
346 }
347
348 /**
349 * Set the command line options supported by this configuration.
350 *
351 * @param options the two dimensional array of options.
352 */
353 public void setOptions(String[][] options) {
354 LinkedHashSet<String[]> customTagStrs = new LinkedHashSet<String[]>();
355 for (int oi = 0; oi < options.length; ++oi) {
356 String[] os = options[oi];
387 linksource = true;
388 try {
389 setTabWidth(Integer.parseInt(os[1]));
390 } catch (NumberFormatException e) {
391 //Set to -1 so that warning will be printed
392 //to indicate what is valid argument.
393 sourcetab = -1;
394 }
395 if (sourcetab <= 0) {
396 message.warning("doclet.sourcetab_warning");
397 setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);
398 }
399 } else if (opt.equals("-notimestamp")) {
400 notimestamp = true;
401 } else if (opt.equals("-nocomment")) {
402 nocomment = true;
403 } else if (opt.equals("-tag") || opt.equals("-taglet")) {
404 customTagStrs.add(os);
405 } else if (opt.equals("-tagletpath")) {
406 tagletpath = os[1];
407 } else if (opt.equals("-keywords")) {
408 keywords = true;
409 } else if (opt.equals("-serialwarn")) {
410 serialwarn = true;
411 } else if (opt.equals("-group")) {
412 group.checkPackageGroups(os[1], os[2]);
413 } else if (opt.equals("-link")) {
414 String url = os[1];
415 extern.link(url, url, root, false);
416 } else if (opt.equals("-linkoffline")) {
417 String url = os[1];
418 String pkglisturl = os[2];
419 extern.link(url, pkglisturl, root, true);
420 }
421 }
422 if (sourcepath.length() == 0) {
423 sourcepath = System.getProperty("env.class.path") == null ? "" :
424 System.getProperty("env.class.path");
425 }
426 if (docencoding == null) {
427 docencoding = encoding;
428 }
429
430 classDocCatalog = new ClassDocCatalog(root.specifiedClasses(), this);
431 initTagletManager(customTagStrs);
432 }
433
434 /**
435 * Set the command line options supported by this configuration.
436 *
437 * @throws DocletAbortException
438 */
439 public void setOptions() {
440 initPackageArray();
441 setOptions(root.options());
442 setSpecificDocletOptions(root.options());
443 }
444
445
446 /**
447 * Initialize the taglet manager. The strings to initialize the simple custom tags should
448 * be in the following format: "[tag name]:[location str]:[heading]".
449 * @param customTagStrs the set two dimensional arrays of strings. These arrays contain
450 * either -tag or -taglet arguments.
451 */
452 private void initTagletManager(Set<String[]> customTagStrs) {
453 tagletManager = tagletManager == null ?
454 new TagletManager(nosince, showversion, showauthor, message) :
455 tagletManager;
456 String[] args;
457 for (Iterator<String[]> it = customTagStrs.iterator(); it.hasNext(); ) {
458 args = it.next();
459 if (args[0].equals("-taglet")) {
460 tagletManager.addCustomTag(args[1], getFileManager(), tagletpath);
461 continue;
|
1 /*
2 * Copyright (c) 1997, 2013, 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
26 package com.sun.tools.doclets.internal.toolkit;
27
28 import java.io.*;
29 import java.util.*;
30
31 import com.sun.javadoc.*;
32 import com.sun.tools.javac.sym.Profiles;
33 import com.sun.tools.javac.jvm.Profile;
34 import com.sun.tools.doclets.internal.toolkit.builders.BuilderFactory;
35 import com.sun.tools.doclets.internal.toolkit.taglets.*;
36 import com.sun.tools.doclets.internal.toolkit.util.*;
37 import javax.tools.JavaFileManager;
38
39 /**
40 * Configure the output based on the options. Doclets should sub-class
41 * Configuration, to configure and add their own options. This class contains
42 * all user options which are supported by the 1.1 doclet and the standard
43 * doclet.
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 * @author Robert Field.
51 * @author Atul Dambalkar.
52 * @author Jamie Ho
53 */
173 * <code>showauthor</code> is set to true if -author option is used.
174 * Default is don't show author information.
175 */
176 public boolean showauthor = false;
177
178 /**
179 * Generate version specific information for the all the classes
180 * if @version tag is used in the doc comment and if -version option is
181 * used. <code>showversion</code> is set to true if -version option is
182 * used.Default is don't show version information.
183 */
184 public boolean showversion = false;
185
186 /**
187 * Sourcepath from where to read the source files. Default is classpath.
188 *
189 */
190 public String sourcepath = "";
191
192 /**
193 * Argument for command line option "-Xprofilespath".
194 */
195 public String profilespath = "";
196
197 /**
198 * Generate profiles documentation if profilespath is set and valid profiles
199 * are present.
200 */
201 public boolean showProfiles = false;
202
203 /**
204 * Don't generate deprecated API information at all, if -nodeprecated
205 * option is used. <code>nodepracted</code> is set to true if
206 * -nodeprecated option is used. Default is generate deprected API
207 * information.
208 */
209 public boolean nodeprecated = false;
210
211 /**
212 * The catalog of classes specified on the command-line
213 */
214 public ClassDocCatalog classDocCatalog;
215
216 /**
217 * Message Retriever for the doclet, to retrieve message from the resource
218 * file for this Configuration, which is common for 1.1 and standard
219 * doclets.
220 *
221 * TODO: Make this private!!!
222 */
223 public MessageRetriever message = null;
243 */
244 public abstract String getDocletSpecificBuildDate();
245
246 /**
247 * This method should be defined in all those doclets(configurations),
248 * which want to derive themselves from this Configuration. This method
249 * can be used to set its own command line options.
250 *
251 * @param options The array of option names and values.
252 * @throws DocletAbortException
253 */
254 public abstract void setSpecificDocletOptions(String[][] options);
255
256 /**
257 * Return the doclet specific {@link MessageRetriever}
258 * @return the doclet specific MessageRetriever.
259 */
260 public abstract MessageRetriever getDocletSpecificMsg();
261
262 /**
263 * A profiles object used to access profiles across various pages.
264 */
265 public Profiles profiles;
266
267 /**
268 * An map of the profiles to packages.
269 */
270 public Map<String,PackageDoc[]> profilePackages;
271
272 /**
273 * An array of the packages specified on the command-line merged
274 * with the array of packages that contain the classes specified on the
275 * command-line. The array is sorted.
276 */
277 public PackageDoc[] packages;
278
279 /**
280 * Constructor. Constructs the message retriever with resource file.
281 */
282 public Configuration() {
283 message =
284 new MessageRetriever(this,
285 "com.sun.tools.doclets.internal.toolkit.resources.doclets");
286 excludedDocFileDirs = new HashSet<String>();
287 excludedQualifiers = new HashSet<String>();
288 setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);
289 }
290
291 /**
292 * Return the builder factory for this doclet.
321 option.equals("-linksource") ||
322 option.equals("-nocomment") ||
323 option.equals("-nodeprecated") ||
324 option.equals("-nosince") ||
325 option.equals("-notimestamp") ||
326 option.equals("-quiet") ||
327 option.equals("-xnodate") ||
328 option.equals("-version")) {
329 return 1;
330 } else if (option.equals("-d") ||
331 option.equals("-docencoding") ||
332 option.equals("-encoding") ||
333 option.equals("-excludedocfilessubdir") ||
334 option.equals("-link") ||
335 option.equals("-sourcetab") ||
336 option.equals("-noqualifier") ||
337 option.equals("-output") ||
338 option.equals("-sourcepath") ||
339 option.equals("-tag") ||
340 option.equals("-taglet") ||
341 option.equals("-tagletpath") ||
342 option.equals("-xprofilespath")) {
343 return 2;
344 } else if (option.equals("-group") ||
345 option.equals("-linkoffline")) {
346 return 3;
347 } else {
348 return -1; // indicate we don't know about it
349 }
350 }
351
352 /**
353 * Perform error checking on the given options.
354 *
355 * @param options the given options to check.
356 * @param reporter the reporter used to report errors.
357 */
358 public abstract boolean validOptions(String options[][],
359 DocErrorReporter reporter);
360
361 private void initProfiles() throws IOException {
362 profiles = Profiles.read(new File(profilespath));
363 // Generate profiles documentation only is profilespath is set and if
364 // profiles is not null and profiles count is 1 or more.
365 showProfiles = (!profilespath.isEmpty() && profiles != null &&
366 profiles.getProfileCount() > 0);
367 }
368
369 private void initProfilePackages() throws IOException {
370 profilePackages = new HashMap<String,PackageDoc[]>();
371 ArrayList<PackageDoc> results;
372 Map<String,PackageDoc> packageIndex = new HashMap<String,PackageDoc>();
373 for (int i = 0; i < packages.length; i++) {
374 PackageDoc pkg = packages[i];
375 packageIndex.put(pkg.name(), pkg);
376 }
377 for (int i = 1; i < profiles.getProfileCount(); i++) {
378 Set<String> profPkgs = profiles.getPackages(i);
379 results = new ArrayList<PackageDoc>();
380 for (String packageName : profPkgs) {
381 packageName = packageName.replace("/", ".");
382 PackageDoc profPkg = packageIndex.get(packageName);
383 if (profPkg != null) {
384 results.add(profPkg);
385 }
386 }
387 Collections.sort(results);
388 PackageDoc[] profilePkgs = results.toArray(new PackageDoc[]{});
389 profilePackages.put(Profile.lookup(i).name, profilePkgs);
390 }
391 }
392
393 private void initPackageArray() {
394 Set<PackageDoc> set = new HashSet<PackageDoc>(Arrays.asList(root.specifiedPackages()));
395 ClassDoc[] classes = root.specifiedClasses();
396 for (int i = 0; i < classes.length; i++) {
397 set.add(classes[i].containingPackage());
398 }
399 ArrayList<PackageDoc> results = new ArrayList<PackageDoc>(set);
400 Collections.sort(results);
401 packages = results.toArray(new PackageDoc[] {});
402 }
403
404 /**
405 * Set the command line options supported by this configuration.
406 *
407 * @param options the two dimensional array of options.
408 */
409 public void setOptions(String[][] options) {
410 LinkedHashSet<String[]> customTagStrs = new LinkedHashSet<String[]>();
411 for (int oi = 0; oi < options.length; ++oi) {
412 String[] os = options[oi];
443 linksource = true;
444 try {
445 setTabWidth(Integer.parseInt(os[1]));
446 } catch (NumberFormatException e) {
447 //Set to -1 so that warning will be printed
448 //to indicate what is valid argument.
449 sourcetab = -1;
450 }
451 if (sourcetab <= 0) {
452 message.warning("doclet.sourcetab_warning");
453 setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);
454 }
455 } else if (opt.equals("-notimestamp")) {
456 notimestamp = true;
457 } else if (opt.equals("-nocomment")) {
458 nocomment = true;
459 } else if (opt.equals("-tag") || opt.equals("-taglet")) {
460 customTagStrs.add(os);
461 } else if (opt.equals("-tagletpath")) {
462 tagletpath = os[1];
463 } else if (opt.equals("-xprofilespath")) {
464 profilespath = os[1];
465 } else if (opt.equals("-keywords")) {
466 keywords = true;
467 } else if (opt.equals("-serialwarn")) {
468 serialwarn = true;
469 } else if (opt.equals("-group")) {
470 group.checkPackageGroups(os[1], os[2]);
471 } else if (opt.equals("-link")) {
472 String url = os[1];
473 extern.link(url, url, root, false);
474 } else if (opt.equals("-linkoffline")) {
475 String url = os[1];
476 String pkglisturl = os[2];
477 extern.link(url, pkglisturl, root, true);
478 }
479 }
480 if (sourcepath.length() == 0) {
481 sourcepath = System.getProperty("env.class.path") == null ? "" :
482 System.getProperty("env.class.path");
483 }
484 if (docencoding == null) {
485 docencoding = encoding;
486 }
487
488 classDocCatalog = new ClassDocCatalog(root.specifiedClasses(), this);
489 initTagletManager(customTagStrs);
490 }
491
492 /**
493 * Set the command line options supported by this configuration.
494 *
495 * @throws DocletAbortException
496 */
497 public void setOptions() {
498 initPackageArray();
499 setOptions(root.options());
500 if (!profilespath.isEmpty()) {
501 try {
502 initProfiles();
503 initProfilePackages();
504 } catch (Exception e) {
505 throw new DocletAbortException();
506 }
507 }
508 setSpecificDocletOptions(root.options());
509 }
510
511
512 /**
513 * Initialize the taglet manager. The strings to initialize the simple custom tags should
514 * be in the following format: "[tag name]:[location str]:[heading]".
515 * @param customTagStrs the set two dimensional arrays of strings. These arrays contain
516 * either -tag or -taglet arguments.
517 */
518 private void initTagletManager(Set<String[]> customTagStrs) {
519 tagletManager = tagletManager == null ?
520 new TagletManager(nosince, showversion, showauthor, message) :
521 tagletManager;
522 String[] args;
523 for (Iterator<String[]> it = customTagStrs.iterator(); it.hasNext(); ) {
524 args = it.next();
525 if (args[0].equals("-taglet")) {
526 tagletManager.addCustomTag(args[1], getFileManager(), tagletpath);
527 continue;
|