Java > Open Source Codes > org > apache > tools > ant > taskdefs > Javadoc


1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one or more
3  * contributor license agreements. See the NOTICE file distributed with
4  * this work for additional information regarding copyright ownership.
5  * The ASF licenses this file to You under the Apache License, Version 2.0
6  * (the "License"); you may not use this file except in compliance with
7  * the License. You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  *
17  */
18 package org.apache.tools.ant.taskdefs;
19
20 import java.io.File ;
21 import java.io.FileWriter ;
22 import java.io.FilenameFilter ;
23 import java.io.IOException ;
24 import java.io.PrintWriter ;
25 import java.io.BufferedReader ;
26 import java.io.FileReader ;
27 import java.net.MalformedURLException ;
28 import java.net.URL ;
29 import java.util.ArrayList ;
30 import java.util.Enumeration ;
31 import java.util.Iterator ;
32 import java.util.Locale ;
33 import java.util.StringTokenizer ;
34 import java.util.Vector ;
35 import org.apache.tools.ant.BuildException;
36 import org.apache.tools.ant.DirectoryScanner;
37 import org.apache.tools.ant.MagicNames;
38 import org.apache.tools.ant.Project;
39 import org.apache.tools.ant.ProjectComponent;
40 import org.apache.tools.ant.Task;
41 import org.apache.tools.ant.types.Commandline;
42 import org.apache.tools.ant.types.DirSet;
43 import org.apache.tools.ant.types.EnumeratedAttribute;
44 import org.apache.tools.ant.types.FileSet;
45 import org.apache.tools.ant.types.Path;
46 import org.apache.tools.ant.types.PatternSet;
47 import org.apache.tools.ant.types.Reference;
48 import org.apache.tools.ant.types.ResourceCollection;
49 import org.apache.tools.ant.types.resources.FileResource;
50 import org.apache.tools.ant.util.FileUtils;
51 import org.apache.tools.ant.util.JavaEnvUtils;
52
53 /**
54  * Generates Javadoc documentation for a collection
55  * of source code.
56  *
57  * <p>Current known limitations are:
58  *
59  * <p><ul>
60  * <li>patterns must be of the form "xxx.*", every other pattern doesn't
61  * work.
62  * <li>there is no control on arguments sanity since they are left
63  * to the Javadoc implementation.
64  * </ul>
65  *
66  * <p>If no <code>doclet</code> is set, then the <code>version</code> and
67  * <code>author</code> are by default <code>"yes"</code>.
68  *
69  * <p>Note: This task is run on another VM because the Javadoc code calls
70  * <code>System.exit()</code> which would break Ant functionality.
71  *
72  * @since Ant 1.1
73  *
74  * @ant.task category="java"
75  */
76 public class Javadoc extends Task {
77     /**
78      * Inner class used to manage doclet parameters.
79      */
80     public class DocletParam {
81         /** The parameter name */
82         private String name;
83
84         /** The parameter value */
85         private String value;
86
87         /**
88          * Set the name of the parameter.
89          *
90          * @param name the name of the doclet parameter
91          */
92         public void setName(String name) {
93             this.name = name;
94         }
95
96         /**
97          * Get the parameter name.
98          *
99          * @return the parameter's name.
100          */
101         public String getName() {
102             return name;
103         }
104
105         /**
106          * Set the parameter value.
107          *
108          * Note that only string values are supported. No resolution of file
109          * paths is performed.
110          *
111          * @param value the parameter value.
112          */
113         public void setValue(String value) {
114             this.value = value;
115         }
116
117         /**
118          * Get the parameter value.
119          *
120          * @return the parameter value.
121          */
122         public String getValue() {
123             return value;
124         }
125     }
126
127     /**
128      * A project aware class used for Javadoc extensions which take a name
129      * and a path such as doclet and taglet arguments.
130      *
131      */
132     public static class ExtensionInfo extends ProjectComponent {
133         /** The name of the extension */
134         private String name;
135
136         /** The optional path to use to load the extension */
137         private Path path;
138
139         /**
140          * Set the name of the extension
141          *
142          * @param name the extension's name.
143          */
144         public void setName(String name) {
145             this.name = name;
146         }
147
148         /**
149          * Get the name of the extension.
150          *
151          * @return the extension's name.
152          */
153         public String getName() {
154             return name;
155         }
156
157         /**
158          * Set the path to use when loading the component.
159          *
160          * @param path a Path instance containing the classpath to use.
161          */
162         public void setPath(Path path) {
163             if (this.path == null) {
164                 this.path = path;
165             } else {
166                 this.path.append(path);
167             }
168         }
169
170         /**
171          * Get the extension's path.
172          *
173          * @return the path to be used to load the extension.
174          * May be <code>null</code>
175          */
176         public Path getPath() {
177             return path;
178         }
179
180         /**
181          * Create an empty nested path to be configured by Ant with the
182          * classpath for the extension.
183          *
184          * @return a new Path instance to be configured.
185          */
186         public Path createPath() {
187             if (path == null) {
188                 path = new Path(getProject());
189             }
190             return path.createPath();
191         }
192
193         /**
194          * Adds a reference to a CLASSPATH defined elsewhere.
195          *
196          * @param r the reference containing the path.
197          */
198         public void setPathRef(Reference r) {
199             createPath().setRefid(r);
200         }
201     }
202
203     /**
204      * This class stores info about doclets.
205      *
206      */
207     public class DocletInfo extends ExtensionInfo {
208
209         /** Collection of doclet parameters. */
210         private Vector params = new Vector ();
211
212         /**
213          * Create a doclet parameter to be configured by Ant.
214          *
215          * @return a new DocletParam instance to be configured.
216          */
217         public DocletParam createParam() {
218             DocletParam param = new DocletParam();
219             params.addElement(param);
220
221             return param;
222         }
223
224         /**
225          * Get the doclet's parameters.
226          *
227          * @return an Enumeration of DocletParam instances.
228          */
229         public Enumeration getParams() {
230             return params.elements();
231         }
232     }
233
234     /**
235      * Used to track info about the packages to be javadoc'd
236      */
237     public static class PackageName {
238         /** The package name */
239         private String name;
240
241         /**
242          * Set the name of the package
243          *
244          * @param name the package name.
245          */
246         public void setName(String name) {
247             this.name = name.trim();
248         }
249
250         /**
251          * Get the package name.
252          *
253          * @return the package's name.
254          */
255         public String getName() {
256             return name;
257         }
258
259         /**
260          * Return a string rep for this object.
261          * @return the package name.
262          */
263         public String toString() {
264             return getName();
265         }
266     }
267
268     /**
269      * This class is used to manage the source files to be processed.
270      */
271     public static class SourceFile {
272         /** The source file */
273         private File file;
274
275         /**
276          * Default constructor
277          */
278         public SourceFile() {
279             //empty
280 }
281
282         /**
283          * Constructor specifying the source file directly
284          *
285          * @param file the source file
286          */
287         public SourceFile(File file) {
288             this.file = file;
289         }
290
291         /**
292          * Set the source file.
293          *
294          * @param file the source file.
295          */
296         public void setFile(File file) {
297             this.file = file;
298         }
299
300         /**
301          * Get the source file.
302          *
303          * @return the source file.
304          */
305         public File getFile() {
306             return file;
307         }
308     }
309
310     /**
311      * An HTML element in the Javadoc.
312      *
313      * This class is used for those Javadoc elements which contain HTML such as
314      * footers, headers, etc.
315      */
316     public static class Html {
317         /** The text for the element */
318         private StringBuffer text = new StringBuffer ();
319
320         /**
321          * Add text to the element.
322          *
323          * @param t the text to be added.
324          */
325         public void addText(String t) {
326             text.append(t);
327         }
328
329         /**
330          * Get the current text for the element.
331          *
332          * @return the current text.
333          */
334         public String getText() {
335             return text.substring(0);
336         }
337     }
338
339     /**
340      * EnumeratedAttribute implementation supporting the Javadoc scoping
341      * values.
342      */
343     public static class AccessType extends EnumeratedAttribute {
344         /**
345          * @return the allowed values for the access type.
346          */
347         public String [] getValues() {
348             // Protected first so if any GUI tool offers a default
349 // based on enum #0, it will be right.
350 return new String [] {"protected", "public", "package", "private"};
351         }
352     }
353
354     /**
355      * Holds a collection of ResourceCollections.
356      *
357      * <p>A separate kind of container is needed since this task
358      * contains special handling for FileSets that has to occur at
359      * task runtime.</p>
360      */
361     public class ResourceCollectionContainer {
362         private ArrayList rcs = new ArrayList ();
363         /**
364          * Add a resource collection to the container.
365          * @param rc the collection to add.
366          */
367         public void add(ResourceCollection rc) {
368             rcs.add(rc);
369         }
370
371         /**
372          * Get an iterator on the collection.
373          * @return an iterator.
374          */
375         private Iterator iterator() {
376             return rcs.iterator();
377         }
378     }
379
380     private static final FileUtils FILE_UTILS = FileUtils.getFileUtils();
381
382     /** The command line built to execute Javadoc. */
383     private Commandline cmd = new Commandline();
384
385     /**
386      * Utility method to add an argument to the command line conditionally
387      * based on the given flag.
388      *
389      * @param b the flag which controls if the argument is added.
390      * @param arg the argument value.
391      */
392     private void addArgIf(boolean b, String arg) {
393         if (b) {
394             cmd.createArgument().setValue(arg);
395         }
396     }
397
398     /**
399      * Utility method to add a Javadoc argument.
400      *
401      * @param key the argument name.
402      * @param value the argument value.
403      */
404     private void addArgIfNotEmpty(String key, String value) {
405         if (value != null && value.length() != 0) {
406             cmd.createArgument().setValue(key);
407             cmd.createArgument().setValue(value);
408         } else {
409             log("Warning: Leaving out empty argument '" + key + "'",
410                 Project.MSG_WARN);
411         }
412     }
413
414     /**
415      * Flag which indicates if the task should fail if there is a
416      * Javadoc error.
417      */
418     private boolean failOnError = false;
419     private Path sourcePath = null;
420     private File destDir = null;
421     private Vector sourceFiles = new Vector ();
422     private Vector packageNames = new Vector ();
423     private Vector excludePackageNames = new Vector (1);
424     private boolean author = true;
425     private boolean version = true;
426     private DocletInfo doclet = null;
427     private Path classpath = null;
428     private Path bootclasspath = null;
429     private String group = null;
430     private String packageList = null;
431     private Vector links = new Vector ();
432     private Vector groups = new Vector ();
433     private Vector tags = new Vector ();
434     private boolean useDefaultExcludes = true;
435     private Html doctitle = null;
436     private Html header = null;
437     private Html footer = null;
438     private Html bottom = null;
439     private boolean useExternalFile = false;
440     private String source = null;
441     private boolean linksource = false;
442     private boolean breakiterator = false;
443     private String noqualifier;
444     private boolean includeNoSourcePackages = false;
445     private boolean old = false;
446     private String executable = null;
447
448     private ResourceCollectionContainer nestedSourceFiles
449         = new ResourceCollectionContainer();
450     private Vector packageSets = new Vector ();
451
452     /**
453      * Work around command line length limit by using an external file
454      * for the sourcefiles.
455      *
456      * @param b true if an external file is to be used.
457      */
458     public void setUseExternalFile(boolean b) {
459         useExternalFile = b;
460     }
461
462     /**
463      * Sets whether default exclusions should be used or not.
464      *
465      * @param useDefaultExcludes "true"|"on"|"yes" when default exclusions
466      * should be used, "false"|"off"|"no" when they
467      * shouldn't be used.
468      */
469     public void setDefaultexcludes(boolean useDefaultExcludes) {
470         this.useDefaultExcludes = useDefaultExcludes;
471     }
472
473     /**
474      * Set the maximum memory to be used by the javadoc process
475      *
476      * @param max a string indicating the maximum memory according to the
477      * JVM conventions (e.g. 128m is 128 Megabytes)
478      */
479     public void setMaxmemory(String max) {
480         cmd.createArgument().setValue("-J-Xmx" + max);
481     }
482
483     /**
484      * Set an additional parameter on the command line
485      *
486      * @param add the additional command line parameter for the javadoc task.
487      */
488     public void setAdditionalparam(String add) {
489         cmd.createArgument().setLine(add);
490     }
491
492     /**
493      * Adds a command-line argument.
494      * @return a command-line argument to configure
495      * @since Ant 1.6
496      */
497     public Commandline.Argument createArg() {
498         return cmd.createArgument();
499     }
500
501     /**
502      * Specify where to find source file
503      *
504      * @param src a Path instance containing the various source directories.
505      */
506     public void setSourcepath(Path src) {
507         if (sourcePath == null) {
508             sourcePath = src;
509         } else {
510             sourcePath.append(src);
511         }
512     }
513
514     /**
515      * Create a path to be configured with the locations of the source
516      * files.
517      *
518      * @return a new Path instance to be configured by the Ant core.
519      */
520     public Path createSourcepath() {
521         if (sourcePath == null) {
522             sourcePath = new Path(getProject());
523         }
524         return sourcePath.createPath();
525     }
526
527     /**
528      * Adds a reference to a CLASSPATH defined elsewhere.
529      *
530      * @param r the reference containing the source path definition.
531      */
532     public void setSourcepathRef(Reference r) {
533         createSourcepath().setRefid(r);
534     }
535
536     /**
537      * Set the directory where the Javadoc output will be generated.
538      *
539      * @param dir the destination directory.
540      */
541     public void setDestdir(File dir) {
542         destDir = dir;
543         cmd.createArgument().setValue("-d");
544         cmd.createArgument().setFile(destDir);
545     }
546
547     /**
548      * Set the list of source files to process.
549      *
550      * @param src a comma separated list of source files.
551      */
552     public void setSourcefiles(String src) {
553         StringTokenizer tok = new StringTokenizer (src, ",");
554         while (tok.hasMoreTokens()) {
555             String f = tok.nextToken();
556             SourceFile sf = new SourceFile();
557             sf.setFile(getProject().resolveFile(f.trim()));
558             addSource(sf);
559         }
560     }
561
562     /**
563      * Add a single source file.
564      *
565      * @param sf the source file to be processed.
566      */
567     public void addSource(SourceFile sf) {
568         sourceFiles.addElement(sf);
569     }
570
571     /**
572      * Set the package names to be processed.
573      *
574      * @param packages a comma separated list of packages specs
575      * (may be wildcarded).
576      *
577      * @see #addPackage for wildcard information.
578      */
579     public void setPackagenames(String packages) {
580         StringTokenizer tok = new StringTokenizer (packages, ",");
581         while (tok.hasMoreTokens()) {
582             String p = tok.nextToken();
583             PackageName pn = new PackageName();
584             pn.setName(p);
585             addPackage(pn);
586         }
587     }
588
589     /**
590      * Add a single package to be processed.
591      *
592      * If the package name ends with &quot;.*&quot; the Javadoc task
593      * will find and process all subpackages.
594      *
595      * @param pn the package name, possibly wildcarded.
596      */
597     public void addPackage(PackageName pn) {
598         packageNames.addElement(pn);
599     }
600
601     /**
602      * Set the list of packages to be excluded.
603      *
604      * @param packages a comma separated list of packages to be excluded.
605      * This may not include wildcards.
606      */
607     public void setExcludePackageNames(String packages) {
608         StringTokenizer tok = new StringTokenizer (packages, ",");
609         while (tok.hasMoreTokens()) {
610             String p = tok.nextToken();
611             PackageName pn = new PackageName();
612             pn.setName(p);
613             addExcludePackage(pn);
614         }
615     }
616
617     /**
618      * Add a package to be excluded from the Javadoc run.
619      *
620      * @param pn the name of the package (wildcards are not permitted).
621      */
622     public void addExcludePackage(PackageName pn) {
623         excludePackageNames.addElement(pn);
624     }
625
626     /**
627      * Specify the file containing the overview to be included in the generated
628      * documentation.
629      *
630      * @param f the file containing the overview.
631      */
632     public void setOverview(File f) {
633         cmd.createArgument().setValue("-overview");
634         cmd.createArgument().setFile(f);
635     }
636
637     /**
638      * Indicate whether only public classes and members are to be included in
639      * the scope processed
640      *
641      * @param b true if scope is to be public.
642      */
643     public void setPublic(boolean b) {
644         addArgIf(b, "-public");
645     }
646
647     /**
648      * Indicate whether only protected and public classes and members are to
649      * be included in the scope processed
650      *
651      * @param b true if scope is to be protected.
652      */
653     public void setProtected(boolean b) {
654         addArgIf(b, "-protected");
655     }
656
657     /**
658      * Indicate whether only package, protected and public classes and
659      * members are to be included in the scope processed
660      *
661      * @param b true if scope is to be package level.
662      */
663     public void setPackage(boolean b) {
664         addArgIf(b, "-package");
665     }
666
667     /**
668      * Indicate whether all classes and
669      * members are to be included in the scope processed
670      *
671      * @param b true if scope is to be private level.
672      */
673     public void setPrivate(boolean b) {
674         addArgIf(b, "-private");
675     }
676
677     /**
678      * Set the scope to be processed. This is an alternative to the
679      * use of the setPublic, setPrivate, etc methods. It gives better build
680      * file control over what scope is processed.
681      *
682      * @param at the scope to be processed.
683      */
684     public void setAccess(AccessType at) {
685         cmd.createArgument().setValue("-" + at.getValue());
686     }
687
688     /**
689      * Set the class that starts the doclet used in generating the
690      * documentation.
691      *
692      * @param docletName the name of the doclet class.
693      */
694     public void setDoclet(String docletName) {
695         if (doclet == null) {
696             doclet = new DocletInfo();
697             doclet.setProject(getProject());
698         }
699         doclet.setName(docletName);
700     }
701
702     /**
703      * Set the classpath used to find the doclet class.
704      *
705      * @param docletPath the doclet classpath.
706      */
707     public void setDocletPath(Path docletPath) {
708         if (doclet == null) {
709             doclet = new DocletInfo();
710             doclet.setProject(getProject());
711         }
712         doclet.setPath(docletPath);
713     }
714
715     /**
716      * Set the classpath used to find the doclet class by reference.
717      *
718      * @param r the reference to the Path instance to use as the doclet
719      * classpath.
720      */
721     public void setDocletPathRef(Reference r) {
722         if (doclet == null) {
723             doclet = new DocletInfo();
724             doclet.setProject(getProject());
725         }
726         doclet.createPath().setRefid(r);
727     }
728
729     /**
730      * Create a doclet to be used in the documentation generation.
731      *
732      * @return a new DocletInfo instance to be configured.
733      */
734     public DocletInfo createDoclet() {
735         if (doclet == null) {
736             doclet = new DocletInfo();
737         }
738         return doclet;
739     }
740
741     /**
742      * Add a taglet
743      *
744      * @param tagletInfo information about the taglet.
745      */
746     public void addTaglet(ExtensionInfo tagletInfo) {
747         tags.addElement(tagletInfo);
748     }
749
750     /**
751      * Indicate whether Javadoc should produce old style (JDK 1.1)
752      * documentation.
753      *
754      * This is not supported by JDK 1.1 and has been phased out in JDK 1.4
755      *
756      * @param b if true attempt to generate old style documentation.
757      */
758     public void setOld(boolean b) {
759         old = b;
760     }
761
762     /**
763      * Set the classpath to be used for this Javadoc run.
764      *
765      * @param path an Ant Path object containing the compilation
766      * classpath.
767      */
768     public void setClasspath(Path path) {
769         if (classpath == null) {
770             classpath = path;
771         } else {
772             classpath.append(path);
773         }
774     }
775
776     /**
777      * Create a Path to be configured with the classpath to use
778      *
779      * @return a new Path instance to be configured with the classpath.
780      */
781     public Path createClasspath() {
782         if (classpath == null) {
783             classpath = new Path(getProject());
784         }
785         return classpath.createPath();
786     }
787
788     /**
789      * Adds a reference to a CLASSPATH defined elsewhere.
790      *
791      * @param r the reference to an instance defining the classpath.
792      */
793     public void setClasspathRef(Reference r) {
794         createClasspath().setRefid(r);
795     }
796
797     /**
798      * Set the boot classpath to use.
799      *
800      * @param path the boot classpath.
801      */
802     public void setBootclasspath(Path path) {
803         if (bootclasspath == null) {
804             bootclasspath = path;
805         } else {
806             bootclasspath.append(path);
807         }
808     }
809
810     /**
811      * Create a Path to be configured with the boot classpath
812      *
813      * @return a new Path instance to be configured with the boot classpath.
814      */
815     public Path createBootclasspath() {
816         if (bootclasspath == null) {
817             bootclasspath = new Path(getProject());
818         }
819         return bootclasspath.createPath();
820     }
821
822     /**
823      * Adds a reference to a CLASSPATH defined elsewhere.
824      *
825      * @param r the reference to an instance defining the bootclasspath.
826      */
827     public void setBootClasspathRef(Reference r) {
828         createBootclasspath().setRefid(r);
829     }
830
831     /**
832      * Set the location of the extensions directories.
833      *
834      * @param path the string version of the path.
835      * @deprecated since 1.5.x.
836      * Use the {@link #setExtdirs(Path)} version.
837      */
838     public void setExtdirs(String path) {
839         cmd.createArgument().setValue("-extdirs");
840         cmd.createArgument().setValue(path);
841     }
842
843     /**
844      * Set the location of the extensions directories.
845      *
846      * @param path a path containing the extension directories.
847      */
848     public void setExtdirs(Path path) {
849         cmd.createArgument().setValue("-extdirs");
850         cmd.createArgument().setPath(path);
851     }
852
853     /**
854      * Run javadoc in verbose mode
855      *
856      * @param b true if operation is to be verbose.
857      */
858     public void setVerbose(boolean b) {
859         addArgIf(b, "-verbose");
860     }
861
862     /**
863      * Set the local to use in documentation generation.
864      *
865      * @param locale the locale to use.
866      */
867     public void setLocale(String locale) {
868         // createArgument(true) is necessary to make sure -locale
869 // is the first argument (required in 1.3+).
870 cmd.createArgument(true).setValue(locale);
871         cmd.createArgument(true).setValue("-locale");
872     }
873
874     /**
875      * Set the encoding name of the source files,
876      *
877      * @param enc the name of the encoding for the source files.
878      */
879     public void setEncoding(String enc) {
880         cmd.createArgument().setValue("-encoding");
881         cmd.createArgument().setValue(enc);
882     }
883
884     /**
885      * Include the version tag in the generated documentation.
886      *
887      * @param b true if the version tag should be included.
888      */
889     public void setVersion(boolean b) {
890         this.version = b;
891     }
892
893     /**
894      * Generate the &quot;use&quot page for each package.
895      *
896      * @param b true if the use page should be generated.
897      */
898     public void setUse(boolean b) {
899         addArgIf(b, "-use");
900     }
901
902
903     /**
904      * Include the author tag in the generated documentation.
905      *
906      * @param b true if the author tag should be included.
907      */
908     public void setAuthor(boolean b) {
909         author = b;
910     }
911
912     /**
913      * Generate a split index
914      *
915      * @param b true if the index should be split into a file per letter.
916      */
917     public void setSplitindex(boolean b) {
918         addArgIf(b, "-splitindex");
919     }
920
921     /**
922      * Set the title to be placed in the HTML &lt;title&gt; tag of the
923      * generated documentation.
924      *
925      * @param title the window title to use.
926      */
927     public void setWindowtitle(String title) {
928         addArgIfNotEmpty("-windowtitle", title);
929     }
930
931     /**
932      * Set the title of the generated overview page.
933      *
934      * @param doctitle the Document title.
935      */
936     public void setDoctitle(String doctitle) {
937         Html h = new Html();
938         h.addText(doctitle);
939         addDoctitle(h);
940     }
941
942     /**
943      * Add a document title to use for the overview page.
944      *
945      * @param text the HTML element containing the document title.
946      */
947     public void addDoctitle(Html text) {
948         doctitle = text;
949     }
950
951     /**
952      * Set the header text to be placed at the top of each output file.
953      *
954      * @param header the header text
955      */
956     pu