Java > Open Source Codes > xdoclet > tagshandler > ConstructorTagsHandler


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
9 import java.util.Iterator ;
10 import java.util.Properties ;
11 import java.util.SortedSet ;
12 import java.util.TreeSet ;
13
14 import org.apache.commons.logging.Log;
15
16 import xjavadoc.XClass;
17 import xjavadoc.XConstructor;
18
19 import xdoclet.XDocletException;
20 import xdoclet.util.DocletUtil;
21 import xdoclet.util.LogUtil;
22
23 /**
24  * @author Jerome Bernard (jerome.bernard@xtremejava.com)
25  * @created Jan 18, 2002
26  * @xdoclet.taghandler namespace="Constructor"
27  * @version $Revision: 1.13 $
28  */
29 public class ConstructorTagsHandler extends AbstractProgramElementTagsHandler
30 {
31
32     /**
33      * Evaluate the body if current class has a constructor with the specified name+parameters. If parameters not
34      * specified then any constructor with the given name and any set of parameters is considered equal to the given
35      * constructor name and so the test result is positive and the body is evaluated. This constructor change the
36      * current constructor to the one specified.
37      *
38      * @param template The body of the block tag
39      * @param attributes The attributes of the template tag
40      * @exception XDocletException Description of Exception
41      * @see #ifHasConstructor(java.lang.String,java.util.Properties)
42      * @doc.tag type="block"
43      * @doc.param name="name" optional="false" description="The name of the constructor we're
44      * searching for its existence in current class."
45      * @doc.param name="parameters" optional="true" description="We're searching for a constructor
46      * that has the exact set of parameters specified in parameters param."
47      * @doc.param name="delimiter" optional="true" description="The parameters param is delimited by
48      * the string specified in delimiter parameter."
49      */
50     public void setCurrentConstructor(String template, Properties attributes) throws XDocletException
51     {
52         String constructorName = attributes.getProperty("name");
53         String parametersStr = attributes.getProperty("parameters");
54         String delimiter = attributes.getProperty("delimiter");
55
56         String [] parameters = null;
57
58         if (parametersStr != null) {
59             if (delimiter == null) {
60                 delimiter = PARAMETER_DELIMITER;
61             }
62
63             parameters = DocletUtil.tokenizeDelimitedToArray(parametersStr, delimiter);
64         }
65
66         XConstructor oldConstructor = getCurrentConstructor();
67
68         if (hasConstructor(getCurrentClass(), constructorName, parameters, true)) {
69             generate(template);
70         }
71
72         setCurrentConstructor(oldConstructor);
73     }
74
75     /**
76      * The comment for the current constructor.
77      *
78      * @param attributes The attributes of the template tag
79      * @return Description of the Returned Value
80      * @exception XDocletException Description of Exception
81      * @see ClassTagsHandler#classComment(java.util.Properties)
82      * @doc.tag type="content"
83      * @doc.param name="no-comment-signs" optional="true" values="true,false" description="If true
84      * then don't decorate the comment with comment signs."
85      * @doc.param name="indent" optional="true" description="Number of spaces to indent the comment.
86      * Default is 0."
87      */
88     public String constructorComment(Properties attributes) throws XDocletException
89     {
90         return memberComment(attributes, FOR_CONSTRUCTOR);
91     }
92
93     /**
94      * Iterates over all exceptions thrown by the current or specified constructor and returns a string containing
95      * definition of all those exceptions.
96      *
97      * @param attributes The attributes of the template tag
98      * @return throws clause for the constructor
99      * @exception XDocletException Description of Exception
100      * @doc.tag type="block"
101      * @doc.param name="constructor" optional="true" description="The constructor name of which
102      * exceptions list is extracted. If not specified then current constructor is used."
103      * @doc.param name="skip" optional="true" description="A comma-separated list of exceptions that
104      * should be skipped and not put into the list."
105      * @doc.param name="append" optional="true" description="A comma-separated list of exceptions that
106      * should be always appended regardless if current constructor has that exception defined or not."
107      */
108     public String exceptionList(Properties attributes) throws XDocletException
109     {
110         return exceptionList(attributes, FOR_CONSTRUCTOR);
111     }
112
113     /**
114      * Loops through all constructors for all classes after first sorting all the constructors.
115      *
116      * @param template The body of the block tag
117      * @param attributes The attributes of the template tag
118      * @exception XDocletException Description of Exception
119      * @doc.tag type="block"
120      * @doc.param name="type" optional="true" description="For all classes by the type."
121      * @doc.param name="extent" optional="true" values="concrete-type,superclass,hierarchy"
122      * description="Specifies the extent of the type search. If concrete-type then only check the concrete type, if
123      * superclass then check also superclass, if hierarchy then search the whole hierarchy and find if the class is
124      * of the specified type. Default is hierarchy."
125      */
126     public void forAllClassConstructors(String template, Properties attributes) throws XDocletException
127     {
128         String typeName = attributes.getProperty("type");
129         int extent = TypeTagsHandler.extractExtentType(attributes.getProperty("extent"));
130
131         SortedSet constructors = new TreeSet ();
132
133         for (Iterator i = getAllClasses().iterator(); i.hasNext(); ) {
134             XClass clazz = (XClass) i.next();
135
136             if (typeName == null || TypeTagsHandler.isOfType(clazz, typeName, extent)) {
137                 Collection classConstructors = clazz.getConstructors();
138
139                 constructors.addAll(classConstructors);
140
141             }
142         }
143
144         Iterator constructorIterator = constructors.iterator();
145
146         while (constructorIterator.hasNext()) {
147             XConstructor current = (XConstructor) constructorIterator.next();
148
149             setCurrentClass(current.getContainingClass());
150             setCurrentConstructor(current);
151
152             generate(template);
153         }
154     }
155
156     /**
157      * Iterates over all constructors of current class and evaluates the body of the tag for each constructor.
158      *
159      * @param template The body of the block tag
160      * @param attributes The attributes of the template tag
161      * @exception XDocletException Description of Exception
162      * @doc.tag type="block"
163      * @doc.param name="superclasses" optional="true" values="true,false" description="If true then
164      * traverse superclasses also, otherwise look up the tag in current concrete class only."
165      * @doc.param name="sort" optional="true" values="true,false" description="If true then sort the
166      * constructors list."
167      */
168     public void forAllConstructors(String template, Properties attributes) throws XDocletException
169     {
170         forAllMembers(template, attributes, FOR_CONSTRUCTOR);
171     }
172
173     /**
174      * Evaluates the body if current constructor doesn't have at least one tag with the specified name.
175      *
176      * @param template The body of the block tag
177      * @param attributes The attributes of the template tag
178      * @exception XDocletException Description of Exception
179      * @doc.tag type="block"
180      * @doc.param name="tagName" optional="false" description="The tag name."
181      * @doc.param name="paramName" description="The parameter name. If not specified, then the raw
182      * content of the tag is returned."
183      * @doc.param name="paramNum" description="The zero-based parameter number. It's used if the user
184      * used the space-separated format for specifying parameters."
185      * @doc.param name="error" description="Show this error message if no tag found."
186      */
187     public void ifDoesntHaveConstructorTag(String template, Properties attributes) throws XDocletException
188     {
189         if (!hasTag(attributes, FOR_CONSTRUCTOR)) {
190             generate(template);
191         }
192         else {
193             String error = attributes.getProperty("error");
194
195             if (error != null) {
196                 getEngine().print(error);
197             }
198         }
199     }
200
201     /**
202      * Evaluates the body if current constructor has at least one tag with the specified name.
203      *
204      * @param template The body of the block tag
205      * @param attributes The attributes of the template tag
206      * @exception XDocletException Description of Exception
207      * @doc.tag type="block"
208      * @doc.param name="tagName" optional="false" description="The tag name."
209      * @doc.param name="paramName" description="The parameter name. If not specified, then the raw
210      * content of the tag is returned."
211      * @doc.param name="paramNum" description="The zero-based parameter number. It's used if the user
212      * used the space-separated format for specifying parameters."
213      * @doc.param name="error" description="Show this error message if no tag found."
214      */
215     public void ifHasConstructorTag(String template, Properties attributes) throws XDocletException
216     {
217         if (hasTag(attributes, FOR_CONSTRUCTOR)) {
218             generate(template);
219         }
220         else {
221             String error = attributes.getProperty("error");
222
223             if (error != null) {
224                 getEngine().print(error);
225             }
226         }
227     }
228
229     /**
230      * Evaluate the current block, and then restore the current constructor before continuing.
231      *
232      * @param template The body of the block tag
233      * @param attributes The attributes of the template tag
234      * @exception XDocletException Description of Exception
235      * @doc.tag type="block"
236      */
237     public void executeAndRestoreConstructor(String template, Properties attributes) throws XDocletException
238     {
239         XConstructor constructor = getCurrentConstructor();
240
241         generate(template);
242         setCurrentConstructor(constructor);
243     }
244
245     /**
246      * Evaluates the body if value for the constructor tag equals the specified value.
247      *
248      * @param template The body of the block tag
249      * @param attributes The attributes of the template tag
250      * @exception XDocletException Description of Exception
251      * @doc.tag type="block"
252      * @doc.param name="tagName" optional="false" description="The tag name."
253      * @doc.param name="paramName" description="The parameter name. If not specified, then the raw
254      * content of the tag is returned."
255      * @doc.param name="paramNum" description="The zero-based parameter number. It's used if the user
256      * used the space-separated format for specifying parameters."
257      */
258     public void ifConstructorTagValueEquals(String template, Properties attributes) throws XDocletException
259     {
260         if (isTagValueEqual(attributes, FOR_CONSTRUCTOR)) {
261             generate(template);
262         }
263     }
264
265     /**
266      * Evaluates the body if value for the constructor tag not equals the specified value.
267      *
268      * @param template The body of the block tag
269      * @param attributes The attributes of the template tag
270      * @exception XDocletException Description of Exception
271      * @doc.tag type="block"
272      * @doc.param name="tagName" optional="false" description="The tag name."
273      * @doc.param name="paramName" description="The parameter name. If not specified, then the raw
274      * content of the tag is returned."
275      * @doc.param name="paramNum" description="The zero-based parameter number. It's used if the user
276      * used the space-separated format for specifying parameters."
277      */
278     public void ifConstructorTagValueNotEquals(String template, Properties attributes) throws XDocletException
279     {
280         if (!isTagValueEqual(attributes, FOR_CONSTRUCTOR)) {
281             generate(template);
282         }
283     }
284
285     /**
286      * Iterates over all constructor tags with the specified tagName for the current constructor probably inside of a
287      * forAllConstructorTags body.
288      *
289      * @param attributes The attributes of the template tag
290      * @return Description of the Returned Value
291      * @exception XDocletException Description of Exception
292      * @doc.tag type="content"
293      * @doc.param name="tagName" optional="false" description="The tag name."
294      * @doc.param name="paramName" description="The parameter name. If not specified, then the raw
295      * content of the tag is returned."
296      * @doc.param name="paramNum" description="The zero-based parameter number. It's used if the user
297      * used the space-separated format for specifying parameters."
298      * @doc.param name="values" description="The valid values for the parameter, comma separated. An
299      * error message is printed if the parameter value is not one of the values."
300      * @doc.param name="default" description="The default value is returned if parameter not specified
301      * by user for the tag."
302      */
303     public String constructorTagValue(Properties attributes) throws XDocletException
304     {
305         return getExpandedDelimitedTagValue(attributes, FOR_CONSTRUCTOR);
306     }
307
308     /**
309      * Iterates over all tags of current constructor and evaluates the body of the tag for each constructor.
310      *
311      * @param template The body of the block tag
312      * @param attributes The attributes of the template tag
313      * @exception XDocletException Description of Exception
314      * @doc.tag type="block"
315      * @doc.param name="tagName" optional="false" description="The tag name."
316      */
317     public void forAllConstructorTags(String template, Properties attributes) throws XDocletException
318     {
319         forAllMemberTags(template, attributes, FOR_CONSTRUCTOR, XDocletTagshandlerMessages.ONLY_CALL_CONSTRUCTOR_NOT_NULL, new String []{"forAllConstructorTags"});
320     }
321
322     /**
323      * Iterates over all tokens in current constructor tag with the name tagName and evaluates the body for every token.
324      *
325      * @param template The body of the block tag
326      * @param attributes The attributes of the template tag
327      * @exception XDocletException Description of Exception
328      * @doc.tag type="block"
329      * @doc.param name="tagName" optional="false" description="The tag name."
330      * @doc.param name="delimiter" description="delimiter for the StringTokenizer. consult javadoc for
331      * java.util.StringTokenizer default is ','"
332      * @doc.param name="skip" description="how many tokens to skip on start"
333      */
334     public void forAllConstructorTagTokens(String template, Properties attributes) throws XDocletException
335     {
336         forAllMemberTagTokens(template, attributes, FOR_CONSTRUCTOR);
337     }
338
339     /**
340      * Return standard javadoc of current constructor.
341      *
342      * @return Description of the Returned Value
343      * @exception XDocletException Description of Exception
344      * @doc.tag type="content"
345      */
346     public String firstSentenceDescriptionOfCurrentConstructor() throws XDocletException
347     {
348         return firstSentenceDescriptionOfCurrentMember(getCurrentConstructor());
349     }
350
351     /**
352      * Describe what the method does
353      *
354      * @return Describe the return value
355      * @exception XDocletException Describe the exception
356      */
357     public String modifiers() throws XDocletException
358     {
359         return modifiers(FOR_CONSTRUCTOR);
360     }
361
362     /**
363      * Returns the name of the current constructor.
364      *
365      * @param attributes The attributes of the template tag
366      * @return Description of the Returned Value
367      * @exception XDocletException Description of Exception
368      * @doc.tag type="content"
369      */
370     public String constructorName(Properties attributes) throws XDocletException
371     {
372         if (attributes != null) {
373             String value = (String ) attributes.get("value");
374
375             if (value != null) {
376                 String m = getCurrentConstructor().getName().substring(Integer.parseInt(value));
377                 // replace first character to lowercase
378 char firstU = m.charAt(0);
379                 char firstL = Character.toLowerCase(firstU);
380
381                 return firstL + m.substring(1);
382             }
383         }
384         return getCurrentConstructor() != null ? getCurrentConstructor().getName() : "";
385     }
386
387     /**
388      * Returns the current constructor name. Used inside block elements.
389      *
390      * @return Description of the Returned Value
391      * @exception XDocletException Description of Exception
392      */
393     public String currentConstructorName() throws XDocletException
394     {
395         return getCurrentConstructor().getName();
396     }
397
398     /**
399      * Evaluate the body if current class has a constructor with the specified name+parameters. If parameters not
400      * specified then any constructor with the given name and any set of parameters is considered equal to the given
401      * constructor name and so the test result is positive and the body is evaluated. This constructor does not change
402      * the current constructor to the one specified.
403      *
404      * @param template The body of the block tag
405      * @param attributes The attributes of the template tag
406      * @exception XDocletException Description of Exception
407      * @see #ifDoesntHaveConstructor(java.lang.String,java.util.Properties)
408      * @doc.tag type="block"
409      * @doc.param name="name" optional="false" description="The name of the constructor we're
410      * searching for its existence in current class."
411      * @doc.param name="parameters" optional="true" description="We're searching for a constructor
412      * that has the exact set of parameters specified in parameters param."
413      * @doc.param name="delimiter" optional="true" description="The parameters param is delimited by
414      * the string specified in delimiter parameter."
415      */
416     public void ifHasConstructor(String template, Properties attributes) throws XDocletException
417     {
418         ifHasConstructor_Impl(template, attributes, true);
419     }
420
421     /**
422      * Evaluate the body if current class doesn't have a constructor with the specified name+parameters. If parameters
423      * not specified then any constructor with the given name and any set of parameters is considered equal to the given
424      * constructor name and so the test result is positive and the body is evaluated.
425      *
426      * @param template The body of the block tag
427      * @param attributes The attributes of the template tag
428      * @exception XDocletException Description of Exception
429      * @see #ifHasConstructor(java.lang.String,java.util.Properties)
430      * @doc.tag type="block"
431      * @doc.param name="name" optional="false" description="The name of the constructor we're
432      * searching for its existence in current class."
433      * @doc.param name="parameters" optional="true" description="We're searching for a constructor
434      * that has the exact set of parameters specified in parameters param."
435      * @doc.param name="delimiter" optional="true" description="The parameters param is delimited by
436      * the string specified in delimiter parameter."
437      */
438     public void ifDoesntHaveConstructor(String template, Properties attributes) throws XDocletException
439     {
440         ifHasConstructor_Impl(template, attributes, false);
441     }
442
443     /**
444      * Returns true if a constructor with the specified parameters is found in the class clazz. The parameters array can
445      * be empty, if so any constructor with any set of parameters is considered equal to the constructor we're searching
446      * for. If not empty, all parameters of the constructor must be equal to the ones specified in parameters array to
447      * have "constructor equality".
448      *
449      * @param clazz Description of Parameter
450      * @param constructorName Description of Parameter
451      * @param parameters Description of Parameter
452      * @param setCurrentConstructor
453      * @return Description of the Returned Value
454      * @exception XDocletException
455      */
456     private boolean hasConstructor(XClass clazz, String constructorName, String [] parameters, boolean setCurrentConstructor)
457          throws XDocletException
458     {
459         return hasExecutableMember(clazz, constructorName, parameters, setCurrentConstructor, FOR_CONSTRUCTOR);
460     }
461
462     /**
463      * The implementation of ifHasConstructor and ifDoesntHaveConstructor tags.
464      *
465      * @param template The body of the block tag
466      * @param attributes The attributes of the template tag
467      * @param hasConstructor Description of Parameter
468      * @exception XDocletException Description of Exception
469      * @see #ifHasConstructor(java.lang.String,java.util.Properties)
470      * @see #ifDoesntHaveConstructor(java.lang.String,java.util.Properties)
471      * @see #hasConstructor(xjavadoc.XClass,java.lang.String,java.lang.String[],boolean)
472      */
473     private void ifHasConstructor_Impl(String template, Properties attributes, boolean hasConstructor) throws XDocletException
474     {
475         Log log = LogUtil.getLog(ConstructorTagsHandler.class, "ifHasConstructor_Impl");
476
477         String constructorName = attributes.getProperty("name");
478         String parametersStr = attributes.getProperty("parameters");
479         String delimiter = attributes.getProperty("delimiter");
480
481         String [] parameters = null;
482
483         if (log.isDebugEnabled()) {
484             log.debug("constructorName=" + constructorName);
485             log.debug("parametersStr=" + parametersStr);
486             log.debug("delimiter=" + delimiter);
487             log.debug("hasConstructor=" + hasConstructor);
488             log.debug("getCurrentClass()=" + getCurrentClass());
489         }
490
491         if (parametersStr != null) {
492             if (delimiter == null) {
493                 delimiter = PARAMETER_DELIMITER;
494             }
495
496             parameters = DocletUtil.tokenizeDelimitedToArray(parametersStr, delimiter);
497
498             if (log.isDebugEnabled()) {
499                 log.debug("parameters.length=" + parameters.length);
500                 log.debug("parameters[0]=" + parameters[0]);
501             }
502         }
503         if (hasConstructor(getCurrentClass(), constructorName, parameters, false) == hasConstructor) {
504             log.debug("constructor found.");
505             generate(template);
506         }
507         else {
508             log.debug("constructor not found.");
509         }
510     }
511 }
512

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags