Thu, 02 Oct 2008 19:58:40 -0700
6754988: Update copyright year
Summary: Update for files that have been modified starting July 2008
Reviewed-by: ohair, tbell
1 /*
2 * Copyright 2003-2008 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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.*;
33 import java.lang.reflect.*;
35 /**
36 * Builds the summary for a given annotation type.
37 *
38 * This code is not part of an API.
39 * It is implementation that is subject to change.
40 * Do not use it as an API
41 *
42 * @author Jamie Ho
43 * @since 1.5
44 */
45 public class AnnotationTypeBuilder extends AbstractBuilder {
47 /**
48 * The root element of the annotation type XML is {@value}.
49 */
50 public static final String ROOT = "AnnotationTypeDoc";
52 /**
53 * The annotation type being documented.
54 */
55 private AnnotationTypeDoc annotationTypeDoc;
57 /**
58 * The doclet specific writer.
59 */
60 private AnnotationTypeWriter writer;
62 /**
63 * Construct a new ClassBuilder.
64 *
65 * @param configuration the current configuration of the
66 * doclet.
67 */
68 private AnnotationTypeBuilder(Configuration configuration) {
69 super(configuration);
70 }
72 /**
73 * Construct a new ClassBuilder.
74 *
75 * @param configuration the current configuration of the doclet.
76 * @param annotationTypeDoc the class being documented.
77 * @param writer the doclet specific writer.
78 */
79 public static AnnotationTypeBuilder getInstance(Configuration configuration,
80 AnnotationTypeDoc annotationTypeDoc, AnnotationTypeWriter writer)
81 throws Exception {
82 AnnotationTypeBuilder builder = new AnnotationTypeBuilder(configuration);
83 builder.configuration = configuration;
84 builder.annotationTypeDoc = annotationTypeDoc;
85 builder.writer = writer;
86 if(containingPackagesSeen == null) {
87 containingPackagesSeen = new HashSet<String>();
88 }
89 return builder;
90 }
92 /**
93 * {@inheritDoc}
94 */
95 public void invokeMethod(String methodName, Class[] paramClasses,
96 Object[] params)
97 throws Exception {
98 if (DEBUG) {
99 configuration.root.printError("DEBUG: " + this.getClass().getName()
100 + "." + methodName);
101 }
102 Method method = this.getClass().getMethod(methodName, paramClasses);
103 method.invoke(this, params);
104 }
106 /**
107 * {@inheritDoc}
108 */
109 public void build() throws IOException {
110 build(LayoutParser.getInstance(configuration).parseXML(ROOT));
111 }
113 /**
114 * {@inheritDoc}
115 */
116 public String getName() {
117 return ROOT;
118 }
120 /**
121 * Handles the <AnnotationTypeDoc> tag.
122 *
123 * @param elements the XML elements that specify how to document a class.
124 */
125 public void buildAnnotationTypeDoc(List elements) throws Exception {
126 build(elements);
127 writer.close();
128 copyDocFiles();
129 }
132 /**
133 * Copy the doc files for the current ClassDoc if necessary.
134 */
135 private void copyDocFiles() {
136 PackageDoc containingPackage = annotationTypeDoc.containingPackage();
137 if((configuration.packages == null ||
138 Arrays.binarySearch(configuration.packages,
139 containingPackage) < 0) &&
140 ! containingPackagesSeen.contains(containingPackage.name())){
141 //Only copy doc files dir if the containing package is not
142 //documented AND if we have not documented a class from the same
143 //package already. Otherwise, we are making duplicate copies.
144 Util.copyDocFiles(configuration,
145 Util.getPackageSourcePath(configuration,
146 annotationTypeDoc.containingPackage()) +
147 DirectoryManager.getDirectoryPath(
148 annotationTypeDoc.containingPackage())
149 + File.separator, DocletConstants.DOC_FILES_DIR_NAME, true);
150 containingPackagesSeen.add(containingPackage.name());
151 }
152 }
154 /**
155 * Build the header of the page.
156 */
157 public void buildAnnotationTypeHeader() {
158 writer.writeHeader(configuration.getText("doclet.AnnotationType") +
159 " " + annotationTypeDoc.name());
160 }
162 /**
163 * If this class is deprecated, print the appropriate information.
164 */
165 public void buildDeprecationInfo () {
166 writer.writeAnnotationTypeDeprecationInfo();
167 }
169 /**
170 * Build the signature of the current annotation type.
171 */
172 public void buildAnnotationTypeSignature() {
173 StringBuffer modifiers = new StringBuffer(
174 annotationTypeDoc.modifiers() + " ");
175 writer.writeAnnotationTypeSignature(
176 Util.replaceText(
177 modifiers.toString(), "interface", "@interface"));
178 }
180 /**
181 * Build the class description.
182 */
183 public void buildAnnotationTypeDescription() {
184 writer.writeAnnotationTypeDescription();
185 }
187 /**
188 * Build the tag information for the current class.
189 */
190 public void buildAnnotationTypeTagInfo() {
191 writer.writeAnnotationTypeTagInfo();
192 }
194 /**
195 * Build the contents of the page.
196 *
197 * @param elements the XML elements that specify how a member summary is
198 * documented.
199 */
200 public void buildMemberSummary(List elements) throws Exception {
201 configuration.getBuilderFactory().
202 getMemberSummaryBuilder(writer).build(elements);
203 writer.completeMemberSummaryBuild();
204 }
206 /**
207 * Build the annotation type optional member documentation.
208 *
209 * @param elements the XML elements that specify how a annotation type
210 * members are documented.
211 */
212 public void buildAnnotationTypeOptionalMemberDetails(List elements)
213 throws Exception {
214 configuration.getBuilderFactory().
215 getAnnotationTypeOptionalMemberBuilder(writer).build(elements);
216 }
218 /**
219 * Build the annotation type required member documentation.
220 *
221 * @param elements the XML elements that specify how a annotation type
222 * members are documented.
223 */
224 public void buildAnnotationTypeRequiredMemberDetails(List elements)
225 throws Exception {
226 configuration.getBuilderFactory().
227 getAnnotationTypeRequiredMemberBuilder(writer).build(elements);
228 }
231 /**
232 * Build the footer of the page.
233 */
234 public void buildAnnotationTypeFooter() {
235 writer.writeFooter();
236 }
237 }