Tue, 18 Jun 2013 20:56:04 -0700
8015657: jdk8 l10n resource file translation update 3
Reviewed-by: yhuang
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 */
26 package com.sun.tools.doclets.internal.toolkit;
28 import java.io.*;
29 import java.util.*;
30 import java.util.regex.Matcher;
31 import java.util.regex.Pattern;
33 import com.sun.javadoc.*;
34 import com.sun.tools.javac.sym.Profiles;
35 import com.sun.tools.javac.jvm.Profile;
36 import com.sun.tools.doclets.internal.toolkit.builders.BuilderFactory;
37 import com.sun.tools.doclets.internal.toolkit.taglets.*;
38 import com.sun.tools.doclets.internal.toolkit.util.*;
39 import javax.tools.JavaFileManager;
41 /**
42 * Configure the output based on the options. Doclets should sub-class
43 * Configuration, to configure and add their own options. This class contains
44 * all user options which are supported by the 1.1 doclet and the standard
45 * doclet.
46 *
47 * <p><b>This is NOT part of any supported API.
48 * If you write code that depends on this, you do so at your own risk.
49 * This code and its internal interfaces are subject to change or
50 * deletion without notice.</b>
51 *
52 * @author Robert Field.
53 * @author Atul Dambalkar.
54 * @author Jamie Ho
55 */
56 public abstract class Configuration {
58 /**
59 * Exception used to report a problem during setOptions.
60 */
61 public static class Fault extends Exception {
62 private static final long serialVersionUID = 0;
64 Fault(String msg) {
65 super(msg);
66 }
68 Fault(String msg, Exception cause) {
69 super(msg, cause);
70 }
71 }
73 /**
74 * The factory for builders.
75 */
76 protected BuilderFactory builderFactory;
78 /**
79 * The taglet manager.
80 */
81 public TagletManager tagletManager;
83 /**
84 * The path to the builder XML input file.
85 */
86 public String builderXMLPath;
88 /**
89 * The default path to the builder XML.
90 */
91 private static final String DEFAULT_BUILDER_XML = "resources/doclet.xml";
93 /**
94 * The path to Taglets
95 */
96 public String tagletpath = "";
98 /**
99 * This is true if option "-serialwarn" is used. Defualt value is false to
100 * suppress excessive warnings about serial tag.
101 */
102 public boolean serialwarn = false;
104 /**
105 * The specified amount of space between tab stops.
106 */
107 public int sourcetab;
109 public String tabSpaces;
111 /**
112 * True if we should generate browsable sources.
113 */
114 public boolean linksource = false;
116 /**
117 * True if command line option "-nosince" is used. Default value is
118 * false.
119 */
120 public boolean nosince = false;
122 /**
123 * True if we should recursively copy the doc-file subdirectories
124 */
125 public boolean copydocfilesubdirs = false;
127 /**
128 * The META charset tag used for cross-platform viewing.
129 */
130 public String charset = "";
132 /**
133 * True if user wants to add member names as meta keywords.
134 * Set to false because meta keywords are ignored in general
135 * by most Internet search engines.
136 */
137 public boolean keywords = false;
139 /**
140 * The meta tag keywords instance.
141 */
142 public final MetaKeywords metakeywords = new MetaKeywords(this);
144 /**
145 * The list of doc-file subdirectories to exclude
146 */
147 protected Set<String> excludedDocFileDirs;
149 /**
150 * The list of qualifiers to exclude
151 */
152 protected Set<String> excludedQualifiers;
154 /**
155 * The Root of the generated Program Structure from the Doclet API.
156 */
157 public RootDoc root;
159 /**
160 * Destination directory name, in which doclet will generate the entire
161 * documentation. Default is current directory.
162 */
163 public String destDirName = "";
165 /**
166 * Destination directory name, in which doclet will copy the doc-files to.
167 */
168 public String docFileDestDirName = "";
170 /**
171 * Encoding for this document. Default is default encoding for this
172 * platform.
173 */
174 public String docencoding = null;
176 /**
177 * True if user wants to suppress descriptions and tags.
178 */
179 public boolean nocomment = false;
181 /**
182 * Encoding for this document. Default is default encoding for this
183 * platform.
184 */
185 public String encoding = null;
187 /**
188 * Generate author specific information for all the classes if @author
189 * tag is used in the doc comment and if -author option is used.
190 * <code>showauthor</code> is set to true if -author option is used.
191 * Default is don't show author information.
192 */
193 public boolean showauthor = false;
195 /**
196 * Generate documentation for JavaFX getters and setters automatically
197 * by copying it from the appropriate property definition.
198 */
199 public boolean javafx = false;
201 /**
202 * Generate version specific information for the all the classes
203 * if @version tag is used in the doc comment and if -version option is
204 * used. <code>showversion</code> is set to true if -version option is
205 * used.Default is don't show version information.
206 */
207 public boolean showversion = false;
209 /**
210 * Sourcepath from where to read the source files. Default is classpath.
211 *
212 */
213 public String sourcepath = "";
215 /**
216 * Argument for command line option "-Xprofilespath".
217 */
218 public String profilespath = "";
220 /**
221 * Generate profiles documentation if profilespath is set and valid profiles
222 * are present.
223 */
224 public boolean showProfiles = false;
226 /**
227 * Don't generate deprecated API information at all, if -nodeprecated
228 * option is used. <code>nodepracted</code> is set to true if
229 * -nodeprecated option is used. Default is generate deprected API
230 * information.
231 */
232 public boolean nodeprecated = false;
234 /**
235 * The catalog of classes specified on the command-line
236 */
237 public ClassDocCatalog classDocCatalog;
239 /**
240 * Message Retriever for the doclet, to retrieve message from the resource
241 * file for this Configuration, which is common for 1.1 and standard
242 * doclets.
243 *
244 * TODO: Make this private!!!
245 */
246 public MessageRetriever message = null;
248 /**
249 * True if user wants to suppress time stamp in output.
250 * Default is false.
251 */
252 public boolean notimestamp= false;
254 /**
255 * The package grouping instance.
256 */
257 public final Group group = new Group(this);
259 /**
260 * The tracker of external package links.
261 */
262 public final Extern extern = new Extern(this);
264 /**
265 * Return the build date for the doclet.
266 */
267 public abstract String getDocletSpecificBuildDate();
269 /**
270 * This method should be defined in all those doclets(configurations),
271 * which want to derive themselves from this Configuration. This method
272 * can be used to set its own command line options.
273 *
274 * @param options The array of option names and values.
275 * @throws DocletAbortException
276 */
277 public abstract void setSpecificDocletOptions(String[][] options) throws Fault;
279 /**
280 * Return the doclet specific {@link MessageRetriever}
281 * @return the doclet specific MessageRetriever.
282 */
283 public abstract MessageRetriever getDocletSpecificMsg();
285 /**
286 * A profiles object used to access profiles across various pages.
287 */
288 public Profiles profiles;
290 /**
291 * An map of the profiles to packages.
292 */
293 public Map<String,PackageDoc[]> profilePackages;
295 /**
296 * An array of the packages specified on the command-line merged
297 * with the array of packages that contain the classes specified on the
298 * command-line. The array is sorted.
299 */
300 public PackageDoc[] packages;
302 /**
303 * Constructor. Constructs the message retriever with resource file.
304 */
305 public Configuration() {
306 message =
307 new MessageRetriever(this,
308 "com.sun.tools.doclets.internal.toolkit.resources.doclets");
309 excludedDocFileDirs = new HashSet<String>();
310 excludedQualifiers = new HashSet<String>();
311 setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);
312 }
314 /**
315 * Return the builder factory for this doclet.
316 *
317 * @return the builder factory for this doclet.
318 */
319 public BuilderFactory getBuilderFactory() {
320 if (builderFactory == null) {
321 builderFactory = new BuilderFactory(this);
322 }
323 return builderFactory;
324 }
326 /**
327 * This method should be defined in all those doclets
328 * which want to inherit from this Configuration. This method
329 * should return the number of arguments to the command line
330 * option (including the option name). For example,
331 * -notimestamp is a single-argument option, so this method would
332 * return 1.
333 *
334 * @param option Command line option under consideration.
335 * @return number of arguments to option (including the
336 * option name). Zero return means option not known.
337 * Negative value means error occurred.
338 */
339 public int optionLength(String option) {
340 option = option.toLowerCase();
341 if (option.equals("-author") ||
342 option.equals("-docfilessubdirs") ||
343 option.equals("-javafx") ||
344 option.equals("-keywords") ||
345 option.equals("-linksource") ||
346 option.equals("-nocomment") ||
347 option.equals("-nodeprecated") ||
348 option.equals("-nosince") ||
349 option.equals("-notimestamp") ||
350 option.equals("-quiet") ||
351 option.equals("-xnodate") ||
352 option.equals("-version")) {
353 return 1;
354 } else if (option.equals("-d") ||
355 option.equals("-docencoding") ||
356 option.equals("-encoding") ||
357 option.equals("-excludedocfilessubdir") ||
358 option.equals("-link") ||
359 option.equals("-sourcetab") ||
360 option.equals("-noqualifier") ||
361 option.equals("-output") ||
362 option.equals("-sourcepath") ||
363 option.equals("-tag") ||
364 option.equals("-taglet") ||
365 option.equals("-tagletpath") ||
366 option.equals("-xprofilespath")) {
367 return 2;
368 } else if (option.equals("-group") ||
369 option.equals("-linkoffline")) {
370 return 3;
371 } else {
372 return -1; // indicate we don't know about it
373 }
374 }
376 /**
377 * Perform error checking on the given options.
378 *
379 * @param options the given options to check.
380 * @param reporter the reporter used to report errors.
381 */
382 public abstract boolean validOptions(String options[][],
383 DocErrorReporter reporter);
385 private void initProfiles() throws IOException {
386 profiles = Profiles.read(new File(profilespath));
387 // Generate profiles documentation only is profilespath is set and if
388 // profiles is not null and profiles count is 1 or more.
389 showProfiles = (!profilespath.isEmpty() && profiles != null &&
390 profiles.getProfileCount() > 0);
391 }
393 private void initProfilePackages() throws IOException {
394 profilePackages = new HashMap<String,PackageDoc[]>();
395 ArrayList<PackageDoc> results;
396 Map<String,PackageDoc> packageIndex = new HashMap<String,PackageDoc>();
397 for (int i = 0; i < packages.length; i++) {
398 PackageDoc pkg = packages[i];
399 packageIndex.put(pkg.name(), pkg);
400 }
401 for (int i = 1; i < profiles.getProfileCount(); i++) {
402 Set<String> profPkgs = profiles.getPackages(i);
403 results = new ArrayList<PackageDoc>();
404 for (String packageName : profPkgs) {
405 packageName = packageName.replace("/", ".");
406 PackageDoc profPkg = packageIndex.get(packageName);
407 if (profPkg != null) {
408 results.add(profPkg);
409 }
410 }
411 Collections.sort(results);
412 PackageDoc[] profilePkgs = results.toArray(new PackageDoc[]{});
413 profilePackages.put(Profile.lookup(i).name, profilePkgs);
414 }
415 }
417 private void initPackageArray() {
418 Set<PackageDoc> set = new HashSet<PackageDoc>(Arrays.asList(root.specifiedPackages()));
419 ClassDoc[] classes = root.specifiedClasses();
420 for (int i = 0; i < classes.length; i++) {
421 set.add(classes[i].containingPackage());
422 }
423 ArrayList<PackageDoc> results = new ArrayList<PackageDoc>(set);
424 Collections.sort(results);
425 packages = results.toArray(new PackageDoc[] {});
426 }
428 /**
429 * Set the command line options supported by this configuration.
430 *
431 * @param options the two dimensional array of options.
432 */
433 public void setOptions(String[][] options) throws Fault {
434 LinkedHashSet<String[]> customTagStrs = new LinkedHashSet<String[]>();
436 // Some options, specifically -link and -linkoffline, require that
437 // the output directory has already been created: so do that first.
438 for (int oi = 0; oi < options.length; ++oi) {
439 String[] os = options[oi];
440 String opt = os[0].toLowerCase();
441 if (opt.equals("-d")) {
442 destDirName = addTrailingFileSep(os[1]);
443 docFileDestDirName = destDirName;
444 ensureOutputDirExists();
445 break;
446 }
447 }
449 for (int oi = 0; oi < options.length; ++oi) {
450 String[] os = options[oi];
451 String opt = os[0].toLowerCase();
452 if (opt.equals("-docfilessubdirs")) {
453 copydocfilesubdirs = true;
454 } else if (opt.equals("-docencoding")) {
455 docencoding = os[1];
456 } else if (opt.equals("-encoding")) {
457 encoding = os[1];
458 } else if (opt.equals("-author")) {
459 showauthor = true;
460 } else if (opt.equals("-javafx")) {
461 javafx = true;
462 } else if (opt.equals("-nosince")) {
463 nosince = true;
464 } else if (opt.equals("-version")) {
465 showversion = true;
466 } else if (opt.equals("-nodeprecated")) {
467 nodeprecated = true;
468 } else if (opt.equals("-sourcepath")) {
469 sourcepath = os[1];
470 } else if (opt.equals("-classpath") &&
471 sourcepath.length() == 0) {
472 sourcepath = os[1];
473 } else if (opt.equals("-excludedocfilessubdir")) {
474 addToSet(excludedDocFileDirs, os[1]);
475 } else if (opt.equals("-noqualifier")) {
476 addToSet(excludedQualifiers, os[1]);
477 } else if (opt.equals("-linksource")) {
478 linksource = true;
479 } else if (opt.equals("-sourcetab")) {
480 linksource = true;
481 try {
482 setTabWidth(Integer.parseInt(os[1]));
483 } catch (NumberFormatException e) {
484 //Set to -1 so that warning will be printed
485 //to indicate what is valid argument.
486 sourcetab = -1;
487 }
488 if (sourcetab <= 0) {
489 message.warning("doclet.sourcetab_warning");
490 setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);
491 }
492 } else if (opt.equals("-notimestamp")) {
493 notimestamp = true;
494 } else if (opt.equals("-nocomment")) {
495 nocomment = true;
496 } else if (opt.equals("-tag") || opt.equals("-taglet")) {
497 customTagStrs.add(os);
498 } else if (opt.equals("-tagletpath")) {
499 tagletpath = os[1];
500 } else if (opt.equals("-xprofilespath")) {
501 profilespath = os[1];
502 } else if (opt.equals("-keywords")) {
503 keywords = true;
504 } else if (opt.equals("-serialwarn")) {
505 serialwarn = true;
506 } else if (opt.equals("-group")) {
507 group.checkPackageGroups(os[1], os[2]);
508 } else if (opt.equals("-link")) {
509 String url = os[1];
510 extern.link(url, url, root, false);
511 } else if (opt.equals("-linkoffline")) {
512 String url = os[1];
513 String pkglisturl = os[2];
514 extern.link(url, pkglisturl, root, true);
515 }
516 }
517 if (sourcepath.length() == 0) {
518 sourcepath = System.getProperty("env.class.path") == null ? "" :
519 System.getProperty("env.class.path");
520 }
521 if (docencoding == null) {
522 docencoding = encoding;
523 }
525 classDocCatalog = new ClassDocCatalog(root.specifiedClasses(), this);
526 initTagletManager(customTagStrs);
527 }
529 /**
530 * Set the command line options supported by this configuration.
531 *
532 * @throws DocletAbortException
533 */
534 public void setOptions() throws Fault {
535 initPackageArray();
536 setOptions(root.options());
537 if (!profilespath.isEmpty()) {
538 try {
539 initProfiles();
540 initProfilePackages();
541 } catch (Exception e) {
542 throw new DocletAbortException();
543 }
544 }
545 setSpecificDocletOptions(root.options());
546 }
548 private void ensureOutputDirExists() throws Fault {
549 DocFile destDir = DocFile.createFileForDirectory(this, destDirName);
550 if (!destDir.exists()) {
551 //Create the output directory (in case it doesn't exist yet)
552 root.printNotice(getText("doclet.dest_dir_create", destDirName));
553 destDir.mkdirs();
554 } else if (!destDir.isDirectory()) {
555 throw new Fault(getText(
556 "doclet.destination_directory_not_directory_0",
557 destDir.getPath()));
558 } else if (!destDir.canWrite()) {
559 throw new Fault(getText(
560 "doclet.destination_directory_not_writable_0",
561 destDir.getPath()));
562 }
563 }
566 /**
567 * Initialize the taglet manager. The strings to initialize the simple custom tags should
568 * be in the following format: "[tag name]:[location str]:[heading]".
569 * @param customTagStrs the set two dimensional arrays of strings. These arrays contain
570 * either -tag or -taglet arguments.
571 */
572 private void initTagletManager(Set<String[]> customTagStrs) {
573 tagletManager = tagletManager == null ?
574 new TagletManager(nosince, showversion, showauthor, javafx, message) :
575 tagletManager;
576 String[] args;
577 for (Iterator<String[]> it = customTagStrs.iterator(); it.hasNext(); ) {
578 args = it.next();
579 if (args[0].equals("-taglet")) {
580 tagletManager.addCustomTag(args[1], getFileManager(), tagletpath);
581 continue;
582 }
583 String[] tokens = tokenize(args[1],
584 TagletManager.SIMPLE_TAGLET_OPT_SEPARATOR, 3);
585 if (tokens.length == 1) {
586 String tagName = args[1];
587 if (tagletManager.isKnownCustomTag(tagName)) {
588 //reorder a standard tag
589 tagletManager.addNewSimpleCustomTag(tagName, null, "");
590 } else {
591 //Create a simple tag with the heading that has the same name as the tag.
592 StringBuilder heading = new StringBuilder(tagName + ":");
593 heading.setCharAt(0, Character.toUpperCase(tagName.charAt(0)));
594 tagletManager.addNewSimpleCustomTag(tagName, heading.toString(), "a");
595 }
596 } else if (tokens.length == 2) {
597 //Add simple taglet without heading, probably to excluding it in the output.
598 tagletManager.addNewSimpleCustomTag(tokens[0], tokens[1], "");
599 } else if (tokens.length >= 3) {
600 tagletManager.addNewSimpleCustomTag(tokens[0], tokens[2], tokens[1]);
601 } else {
602 message.error("doclet.Error_invalid_custom_tag_argument", args[1]);
603 }
604 }
605 }
607 /**
608 * Given a string, return an array of tokens. The separator can be escaped
609 * with the '\' character. The '\' character may also be escaped by the
610 * '\' character.
611 *
612 * @param s the string to tokenize.
613 * @param separator the separator char.
614 * @param maxTokens the maximum number of tokens returned. If the
615 * max is reached, the remaining part of s is appended
616 * to the end of the last token.
617 *
618 * @return an array of tokens.
619 */
620 private String[] tokenize(String s, char separator, int maxTokens) {
621 List<String> tokens = new ArrayList<String>();
622 StringBuilder token = new StringBuilder ();
623 boolean prevIsEscapeChar = false;
624 for (int i = 0; i < s.length(); i += Character.charCount(i)) {
625 int currentChar = s.codePointAt(i);
626 if (prevIsEscapeChar) {
627 // Case 1: escaped character
628 token.appendCodePoint(currentChar);
629 prevIsEscapeChar = false;
630 } else if (currentChar == separator && tokens.size() < maxTokens-1) {
631 // Case 2: separator
632 tokens.add(token.toString());
633 token = new StringBuilder();
634 } else if (currentChar == '\\') {
635 // Case 3: escape character
636 prevIsEscapeChar = true;
637 } else {
638 // Case 4: regular character
639 token.appendCodePoint(currentChar);
640 }
641 }
642 if (token.length() > 0) {
643 tokens.add(token.toString());
644 }
645 return tokens.toArray(new String[] {});
646 }
648 private void addToSet(Set<String> s, String str){
649 StringTokenizer st = new StringTokenizer(str, ":");
650 String current;
651 while(st.hasMoreTokens()){
652 current = st.nextToken();
653 s.add(current);
654 }
655 }
657 /**
658 * Add a trailing file separator, if not found. Remove superfluous
659 * file separators if any. Preserve the front double file separator for
660 * UNC paths.
661 *
662 * @param path Path under consideration.
663 * @return String Properly constructed path string.
664 */
665 public static String addTrailingFileSep(String path) {
666 String fs = System.getProperty("file.separator");
667 String dblfs = fs + fs;
668 int indexDblfs;
669 while ((indexDblfs = path.indexOf(dblfs, 1)) >= 0) {
670 path = path.substring(0, indexDblfs) +
671 path.substring(indexDblfs + fs.length());
672 }
673 if (!path.endsWith(fs))
674 path += fs;
675 return path;
676 }
678 /**
679 * This checks for the validity of the options used by the user.
680 * This works exactly like
681 * {@link com.sun.javadoc.Doclet#validOptions(String[][],
682 * DocErrorReporter)}. This will validate the options which are shared
683 * by our doclets. For example, this method will flag an error using
684 * the DocErrorReporter if user has used "-nohelp" and "-helpfile" option
685 * together.
686 *
687 * @param options options used on the command line.
688 * @param reporter used to report errors.
689 * @return true if all the options are valid.
690 */
691 public boolean generalValidOptions(String options[][],
692 DocErrorReporter reporter) {
693 boolean docencodingfound = false;
694 String encoding = "";
695 for (int oi = 0; oi < options.length; oi++) {
696 String[] os = options[oi];
697 String opt = os[0].toLowerCase();
698 if (opt.equals("-docencoding")) {
699 docencodingfound = true;
700 if (!checkOutputFileEncoding(os[1], reporter)) {
701 return false;
702 }
703 } else if (opt.equals("-encoding")) {
704 encoding = os[1];
705 }
706 }
707 if (!docencodingfound && encoding.length() > 0) {
708 if (!checkOutputFileEncoding(encoding, reporter)) {
709 return false;
710 }
711 }
712 return true;
713 }
715 /**
716 * Check the validity of the given Source or Output File encoding on this
717 * platform.
718 *
719 * @param docencoding output file encoding.
720 * @param reporter used to report errors.
721 */
722 private boolean checkOutputFileEncoding(String docencoding,
723 DocErrorReporter reporter) {
724 OutputStream ost= new ByteArrayOutputStream();
725 OutputStreamWriter osw = null;
726 try {
727 osw = new OutputStreamWriter(ost, docencoding);
728 } catch (UnsupportedEncodingException exc) {
729 reporter.printError(getText("doclet.Encoding_not_supported",
730 docencoding));
731 return false;
732 } finally {
733 try {
734 if (osw != null) {
735 osw.close();
736 }
737 } catch (IOException exc) {
738 }
739 }
740 return true;
741 }
743 /**
744 * Return true if the given doc-file subdirectory should be excluded and
745 * false otherwise.
746 * @param docfilesubdir the doc-files subdirectory to check.
747 */
748 public boolean shouldExcludeDocFileDir(String docfilesubdir){
749 if (excludedDocFileDirs.contains(docfilesubdir)) {
750 return true;
751 } else {
752 return false;
753 }
754 }
756 /**
757 * Return true if the given qualifier should be excluded and false otherwise.
758 * @param qualifier the qualifier to check.
759 */
760 public boolean shouldExcludeQualifier(String qualifier){
761 if (excludedQualifiers.contains("all") ||
762 excludedQualifiers.contains(qualifier) ||
763 excludedQualifiers.contains(qualifier + ".*")) {
764 return true;
765 } else {
766 int index = -1;
767 while ((index = qualifier.indexOf(".", index + 1)) != -1) {
768 if (excludedQualifiers.contains(qualifier.substring(0, index + 1) + "*")) {
769 return true;
770 }
771 }
772 return false;
773 }
774 }
776 /**
777 * Return the qualified name of the <code>ClassDoc</code> if it's qualifier is not excluded. Otherwise,
778 * return the unqualified <code>ClassDoc</code> name.
779 * @param cd the <code>ClassDoc</code> to check.
780 */
781 public String getClassName(ClassDoc cd) {
782 PackageDoc pd = cd.containingPackage();
783 if (pd != null && shouldExcludeQualifier(cd.containingPackage().name())) {
784 return cd.name();
785 } else {
786 return cd.qualifiedName();
787 }
788 }
790 public String getText(String key) {
791 try {
792 //Check the doclet specific properties file.
793 return getDocletSpecificMsg().getText(key);
794 } catch (Exception e) {
795 //Check the shared properties file.
796 return message.getText(key);
797 }
798 }
800 public String getText(String key, String a1) {
801 try {
802 //Check the doclet specific properties file.
803 return getDocletSpecificMsg().getText(key, a1);
804 } catch (Exception e) {
805 //Check the shared properties file.
806 return message.getText(key, a1);
807 }
808 }
810 public String getText(String key, String a1, String a2) {
811 try {
812 //Check the doclet specific properties file.
813 return getDocletSpecificMsg().getText(key, a1, a2);
814 } catch (Exception e) {
815 //Check the shared properties file.
816 return message.getText(key, a1, a2);
817 }
818 }
820 public String getText(String key, String a1, String a2, String a3) {
821 try {
822 //Check the doclet specific properties file.
823 return getDocletSpecificMsg().getText(key, a1, a2, a3);
824 } catch (Exception e) {
825 //Check the shared properties file.
826 return message.getText(key, a1, a2, a3);
827 }
828 }
830 public abstract Content newContent();
832 /**
833 * Get the configuration string as a content.
834 *
835 * @param key the key to look for in the configuration file
836 * @return a content tree for the text
837 */
838 public Content getResource(String key) {
839 Content c = newContent();
840 c.addContent(getText(key));
841 return c;
842 }
844 /**
845 * Get the configuration string as a content.
846 *
847 * @param key the key to look for in the configuration file
848 * @param o string or content argument added to configuration text
849 * @return a content tree for the text
850 */
851 public Content getResource(String key, Object o) {
852 return getResource(key, o, null, null);
853 }
855 /**
856 * Get the configuration string as a content.
857 *
858 * @param key the key to look for in the configuration file
859 * @param o string or content argument added to configuration text
860 * @return a content tree for the text
861 */
862 public Content getResource(String key, Object o1, Object o2) {
863 return getResource(key, o1, o2, null);
864 }
866 /**
867 * Get the configuration string as a content.
868 *
869 * @param key the key to look for in the configuration file
870 * @param o1 string or content argument added to configuration text
871 * @param o2 string or content argument added to configuration text
872 * @return a content tree for the text
873 */
874 public Content getResource(String key, Object o0, Object o1, Object o2) {
875 Content c = newContent();
876 Pattern p = Pattern.compile("\\{([012])\\}");
877 String text = getText(key);
878 Matcher m = p.matcher(text);
879 int start = 0;
880 while (m.find(start)) {
881 c.addContent(text.substring(start, m.start()));
883 Object o = null;
884 switch (m.group(1).charAt(0)) {
885 case '0': o = o0; break;
886 case '1': o = o1; break;
887 case '2': o = o2; break;
888 }
890 if (o == null) {
891 c.addContent("{" + m.group(1) + "}");
892 } else if (o instanceof String) {
893 c.addContent((String) o);
894 } else if (o instanceof Content) {
895 c.addContent((Content) o);
896 }
898 start = m.end();
899 }
901 c.addContent(text.substring(start));
902 return c;
903 }
906 /**
907 * Return true if the ClassDoc element is getting documented, depending upon
908 * -nodeprecated option and the deprecation information. Return true if
909 * -nodeprecated is not used. Return false if -nodeprecated is used and if
910 * either ClassDoc element is deprecated or the containing package is deprecated.
911 *
912 * @param cd the ClassDoc for which the page generation is checked
913 */
914 public boolean isGeneratedDoc(ClassDoc cd) {
915 if (!nodeprecated) {
916 return true;
917 }
918 return !(Util.isDeprecated(cd) || Util.isDeprecated(cd.containingPackage()));
919 }
921 /**
922 * Return the doclet specific instance of a writer factory.
923 * @return the {@link WriterFactory} for the doclet.
924 */
925 public abstract WriterFactory getWriterFactory();
927 /**
928 * Return the input stream to the builder XML.
929 *
930 * @return the input steam to the builder XML.
931 * @throws FileNotFoundException when the given XML file cannot be found.
932 */
933 public InputStream getBuilderXML() throws IOException {
934 return builderXMLPath == null ?
935 Configuration.class.getResourceAsStream(DEFAULT_BUILDER_XML) :
936 DocFile.createFileForInput(this, builderXMLPath).openInputStream();
937 }
939 /**
940 * Return the Locale for this document.
941 */
942 public abstract Locale getLocale();
944 /**
945 * Return the current file manager.
946 */
947 public abstract JavaFileManager getFileManager();
949 /**
950 * Return the comparator that will be used to sort member documentation.
951 * To no do any sorting, return null.
952 *
953 * @return the {@link java.util.Comparator} used to sort members.
954 */
955 public abstract Comparator<ProgramElementDoc> getMemberComparator();
957 private void setTabWidth(int n) {
958 sourcetab = n;
959 tabSpaces = String.format("%" + n + "s", "");
960 }
962 public abstract boolean showMessage(SourcePosition pos, String key);
963 }