View Javadoc
1   /*
2    * Copyright (c) 2001, 2012, 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.doclets.internal.toolkit.util;
27  
28  import java.util.*;
29  import com.sun.javadoc.*;
30  import com.sun.tools.doclets.internal.toolkit.Configuration;
31  
32  /**
33   * This class acts as an artificial PackageDoc for classes specified
34   * on the command line when running Javadoc.  For example, if you
35   * specify several classes from package java.lang, this class will catalog
36   * those classes so that we can retrieve all of the classes from a particular
37   * package later.
38   *
39   *  <p><b>This is NOT part of any supported API.
40   *  If you write code that depends on this, you do so at your own risk.
41   *  This code and its internal interfaces are subject to change or
42   *  deletion without notice.</b>
43   *
44   * @author Jamie Ho
45   * @since 1.4
46   */
47  
48   public class ClassDocCatalog {
49  
50       /**
51        * Stores the set of packages that the classes specified on the command line
52        * belong to.  Note that the default package is "".
53        */
54       private Set<String> packageSet;
55  
56  
57       /**
58        * Stores all classes for each package
59        */
60       private Map<String,Set<ClassDoc>> allClasses;
61  
62       /**
63        * Stores ordinary classes (excluding Exceptions and Errors) for each
64        * package
65        */
66       private Map<String,Set<ClassDoc>> ordinaryClasses;
67  
68       /**
69        * Stores exceptions for each package
70        */
71       private Map<String,Set<ClassDoc>> exceptions;
72  
73      /**
74       * Stores enums for each package.
75       */
76      private Map<String,Set<ClassDoc>> enums;
77  
78      /**
79       * Stores annotation types for each package.
80       */
81      private Map<String,Set<ClassDoc>> annotationTypes;
82  
83       /**
84        * Stores errors for each package
85        */
86       private Map<String,Set<ClassDoc>> errors;
87  
88       /**
89        * Stores interfaces for each package
90        */
91       private Map<String,Set<ClassDoc>> interfaces;
92  
93       private Configuration configuration;
94  
95       /**
96        * Construct a new ClassDocCatalog.
97        *
98        * @param classdocs the array of ClassDocs to catalog
99        */
100      public ClassDocCatalog (ClassDoc[] classdocs, Configuration config) {
101          init();
102          this.configuration = config;
103          for (int i = 0; i < classdocs.length; i++) {
104              addClassDoc(classdocs[i]);
105          }
106      }
107 
108      /**
109       * Construct a new ClassDocCatalog.
110       *
111       */
112      public ClassDocCatalog () {
113          init();
114      }
115 
116      private void init() {
117          allClasses = new HashMap<String,Set<ClassDoc>>();
118          ordinaryClasses = new HashMap<String,Set<ClassDoc>>();
119          exceptions = new HashMap<String,Set<ClassDoc>>();
120          enums = new HashMap<String,Set<ClassDoc>>();
121          annotationTypes = new HashMap<String,Set<ClassDoc>>();
122          errors = new HashMap<String,Set<ClassDoc>>();
123          interfaces = new HashMap<String,Set<ClassDoc>>();
124          packageSet = new HashSet<String>();
125      }
126 
127      /**
128       * Add the given class to the catalog.
129       * @param classdoc the ClassDoc to add to the catelog.
130       */
131       public void addClassDoc(ClassDoc classdoc) {
132         if (classdoc == null) {
133             return;
134         }
135         addClass(classdoc, allClasses);
136         if (classdoc.isOrdinaryClass()) {
137             addClass(classdoc, ordinaryClasses);
138         } else if (classdoc.isException()) {
139             addClass(classdoc, exceptions);
140         } else if (classdoc.isEnum()) {
141             addClass(classdoc, enums);
142         } else if (classdoc.isAnnotationType()) {
143             addClass(classdoc, annotationTypes);
144         } else if (classdoc.isError()) {
145             addClass(classdoc, errors);
146         } else if (classdoc.isInterface()) {
147             addClass(classdoc, interfaces);
148         }
149       }
150 
151       /**
152        * Add the given class to the given map.
153        * @param classdoc the ClassDoc to add to the catelog.
154        * @param map the Map to add the ClassDoc to.
155        */
156       private void addClass(ClassDoc classdoc, Map<String,Set<ClassDoc>> map) {
157 
158           PackageDoc pkg = classdoc.containingPackage();
159           if (pkg.isIncluded() || (configuration.nodeprecated && Util.isDeprecated(pkg))) {
160               //No need to catalog this class if it's package is
161               //included on the command line or if -nodeprecated option is set
162               // and the containing package is marked as deprecated.
163               return;
164           }
165           String key = Util.getPackageName(pkg);
166           Set<ClassDoc> s = map.get(key);
167           if (s == null) {
168               packageSet.add(key);
169               s = new HashSet<ClassDoc>();
170           }
171           s.add(classdoc);
172           map.put(key, s);
173 
174       }
175 
176       private ClassDoc[] getArray(Map<String,Set<ClassDoc>> m, String key) {
177           Set<ClassDoc> s = m.get(key);
178           if (s == null) {
179               return new ClassDoc[] {};
180           } else {
181               return s.toArray(new ClassDoc[] {});
182           }
183       }
184 
185       /**
186        * Return all of the classes specified on the command-line that
187        * belong to the given package.
188        * @param pkgDoc the package to return the classes for.
189        */
190       public ClassDoc[] allClasses(PackageDoc pkgDoc) {
191           return pkgDoc.isIncluded() ?
192                 pkgDoc.allClasses() :
193                 getArray(allClasses, Util.getPackageName(pkgDoc));
194       }
195 
196       /**
197        * Return all of the classes specified on the command-line that
198        * belong to the given package.
199        * @param packageName the name of the package specified on the
200        * command-line.
201        */
202       public ClassDoc[] allClasses(String packageName) {
203           return getArray(allClasses, packageName);
204       }
205 
206      /**
207       * Return the array of package names that this catalog stores
208       * ClassDocs for.
209       */
210      public String[] packageNames() {
211          return packageSet.toArray(new String[] {});
212      }
213 
214      /**
215       * Return true if the given package is known to this catalog.
216       * @param packageName the name to check.
217       * @return true if this catalog has any information about
218       * classes in the given package.
219       */
220      public boolean isKnownPackage(String packageName) {
221          return packageSet.contains(packageName);
222      }
223 
224 
225       /**
226        * Return all of the errors specified on the command-line
227        * that belong to the given package.
228        * @param packageName the name of the package specified on the
229        * command-line.
230        */
231       public ClassDoc[] errors(String packageName) {
232           return getArray(errors, packageName);
233       }
234 
235       /**
236        * Return all of the exceptions specified on the command-line
237        * that belong to the given package.
238        * @param packageName the name of the package specified on the
239        * command-line.
240        */
241       public ClassDoc[] exceptions(String packageName) {
242           return getArray(exceptions, packageName);
243       }
244 
245       /**
246        * Return all of the enums specified on the command-line
247        * that belong to the given package.
248        * @param packageName the name of the package specified on the
249        * command-line.
250        */
251       public ClassDoc[] enums(String packageName) {
252           return getArray(enums, packageName);
253       }
254 
255       /**
256        * Return all of the annotation types specified on the command-line
257        * that belong to the given package.
258        * @param packageName the name of the package specified on the
259        * command-line.
260        */
261       public ClassDoc[] annotationTypes(String packageName) {
262           return getArray(annotationTypes, packageName);
263       }
264 
265       /**
266        * Return all of the interfaces specified on the command-line
267        * that belong to the given package.
268        * @param packageName the name of the package specified on the
269        * command-line.
270        */
271       public ClassDoc[] interfaces(String packageName) {
272           return getArray(interfaces, packageName);
273       }
274 
275       /**
276        * Return all of the ordinary classes specified on the command-line
277        * that belong to the given package.
278        * @param packageName the name of the package specified on the
279        * command-line.
280        */
281       public ClassDoc[] ordinaryClasses(String packageName) {
282           return getArray(ordinaryClasses, packageName);
283       }
284 }