View Javadoc

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  
46  
47  package org.codehaus.modello.plugin.java.javasource;
48  
49  /*
50   * Copyright (c) 2004, Codehaus.org
51   *
52   * Permission is hereby granted, free of charge, to any person obtaining a copy of
53   * this software and associated documentation files (the "Software"), to deal in
54   * the Software without restriction, including without limitation the rights to
55   * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
56   * of the Software, and to permit persons to whom the Software is furnished to do
57   * so, subject to the following conditions:
58   *
59   * The above copyright notice and this permission notice shall be included in all
60   * copies or substantial portions of the Software.
61   *
62   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
63   * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
64   * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
65   * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
66   * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
67   * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
68   * SOFTWARE.
69   */
70  
71  import java.util.Enumeration;
72  import java.util.Vector;
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  
84      /**
85       * An ordered list of descriptors
86       */
87      private Vector<JDocDescriptor> _descriptors = null;
88  
89      /**
90       * The internal buffer for this JDocComment
91       */
92      private StringBuffer _comment = null;
93  
94      /**
95       * Creates a new JavaDoc Comment
96       */
97      public JDocComment()
98      {
99          super();
100         _descriptors = new Vector<JDocDescriptor>();
101         _comment = new StringBuffer();
102     } //--  JDocComment
103 
104     /**
105      * Adds the given JDocDescriptor to this JDocComment
106      *
107      * @param jdesc the JDocDescriptor to add
108      */
109     public void addDescriptor( JDocDescriptor jdesc )
110     {
111 
112         if ( jdesc == null ) return;
113         //-- on the fly sorting of descriptors
114         if ( _descriptors.size() == 0 )
115         {
116             _descriptors.addElement( jdesc );
117             return;
118         }
119 
120         for ( int i = 0; i < _descriptors.size(); i++ )
121         {
122             JDocDescriptor jdd
123                 = (JDocDescriptor) _descriptors.elementAt( i );
124 
125             short compare = jdesc.compareTo( jdd );
126 
127             switch ( compare )
128             {
129                 case 0: // equal
130                     _descriptors.insertElementAt( jdesc, i + 1 );
131                     return;
132                 case -1: //-- less than
133                     _descriptors.insertElementAt( jdesc, i );
134                     return;
135                 case 1:
136                     //-- keep looking
137                     break;
138             }
139         }
140 
141         //-- if we make it here we need to add
142         _descriptors.addElement( jdesc );
143 
144     } //-- addException
145 
146     /**
147      * Appends the comment String to this JDocComment
148      *
149      * @param comment the comment to append
150      */
151     public void appendComment( String comment )
152     {
153         _comment.append( comment );
154     } //-- appendComment
155 
156     /**
157      * Returns the String value of this JDocComment.
158      *
159      * @return the String value of the JDocComment.
160      */
161     public String getComment()
162     {
163         return _comment.toString();
164     } //-- getComment
165 
166     /**
167      * Returns an enumeration of the parameters of this JDocComment
168      *
169      * @return an enumeration of the parameters of this JDocComment
170      */
171     public Enumeration<JDocDescriptor> getDescriptors()
172     {
173         return _descriptors.elements();
174     } //-- getDescriptors
175 
176     /**
177      * Returns the length of the comment
178      *
179      * @return the length of the comment
180      */
181     public int getLength()
182     {
183         return _comment.length();
184     } //-- getLength
185 
186     /**
187      * Returns the Parameter Descriptor associated with the
188      * given name
189      *
190      * @param name the name of the parameter
191      * @return the Parameter Descriptor associated with the
192      * given name
193      */
194     public JDocDescriptor getParamDescriptor( String name )
195     {
196         if ( name == null ) return null;
197 
198         for ( int i = 0; i < _descriptors.size(); i++ )
199         {
200             JDocDescriptor jdd
201                 = (JDocDescriptor) _descriptors.elementAt( i );
202             if ( jdd.getType() == JDocDescriptor.PARAM )
203             {
204                 if ( name.equals( jdd.getName() ) )
205                     return jdd;
206             }
207         }
208         return null;
209 
210     } //-- getParamDescriptor
211 
212 
213     /**
214      * prints this JavaDoc comment using the given JSourceWriter
215      *
216      * @param jsw the JSourceWriter to print to
217      */
218     public void print( JSourceWriter jsw )
219     {
220 
221         //-- I reuse JComment for printing
222         JComment jComment = new JComment( JComment.JAVADOC_STYLE );
223 
224         jComment.setComment( _comment.toString() );
225 
226         //-- force a separating "*" for readability
227         if ( _descriptors.size() > 0 )
228         {
229             jComment.appendComment( "\n" );
230         }
231 
232         for ( int i = 0; i < _descriptors.size(); i++ )
233         {
234             jComment.appendComment( "\n" );
235             jComment.appendComment( _descriptors.elementAt( i ).toString() );
236         }
237         jComment.print( jsw );
238     } //-- print
239 
240     /**
241      * Sets the comment String of this JDocComment
242      *
243      * @param comment the comment String of this JDocComment
244      */
245     public void setComment( String comment )
246     {
247         _comment.setLength( 0 );
248         _comment.append( comment );
249     } //-- setComment
250 
251     /**
252      * Returns the String representation of this Java Doc Comment
253      *
254      * @return the String representation of this Java Doc Comment
255      */
256     public String toString()
257     {
258         StringBuffer sb = new StringBuffer();
259         sb.append( "/**\n" );
260         sb.append( " * " );
261 
262         sb.append( " */\n" );
263 
264         return sb.toString();
265     } //-- toString
266 
267 } //-- JDocComment
268