1 /*

     2  * Copyright (c) 1997, 2015, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package com.sun.tools.javadoc;

    27 

    28 import java.io.IOException;

    29 import java.io.InputStream;

    30 

    31 import javax.tools.FileObject;

    32 

    33 import com.sun.javadoc.*;

    34 import com.sun.source.util.TreePath;

    35 import com.sun.tools.javac.code.Attribute;

    36 import com.sun.tools.javac.code.Symbol;

    37 import com.sun.tools.javac.code.Symbol.ClassSymbol;

    38 import com.sun.tools.javac.code.Symbol.PackageSymbol;

    39 import com.sun.tools.javac.tree.JCTree;

    40 import com.sun.tools.javac.tree.JCTree.JCCompilationUnit;

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

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

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

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

    45 

    46 import static com.sun.tools.javac.code.Scope.LookupKind.NON_RECURSIVE;

    47 

    48 /**

    49  * Represents a java package.  Provides access to information

    50  * about the package, the package's comment and tags, and the

    51  * classes in the package.

    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 Kaiyang Liu (original)

    60  * @author Robert Field (rewrite)

    61  * @author Neal Gafter (rewrite)

    62  * @author Scott Seligman (package-info.java)

    63  */

    64 

    65 public class PackageDocImpl extends DocImpl implements PackageDoc {

    66 

    67     public final PackageSymbol sym;

    68     private JCCompilationUnit tree = null;    // for source position

    69 

    70     public FileObject docPath = null;

    71     private boolean foundDoc;   // found a doc comment in either

    72                                 // package.html or package-info.java

    73 

    74     boolean isIncluded = false;  // Set in RootDocImpl.

    75     public boolean setDocPath = false;  //Flag to avoid setting doc path multiple times.

    76 

    77     /**

    78      * Constructor

    79      */

    80     public PackageDocImpl(DocEnv env, PackageSymbol sym) {

    81         this(env, sym, null);

    82     }

    83 

    84     /**

    85      * Constructor

    86      */

    87     public PackageDocImpl(DocEnv env, PackageSymbol sym, TreePath treePath) {

    88         super(env, treePath);

    89         this.sym = sym;

    90         this.tree = (treePath == null) ? null : (JCCompilationUnit) treePath.getCompilationUnit();

    91         foundDoc = (documentation != null);

    92     }

    93 

    94     void setTree(JCTree tree) {

    95         this.tree = (JCCompilationUnit) tree;

    96     }

    97 

    98     public void setTreePath(TreePath treePath) {

    99         super.setTreePath(treePath);

   100         checkDoc();

   101     }

   102 

   103     /**

   104      * Do lazy initialization of "documentation" string.

   105      */

   106     protected String documentation() {

   107         if (documentation != null)

   108             return documentation;

   109         if (docPath != null) {

   110             // read from file

   111             try {

   112                 InputStream s = docPath.openInputStream();

   113                 documentation = readHTMLDocumentation(s, docPath);

   114             } catch (IOException exc) {

   115                 documentation = "";

   116                 env.error(null, "javadoc.File_Read_Error", docPath.getName());

   117             }

   118         } else {

   119             // no doc file to be had

   120             documentation = "";

   121         }

   122         return documentation;

   123     }

   124 

   125     /**

   126      * Cache of all classes contained in this package, including

   127      * member classes of those classes, and their member classes, etc.

   128      * Includes only those classes at the specified protection level

   129      * and weaker.

   130      */

   131     private List<ClassDocImpl> allClassesFiltered = null;

   132 

   133     /**

   134      * Cache of all classes contained in this package, including

   135      * member classes of those classes, and their member classes, etc.

   136      */

   137     private List<ClassDocImpl> allClasses = null;

   138 

   139     /**

   140      * Return a list of all classes contained in this package, including

   141      * member classes of those classes, and their member classes, etc.

   142      */

   143     private List<ClassDocImpl> getClasses(boolean filtered) {

   144         if (allClasses != null && !filtered) {

   145             return allClasses;

   146         }

   147         if (allClassesFiltered != null && filtered) {

   148             return allClassesFiltered;

   149         }

   150         ListBuffer<ClassDocImpl> classes = new ListBuffer<>();

   151         for (Symbol enumerated : sym.members().getSymbols(NON_RECURSIVE)) {

   152             if (enumerated != null) {

   153                 ClassSymbol s = (ClassSymbol)enumerated;

   154                 ClassDocImpl c = env.getClassDoc(s);

   155                 if (c != null && !c.isSynthetic())

   156                     c.addAllClasses(classes, filtered);

   157             }

   158         }

   159         if (filtered)

   160             return allClassesFiltered = classes.toList();

   161         else

   162             return allClasses = classes.toList();

   163     }

   164 

   165     /**

   166      * Add all included classes (including Exceptions and Errors)

   167      * and interfaces.

   168      */

   169     public void addAllClassesTo(ListBuffer<ClassDocImpl> list) {

   170         list.appendList(getClasses(true));

   171     }

   172 

   173     /**

   174      * Get all classes (including Exceptions and Errors)

   175      * and interfaces.

   176      * @since J2SE1.4.

   177      *

   178      * @return all classes and interfaces in this package, filtered to include

   179      * only the included classes if filter==true.

   180      */

   181     public ClassDoc[] allClasses(boolean filter) {

   182         List<ClassDocImpl> classes = getClasses(filter);

   183         return classes.toArray(new ClassDocImpl[classes.length()]);

   184     }

   185 

   186     /**

   187      * Get all included classes (including Exceptions and Errors)

   188      * and interfaces.  Same as allClasses(true).

   189      *

   190      * @return all included classes and interfaces in this package.

   191      */

   192     public ClassDoc[] allClasses() {

   193         return allClasses(true);

   194     }

   195 

   196     /**

   197      * Get ordinary classes (that is, exclude exceptions, errors,

   198      * enums, interfaces, and annotation types) in this package.

   199      *

   200      * @return included ordinary classes in this package.

   201      */

   202     public ClassDoc[] ordinaryClasses() {

   203         ListBuffer<ClassDocImpl> ret = new ListBuffer<>();

   204         for (ClassDocImpl c : getClasses(true)) {

   205             if (c.isOrdinaryClass()) {

   206                 ret.append(c);

   207             }

   208         }

   209         return ret.toArray(new ClassDocImpl[ret.length()]);

   210     }

   211 

   212     /**

   213      * Get Exception classes in this package.

   214      *

   215      * @return included Exceptions in this package.

   216      */

   217     public ClassDoc[] exceptions() {

   218         ListBuffer<ClassDocImpl> ret = new ListBuffer<>();

   219         for (ClassDocImpl c : getClasses(true)) {

   220             if (c.isException()) {

   221                 ret.append(c);

   222             }

   223         }

   224         return ret.toArray(new ClassDocImpl[ret.length()]);

   225     }

   226 

   227     /**

   228      * Get Error classes in this package.

   229      *

   230      * @return included Errors in this package.

   231      */

   232     public ClassDoc[] errors() {

   233         ListBuffer<ClassDocImpl> ret = new ListBuffer<>();

   234         for (ClassDocImpl c : getClasses(true)) {

   235             if (c.isError()) {

   236                 ret.append(c);

   237             }

   238         }

   239         return ret.toArray(new ClassDocImpl[ret.length()]);

   240     }

   241 

   242     /**

   243      * Get included enum types in this package.

   244      *

   245      * @return included enum types in this package.

   246      */

   247     public ClassDoc[] enums() {

   248         ListBuffer<ClassDocImpl> ret = new ListBuffer<>();

   249         for (ClassDocImpl c : getClasses(true)) {

   250             if (c.isEnum()) {

   251                 ret.append(c);

   252             }

   253         }

   254         return ret.toArray(new ClassDocImpl[ret.length()]);

   255     }

   256 

   257     /**

   258      * Get included interfaces in this package, omitting annotation types.

   259      *

   260      * @return included interfaces in this package.

   261      */

   262     public ClassDoc[] interfaces() {

   263         ListBuffer<ClassDocImpl> ret = new ListBuffer<>();

   264         for (ClassDocImpl c : getClasses(true)) {

   265             if (c.isInterface()) {

   266                 ret.append(c);

   267             }

   268         }

   269         return ret.toArray(new ClassDocImpl[ret.length()]);

   270     }

   271 

   272     /**

   273      * Get included annotation types in this package.

   274      *

   275      * @return included annotation types in this package.

   276      */

   277     public AnnotationTypeDoc[] annotationTypes() {

   278         ListBuffer<AnnotationTypeDocImpl> ret = new ListBuffer<>();

   279         for (ClassDocImpl c : getClasses(true)) {

   280             if (c.isAnnotationType()) {

   281                 ret.append((AnnotationTypeDocImpl)c);

   282             }

   283         }

   284         return ret.toArray(new AnnotationTypeDocImpl[ret.length()]);

   285     }

   286 

   287     /**

   288      * Get the annotations of this package.

   289      * Return an empty array if there are none.

   290      */

   291     public AnnotationDesc[] annotations() {

   292         AnnotationDesc res[] = new AnnotationDesc[sym.getRawAttributes().length()];

   293         int i = 0;

   294         for (Attribute.Compound a : sym.getRawAttributes()) {

   295             res[i++] = new AnnotationDescImpl(env, a);

   296         }

   297         return res;

   298     }

   299 

   300 

   301     /**

   302      * Lookup for a class within this package.

   303      *

   304      * @return ClassDocImpl of found class, or null if not found.

   305      */

   306     public ClassDoc findClass(String className) {

   307         final boolean filtered = true;

   308         for (ClassDocImpl c : getClasses(filtered)) {

   309             if (c.name().equals(className)) {

   310                 return c;

   311             }

   312         }

   313         return null;

   314     }

   315 

   316     /**

   317      * Return true if this package is included in the active set.

   318      */

   319     public boolean isIncluded() {

   320         return isIncluded;

   321     }

   322 

   323     /**

   324      * Get package name.

   325      *

   326      * Note that we do not provide a means of obtaining the simple

   327      * name of a package -- package names are always returned in their

   328      * uniquely qualified form.

   329      */

   330     public String name() {

   331         return qualifiedName();

   332     }

   333 

   334     /**

   335      * Get package name.

   336      */

   337     public String qualifiedName() {

   338         if (qualifiedName == null) {

   339             Name fullname = sym.getQualifiedName();

   340             // Some bogus tests depend on the interned "" being returned.

   341             // See 6457276.

   342             qualifiedName = fullname.isEmpty() ? "" : fullname.toString();

   343         }

   344         return qualifiedName;

   345     }

   346 

   347     private String qualifiedName;

   348 

   349     /**

   350      * set doc path for an unzipped directory

   351      */

   352     public void setDocPath(FileObject path) {

   353         setDocPath = true;

   354         if (path == null)

   355             return;

   356         if (!path.equals(docPath)) {

   357             docPath = path;

   358             checkDoc();

   359         }

   360     }

   361 

   362     // Has checkDoc() sounded off yet?

   363     private boolean checkDocWarningEmitted = false;

   364 

   365     /**

   366      * Invoked when a source of package doc comments is located.

   367      * Emits a diagnostic if this is the second one.

   368      */

   369     private void checkDoc() {

   370         if (foundDoc) {

   371             if (!checkDocWarningEmitted) {

   372                 env.warning(null, "javadoc.Multiple_package_comments", name());

   373                 checkDocWarningEmitted = true;

   374             }

   375         } else {

   376             foundDoc = true;

   377         }

   378     }

   379 

   380     /**

   381      * Return the source position of the entity, or null if

   382      * no position is available.

   383      */

   384     public SourcePosition position() {

   385         return (tree != null)

   386                 ? SourcePositionImpl.make(tree.sourcefile, tree.pos, tree.lineMap)

   387                 : SourcePositionImpl.make(docPath, Position.NOPOS, null);

   388     }

   389 }