Fri, 18 Jun 2010 21:13:56 -0700
6961178: Allow doclet.xml to contain XML attributes
Reviewed-by: bpatel
1 /*
2 * Copyright (c) 2003, 2008, 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.builders;
28 import com.sun.tools.doclets.internal.toolkit.util.*;
29 import com.sun.tools.doclets.internal.toolkit.*;
30 import com.sun.javadoc.*;
31 import java.io.*;
32 import java.util.*;
34 /**
35 * Builds the summary for a given annotation type.
36 *
37 * This code is not part of an API.
38 * It is implementation that is subject to change.
39 * Do not use it as an API
40 *
41 * @author Jamie Ho
42 * @since 1.5
43 */
44 public class AnnotationTypeBuilder extends AbstractBuilder {
46 /**
47 * The root element of the annotation type XML is {@value}.
48 */
49 public static final String ROOT = "AnnotationTypeDoc";
51 /**
52 * The annotation type being documented.
53 */
54 private AnnotationTypeDoc annotationTypeDoc;
56 /**
57 * The doclet specific writer.
58 */
59 private AnnotationTypeWriter writer;
61 /**
62 * Construct a new ClassBuilder.
63 *
64 * @param configuration the current configuration of the
65 * doclet.
66 */
67 private AnnotationTypeBuilder(Configuration configuration) {
68 super(configuration);
69 }
71 /**
72 * Construct a new ClassBuilder.
73 *
74 * @param configuration the current configuration of the doclet.
75 * @param annotationTypeDoc the class being documented.
76 * @param writer the doclet specific writer.
77 */
78 public static AnnotationTypeBuilder getInstance(Configuration configuration,
79 AnnotationTypeDoc annotationTypeDoc, AnnotationTypeWriter writer)
80 throws Exception {
81 AnnotationTypeBuilder builder = new AnnotationTypeBuilder(configuration);
82 builder.configuration = configuration;
83 builder.annotationTypeDoc = annotationTypeDoc;
84 builder.writer = writer;
85 if(containingPackagesSeen == null) {
86 containingPackagesSeen = new HashSet<String>();
87 }
88 return builder;
89 }
91 /**
92 * {@inheritDoc}
93 */
94 public void build() throws IOException {
95 build(LayoutParser.getInstance(configuration).parseXML(ROOT));
96 }
98 /**
99 * {@inheritDoc}
100 */
101 public String getName() {
102 return ROOT;
103 }
105 /**
106 * Handles the <AnnotationTypeDoc> tag.
107 *
108 * @param elements the XML elements that specify how to document a class.
109 */
110 public void buildAnnotationTypeDoc(XMLNode node) throws Exception {
111 buildChildren(node);
112 writer.close();
113 copyDocFiles();
114 }
117 /**
118 * Copy the doc files for the current ClassDoc if necessary.
119 */
120 private void copyDocFiles() {
121 PackageDoc containingPackage = annotationTypeDoc.containingPackage();
122 if((configuration.packages == null ||
123 Arrays.binarySearch(configuration.packages,
124 containingPackage) < 0) &&
125 ! containingPackagesSeen.contains(containingPackage.name())){
126 //Only copy doc files dir if the containing package is not
127 //documented AND if we have not documented a class from the same
128 //package already. Otherwise, we are making duplicate copies.
129 Util.copyDocFiles(configuration,
130 Util.getPackageSourcePath(configuration,
131 annotationTypeDoc.containingPackage()) +
132 DirectoryManager.getDirectoryPath(
133 annotationTypeDoc.containingPackage())
134 + File.separator, DocletConstants.DOC_FILES_DIR_NAME, true);
135 containingPackagesSeen.add(containingPackage.name());
136 }
137 }
139 /**
140 * Build the header of the page.
141 */
142 public void buildAnnotationTypeHeader(XMLNode node) {
143 writer.writeHeader(configuration.getText("doclet.AnnotationType") +
144 " " + annotationTypeDoc.name());
145 }
147 /**
148 * If this class is deprecated, print the appropriate information.
149 */
150 public void buildDeprecationInfo (XMLNode node) {
151 writer.writeAnnotationTypeDeprecationInfo();
152 }
154 /**
155 * Build the signature of the current annotation type.
156 */
157 public void buildAnnotationTypeSignature(XMLNode node) {
158 StringBuffer modifiers = new StringBuffer(
159 annotationTypeDoc.modifiers() + " ");
160 writer.writeAnnotationTypeSignature(
161 Util.replaceText(
162 modifiers.toString(), "interface", "@interface"));
163 }
165 /**
166 * Build the class description.
167 */
168 public void buildAnnotationTypeDescription(XMLNode node) {
169 writer.writeAnnotationTypeDescription();
170 }
172 /**
173 * Build the tag information for the current class.
174 */
175 public void buildAnnotationTypeTagInfo(XMLNode node) {
176 writer.writeAnnotationTypeTagInfo();
177 }
179 /**
180 * Build the contents of the page.
181 *
182 * @param elements the XML elements that specify how a member summary is
183 * documented.
184 */
185 public void buildMemberSummary(XMLNode node) throws Exception {
186 configuration.getBuilderFactory().
187 getMemberSummaryBuilder(writer).buildChildren(node);
188 writer.completeMemberSummaryBuild();
189 }
191 /**
192 * Build the annotation type optional member documentation.
193 *
194 * @param elements the XML elements that specify how a annotation type
195 * members are documented.
196 */
197 public void buildAnnotationTypeOptionalMemberDetails(XMLNode node)
198 throws Exception {
199 configuration.getBuilderFactory().
200 getAnnotationTypeOptionalMemberBuilder(writer).buildChildren(node);
201 }
203 /**
204 * Build the annotation type required member documentation.
205 *
206 * @param elements the XML elements that specify how a annotation type
207 * members are documented.
208 */
209 public void buildAnnotationTypeRequiredMemberDetails(XMLNode node)
210 throws Exception {
211 configuration.getBuilderFactory().
212 getAnnotationTypeRequiredMemberBuilder(writer).buildChildren(node);
213 }
216 /**
217 * Build the footer of the page.
218 */
219 public void buildAnnotationTypeFooter(XMLNode node) {
220 writer.writeFooter();
221 }
222 }