1 /**
2 * Redistribution and use of this software and associated documentation
3 * ("Software"), with or without modification, are permitted provided
4 * that the following conditions are met:
5 *
6 * 1. Redistributions of source code must retain copyright
7 * statements and notices. Redistributions must also contain a
8 * copy of this document.
9 *
10 * 2. Redistributions in binary form must reproduce the
11 * above copyright notice, this list of conditions and the
12 * following disclaimer in the documentation and/or other
13 * materials provided with the distribution.
14 *
15 * 3. The name "Exolab" must not be used to endorse or promote
16 * products derived from this Software without prior written
17 * permission of Intalio, Inc. For written permission,
18 * please contact info@codehaus.org.
19 *
20 * 4. Products derived from this Software may not be called "Exolab"
21 * nor may "Exolab" appear in their names without prior written
22 * permission of Intalio, Inc. Exolab is a registered
23 * trademark of Intalio, Inc.
24 *
25 * 5. Due credit should be given to the Exolab Project
26 * (http://www.codehaus.org/).
27 *
28 * THIS SOFTWARE IS PROVIDED BY INTALIO, INC. AND CONTRIBUTORS
29 * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
30 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
31 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
32 * INTALIO, INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
33 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
34 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
35 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
36 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
37 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
38 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
39 * OF THE POSSIBILITY OF SUCH DAMAGE.
40 *
41 * Copyright 1999-2003 (C) Intalio, Inc. All Rights Reserved.
42 *
43 * $Id$
44 */
45 package org.codehaus.modello.plugin.java.javasource;
46
47 /*
48 * Copyright (c) 2004, Codehaus.org
49 *
50 * Permission is hereby granted, free of charge, to any person obtaining a copy of
51 * this software and associated documentation files (the "Software"), to deal in
52 * the Software without restriction, including without limitation the rights to
53 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
54 * of the Software, and to permit persons to whom the Software is furnished to do
55 * so, subject to the following conditions:
56 *
57 * The above copyright notice and this permission notice shall be included in all
58 * copies or substantial portions of the Software.
59 *
60 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
61 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
62 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
63 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
64 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
65 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
66 * SOFTWARE.
67 */
68
69 import java.util.ArrayList;
70 import java.util.Collections;
71 import java.util.Enumeration;
72 import java.util.List;
73
74 /**
75 * A class that "SOMEWHAT" represents a Java Doc Comment.
76 *
77 * @author <a href="mailto:kvisco@intalio.com">Keith Visco</a>
78 * @version $Revision$ $Date$
79 */
80 public class JDocComment {
81
82 /**
83 * An ordered list of descriptors
84 */
85 private List<JDocDescriptor> _descriptors = null;
86
87 /**
88 * The internal buffer for this JDocComment
89 */
90 private StringBuilder _comment = null;
91
92 /**
93 * Creates a new JavaDoc Comment
94 */
95 public JDocComment() {
96 super();
97 _descriptors = new ArrayList<JDocDescriptor>();
98 _comment = new StringBuilder();
99 } // -- JDocComment
100
101 /**
102 * Adds the given JDocDescriptor to this JDocComment
103 *
104 * @param jdesc the JDocDescriptor to add
105 */
106 public void addDescriptor(JDocDescriptor jdesc) {
107
108 if (jdesc == null) return;
109 // -- on the fly sorting of descriptors
110 if (_descriptors.size() == 0) {
111 _descriptors.add(jdesc);
112 return;
113 }
114
115 for (int i = 0; i < _descriptors.size(); i++) {
116 JDocDescriptor jdd = _descriptors.get(i);
117
118 short compare = jdesc.compareTo(jdd);
119
120 switch (compare) {
121 case 0: // equal
122 _descriptors.add(i + 1, jdesc);
123 return;
124 case -1: // -- less than
125 _descriptors.add(i, jdesc);
126 return;
127 case 1:
128 // -- keep looking
129 break;
130 }
131 }
132
133 // -- if we make it here we need to add
134 _descriptors.add(jdesc);
135 } // -- addException
136
137 /**
138 * Appends the comment String to this JDocComment
139 *
140 * @param comment the comment to append
141 */
142 public void appendComment(String comment) {
143 _comment.append(comment);
144 } // -- appendComment
145
146 /**
147 * Returns the String value of this JDocComment.
148 *
149 * @return the String value of the JDocComment.
150 */
151 public String getComment() {
152 return _comment.toString();
153 } // -- getComment
154
155 /**
156 * Returns an enumeration of the parameters of this JDocComment
157 *
158 * @return an enumeration of the parameters of this JDocComment
159 */
160 public Enumeration<JDocDescriptor> getDescriptors() {
161 return Collections.enumeration(_descriptors);
162 } // -- getDescriptors
163
164 /**
165 * Returns the length of the comment
166 *
167 * @return the length of the comment
168 */
169 public int getLength() {
170 return _comment.length();
171 } // -- getLength
172
173 /**
174 * Returns the Parameter Descriptor associated with the
175 * given name
176 *
177 * @param name the name of the parameter
178 * @return the Parameter Descriptor associated with the
179 * given name
180 */
181 public JDocDescriptor getParamDescriptor(String name) {
182 if (name == null) return null;
183
184 for (JDocDescriptor jdd : _descriptors) {
185 if (jdd.getType() == JDocDescriptor.PARAM) {
186 if (name.equals(jdd.getName())) return jdd;
187 }
188 }
189 return null;
190 } // -- getParamDescriptor
191
192 /**
193 * prints this JavaDoc comment using the given JSourceWriter
194 *
195 * @param jsw the JSourceWriter to print to
196 */
197 public void print(JSourceWriter jsw) {
198
199 // -- I reuse JComment for printing
200 JComment jComment = new JComment(JComment.JAVADOC_STYLE);
201
202 jComment.setComment(_comment.toString());
203
204 // -- force a separating "*" for readability
205 if (_descriptors.size() > 0) {
206 jComment.appendComment("\n");
207 }
208
209 for (int i = 0; i < _descriptors.size(); i++) {
210 jComment.appendComment("\n");
211 jComment.appendComment(_descriptors.get(i).toString());
212 }
213 jComment.print(jsw);
214 } // -- print
215
216 /**
217 * Sets the comment String of this JDocComment
218 *
219 * @param comment the comment String of this JDocComment
220 */
221 public void setComment(String comment) {
222 _comment.setLength(0);
223 _comment.append(comment);
224 } // -- setComment
225
226 /**
227 * Returns the String representation of this Java Doc Comment
228 *
229 * @return the String representation of this Java Doc Comment
230 */
231 public String toString() {
232 StringBuilder sb = new StringBuilder();
233 sb.append("/**\n");
234 sb.append(" * ");
235
236 sb.append(" */\n");
237
238 return sb.toString();
239 } // -- toString
240 } // -- JDocComment