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-2002 (C) Intalio, Inc. All Rights Reserved.
42   *
43   * $Id$
44   */
45  
46  package org.codehaus.modello.plugin.java.javasource;
47  
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.Vector;
72  
73  /**
74   * A class which holds information about the methods of
75   * a JClass.
76   * Modelled closely after the Java Reflection API.
77   * This class is part of package which is used to
78   * create source code.
79   * @author <a href="mailto:kvisco@intalio.com">Keith Visco</a>
80   * @version $Revision$ $Date$
81   **/
82  public class JMethod implements JMember
83  {
84  
85  
86      /**
87       * The set of classes that contain this JMethod.
88       **/
89      private Vector<JClass> _classes = null;
90  
91      /**
92       * The JavaDoc comment for this JMethod. This
93       * will overwrite the JavaDoc for the
94       * JMethodSignature.
95       **/
96      private JDocComment jdc = null;
97  
98      /**
99       * The source code for this method
100      **/
101     private JSourceCode source = null;
102 
103     /**
104      * The signature for this method.
105      **/
106     private JMethodSignature _signature = null;
107 
108     /**
109      * The annotation(s) for this method.
110      */
111     private JAnnotations annotations = null;
112 
113     /**
114      * Creates a new JMethod with the given name and "void" return type.
115      *
116      * @param name, the method name. Must not be null.
117      **/
118     public JMethod( String name )
119     {
120         this( name, null, null );
121     } //-- JMethod
122 
123     /**
124      * Creates a new JMethod with the given name and returnType.
125      * For "void" return types, simply pass in null as the returnType.
126      *
127      * @param name, the method name. Must not be null.
128      * @param returnType the return type of the method. May be null.
129      * @deprecated removed in future version of javasource
130      **/
131     public JMethod( JType returnType, String name )
132     {
133         this( name, returnType, null );
134     } //-- JMethod
135 
136     /**
137      * Creates a new JMethod with the given name and returnType.
138      * For "void" return types, simply pass in null as the returnType.
139      *
140      * @param name, the method name. Must not be null.
141      * @param returnType the return type of the method. May be null.
142      * @param returnDoc Javadoc comment for the &#064;return annotation. If
143      *            null, a default (and mostly useless) javadoc comment will be
144      *            generated.
145      **/
146     public JMethod( final String name, final JType returnType, final String returnDoc )
147     {
148         if ( ( name == null ) || ( name.length() == 0 ) )
149         {
150             String err = "The method name must not be null or zero-length";
151             throw new IllegalArgumentException( err );
152         }
153 
154         _classes = new Vector<JClass>( 1 );
155         this.source = new JSourceCode();
156         _signature = new JMethodSignature( name, returnType );
157         this.jdc = _signature.getJDocComment();
158         jdc.appendComment( "Method " + name + "." );
159 
160         //-- create comment
161         if ( returnType != null )
162         {
163             if ( returnDoc != null && returnDoc.length() > 0 )
164             {
165                 jdc.addDescriptor( JDocDescriptor.createReturnDesc( returnDoc ) );
166             }
167             else
168             {
169                 jdc.addDescriptor( JDocDescriptor.createReturnDesc( returnType.getLocalName() ) );
170             }
171         }
172     }
173 
174     /**
175      * Adds the given Exception to this Method's throws clause.
176      *
177      * @param exp the JClass representing the Exception
178      **/
179     public void addException( JClass exp )
180     {
181         _signature.addException( exp );
182     } //-- addException
183 
184 
185     /**
186      * Adds the given parameter to this JMethod's list of parameters.
187      *
188      * @param parameter the parameter to add to the this Methods
189      * list of parameters.
190      * @throws java.lang.IllegalArgumentException when a parameter already
191      * exists for this Method with the same name as the new parameter
192      **/
193     public void addParameter( JParameter parameter )
194         throws IllegalArgumentException
195     {
196         _signature.addParameter( parameter );
197     } //-- addParameter
198 
199     /**
200      * Returns the JDocComment describing this member.
201      * @return the JDocComment describing this member.
202      **/
203     public JDocComment getJDocComment()
204     {
205         return this.jdc;
206     } //-- getJDocComment
207 
208     /**
209      * Returns the class in which this JMember has been declared
210      * @return the class in which this JMember has been declared
211      **
212      public JClass getDeclaringClass() {
213      return _declaringClass;
214      } //-- getDeclaringClass
215      */
216 
217     /**
218      * Returns the exceptions that this JMember throws.
219      *
220      * @return the exceptions that this JMember throws.
221      **/
222     public JClass[] getExceptions()
223     {
224         return _signature.getExceptions();
225     } //-- getExceptions
226 
227 
228     /**
229      * Returns the modifiers for this JMember.
230      *
231      * @return the modifiers for this JMember.
232      **/
233     public JModifiers getModifiers()
234     {
235         return _signature.getModifiers();
236     } //-- getModifiers
237 
238     /**
239      * Returns the name of this JMember.
240      *
241      * @return the name of this JMember.
242      **/
243     public String getName()
244     {
245         return _signature.getName();
246     } //-- getName
247 
248     /**
249      * Returns the JParameter at the given index.
250      *
251      * @param index the index of the JParameter to return.
252      * @return the JParameter at the given index.
253      **/
254     public JParameter getParameter( int index )
255     {
256         return _signature.getParameter( index );
257     } //-- getParameter
258 
259     /**
260      * Returns the set of JParameters for this JMethod.
261      * <BR>
262      * <B>Note:</B> the array is a copy, the params in the array
263      * are the actual references.
264      *
265      * @return the set of JParameters for this JMethod
266      **/
267     public JParameter[] getParameters()
268     {
269         return _signature.getParameters();
270     } //-- getParameters
271 
272     /**
273      * Returns the JType that represents the return type of the method.
274      *
275      * @return the JType that represents the return type of the method.
276      **/
277     public JType getReturnType()
278     {
279         return _signature.getReturnType();
280     } //-- getReturnType
281 
282     /**
283      * Returns the JMethodSignature for this JMethod.
284      *
285      * @return the JMethodSignature for this JMethod.
286      **/
287     public JMethodSignature getSignature()
288     {
289         return _signature;
290     } //-- getSignature
291 
292     /**
293      * Returns the JSourceCode for the method body.
294      *
295      * @return the JSourceCode for the method body.
296      **/
297     public JSourceCode getSourceCode()
298     {
299         return this.source;
300     } //-- getSourceCode
301 
302     /**
303      * Sets the comment describing this member. The comment
304      * will be printed when this member is printed with the
305      * Class Printer.
306      *
307      * @param comment the comment for this member
308      * @see #getJDocComment
309      **/
310     public void setComment( String comment )
311     {
312         jdc.setComment( comment );
313     } //-- setComment
314 
315     /**
316      * Sets the JModifiers for this JMethod. This
317      * JMethod will use only a copy of the JModifiers.
318      * <B>Note:</B> The JModifiers will be set in the
319      * containing JMethodSignature. If the JMethodSignature
320      * is used by other methods, keep in mind that it will be
321      * changed.
322      *
323      * @param modifiers the JModifiers to set.
324      **/
325     public void setModifiers( JModifiers modifiers )
326     {
327         _signature.setModifiers( modifiers );
328     } //-- setModifiers
329 
330     /**
331      * Sets the given string as the source code (method body)
332      * for this JMethod.
333      *
334      * @param source the String that represents the method body.
335      **/
336     public void setSourceCode( String source )
337     {
338         this.source = new JSourceCode( source );
339     } //-- setSource
340 
341     /**
342      * Sets the given JSourceCode as the source code (method body)
343      * for this JMethod.
344      *
345      * @param source the JSourceCode that represents the method body.
346      **/
347     public void setSourceCode( JSourceCode source )
348     {
349         this.source = source;
350     } //-- setSource;
351 
352     /**
353      * Prints this JMethod to the given JSourceWriter.
354      *
355      * @param jsw the JSourceWriter to print to.
356      **/
357     public void print( JSourceWriter jsw )
358     {
359 
360         //------------/
361         //- Java Doc -/
362         //------------/
363 
364         jdc.print( jsw );
365 
366         //--------------------/
367         // - Annotations     -/
368         //--------------------/
369 
370         JAnnotations annotations = getAnnotations();
371         if ( annotations != null ) annotations.print( jsw );
372 
373         //--------------------/
374         //- Method Signature -/
375         //--------------------/
376 
377         _signature.print( jsw, false );
378 
379         if ( _signature.getModifiers().isAbstract() )
380         {
381             jsw.writeln( ";" );
382         }
383         else
384         {
385             jsw.writeln();
386             jsw.writeln( "{" );
387             source.print( jsw );
388             jsw.write( "} //-- " );
389             jsw.writeln( toString() );
390         }
391     } //-- print
392 
393 
394     /**
395      * Returns the String representation of this JMethod,
396      * which is the method prototype.
397      * @return the String representation of this JMethod, which
398      * is simply the method prototype
399      **/
400     public String toString()
401     {
402         return _signature.toString();
403     } //-- toString
404 
405     //---------------------/
406     //- PROTECTED METHODS -/
407     //---------------------/
408 
409     /**
410      * Adds the given JClass to the set of classes that
411      * contain this method.
412      *
413      * @param jClass the JClass to add as one of
414      * the JClasses that contain this method.
415      **/
416     protected void addDeclaringClass( JClass jClass )
417     {
418         _classes.addElement( jClass );
419     } //-- addDeclaringClass
420 
421     /**
422      * Removes the given JClass from the set of classes that
423      * contain this method.
424      *
425      * @param jClass the JClass to add as one of
426      * the JClasses that contain this method.
427      **/
428     protected void removeDeclaringClass( JClass jClass )
429     {
430         _classes.removeElement( jClass );
431     } //-- removeDeclaringClass
432 
433     protected String[] getParameterClassNames()
434     {
435         return _signature.getParameterClassNames();
436     } //-- getParameterClassNames
437 
438     /**
439      * @return the annotations
440      */
441     public JAnnotations getAnnotations()
442     {
443         return annotations;
444     }
445 
446     /**
447      * @param annotation the annotation to append
448      */
449     public void appendAnnotation( String annotation )
450     {
451         if ( annotations == null )
452         {
453             annotations = new JAnnotations();
454         }
455         annotations.appendAnnotation( annotation );
456     }
457 
458     /**
459      * @param annotations the annotations to set
460      */
461     public void setAnnotations( JAnnotations annotations )
462     {
463         this.annotations = annotations;
464     }
465 
466 } //-- JMember