001: /**
002: * Redistribution and use of this software and associated documentation
003: * ("Software"), with or without modification, are permitted provided
004: * that the following conditions are met:
005: *
006: * 1. Redistributions of source code must retain copyright
007: * statements and notices. Redistributions must also contain a
008: * copy of this document.
009: *
010: * 2. Redistributions in binary form must reproduce the
011: * above copyright notice, this list of conditions and the
012: * following disclaimer in the documentation and/or other
013: * materials provided with the distribution.
014: *
015: * 3. The name "Exolab" must not be used to endorse or promote
016: * products derived from this Software without prior written
017: * permission of Intalio, Inc. For written permission,
018: * please contact info@exolab.org.
019: *
020: * 4. Products derived from this Software may not be called "Exolab"
021: * nor may "Exolab" appear in their names without prior written
022: * permission of Intalio, Inc. Exolab is a registered
023: * trademark of Intalio, Inc.
024: *
025: * 5. Due credit should be given to the Exolab Project
026: * (http://www.exolab.org/).
027: *
028: * THIS SOFTWARE IS PROVIDED BY INTALIO, INC. AND CONTRIBUTORS
029: * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
030: * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
031: * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
032: * INTALIO, INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
033: * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
034: * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
035: * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
036: * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
037: * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
038: * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
039: * OF THE POSSIBILITY OF SUCH DAMAGE.
040: *
041: * Copyright 1999-2003 (C) Intalio, Inc. All Rights Reserved.
042: */package org.exolab.javasource;
043:
044: import java.util.Enumeration;
045: import java.util.Vector;
046:
047: /**
048: * A class that "SOMEWHAT" represents a JavaDoc Comment.
049: *
050: * @author <a href="mailto:keith AT kvisco DOT com">Keith Visco</a>
051: * @version $Revision: 6669 $ $Date: 2005-02-26 17:30:28 -0700 (Sat, 26 Feb 2005) $
052: */
053: public final class JDocComment {
054: //--------------------------------------------------------------------------
055:
056: /** An ordered list of descriptors. */
057: private Vector _descriptors = null;
058:
059: /** The internal buffer for this JDocComment. */
060: private StringBuffer _comment = null;
061:
062: //--------------------------------------------------------------------------
063:
064: /**
065: * Creates a new JavaDoc Comment.
066: */
067: public JDocComment() {
068: super ();
069:
070: _descriptors = new Vector();
071: _comment = new StringBuffer();
072: }
073:
074: /**
075: * Creates a new JavaDoc Comment and initializie it with given JDocDescriptor.
076: *
077: * @param jdesc The JDocDescriptor to add.
078: */
079: public JDocComment(final JDocDescriptor jdesc) {
080: super ();
081:
082: _descriptors = new Vector();
083: _comment = new StringBuffer();
084:
085: addDescriptor(jdesc);
086: }
087:
088: //--------------------------------------------------------------------------
089:
090: /**
091: * Adds the given JDocDescriptor to this JDocComment.
092: *
093: * @param jdesc The JDocDescriptor to add.
094: */
095: public void addDescriptor(final JDocDescriptor jdesc) {
096: if (jdesc == null) {
097: return;
098: }
099: //-- on the fly sorting of descriptors
100: if (_descriptors.size() == 0) {
101: _descriptors.addElement(jdesc);
102: return;
103: }
104:
105: for (int i = 0; i < _descriptors.size(); i++) {
106: JDocDescriptor jdd = (JDocDescriptor) _descriptors
107: .elementAt(i);
108:
109: short compare = jdesc.compareTo(jdd);
110:
111: switch (compare) {
112: case 0: // equal
113: _descriptors.insertElementAt(jdesc, i + 1);
114: return;
115: case -1: //-- less than
116: _descriptors.insertElementAt(jdesc, i);
117: return;
118: default:
119: //-- keep looking
120: break;
121: }
122: }
123:
124: //-- if we make it here we need to add
125: _descriptors.addElement(jdesc);
126: }
127:
128: /**
129: * Appends the provided comment String to this JDocComment.
130: *
131: * @param comment The comment to append.
132: */
133: public void appendComment(final String comment) {
134: _comment.append(comment);
135: }
136:
137: /**
138: * Returns the String value of this JDocComment.
139: *
140: * @return The String value of this JDocComment.
141: */
142: public String getComment() {
143: return _comment.toString();
144: }
145:
146: /**
147: * Sets the comment String of this JDocComment.
148: *
149: * @param comment The comment String of this JDocComment.
150: */
151: public void setComment(final String comment) {
152: _comment.setLength(0);
153: _comment.append(comment);
154: }
155:
156: /**
157: * Returns an Enumeration of the parameters of this JDocComment.
158: *
159: * @return An Enumeration of the parameters of this JDocComment.
160: */
161: public Enumeration getDescriptors() {
162: return _descriptors.elements();
163: }
164:
165: /**
166: * Returns the length of the JavaDoc comment in characters.
167: *
168: * @return The length of the JavaDoc comment in characters.
169: */
170: public int getLength() {
171: return _comment.length();
172: }
173:
174: /**
175: * Returns the Parameter Descriptor associated with the given name.
176: *
177: * @param name The name whose ParamDescriptor is being searched for.
178: * @return the Parameter Descriptor associated with the given name.
179: */
180: public JDocDescriptor getParamDescriptor(final String name) {
181: if (name == null) {
182: return null;
183: }
184:
185: for (int i = 0; i < _descriptors.size(); i++) {
186: JDocDescriptor jdd = (JDocDescriptor) _descriptors
187: .elementAt(i);
188: if (jdd.getType() == JDocDescriptor.PARAM) {
189: if (name.equals(jdd.getName())) {
190: return jdd;
191: }
192: }
193: }
194: return null;
195: }
196:
197: //--------------------------------------------------------------------------
198:
199: /**
200: * Prints this JavaDoc comment using the given JSourceWriter.
201: *
202: * @param jsw The JSourceWriter to print to.
203: */
204: public void print(final JSourceWriter jsw) {
205: //-- I reuse JComment for printing
206: JComment jComment = new JComment(JComment.JAVADOC_STYLE);
207:
208: jComment.setComment(_comment.toString());
209:
210: //-- force a separating "*" for readability
211: if (_descriptors.size() > 0) {
212: jComment.appendComment("\n");
213: }
214:
215: for (int i = 0; i < _descriptors.size(); i++) {
216: jComment.appendComment("\n");
217: jComment
218: .appendComment(_descriptors.elementAt(i).toString());
219: }
220: jComment.print(jsw);
221: }
222:
223: /**
224: * {@inheritDoc}
225: */
226: public String toString() {
227: StringBuffer sb = new StringBuffer();
228: sb.append("/**\n");
229: sb.append(" * ");
230: sb.append(" */\n");
231: return sb.toString();
232: }
233:
234: //--------------------------------------------------------------------------
235: }
|