src/share/classes/com/sun/tools/doclets/internal/toolkit/Configuration.java

Thu, 02 Oct 2008 19:58:40 -0700

author
xdono
date
Thu, 02 Oct 2008 19:58:40 -0700
changeset 117
24a47c3062fe
parent 74
5a9172b251dd
child 140
22c4c1143a3a
permissions
-rw-r--r--

6754988: Update copyright year
Summary: Update for files that have been modified starting July 2008
Reviewed-by: ohair, tbell

duke@1 1 /*
xdono@117 2 * Copyright 1997-2008 Sun Microsystems, Inc. All Rights Reserved.
duke@1 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
duke@1 4 *
duke@1 5 * This code is free software; you can redistribute it and/or modify it
duke@1 6 * under the terms of the GNU General Public License version 2 only, as
duke@1 7 * published by the Free Software Foundation. Sun designates this
duke@1 8 * particular file as subject to the "Classpath" exception as provided
duke@1 9 * by Sun in the LICENSE file that accompanied this code.
duke@1 10 *
duke@1 11 * This code is distributed in the hope that it will be useful, but WITHOUT
duke@1 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@1 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
duke@1 14 * version 2 for more details (a copy is included in the LICENSE file that
duke@1 15 * accompanied this code).
duke@1 16 *
duke@1 17 * You should have received a copy of the GNU General Public License version
duke@1 18 * 2 along with this work; if not, write to the Free Software Foundation,
duke@1 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@1 20 *
duke@1 21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
duke@1 22 * CA 95054 USA or visit www.sun.com if you need additional information or
duke@1 23 * have any questions.
duke@1 24 */
duke@1 25
duke@1 26 package com.sun.tools.doclets.internal.toolkit;
duke@1 27
duke@1 28 import com.sun.tools.doclets.internal.toolkit.taglets.*;
duke@1 29 import com.sun.tools.doclets.internal.toolkit.util.*;
duke@1 30 import com.sun.tools.doclets.internal.toolkit.builders.BuilderFactory;
duke@1 31 import com.sun.javadoc.*;
duke@1 32 import java.util.*;
duke@1 33 import java.io.*;
duke@1 34
duke@1 35 /**
duke@1 36 * Configure the output based on the options. Doclets should sub-class
duke@1 37 * Configuration, to configure and add their own options. This class contains
duke@1 38 * all user options which are supported by the 1.1 doclet and the standard
duke@1 39 * doclet.
duke@1 40 *
duke@1 41 * This code is not part of an API.
duke@1 42 * It is implementation that is subject to change.
duke@1 43 * Do not use it as an API
duke@1 44 *
duke@1 45 * @author Robert Field.
duke@1 46 * @author Atul Dambalkar.
duke@1 47 * @author Jamie Ho
duke@1 48 */
duke@1 49 public abstract class Configuration {
duke@1 50
duke@1 51 /**
duke@1 52 * The factory for builders.
duke@1 53 */
duke@1 54 protected BuilderFactory builderFactory;
duke@1 55
duke@1 56 /**
duke@1 57 * The taglet manager.
duke@1 58 */
duke@1 59 public TagletManager tagletManager;
duke@1 60
duke@1 61 /**
duke@1 62 * The path to the builder XML input file.
duke@1 63 */
duke@1 64 public String builderXMLPath;
duke@1 65
duke@1 66 /**
duke@1 67 * The default path to the builder XML.
duke@1 68 */
duke@1 69 private static final String DEFAULT_BUILDER_XML = "resources/doclet.xml";
duke@1 70
duke@1 71 /**
duke@1 72 * The path to Taglets
duke@1 73 */
duke@1 74 public String tagletpath = "";
duke@1 75
duke@1 76 /**
duke@1 77 * This is true if option "-serialwarn" is used. Defualt value is false to
duke@1 78 * supress excessive warnings about serial tag.
duke@1 79 */
duke@1 80 public boolean serialwarn = false;
duke@1 81
duke@1 82 /**
duke@1 83 * The specified amount of space between tab stops.
duke@1 84 */
duke@1 85 public int sourcetab = DocletConstants.DEFAULT_TAB_STOP_LENGTH;
duke@1 86
duke@1 87 /**
duke@1 88 * True if we should generate browsable sources.
duke@1 89 */
duke@1 90 public boolean linksource = false;
duke@1 91
duke@1 92 /**
duke@1 93 * True if command line option "-nosince" is used. Default value is
duke@1 94 * false.
duke@1 95 */
duke@1 96 public boolean nosince = false;
duke@1 97
duke@1 98 /**
duke@1 99 * True if we should recursively copy the doc-file subdirectories
duke@1 100 */
duke@1 101 public boolean copydocfilesubdirs = false;
duke@1 102
duke@1 103 /**
duke@1 104 * The META charset tag used for cross-platform viewing.
duke@1 105 */
duke@1 106 public String charset = "";
duke@1 107
duke@1 108 /**
duke@1 109 * True if user wants to add member names as meta keywords.
duke@1 110 * Set to false because meta keywords are ignored in general
duke@1 111 * by most Internet search engines.
duke@1 112 */
duke@1 113 public boolean keywords = false;
duke@1 114
duke@1 115 /**
duke@1 116 * The meta tag keywords sole-instance.
duke@1 117 */
duke@1 118 public final MetaKeywords metakeywords = MetaKeywords.getInstance(this);
duke@1 119
duke@1 120 /**
duke@1 121 * The list of doc-file subdirectories to exclude
duke@1 122 */
jjg@74 123 protected Set<String> excludedDocFileDirs;
duke@1 124
duke@1 125 /**
duke@1 126 * The list of qualifiers to exclude
duke@1 127 */
jjg@74 128 protected Set<String> excludedQualifiers;
duke@1 129
duke@1 130 /**
duke@1 131 * The Root of the generated Program Structure from the Doclet API.
duke@1 132 */
duke@1 133 public RootDoc root;
duke@1 134
duke@1 135 /**
duke@1 136 * Destination directory name, in which doclet will generate the entire
duke@1 137 * documentation. Default is current directory.
duke@1 138 */
duke@1 139 public String destDirName = "";
duke@1 140
duke@1 141 /**
duke@1 142 * Destination directory name, in which doclet will copy the doc-files to.
duke@1 143 */
duke@1 144 public String docFileDestDirName = "";
duke@1 145
duke@1 146 /**
duke@1 147 * Encoding for this document. Default is default encoding for this
duke@1 148 * platform.
duke@1 149 */
duke@1 150 public String docencoding = null;
duke@1 151
duke@1 152 /**
duke@1 153 * True if user wants to suppress descriptions and tags.
duke@1 154 */
duke@1 155 public boolean nocomment = false;
duke@1 156
duke@1 157 /**
duke@1 158 * Encoding for this document. Default is default encoding for this
duke@1 159 * platform.
duke@1 160 */
duke@1 161 public String encoding = null;
duke@1 162
duke@1 163 /**
duke@1 164 * Generate author specific information for all the classes if @author
duke@1 165 * tag is used in the doc comment and if -author option is used.
duke@1 166 * <code>showauthor</code> is set to true if -author option is used.
duke@1 167 * Default is don't show author information.
duke@1 168 */
duke@1 169 public boolean showauthor = false;
duke@1 170
duke@1 171 /**
duke@1 172 * Generate version specific information for the all the classes
duke@1 173 * if @version tag is used in the doc comment and if -version option is
duke@1 174 * used. <code>showversion</code> is set to true if -version option is
duke@1 175 * used.Default is don't show version information.
duke@1 176 */
duke@1 177 public boolean showversion = false;
duke@1 178
duke@1 179 /**
duke@1 180 * Sourcepath from where to read the source files. Default is classpath.
duke@1 181 *
duke@1 182 */
duke@1 183 public String sourcepath = "";
duke@1 184
duke@1 185 /**
duke@1 186 * Don't generate deprecated API information at all, if -nodeprecated
duke@1 187 * option is used. <code>nodepracted</code> is set to true if
duke@1 188 * -nodeprecated option is used. Default is generate deprected API
duke@1 189 * information.
duke@1 190 */
duke@1 191 public boolean nodeprecated = false;
duke@1 192
duke@1 193 /**
duke@1 194 * The catalog of classes specified on the command-line
duke@1 195 */
duke@1 196 public ClassDocCatalog classDocCatalog;
duke@1 197
duke@1 198 /**
duke@1 199 * Message Retriever for the doclet, to retrieve message from the resource
duke@1 200 * file for this Configuration, which is common for 1.1 and standard
duke@1 201 * doclets.
duke@1 202 *
duke@1 203 * TODO: Make this private!!!
duke@1 204 */
duke@1 205 public MessageRetriever message = null;
duke@1 206
duke@1 207 /**
duke@1 208 * True if user wants to suppress time stamp in output.
duke@1 209 * Default is false.
duke@1 210 */
duke@1 211 public boolean notimestamp= false;
duke@1 212
duke@1 213 /**
duke@1 214 * The package grouping sole-instance.
duke@1 215 */
duke@1 216 public final Group group = Group.getInstance(this);
duke@1 217
duke@1 218 /**
duke@1 219 * The tracker of external package links (sole-instance).
duke@1 220 */
duke@1 221 public final Extern extern = new Extern(this);
duke@1 222
duke@1 223 /**
duke@1 224 * Return the build date for the doclet.
duke@1 225 */
duke@1 226 public abstract String getDocletSpecificBuildDate();
duke@1 227
duke@1 228 /**
duke@1 229 * This method should be defined in all those doclets(configurations),
duke@1 230 * which want to derive themselves from this Configuration. This method
duke@1 231 * can be used to set its own command line options.
duke@1 232 *
duke@1 233 * @param options The array of option names and values.
duke@1 234 * @throws DocletAbortException
duke@1 235 */
duke@1 236 public abstract void setSpecificDocletOptions(String[][] options);
duke@1 237
duke@1 238 /**
duke@1 239 * Return the doclet specific {@link MessageRetriever}
duke@1 240 * @return the doclet specific MessageRetriever.
duke@1 241 */
duke@1 242 public abstract MessageRetriever getDocletSpecificMsg();
duke@1 243
duke@1 244 /**
duke@1 245 * An array of the packages specified on the command-line merged
duke@1 246 * with the array of packages that contain the classes specified on the
duke@1 247 * command-line. The array is sorted.
duke@1 248 */
duke@1 249 public PackageDoc[] packages;
duke@1 250
duke@1 251 /**
duke@1 252 * Constructor. Constructs the message retriever with resource file.
duke@1 253 */
duke@1 254 public Configuration() {
duke@1 255 message =
duke@1 256 new MessageRetriever(this,
duke@1 257 "com.sun.tools.doclets.internal.toolkit.resources.doclets");
jjg@74 258 excludedDocFileDirs = new HashSet<String>();
jjg@74 259 excludedQualifiers = new HashSet<String>();
duke@1 260 }
duke@1 261
duke@1 262 /**
duke@1 263 * Return the builder factory for this doclet.
duke@1 264 *
duke@1 265 * @return the builder factory for this doclet.
duke@1 266 */
duke@1 267 public BuilderFactory getBuilderFactory() {
duke@1 268 if (builderFactory == null) {
duke@1 269 builderFactory = new BuilderFactory(this);
duke@1 270 }
duke@1 271 return builderFactory;
duke@1 272 }
duke@1 273
duke@1 274 /**
duke@1 275 * This method should be defined in all those doclets
duke@1 276 * which want to inherit from this Configuration. This method
duke@1 277 * should return the number of arguments to the command line
duke@1 278 * option (including the option name). For example,
duke@1 279 * -notimestamp is a single-argument option, so this method would
duke@1 280 * return 1.
duke@1 281 *
duke@1 282 * @param option Command line option under consideration.
duke@1 283 * @return number of arguments to option (including the
duke@1 284 * option name). Zero return means option not known.
duke@1 285 * Negative value means error occurred.
duke@1 286 */
duke@1 287 public int optionLength(String option) {
duke@1 288 option = option.toLowerCase();
duke@1 289 if (option.equals("-author") ||
duke@1 290 option.equals("-docfilessubdirs") ||
duke@1 291 option.equals("-keywords") ||
duke@1 292 option.equals("-linksource") ||
duke@1 293 option.equals("-nocomment") ||
duke@1 294 option.equals("-nodeprecated") ||
duke@1 295 option.equals("-nosince") ||
duke@1 296 option.equals("-notimestamp") ||
duke@1 297 option.equals("-quiet") ||
duke@1 298 option.equals("-xnodate") ||
duke@1 299 option.equals("-version")) {
duke@1 300 return 1;
duke@1 301 } else if (option.equals("-d") ||
duke@1 302 option.equals("-docencoding") ||
duke@1 303 option.equals("-encoding") ||
duke@1 304 option.equals("-excludedocfilessubdir") ||
duke@1 305 option.equals("-link") ||
duke@1 306 option.equals("-sourcetab") ||
duke@1 307 option.equals("-noqualifier") ||
duke@1 308 option.equals("-output") ||
duke@1 309 option.equals("-sourcepath") ||
duke@1 310 option.equals("-tag") ||
duke@1 311 option.equals("-taglet") ||
duke@1 312 option.equals("-tagletpath")) {
duke@1 313 return 2;
duke@1 314 } else if (option.equals("-group") ||
duke@1 315 option.equals("-linkoffline")) {
duke@1 316 return 3;
duke@1 317 } else {
duke@1 318 return -1; // indicate we don't know about it
duke@1 319 }
duke@1 320 }
duke@1 321
duke@1 322 /**
duke@1 323 * Perform error checking on the given options.
duke@1 324 *
duke@1 325 * @param options the given options to check.
duke@1 326 * @param reporter the reporter used to report errors.
duke@1 327 */
duke@1 328 public abstract boolean validOptions(String options[][],
duke@1 329 DocErrorReporter reporter);
duke@1 330
duke@1 331 private void initPackageArray() {
jjg@74 332 Set<PackageDoc> set = new HashSet<PackageDoc>(Arrays.asList(root.specifiedPackages()));
duke@1 333 ClassDoc[] classes = root.specifiedClasses();
duke@1 334 for (int i = 0; i < classes.length; i++) {
duke@1 335 set.add(classes[i].containingPackage());
duke@1 336 }
jjg@74 337 ArrayList<PackageDoc> results = new ArrayList<PackageDoc>(set);
duke@1 338 Collections.sort(results);
jjg@74 339 packages = results.toArray(new PackageDoc[] {});
duke@1 340 }
duke@1 341
duke@1 342 /**
duke@1 343 * Set the command line options supported by this configuration.
duke@1 344 *
duke@1 345 * @param options the two dimensional array of options.
duke@1 346 */
duke@1 347 public void setOptions(String[][] options) {
jjg@74 348 LinkedHashSet<String[]> customTagStrs = new LinkedHashSet<String[]>();
duke@1 349 for (int oi = 0; oi < options.length; ++oi) {
duke@1 350 String[] os = options[oi];
duke@1 351 String opt = os[0].toLowerCase();
duke@1 352 if (opt.equals("-d")) {
duke@1 353 destDirName = addTrailingFileSep(os[1]);
duke@1 354 docFileDestDirName = destDirName;
duke@1 355 } else if (opt.equals("-docfilessubdirs")) {
duke@1 356 copydocfilesubdirs = true;
duke@1 357 } else if (opt.equals("-docencoding")) {
duke@1 358 docencoding = os[1];
duke@1 359 } else if (opt.equals("-encoding")) {
duke@1 360 encoding = os[1];
duke@1 361 } else if (opt.equals("-author")) {
duke@1 362 showauthor = true;
duke@1 363 } else if (opt.equals("-version")) {
duke@1 364 showversion = true;
duke@1 365 } else if (opt.equals("-nodeprecated")) {
duke@1 366 nodeprecated = true;
duke@1 367 } else if (opt.equals("-sourcepath")) {
duke@1 368 sourcepath = os[1];
duke@1 369 } else if (opt.equals("-classpath") &&
duke@1 370 sourcepath.length() == 0) {
duke@1 371 sourcepath = os[1];
duke@1 372 } else if (opt.equals("-excludedocfilessubdir")) {
duke@1 373 addToSet(excludedDocFileDirs, os[1]);
duke@1 374 } else if (opt.equals("-noqualifier")) {
duke@1 375 addToSet(excludedQualifiers, os[1]);
duke@1 376 } else if (opt.equals("-linksource")) {
duke@1 377 linksource = true;
duke@1 378 } else if (opt.equals("-sourcetab")) {
duke@1 379 linksource = true;
duke@1 380 try {
duke@1 381 sourcetab = Integer.parseInt(os[1]);
duke@1 382 } catch (NumberFormatException e) {
duke@1 383 //Set to -1 so that warning will be printed
duke@1 384 //to indicate what is valid argument.
duke@1 385 sourcetab = -1;
duke@1 386 }
duke@1 387 if (sourcetab <= 0) {
duke@1 388 message.warning("doclet.sourcetab_warning");
duke@1 389 sourcetab = DocletConstants.DEFAULT_TAB_STOP_LENGTH;
duke@1 390 }
duke@1 391 } else if (opt.equals("-notimestamp")) {
duke@1 392 notimestamp = true;
duke@1 393 } else if (opt.equals("-nocomment")) {
duke@1 394 nocomment = true;
duke@1 395 } else if (opt.equals("-tag") || opt.equals("-taglet")) {
duke@1 396 customTagStrs.add(os);
duke@1 397 } else if (opt.equals("-tagletpath")) {
duke@1 398 tagletpath = os[1];
duke@1 399 } else if (opt.equals("-keywords")) {
duke@1 400 keywords = true;
duke@1 401 } else if (opt.equals("-serialwarn")) {
duke@1 402 serialwarn = true;
duke@1 403 } else if (opt.equals("-group")) {
duke@1 404 group.checkPackageGroups(os[1], os[2]);
duke@1 405 } else if (opt.equals("-link")) {
duke@1 406 String url = os[1];
duke@1 407 extern.url(url, url, root, false);
duke@1 408 } else if (opt.equals("-linkoffline")) {
duke@1 409 String url = os[1];
duke@1 410 String pkglisturl = os[2];
duke@1 411 extern.url(url, pkglisturl, root, true);
duke@1 412 }
duke@1 413 }
duke@1 414 if (sourcepath.length() == 0) {
duke@1 415 sourcepath = System.getProperty("env.class.path") == null ? "" :
duke@1 416 System.getProperty("env.class.path");
duke@1 417 }
duke@1 418 if (docencoding == null) {
duke@1 419 docencoding = encoding;
duke@1 420 }
duke@1 421
duke@1 422 classDocCatalog = new ClassDocCatalog(root.specifiedClasses());
duke@1 423 initTagletManager(customTagStrs);
duke@1 424 }
duke@1 425
duke@1 426 /**
duke@1 427 * Set the command line options supported by this configuration.
duke@1 428 *
duke@1 429 * @throws DocletAbortException
duke@1 430 */
duke@1 431 public void setOptions() {
duke@1 432 initPackageArray();
duke@1 433 setOptions(root.options());
duke@1 434 setSpecificDocletOptions(root.options());
duke@1 435 }
duke@1 436
duke@1 437
duke@1 438 /**
duke@1 439 * Initialize the taglet manager. The strings to initialize the simple custom tags should
duke@1 440 * be in the following format: "[tag name]:[location str]:[heading]".
duke@1 441 * @param customTagStrs the set two dimentional arrays of strings. These arrays contain
duke@1 442 * either -tag or -taglet arguments.
duke@1 443 */
duke@1 444 private void initTagletManager(Set customTagStrs) {
duke@1 445 tagletManager = tagletManager == null ?
duke@1 446 new TagletManager(nosince, showversion, showauthor, message) :
duke@1 447 tagletManager;
duke@1 448 String[] args;
duke@1 449 for (Iterator it = customTagStrs.iterator(); it.hasNext(); ) {
duke@1 450 args = (String[]) it.next();
duke@1 451 if (args[0].equals("-taglet")) {
duke@1 452 tagletManager.addCustomTag(args[1], tagletpath);
duke@1 453 continue;
duke@1 454 }
duke@1 455 String[] tokens = Util.tokenize(args[1],
duke@1 456 TagletManager.SIMPLE_TAGLET_OPT_SEPERATOR, 3);
duke@1 457 if (tokens.length == 1) {
duke@1 458 String tagName = args[1];
duke@1 459 if (tagletManager.isKnownCustomTag(tagName)) {
duke@1 460 //reorder a standard tag
duke@1 461 tagletManager.addNewSimpleCustomTag(tagName, null, "");
duke@1 462 } else {
duke@1 463 //Create a simple tag with the heading that has the same name as the tag.
duke@1 464 StringBuffer heading = new StringBuffer(tagName + ":");
duke@1 465 heading.setCharAt(0, Character.toUpperCase(tagName.charAt(0)));
duke@1 466 tagletManager.addNewSimpleCustomTag(tagName, heading.toString(), "a");
duke@1 467 }
duke@1 468 } else if (tokens.length == 2) {
duke@1 469 //Add simple taglet without heading, probably to excluding it in the output.
duke@1 470 tagletManager.addNewSimpleCustomTag(tokens[0], tokens[1], "");
duke@1 471 } else if (tokens.length >= 3) {
duke@1 472 tagletManager.addNewSimpleCustomTag(tokens[0], tokens[2], tokens[1]);
duke@1 473 } else {
duke@1 474 message.error("doclet.Error_invalid_custom_tag_argument", args[1]);
duke@1 475 }
duke@1 476 }
duke@1 477 }
duke@1 478
jjg@74 479 private void addToSet(Set<String> s, String str){
duke@1 480 StringTokenizer st = new StringTokenizer(str, ":");
duke@1 481 String current;
duke@1 482 while(st.hasMoreTokens()){
duke@1 483 current = st.nextToken();
duke@1 484 s.add(current);
duke@1 485 }
duke@1 486 }
duke@1 487
duke@1 488 /**
duke@1 489 * Add a traliling file separator, if not found or strip off extra trailing
duke@1 490 * file separators if any.
duke@1 491 *
duke@1 492 * @param path Path under consideration.
duke@1 493 * @return String Properly constructed path string.
duke@1 494 */
duke@1 495 String addTrailingFileSep(String path) {
duke@1 496 String fs = System.getProperty("file.separator");
duke@1 497 String dblfs = fs + fs;
duke@1 498 int indexDblfs;
duke@1 499 while ((indexDblfs = path.indexOf(dblfs)) >= 0) {
duke@1 500 path = path.substring(0, indexDblfs) +
duke@1 501 path.substring(indexDblfs + fs.length());
duke@1 502 }
duke@1 503 if (!path.endsWith(fs))
duke@1 504 path += fs;
duke@1 505 return path;
duke@1 506 }
duke@1 507
duke@1 508 /**
duke@1 509 * This checks for the validity of the options used by the user.
duke@1 510 * This works exactly like
duke@1 511 * {@link com.sun.javadoc.Doclet#validOptions(String[][],
duke@1 512 * DocErrorReporter)}. This will validate the options which are shared
duke@1 513 * by our doclets. For example, this method will flag an error using
duke@1 514 * the DocErrorReporter if user has used "-nohelp" and "-helpfile" option
duke@1 515 * together.
duke@1 516 *
duke@1 517 * @param options options used on the command line.
duke@1 518 * @param reporter used to report errors.
duke@1 519 * @return true if all the options are valid.
duke@1 520 */
duke@1 521 public boolean generalValidOptions(String options[][],
duke@1 522 DocErrorReporter reporter) {
duke@1 523 boolean docencodingfound = false;
duke@1 524 String encoding = "";
duke@1 525 for (int oi = 0; oi < options.length; oi++) {
duke@1 526 String[] os = options[oi];
duke@1 527 String opt = os[0].toLowerCase();
duke@1 528 if (opt.equals("-d")) {
duke@1 529 String destdirname = addTrailingFileSep(os[1]);
duke@1 530 File destDir = new File(destdirname);
duke@1 531 if (!destDir.exists()) {
duke@1 532 //Create the output directory (in case it doesn't exist yet)
duke@1 533 reporter.printNotice(getText("doclet.dest_dir_create",
duke@1 534 destdirname));
duke@1 535 (new File(destdirname)).mkdirs();
duke@1 536 } else if (!destDir.isDirectory()) {
duke@1 537 reporter.printError(getText(
duke@1 538 "doclet.destination_directory_not_directory_0",
duke@1 539 destDir.getPath()));
duke@1 540 return false;
duke@1 541 } else if (!destDir.canWrite()) {
duke@1 542 reporter.printError(getText(
duke@1 543 "doclet.destination_directory_not_writable_0",
duke@1 544 destDir.getPath()));
duke@1 545 return false;
duke@1 546 }
duke@1 547 } else if (opt.equals("-docencoding")) {
duke@1 548 docencodingfound = true;
duke@1 549 if (!checkOutputFileEncoding(os[1], reporter)) {
duke@1 550 return false;
duke@1 551 }
duke@1 552 } else if (opt.equals("-encoding")) {
duke@1 553 encoding = os[1];
duke@1 554 }
duke@1 555 }
duke@1 556 if (!docencodingfound && encoding.length() > 0) {
duke@1 557 if (!checkOutputFileEncoding(encoding, reporter)) {
duke@1 558 return false;
duke@1 559 }
duke@1 560 }
duke@1 561 return true;
duke@1 562 }
duke@1 563
duke@1 564 /**
duke@1 565 * Check the validity of the given Source or Output File encoding on this
duke@1 566 * platform.
duke@1 567 *
duke@1 568 * @param docencoding output file encoding.
duke@1 569 * @param reporter used to report errors.
duke@1 570 */
duke@1 571 private boolean checkOutputFileEncoding(String docencoding,
duke@1 572 DocErrorReporter reporter) {
duke@1 573 OutputStream ost= new ByteArrayOutputStream();
duke@1 574 OutputStreamWriter osw = null;
duke@1 575 try {
duke@1 576 osw = new OutputStreamWriter(ost, docencoding);
duke@1 577 } catch (UnsupportedEncodingException exc) {
duke@1 578 reporter.printError(getText("doclet.Encoding_not_supported",
duke@1 579 docencoding));
duke@1 580 return false;
duke@1 581 } finally {
duke@1 582 try {
duke@1 583 if (osw != null) {
duke@1 584 osw.close();
duke@1 585 }
duke@1 586 } catch (IOException exc) {
duke@1 587 }
duke@1 588 }
duke@1 589 return true;
duke@1 590 }
duke@1 591
duke@1 592 /**
duke@1 593 * Return true if the given doc-file subdirectory should be excluded and
duke@1 594 * false otherwise.
duke@1 595 * @param docfilesubdir the doc-files subdirectory to check.
duke@1 596 */
duke@1 597 public boolean shouldExcludeDocFileDir(String docfilesubdir){
duke@1 598 if (excludedDocFileDirs.contains(docfilesubdir)) {
duke@1 599 return true;
duke@1 600 } else {
duke@1 601 return false;
duke@1 602 }
duke@1 603 }
duke@1 604
duke@1 605 /**
duke@1 606 * Return true if the given qualifier should be excluded and false otherwise.
duke@1 607 * @param qualifier the qualifier to check.
duke@1 608 */
duke@1 609 public boolean shouldExcludeQualifier(String qualifier){
duke@1 610 if (excludedQualifiers.contains("all") ||
duke@1 611 excludedQualifiers.contains(qualifier) ||
duke@1 612 excludedQualifiers.contains(qualifier + ".*")) {
duke@1 613 return true;
duke@1 614 } else {
duke@1 615 int index = -1;
duke@1 616 while ((index = qualifier.indexOf(".", index + 1)) != -1) {
duke@1 617 if (excludedQualifiers.contains(qualifier.substring(0, index + 1) + "*")) {
duke@1 618 return true;
duke@1 619 }
duke@1 620 }
duke@1 621 return false;
duke@1 622 }
duke@1 623 }
duke@1 624
duke@1 625 /**
duke@1 626 * Return the qualified name of the <code>ClassDoc</code> if it's qualifier is not excluded. Otherwise,
duke@1 627 * return the unqualified <code>ClassDoc</code> name.
duke@1 628 * @param cd the <code>ClassDoc</code> to check.
duke@1 629 */
duke@1 630 public String getClassName(ClassDoc cd) {
duke@1 631 PackageDoc pd = cd.containingPackage();
duke@1 632 if (pd != null && shouldExcludeQualifier(cd.containingPackage().name())) {
duke@1 633 return cd.name();
duke@1 634 } else {
duke@1 635 return cd.qualifiedName();
duke@1 636 }
duke@1 637 }
duke@1 638
duke@1 639 public String getText(String key) {
duke@1 640 try {
duke@1 641 //Check the doclet specific properties file.
duke@1 642 return getDocletSpecificMsg().getText(key);
duke@1 643 } catch (Exception e) {
duke@1 644 //Check the shared properties file.
duke@1 645 return message.getText(key);
duke@1 646 }
duke@1 647 }
duke@1 648
duke@1 649 public String getText(String key, String a1) {
duke@1 650 try {
duke@1 651 //Check the doclet specific properties file.
duke@1 652 return getDocletSpecificMsg().getText(key, a1);
duke@1 653 } catch (Exception e) {
duke@1 654 //Check the shared properties file.
duke@1 655 return message.getText(key, a1);
duke@1 656 }
duke@1 657 }
duke@1 658
duke@1 659 public String getText(String key, String a1, String a2) {
duke@1 660 try {
duke@1 661 //Check the doclet specific properties file.
duke@1 662 return getDocletSpecificMsg().getText(key, a1, a2);
duke@1 663 } catch (Exception e) {
duke@1 664 //Check the shared properties file.
duke@1 665 return message.getText(key, a1, a2);
duke@1 666 }
duke@1 667 }
duke@1 668
duke@1 669 public String getText(String key, String a1, String a2, String a3) {
duke@1 670 try {
duke@1 671 //Check the doclet specific properties file.
duke@1 672 return getDocletSpecificMsg().getText(key, a1, a2, a3);
duke@1 673 } catch (Exception e) {
duke@1 674 //Check the shared properties file.
duke@1 675 return message.getText(key, a1, a2, a3);
duke@1 676 }
duke@1 677 }
duke@1 678
duke@1 679 /**
duke@1 680 * Return true if the doc element is getting documented, depending upon
duke@1 681 * -nodeprecated option and @deprecated tag used. Return true if
duke@1 682 * -nodeprecated is not used or @deprecated tag is not used.
duke@1 683 */
duke@1 684 public boolean isGeneratedDoc(Doc doc) {
duke@1 685 if (!nodeprecated) {
duke@1 686 return true;
duke@1 687 }
duke@1 688 return (doc.tags("deprecated")).length == 0;
duke@1 689 }
duke@1 690
duke@1 691 /**
duke@1 692 * Return the doclet specific instance of a writer factory.
duke@1 693 * @return the {@link WriterFactory} for the doclet.
duke@1 694 */
duke@1 695 public abstract WriterFactory getWriterFactory();
duke@1 696
duke@1 697 /**
duke@1 698 * Return the input stream to the builder XML.
duke@1 699 *
duke@1 700 * @return the input steam to the builder XML.
duke@1 701 * @throws FileNotFoundException when the given XML file cannot be found.
duke@1 702 */
duke@1 703 public InputStream getBuilderXML() throws FileNotFoundException {
duke@1 704 return builderXMLPath == null ?
duke@1 705 Configuration.class.getResourceAsStream(DEFAULT_BUILDER_XML) :
duke@1 706 new FileInputStream(new File(builderXMLPath));
duke@1 707 }
duke@1 708
duke@1 709 /**
duke@1 710 * Return the comparator that will be used to sort member documentation.
duke@1 711 * To no do any sorting, return null.
duke@1 712 *
duke@1 713 * @return the {@link java.util.Comparator} used to sort members.
duke@1 714 */
jjg@74 715 public abstract Comparator<ProgramElementDoc> getMemberComparator();
duke@1 716 }

mercurial