jdk8-mips64-public/langtools: src/share/classes/com/sun/tools/javadoc/Start.java@019063968164

     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.javadoc;

    28 import java.io.File;

    29 import java.io.FileNotFoundException;

    30 import java.io.IOException;

    31 import java.io.PrintWriter;

    32 import java.util.ArrayList;

    33 import java.util.Collection;

    34 import java.util.Collections;

    36 import javax.tools.JavaFileManager;

    37 import javax.tools.JavaFileObject;

    39 import com.sun.javadoc.*;

    40 import com.sun.tools.javac.main.CommandLine;

    41 import com.sun.tools.javac.util.ClientCodeException;

    42 import com.sun.tools.javac.util.Context;

    43 import com.sun.tools.javac.util.List;

    44 import com.sun.tools.javac.util.ListBuffer;

    45 import com.sun.tools.javac.util.Log;

    46 import com.sun.tools.javac.util.Options;

    47 import static com.sun.tools.javac.code.Flags.*;

    49 /**

    50  * Main program of Javadoc.

    51  * Previously named "Main".

    52  *

    53  *  <p><b>This is NOT part of any supported API.

    54  *  If you write code that depends on this, you do so at your own risk.

    55  *  This code and its internal interfaces are subject to change or

    56  *  deletion without notice.</b>

    57  *

    58  * @since 1.2

    59  * @author Robert Field

    60  * @author Neal Gafter (rewrite)

    61  */

    62 public class Start extends ToolOption.Helper {

    63     /** Context for this invocation. */

    64     private final Context context;

    66     private final String defaultDocletClassName;

    67     private final ClassLoader docletParentClassLoader;

    69     private static final String javadocName = "javadoc";

    71     private static final String standardDocletClassName =

    72         "com.sun.tools.doclets.standard.Standard";

    74     private long defaultFilter = PUBLIC | PROTECTED;

    76     private final Messager messager;

    78     private DocletInvoker docletInvoker;

    80     /**

    81      * In API mode, exceptions thrown while calling the doclet are

    82      * propagated using ClientCodeException.

    83      */

    84     private boolean apiMode;

    86     Start(String programName,

    87           PrintWriter errWriter,

    88           PrintWriter warnWriter,

    89           PrintWriter noticeWriter,

    90           String defaultDocletClassName) {

    91         this(programName, errWriter, warnWriter, noticeWriter, defaultDocletClassName, null);

    92     }

    94     Start(String programName,

    95           PrintWriter errWriter,

    96           PrintWriter warnWriter,

    97           PrintWriter noticeWriter,

    98           String defaultDocletClassName,

    99           ClassLoader docletParentClassLoader) {

   100         context = new Context();

   101         messager = new Messager(context, programName, errWriter, warnWriter, noticeWriter);

   102         this.defaultDocletClassName = defaultDocletClassName;

   103         this.docletParentClassLoader = docletParentClassLoader;

   104     }

   106     Start(String programName, String defaultDocletClassName) {

   107         this(programName, defaultDocletClassName, null);

   108     }

   110     Start(String programName, String defaultDocletClassName,

   111           ClassLoader docletParentClassLoader) {

   112         context = new Context();

   113         messager = new Messager(context, programName);

   114         this.defaultDocletClassName = defaultDocletClassName;

   115         this.docletParentClassLoader = docletParentClassLoader;

   116     }

   118     Start(String programName, ClassLoader docletParentClassLoader) {

   119         this(programName, standardDocletClassName, docletParentClassLoader);

   120     }

   122     Start(String programName) {

   123         this(programName, standardDocletClassName);

   124     }

   126     Start(ClassLoader docletParentClassLoader) {

   127         this(javadocName, docletParentClassLoader);

   128     }

   130     Start() {

   131         this(javadocName);

   132     }

   134     public Start(Context context) {

   135         context.getClass(); // null check

   136         this.context = context;

   137         apiMode = true;

   138         defaultDocletClassName = standardDocletClassName;

   139         docletParentClassLoader = null;

   141         Log log = context.get(Log.logKey);

   142         if (log instanceof Messager)

   143             messager = (Messager) log;

   144         else {

   145             PrintWriter out = context.get(Log.outKey);

   146             messager = (out == null) ? new Messager(context, javadocName)

   147                     : new Messager(context, javadocName, out, out, out);

   148         }

   149     }

   151     /**

   152      * Usage

   153      */

   154     @Override

   155     void usage() {

   156         usage(true);

   157     }

   159     void usage(boolean exit) {

   160         usage("main.usage", "-help", null, exit);

   161     }

   163     @Override

   164     void Xusage() {

   165         Xusage(true);

   166     }

   168     void Xusage(boolean exit) {

   169         usage("main.Xusage", "-X", "main.Xusage.foot", exit);

   170     }

   172     private void usage(String main, String doclet, String foot, boolean exit) {

   173         // RFE: it would be better to replace the following with code to

   174         // write a header, then help for each option, then a footer.

   175         messager.notice(main);

   177         // let doclet print usage information (does nothing on error)

   178         if (docletInvoker != null) {

   179             // RFE: this is a pretty bad way to get the doclet to show

   180             // help info. Moreover, the output appears on stdout,

   181             // and <i>not</i> on any of the standard streams passed

   182             // to javadoc, and in particular, not to the noticeWriter

   183             // But, to fix this, we need to fix the Doclet API.

   184             docletInvoker.optionLength(doclet);

   185         }

   187         if (foot != null)

   188             messager.notice(foot);

   190         if (exit) exit();

   191     }

   193     /**

   194      * Exit

   195      */

   196     private void exit() {

   197         messager.exit();

   198     }

   201     /**

   202      * Main program - external wrapper

   203      */

   204     int begin(String... argv) {

   205         boolean ok = begin(null, argv, Collections.<JavaFileObject> emptySet());

   206         return ok ? 0 : 1;

   207     }

   209     public boolean begin(Class<?> docletClass, Iterable<String> options, Iterable<? extends JavaFileObject> fileObjects) {

   210         Collection<String> opts = new ArrayList<String>();

   211         for (String opt: options) opts.add(opt);

   212         return begin(docletClass, opts.toArray(new String[opts.size()]), fileObjects);

   213     }

   215     private boolean begin(Class<?> docletClass, String[] options, Iterable<? extends JavaFileObject> fileObjects) {

   216         boolean failed = false;

   218         try {

   219             failed = !parseAndExecute(docletClass, options, fileObjects);

   220         } catch (Messager.ExitJavadoc exc) {

   221             // ignore, we just exit this way

   222         } catch (OutOfMemoryError ee) {

   223             messager.error(Messager.NOPOS, "main.out.of.memory");

   224             failed = true;

   225         } catch (ClientCodeException e) {

   226             // simply rethrow these exceptions, to be caught and handled by JavadocTaskImpl

   227             throw e;

   228         } catch (Error ee) {

   229             ee.printStackTrace(System.err);

   230             messager.error(Messager.NOPOS, "main.fatal.error");

   231             failed = true;

   232         } catch (Exception ee) {

   233             ee.printStackTrace(System.err);

   234             messager.error(Messager.NOPOS, "main.fatal.exception");

   235             failed = true;

   236         } finally {

   237             messager.exitNotice();

   238             messager.flush();

   239         }

   240         failed |= messager.nerrors() > 0;

   241         failed |= rejectWarnings && messager.nwarnings() > 0;

   242         return !failed;

   243     }

   245     /**

   246      * Main program - internal

   247      */

   248     private boolean parseAndExecute(

   249             Class<?> docletClass,

   250             String[] argv,

   251             Iterable<? extends JavaFileObject> fileObjects) throws IOException {

   252         long tm = System.currentTimeMillis();

   254         ListBuffer<String> javaNames = new ListBuffer<String>();

   256         // Preprocess @file arguments

   257         try {

   258             argv = CommandLine.parse(argv);

   259         } catch (FileNotFoundException e) {

   260             messager.error(Messager.NOPOS, "main.cant.read", e.getMessage());

   261             exit();

   262         } catch (IOException e) {

   263             e.printStackTrace(System.err);

   264             exit();

   265         }

   268         JavaFileManager fileManager = context.get(JavaFileManager.class);

   269         setDocletInvoker(docletClass, fileManager, argv);

   271         compOpts = Options.instance(context);

   273         // Parse arguments

   274         for (int i = 0 ; i < argv.length ; i++) {

   275             String arg = argv[i];

   277             ToolOption o = ToolOption.get(arg);

   278             if (o != null) {

   279                 // hack: this restriction should be removed

   280                 if (o == ToolOption.LOCALE && i > 0)

   281                     usageError("main.locale_first");

   283                 if (o.hasArg) {

   284                     oneArg(argv, i++);

   285                     o.process(this, argv[i]);

   286                 } else {

   287                     setOption(arg);

   288                     o.process(this);

   289                 }

   291             } else if (arg.startsWith("-XD")) {

   292                 // hidden javac options

   293                 String s = arg.substring("-XD".length());

   294                 int eq = s.indexOf('=');

   295                 String key = (eq < 0) ? s : s.substring(0, eq);

   296                 String value = (eq < 0) ? s : s.substring(eq+1);

   297                 compOpts.put(key, value);

   298             }

   299             // call doclet for its options

   300             // other arg starts with - is invalid

   301             else if (arg.startsWith("-")) {

   302                 int optionLength;

   303                 optionLength = docletInvoker.optionLength(arg);

   304                 if (optionLength < 0) {

   305                     // error already displayed

   306                     exit();

   307                 } else if (optionLength == 0) {

   308                     // option not found

   309                     usageError("main.invalid_flag", arg);

   310                 } else {

   311                     // doclet added option

   312                     if ((i + optionLength) > argv.length) {

   313                         usageError("main.requires_argument", arg);

   314                     }

   315                     ListBuffer<String> args = new ListBuffer<String>();

   316                     for (int j = 0; j < optionLength-1; ++j) {

   317                         args.append(argv[++i]);

   318                     }

   319                     setOption(arg, args.toList());

   320                 }

   321             } else {

   322                 javaNames.append(arg);

   323             }

   324         }

   325         compOpts.notifyListeners();

   327         if (javaNames.isEmpty() && subPackages.isEmpty() && isEmpty(fileObjects)) {

   328             usageError("main.No_packages_or_classes_specified");

   329         }

   331         if (!docletInvoker.validOptions(options.toList())) {

   332             // error message already displayed

   333             exit();

   334         }

   336         JavadocTool comp = JavadocTool.make0(context);

   337         if (comp == null) return false;

   339         if (showAccess == null) {

   340             setFilter(defaultFilter);

   341         }

   343         LanguageVersion languageVersion = docletInvoker.languageVersion();

   344         RootDocImpl root = comp.getRootDocImpl(

   345                 docLocale,

   346                 encoding,

   347                 showAccess,

   348                 javaNames.toList(),

   349                 options.toList(),

   350                 fileObjects,

   351                 breakiterator,

   352                 subPackages.toList(),

   353                 excludedPackages.toList(),

   354                 docClasses,

   355                 // legacy?

   356                 languageVersion == null || languageVersion == LanguageVersion.JAVA_1_1,

   357                 quiet);

   359         // release resources

   360         comp = null;

   362         // pass off control to the doclet

   363         boolean ok = root != null;

   364         if (ok) ok = docletInvoker.start(root);

   366         // We're done.

   367         if (compOpts.get("-verbose") != null) {

   368             tm = System.currentTimeMillis() - tm;

   369             messager.notice("main.done_in", Long.toString(tm));

   370         }

   372         return ok;

   373     }

   375     private <T> boolean isEmpty(Iterable<T> iter) {

   376         return !iter.iterator().hasNext();

   377     }

   379     /**

   380      * Init the doclet invoker.

   381      * The doclet class may be given explicitly, or via the -doclet option in

   382      * argv.

   383      * If the doclet class is not given explicitly, it will be loaded from

   384      * the file manager's DOCLET_PATH location, if available, or via the

   385      * -doclet path option in argv.

   386      * @param docletClass The doclet class. May be null.

   387      * @param fileManager The file manager used to get the class loader to load

   388      * the doclet class if required. May be null.

   389      * @param argv Args containing -doclet and -docletpath, in case they are required.

   390      */

   391     private void setDocletInvoker(Class<?> docletClass, JavaFileManager fileManager, String[] argv) {

   392         if (docletClass != null) {

   393             docletInvoker = new DocletInvoker(messager, docletClass, apiMode);

   394             // TODO, check no -doclet, -docletpath

   395             return;

   396         }

   398         String docletClassName = null;

   399         String docletPath = null;

   401         // Parse doclet specifying arguments

   402         for (int i = 0 ; i < argv.length ; i++) {

   403             String arg = argv[i];

   404             if (arg.equals(ToolOption.DOCLET.opt)) {

   405                 oneArg(argv, i++);

   406                 if (docletClassName != null) {

   407                     usageError("main.more_than_one_doclet_specified_0_and_1",

   408                                docletClassName, argv[i]);

   409                 }

   410                 docletClassName = argv[i];

   411             } else if (arg.equals(ToolOption.DOCLETPATH.opt)) {

   412                 oneArg(argv, i++);

   413                 if (docletPath == null) {

   414                     docletPath = argv[i];

   415                 } else {

   416                     docletPath += File.pathSeparator + argv[i];

   417                 }

   418             }

   419         }

   421         if (docletClassName == null) {

   422             docletClassName = defaultDocletClassName;

   423         }

   425         // attempt to find doclet

   426         docletInvoker = new DocletInvoker(messager, fileManager,

   427                 docletClassName, docletPath,

   428                 docletParentClassLoader,

   429                 apiMode);

   430     }

   432     /**

   433      * Set one arg option.

   434      * Error and exit if one argument is not provided.

   435      */

   436     private void oneArg(String[] args, int index) {

   437         if ((index + 1) < args.length) {

   438             setOption(args[index], args[index+1]);

   439         } else {

   440             usageError("main.requires_argument", args[index]);

   441         }

   442     }

   444     @Override

   445     void usageError(String key, Object... args) {

   446         messager.error(Messager.NOPOS, key, args);

   447         usage(true);

   448     }

   450     /**

   451      * indicate an option with no arguments was given.

   452      */

   453     private void setOption(String opt) {

   454         String[] option = { opt };

   455         options.append(option);

   456     }

   458     /**

   459      * indicate an option with one argument was given.

   460      */

   461     private void setOption(String opt, String argument) {

   462         String[] option = { opt, argument };

   463         options.append(option);

   464     }

   466     /**

   467      * indicate an option with the specified list of arguments was given.

   468      */

   469     private void setOption(String opt, List<String> arguments) {

   470         String[] args = new String[arguments.length() + 1];

   471         int k = 0;

   472         args[k++] = opt;

   473         for (List<String> i = arguments; i.nonEmpty(); i=i.tail) {

   474             args[k++] = i.head;

   475         }

   476         options.append(args);

   477     }

   478 }

Mercurial > jdk8-mips64-public > langtools / file revision

src/share/classes/com/sun/tools/javadoc/Start.java@019063968164

src/share/classes/com/sun/tools/javadoc/Start.java