Sun, 24 Feb 2013 11:36:58 -0800
7112427: The doclet needs to be able to generate JavaFX documentation.
Reviewed-by: jjg
Contributed-by: jan.valenta@oracle.com
1 /*
2 * Copyright (c) 1998, 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.doclets.internal.toolkit.util;
28 import java.util.*;
30 import com.sun.javadoc.*;
31 import com.sun.tools.doclets.internal.toolkit.*;
33 /**
34 * Build the mapping of each Unicode character with it's member lists
35 * containing members names starting with it. Also build a list for all the
36 * Unicode characters which start a member name. Member name is
37 * classkind or field or method or constructor name.
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 * @since 1.2
45 * @see java.lang.Character
46 * @author Atul M Dambalkar
47 */
48 public class IndexBuilder {
50 /**
51 * Mapping of each Unicode Character with the member list containing
52 * members with names starting with it.
53 */
54 private Map<Character,List<Doc>> indexmap = new HashMap<Character,List<Doc>>();
56 /**
57 * Don't generate deprecated information if true.
58 */
59 private boolean noDeprecated;
61 /**
62 * Build this Index only for classes?
63 */
64 private boolean classesOnly;
66 /**
67 * Indicates javafx mode.
68 */
69 private boolean javafx;
71 // make ProgramElementDoc[] when new toArray is available
72 protected final Object[] elements;
74 /**
75 * A comparator used to sort classes and members.
76 * Note: Maybe this compare code belongs in the tool?
77 */
78 private class DocComparator implements Comparator<Doc> {
79 public int compare(Doc d1, Doc d2) {
80 String doc1 = d1.name();
81 String doc2 = d2.name();
82 int compareResult;
83 if ((compareResult = doc1.compareToIgnoreCase(doc2)) != 0) {
84 return compareResult;
85 } else if (d1 instanceof ProgramElementDoc && d2 instanceof ProgramElementDoc) {
86 doc1 = (((ProgramElementDoc) d1).qualifiedName());
87 doc2 = (((ProgramElementDoc) d2).qualifiedName());
88 return doc1.compareToIgnoreCase(doc2);
89 } else {
90 return 0;
91 }
92 }
93 }
95 /**
96 * Constructor. Build the index map.
97 *
98 * @param configuration the current configuration of the doclet.
99 * @param noDeprecated true if -nodeprecated option is used,
100 * false otherwise.
101 */
102 public IndexBuilder(Configuration configuration, boolean noDeprecated) {
103 this(configuration, noDeprecated, false);
104 }
106 /**
107 * Constructor. Build the index map.
108 *
109 * @param configuration the current configuration of the doclet.
110 * @param noDeprecated true if -nodeprecated option is used,
111 * false otherwise.
112 * @param classesOnly Include only classes in index.
113 */
114 public IndexBuilder(Configuration configuration, boolean noDeprecated,
115 boolean classesOnly) {
116 if (classesOnly) {
117 configuration.message.notice("doclet.Building_Index_For_All_Classes");
118 } else {
119 configuration.message.notice("doclet.Building_Index");
120 }
121 this.noDeprecated = noDeprecated;
122 this.classesOnly = classesOnly;
123 this.javafx = configuration.javafx;
124 buildIndexMap(configuration.root);
125 Set<Character> set = indexmap.keySet();
126 elements = set.toArray();
127 Arrays.sort(elements);
128 }
130 /**
131 * Sort the index map. Traverse the index map for all it's elements and
132 * sort each element which is a list.
133 */
134 protected void sortIndexMap() {
135 for (Iterator<List<Doc>> it = indexmap.values().iterator(); it.hasNext(); ) {
136 Collections.sort(it.next(), new DocComparator());
137 }
138 }
140 /**
141 * Get all the members in all the Packages and all the Classes
142 * given on the command line. Form separate list of those members depending
143 * upon their names.
144 *
145 * @param root Root of the documemt.
146 */
147 protected void buildIndexMap(RootDoc root) {
148 PackageDoc[] packages = root.specifiedPackages();
149 ClassDoc[] classes = root.classes();
150 if (!classesOnly) {
151 if (packages.length == 0) {
152 Set<PackageDoc> set = new HashSet<PackageDoc>();
153 PackageDoc pd;
154 for (int i = 0; i < classes.length; i++) {
155 pd = classes[i].containingPackage();
156 if (pd != null && pd.name().length() > 0) {
157 set.add(pd);
158 }
159 }
160 adjustIndexMap(set.toArray(packages));
161 } else {
162 adjustIndexMap(packages);
163 }
164 }
165 adjustIndexMap(classes);
166 if (!classesOnly) {
167 for (int i = 0; i < classes.length; i++) {
168 if (shouldAddToIndexMap(classes[i])) {
169 putMembersInIndexMap(classes[i]);
170 }
171 }
172 }
173 sortIndexMap();
174 }
176 /**
177 * Put all the members(fields, methods and constructors) in the classdoc
178 * to the indexmap.
179 *
180 * @param classdoc ClassDoc whose members will be added to the indexmap.
181 */
182 protected void putMembersInIndexMap(ClassDoc classdoc) {
183 adjustIndexMap(classdoc.fields());
184 adjustIndexMap(classdoc.methods());
185 adjustIndexMap(classdoc.constructors());
186 }
189 /**
190 * Adjust list of members according to their names. Check the first
191 * character in a member name, and then add the member to a list of members
192 * for that particular unicode character.
193 *
194 * @param elements Array of members.
195 */
196 protected void adjustIndexMap(Doc[] elements) {
197 for (int i = 0; i < elements.length; i++) {
198 if (shouldAddToIndexMap(elements[i])) {
199 String name = elements[i].name();
200 char ch = (name.length()==0)?
201 '*' :
202 Character.toUpperCase(name.charAt(0));
203 Character unicode = new Character(ch);
204 List<Doc> list = indexmap.get(unicode);
205 if (list == null) {
206 list = new ArrayList<Doc>();
207 indexmap.put(unicode, list);
208 }
209 list.add(elements[i]);
210 }
211 }
212 }
214 /**
215 * Should this doc element be added to the index map?
216 */
217 protected boolean shouldAddToIndexMap(Doc element) {
218 if (javafx) {
219 if (element.tags("treatAsPrivate").length > 0) {
220 return false;
221 }
222 }
224 if (element instanceof PackageDoc)
225 // Do not add to index map if -nodeprecated option is set and the
226 // package is marked as deprecated.
227 return !(noDeprecated && Util.isDeprecated(element));
228 else
229 // Do not add to index map if -nodeprecated option is set and if the
230 // Doc is marked as deprecated or the containing package is marked as
231 // deprecated.
232 return !(noDeprecated &&
233 (Util.isDeprecated(element) ||
234 Util.isDeprecated(((ProgramElementDoc)element).containingPackage())));
235 }
237 /**
238 * Return a map of all the individual member lists with Unicode character.
239 *
240 * @return Map index map.
241 */
242 public Map<Character,List<Doc>> getIndexMap() {
243 return indexmap;
244 }
246 /**
247 * Return the sorted list of members, for passed Unicode Character.
248 *
249 * @param index index Unicode character.
250 * @return List member list for specific Unicode character.
251 */
252 public List<Doc> getMemberList(Character index) {
253 return indexmap.get(index);
254 }
256 /**
257 * Array of IndexMap keys, Unicode characters.
258 */
259 public Object[] elements() {
260 return elements;
261 }
262 }