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      * @return the Parameter Descriptor associated with the
191      * given name
192      */
193     public JDocDescriptor getParamDescriptor( String name )
194     {
195         if ( name == null ) return null;
196 
197         for ( int i = 0; i < _descriptors.size(); i++ )
198         {
199             JDocDescriptor jdd
200                 = (JDocDescriptor) _descriptors.elementAt( i );
201             if ( jdd.getType() == JDocDescriptor.PARAM )
202             {
203                 if ( name.equals( jdd.getName() ) )
204                     return jdd;
205             }
206         }
207         return null;
208 
209     } //-- getParamDescriptor
210 
211 
212     /**
213      * prints this JavaDoc comment using the given JSourceWriter
214      *
215      * @param jsw the JSourceWriter to print to
216      */
217     public void print( JSourceWriter jsw )
218     {
219 
220         //-- I reuse JComment for printing
221         JComment jComment = new JComment( JComment.JAVADOC_STYLE );
222 
223         jComment.setComment( _comment.toString() );
224 
225         //-- force a separating "*" for readability
226         if ( _descriptors.size() > 0 )
227         {
228             jComment.appendComment( "\n" );
229         }
230 
231         for ( int i = 0; i < _descriptors.size(); i++ )
232         {
233             jComment.appendComment( "\n" );
234             jComment.appendComment( _descriptors.elementAt( i ).toString() );
235         }
236         jComment.print( jsw );
237     } //-- print
238 
239     /**
240      * Sets the comment String of this JDocComment
241      *
242      * @param comment the comment String of this JDocComment
243      */
244     public void setComment( String comment )
245     {
246         _comment.setLength( 0 );
247         _comment.append( comment );
248     } //-- setComment
249 
250     /**
251      * Returns the String representation of this Java Doc Comment
252      *
253      * @return the String representation of this Java Doc Comment
254      */
255     public String toString()
256     {
257         StringBuffer sb = new StringBuffer();
258         sb.append( "/**\n" );
259         sb.append( " * " );
260 
261         sb.append( " */\n" );
262 
263         return sb.toString();
264     } //-- toString
265 
266 } //-- JDocComment
267