ParameterTagsHandler


1   /*
2    * Copyright (c) 2001, 2002 The XDoclet team
3    * All rights reserved.
4    */
5   package xdoclet.tagshandler;
6   
7   import java.util.Collection  ;
8   import java.util.Iterator  ;
9   import java.util.Properties  ;
10  import java.util.StringTokenizer  ;
11  
12  import xjavadoc.*;
13  
14  import xdoclet.XDocletException;
15  import xdoclet.util.TypeConversionUtil;
16  
17  /**
18   * @author               Ara Abrahamian (ara_e@email.com)
19   * @created              Oct 15, 2001
20   * @xdoclet.taghandler   namespace="Parameter"
21   * @version              $Revision: 1.19 $
22   */
23  public class ParameterTagsHandler extends AbstractProgramElementTagsHandler
24  {
25  
26      /**
27       * The current method's current parameter. forAllMethodParams sets the value while looping over the parameters of
28       * current method.
29       *
30       * @see   #forAllMethodParams(java.lang.String)
31       */
32      protected static XParameter currentMethodParameter;
33  
34      /**
35       * The <code>currentMethodParamTag</code> holds the current ParamTag corresponding to the current Parameter.
36       *
37       * @see   #forAllMethodParams(java.lang.String)
38       */
39      protected static XTag currentMethodParamTag;
40      protected String   currentName;
41  
42      public static String   getMethodParamTypeFor(XParameter param)
43      {
44          return param.getType().getQualifiedName() + param.getDimensionAsString();
45      }
46  
47      /**
48       * Returns the type of the current method parameter, current method parameter is set inside a forAllMethodParams tag
49       * in each iteration. Do not forget to add array dimensions if any.
50       *
51       * @param attributes
52       * @return                      Description of the Returned Value
53       * @exception XDocletException  Description of Exception
54       * @doc.tag                     type="content"
55       */
56      public String   methodParamType(Properties   attributes) throws XDocletException
57      {
58          return getMethodParamTypeFor(currentMethodParameter);
59      }
60  
61      /**
62       * The <code>methodParamDescription</code> method returns the comment text associated with the ParamTag for the
63       * current Parameter
64       *
65       * @return                      a <code>String</code> value
66       * @exception XDocletException  if an error occurs
67       * @doc.tag                     type="content"
68       */
69      public String   methodParamDescription() throws XDocletException
70      {
71          if (currentMethodParamTag == null) {
72              return "no description";
73          }
74          // end of if ()
75  
76          return currentMethodParamTag.getValue();
77      }
78  
79      /**
80       * Returns the name of the current method parameter, current method parameter is set inside a forAllMethodParams tag
81       * in each iteration.
82       *
83       * @return                      name of the current method parameter
84       * @exception XDocletException  Description of Exception
85       * @doc.tag                     type="content"
86       */
87      public String   methodParamName() throws XDocletException
88      {
89          return currentMethodParameter.getName();
90      }
91  
92      /**
93       * Iterates over all parameters of current method and evaluates the body of the tag for each method.
94       *
95       * @param template              The body of the block tag
96       * @exception XDocletException  Description of Exception
97       * @doc.tag                     type="block"
98       */
99      public void forAllMethodParams(String   template) throws XDocletException
100     {
101         forAllParams(getCurrentMethod(), template);
102     }
103 
104     /**
105      * Iterates over all parameters of current constructor and evaluates the body of the tag for each method.
106      *
107      * @param template              The body of the block tag
108      * @exception XDocletException  Description of Exception
109      * @doc.tag                     type="block"
110      */
111     public void forAllConstructorParams(String   template) throws XDocletException
112     {
113         forAllParams(getCurrentConstructor(), template);
114     }
115 
116     /**
117      * Evaluates the body of the tag if current method/constructor has parameters.
118      *
119      * @param template              The body of the block tag
120      * @param attributes
121      * @exception XDocletException  Description of Exception
122      * @doc.tag                     type="block"
123      * @doc.param                   name="forConstructor" optional="true" values="true,false" description="If true, then
124      *      look for parameters of current constructor instead of current method"
125      */
126     public void ifHasParams(String   template, Properties   attributes) throws XDocletException
127     {
128         String   constr = (String  ) attributes.get("forConstructor");
129 
130         Collection   parameters;
131 
132         if ("true".equals(constr)) {
133             parameters = getCurrentConstructor().getParameters();
134         }
135         else {
136             parameters = getCurrentMethod().getParameters();
137         }
138 
139         if (parameters != null && parameters.size() > 0)
140             generate(template);
141     }
142 
143     /**
144      * Iterates over all parameters in current method and returns a string containing definition of all those
145      * parameters.
146      *
147      * @param attributes            The attributes of the template tag
148      * @return                      Description of the Returned Value
149      * @exception XDocletException  Description of Exception
150      * @doc.tag                     type="block"
151      * @doc.param                   name="includeDefinition" optional="true" values="true,false" description="If true
152      *      then include the parameter type of parameters in the composed string."
153      * @doc.param                   name="forConstructor" optional="true" values="true,false" description="If true, then
154      *      look for parameters of current constructor instead of current method"
155      */
156     public String   parameterList(Properties   attributes) throws XDocletException
157     {
158         boolean incl = TypeConversionUtil.stringToBoolean(attributes.getProperty("includeDefinition"), true);
159         boolean constr = TypeConversionUtil.stringToBoolean(attributes.getProperty("forConstructor"), false);
160 
161         Collection   parameters;
162 
163         if (constr == true) {
164             parameters = getCurrentConstructor().getParameters();
165         }
166         else {
167             parameters = getCurrentMethod().getParameters();
168         }
169 
170         StringBuffer   sbuf = new StringBuffer  ();
171         String   type = null;
172         String   name = null;
173 
174         boolean comma = false;
175 
176         for (Iterator   i = parameters.iterator(); i.hasNext(); ) {
177             XParameter parameter = (XParameter) i.next();
178 
179             type = getMethodParamTypeFor(parameter);
180 
181             name = parameter.getName();
182             if (type == null) {
183                 throw new XDocletException("FATAL:" + name);
184             }
185 
186             if (comma) {
187                 sbuf.append(',');
188             }
189 
190             if (incl == true) {
191                 sbuf.append(type).append(' ').append(name);
192             }
193             else {
194                 sbuf.append(name);
195             }
196 
197             comma = true;
198         }
199 
200         String   result = sbuf.toString();
201 
202         return result;
203     }
204 
205     /**
206      * Gets the value of the parameter specified by paramName of current tag, and assuming the value has the format of a
207      * typical method definition extracts of parameter types out of it and evaluates the body for each parameter type.
208      * current parameter type can be accessed as &lt;XDtParameter:currentToken/&gt;. Also gives back parameter name as
209      * &lt;XDtParameter:currentName/&gt;
210      *
211      * @param attributes            The attributes of the template tag
212      * @param template              The body of the block tag
213      * @exception XDocletException  Description of Exception
214      * @doc.tag                     type="block"
215      * @doc.param                   name="paramName" optional="false" description="The parameter name that its value is
216      *      used for extracting parameter types out of it."
217      */
218     public void forAllParameterTypes(String   template, Properties   attributes) throws XDocletException
219     {
220         String   paramName = attributes.getProperty("paramName");
221         String   value = getCurrentClassTag().getAttributeValue(paramName);
222         String   oldToken = currentToken;
223 
224         // findAll(int p1, int p2) -> int p1, int p2
225         value = value.substring(value.indexOf('(') + 1, value.lastIndexOf(')'));
226 
227         StringTokenizer   st = new StringTokenizer  (value, ",", false);
228         int tokenNr = 0;
229 
230         while (st.hasMoreTokens()) {
231             tokenNr++;
232             currentToken = st.nextToken().trim();
233 
234             int spaceposBetweenTypeAndName = currentToken.lastIndexOf(' ');
235 
236             spaceposBetweenTypeAndName = spaceposBetweenTypeAndName == -1 ? currentToken.lastIndexOf('\t') : spaceposBetweenTypeAndName;
237 
238             if (spaceposBetweenTypeAndName != -1) {
239                 currentName = currentToken.substring(spaceposBetweenTypeAndName).trim();
240                 currentToken = currentToken.substring(0, spaceposBetweenTypeAndName).trim();
241             }
242             else {
243                 currentName = "param" + tokenNr;
244             }
245 
246             generate(template);
247         }
248 
249         currentToken = oldToken;
250     }
251 
252     /**
253      * return name of parameter currently being iterated - ugly hack...
254      *
255      * @return
256      * @doc.tag   type="content"
257      */
258     public String   currentName()
259     {
260         return currentName;
261     }
262 
263     /**
264      * Describe what the method does
265      *
266      * @param member                Describe what the parameter does
267      * @param template              Describe what the parameter does
268      * @exception XDocletException  Describe the exception
269      */
270     private void forAllParams(XExecutableMember member, String   template) throws XDocletException
271     {
272         Collection   parameters = member.getParameters();
273         Collection   paramTags = member.getDoc().getTags("param");
274 
275         for (Iterator   k = parameters.iterator(); k.hasNext(); ) {
276             currentMethodParameter = (XParameter) k.next();
277             currentMethodParamTag = null;
278             for (Iterator   tagIterator = paramTags.iterator(); tagIterator.hasNext(); ) {
279                 // find @param xxx
280                 XTag paramTag = (XTag) tagIterator.next();
281                 String   paramTagValue = paramTag.getValue();
282                 StringTokenizer   st = new StringTokenizer  (paramTagValue);
283                 String   paramTagParam = null;
284 
285                 if (st.hasMoreTokens()) {
286                     paramTagParam = st.nextToken();
287                 }
288 
289                 if (currentMethodParameter.getName().equals(paramTagParam)) {
290                     currentMethodParamTag = paramTag;
291                     break;
292                 }
293             }
294             generate(template);
295         }
296     }
297 }
298
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags