OjbMemberTagsHandler


1   package xdoclet.modules.ojb;
2   
3   /* Copyright 2003-2005 The Apache Software Foundation
4    *
5    * Licensed under the Apache License, Version 2.0 (the "License");
6    * you may not use this file except in compliance with the License.
7    * You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  import java.util.*;
19  
20  import xjavadoc.*;
21  import xdoclet.XDocletException;
22  import xdoclet.tagshandler.AbstractProgramElementTagsHandler;
23  import xdoclet.tagshandler.ClassTagsHandler;
24  import xdoclet.tagshandler.MethodTagsHandler;
25  import xdoclet.tagshandler.XDocletTagshandlerMessages;
26  import xdoclet.util.Translator;
27  import xdoclet.util.TypeConversionUtil;
28  
29  /**
30   * @author               <a HREF="mailto:tomdz@users.sourceforge.net">Thomas Dudziak (tomdz@users.sourceforge.net)</a>
31   * @created              March 22, 2003
32   * @xdoclet.taghandler   namespace="OjbMember"
33   */
34  public class OjbMemberTagsHandler extends AbstractProgramElementTagsHandler
35  {
36  
37      /**
38       * Returns the name of the current member which is the name in the case of a field, or the property name for an
39       * accessor method.
40       *
41       * @return                      The member name
42       * @exception XDocletException  if an error occurs
43       */
44      public static String   getMemberName() throws XDocletException
45      {
46          if (getCurrentField() != null) {
47              return getCurrentField().getName();
48          }
49          else if (getCurrentMethod() != null) {
50              return MethodTagsHandler.getPropertyNameFor(getCurrentMethod());
51          }
52          else {
53              return null;
54          }
55      }
56  
57      /**
58       * Returns the type of the current member which is the type in the case of a field, the return type for a getter
59       * method, or the type of the parameter for a setter method.
60       *
61       * @return                      The member type
62       * @exception XDocletException  if an error occurs
63       */
64      public static XClass getMemberType() throws XDocletException
65      {
66          if (getCurrentField() != null) {
67              return getCurrentField().getType();
68          }
69          else if (getCurrentMethod() != null) {
70              XMethod method = getCurrentMethod();
71  
72              if (MethodTagsHandler.isGetterMethod(method)) {
73                  return method.getReturnType().getType();
74              }
75              else if (MethodTagsHandler.isSetterMethod(method)) {
76                  XParameter param = (XParameter)method.getParameters().iterator().next();
77  
78                  return param.getType();
79              }
80          }
81          return null;
82      }
83  
84      /**
85       * Returns the dimension of the type of the current member.
86       *
87       * @return                      The member dimension
88       * @exception XDocletException  if an error occurs
89       * @see                         OjbMemberTagsHandler#getMemberType()
90       */
91      public static int getMemberDimension() throws XDocletException
92      {
93          if (getCurrentField() != null) {
94              return getCurrentField().getDimension();
95          }
96          else if (getCurrentMethod() != null) {
97              XMethod method = getCurrentMethod();
98  
99              if (MethodTagsHandler.isGetterMethod(method)) {
100                 return method.getReturnType().getDimension();
101             }
102             else if (MethodTagsHandler.isSetterMethod(method)) {
103                 XParameter param = (XParameter)method.getParameters().iterator().next();
104 
105                 return param.getDimension();
106             }
107         }
108         return 0;
109     }
110 
111     /**
112      * The <code>isField</code> processes the template body if the current member is a field.
113      *
114      * @param template              a <code>String</code> value
115      * @param attributes            a <code>Properties</code> value
116      * @exception XDocletException  if an error occurs
117      * @doc:tag                     type="content"
118      */
119     public void isField(String   template, Properties attributes) throws XDocletException
120     {
121         if (getCurrentField() != null) {
122             generate(template);
123         }
124     }
125 
126     /**
127      * The <code>isMethod</code> processes the template body if the current member is a method.
128      *
129      * @param template              a <code>String</code> value
130      * @param attributes            a <code>Properties</code> value
131      * @exception XDocletException  if an error occurs
132      * @doc:tag                     type="block"
133      */
134     public void isMethod(String   template, Properties attributes) throws XDocletException
135     {
136         if (getCurrentMethod() != null) {
137             generate(template);
138         }
139     }
140 
141     /**
142      * The <code>forAllMembers</code> method iterates through all fields of the current class. In contrast to the <code>FieldTagsHandler.forAllFields</code>
143      * method, this method operates on both fields and accessors (get/set/is-methods). In addition, the method
144      * automatically includes all supertype-fields (i.e., accessors for base interfaces) if the corresponding attribute
145      * is set (superclasses). The fields can optionally be limited to those posessing a specified tag.
146      *
147      * @param template              a <code>String</code> value
148      * @param attributes            a <code>Properties</code> value
149      * @exception XDocletException  if an error occurs
150      * @doc:tag                     type="block"
151      * @doc.param                   name="class" optional="true" description="Specifies the type to be searched. If not
152      *      specified, then the current type is used."
153      * @doc.param                   name="superclasses" optional="true" description="Specifies whether super types shall
154      *      be processed as well."
155      * @doc.param                   name="sort" optional="true" values="true,false" description="If true then sort the
156      *      fields list."
157      * @doc.param                   name="tagName" optional="true" description="Specifies a tag that all fields must
158      *      posess in order to be processed."
159      * @doc.param                   name="paramName" optional="true" description="Specifies a param that the given tag
160      *      must have."
161      * @doc.param                   name="value" optional="true" description="Specifies the value that the param must
162      *      have."
163      */
164     public void forAllMembers(String   template, Properties attributes) throws XDocletException
165     {
166         if (getCurrentClass() == null) {
167             return;
168         }
169 
170         String   className = attributes.getProperty("class");
171         XClass type = null;
172 
173         if ((className == null) || (className.length() == 0)) {
174             type = getCurrentClass();
175         }
176         else {
177             XClass curType;
178 
179             for (Iterator it = ClassTagsHandler.getAllClasses().iterator(); it.hasNext(); ) {
180                 curType = (XClass)it.next();
181                 if (className.equals(curType.getQualifiedName())) {
182                     type = curType;
183                     break;
184                 }
185             }
186             if (type == null) {
187                 throw new XDocletException(Translator.getString(XDocletModulesOjbMessages.class,
188                     XDocletModulesOjbMessages.COULD_NOT_FIND_TYPE,
189                     new String  []{className}));
190             }
191         }
192 
193         String   tagName = attributes.getProperty("tagName");
194         String   paramName = attributes.getProperty("paramName");
195         String   paramValue = attributes.getProperty("value");
196         boolean superTypes = TypeConversionUtil.stringToBoolean(attributes.getProperty("superclasses"), true);
197         boolean sort = TypeConversionUtil.stringToBoolean(attributes.getProperty("sort"), true);
198         ArrayList allMemberNames = new ArrayList();
199         HashMap allMembers = new HashMap();
200 
201         if (superTypes) {
202             addMembersInclSupertypes(allMemberNames, allMembers, type, tagName, paramName, paramValue);
203         }
204         else {
205             addMembers(allMemberNames, allMembers, type, tagName, paramName, paramValue);
206         }
207         if (sort) {
208             Collections.sort(allMemberNames);
209         }
210         for (Iterator it = allMemberNames.iterator(); it.hasNext(); ) {
211             XMember member = (XMember) allMembers.get(it.next());
212 
213             if (member instanceof XField) {
214                 setCurrentField((XField) member);
215             }
216             else if (member instanceof XMethod) {
217                 setCurrentMethod((XMethod) member);
218             }
219             generate(template);
220             if (member instanceof XField) {
221                 setCurrentField(null);
222             }
223             else if (member instanceof XMethod) {
224                 setCurrentMethod(null);
225             }
226         }
227     }
228 
229     /**
230      * Iterates over all tags of current member and evaluates the template for each one.
231      *
232      * @param template              The template to be evaluated
233      * @param attributes            The attributes of the template tag
234      * @exception XDocletException  If an error occurs
235      * @doc.tag                     type="block"
236      * @doc.param                   name="tagName" optional="false" description="The tag name."
237      * @doc.param                   name="paramName" optional="true" description="The parameter name."
238      */
239     public void forAllMemberTags(String   template, Properties attributes) throws XDocletException
240     {
241         if (getCurrentField() != null) {
242             forAllMemberTags(template, attributes, FOR_FIELD, XDocletTagshandlerMessages.ONLY_CALL_FIELD_NOT_NULL, new String  []{"forAllMemberTags"});
243         }
244         else if (getCurrentMethod() != null) {
245             forAllMemberTags(template, attributes, FOR_METHOD, XDocletTagshandlerMessages.ONLY_CALL_METHOD_NOT_NULL, new String  []{"forAllMemberTags"});
246         }
247     }
248 
249     /**
250      * Iterates over all tokens in current member tag with the name tagName and evaluates the body for every token.
251      *
252      * @param template              The body of the block tag
253      * @param attributes            The attributes of the template tag
254      * @exception XDocletException  If an error occurs
255      * @doc.tag                     type="block"
256      * @doc.param                   name="tagName" optional="false" description="The tag name."
257      * @doc.param                   name="delimiter" description="delimiter for the StringTokenizer. consult javadoc for
258      *      java.util.StringTokenizer default is ','"
259      * @doc.param                   name="skip" description="how many tokens to skip on start"
260      */
261     public void forAllMemberTagTokens(String   template, Properties attributes) throws XDocletException
262     {
263         if (getCurrentField() != null) {
264             forAllMemberTagTokens(template, attributes, FOR_FIELD);
265         }
266         else if (getCurrentMethod() != null) {
267             forAllMemberTagTokens(template, attributes, FOR_METHOD);
268         }
269     }
270 
271     /**
272      * Returns the name of the member which is the name in the case of a field, or the property name for an accessor
273      * method.
274      *
275      * @param attributes            The attributes of the template tag
276      * @return                      The member name
277      * @exception XDocletException  if an error occurs
278      * @doc.tag                     type="content"
279      */
280     public String   memberName(Properties attributes) throws XDocletException
281     {
282         return getMemberName();
283     }
284 
285     /**
286      * Evaluates the body if current member has no tag with the specified name.
287      *
288      * @param template              The body of the block tag
289      * @param attributes            The attributes of the template tag
290      * @exception XDocletException  Description of Exception
291      * @doc.tag                     type="block"
292      * @doc.param                   name="tagName" optional="false" description="The tag name."
293      * @doc.param                   name="paramName" description="The parameter name. If not specified, then the raw
294      *      content of the tag is returned."
295      * @doc.param                   name="paramNum" description="The zero-based parameter number. It's used if the user
296      *      used the space-separated format for specifying parameters."
297      * @doc.param                   name="error" description="Show this error message if no tag found."
298      */
299     public void ifDoesntHaveMemberTag(String   template, Properties attributes) throws XDocletException
300     {
301         boolean result = false;
302 
303         if (getCurrentField() != null) {
304             if (!hasTag(attributes, FOR_FIELD)) {
305                 result = true;
306                 generate(template);
307             }
308         }
309         else if (getCurrentMethod() != null) {
310             if (!hasTag(attributes, FOR_METHOD)) {
311                 result = true;
312                 generate(template);
313             }
314         }
315         if (!result) {
316             String   error = attributes.getProperty("error");
317 
318             if (error != null) {
319                 getEngine().print(error);
320             }
321         }
322     }
323 
324     /**
325      * Evaluates the body if the current class has at least one member with at least one tag with the specified name.
326      *
327      * @param template              The body of the block tag
328      * @param attributes            The attributes of the template tag
329      * @exception XDocletException  Description of Exception
330      * @doc.tag                     type="block"
331      * @doc.param                   name="tagName" optional="false" description="The tag name."
332      * @doc.param                   name="paramName" description="The parameter name. If not specified, then the raw
333      *      content of the tag is returned."
334      * @doc.param                   name="error" description="Show this error message if no tag found."
335      */
336     public void ifHasMemberWithTag(String   template, Properties attributes) throws XDocletException
337     {
338         ArrayList allMemberNames = new ArrayList();
339         HashMap allMembers = new HashMap();
340         boolean hasTag = false;
341 
342         addMembers(allMemberNames, allMembers, getCurrentClass(), null, null, null);
343         for (Iterator it = allMemberNames.iterator(); it.hasNext(); ) {
344             XMember member = (XMember) allMembers.get(it.next());
345 
346             if (member instanceof XField) {
347                 setCurrentField((XField)member);
348                 if (hasTag(attributes, FOR_FIELD)) {
349                     hasTag = true;
350                 }
351                 setCurrentField(null);
352             }
353             else if (member instanceof XMethod) {
354                 setCurrentMethod((XMethod)member);
355                 if (hasTag(attributes, FOR_METHOD)) {
356                     hasTag = true;
357                 }
358                 setCurrentMethod(null);
359             }
360             if (hasTag) {
361                 generate(template);
362                 break;
363             }
364         }
365     }
366 
367     /**
368      * Evaluates the body if current member has at least one tag with the specified name.
369      *
370      * @param template              The body of the block tag
371      * @param attributes            The attributes of the template tag
372      * @exception XDocletException  Description of Exception
373      * @doc.tag                     type="block"
374      * @doc.param                   name="tagName" optional="false" description="The tag name."
375      * @doc.param                   name="paramName" description="The parameter name. If not specified, then the raw
376      *      content of the tag is returned."
377      * @doc.param                   name="paramNum" description="The zero-based parameter number. It's used if the user
378      *      used the space-separated format for specifying parameters."
379      * @doc.param                   name="error" description="Show this error message if no tag found."
380      */
381     public void ifHasMemberTag(String   template, Properties attributes) throws XDocletException
382     {
383         boolean result = false;
384 
385         if (getCurrentField() != null) {
386             if (hasTag(attributes, FOR_FIELD)) {
387                 result = true;
388                 generate(template);
389             }
390         }
391         else if (getCurrentMethod() != null) {
392             if (hasTag(attributes, FOR_METHOD)) {
393                 result = true;
394                 generate(template);
395             }
396         }
397         if (!result) {
398             String   error = attributes.getProperty("error");
399 
400             if (error != null) {
401                 getEngine().print(error);
402             }
403         }
404     }
405 
406     /**
407      * Returns the value of the tag/parameter combination for the current member tag
408      *
409      * @param attributes            The attributes of the template tag
410      * @return                      Description of the Returned Value
411      * @exception XDocletException  Description of Exception
412      * @doc.tag                     type="content"
413      * @doc.param                   name="tagName" optional="false" description="The tag name."
414      * @doc.param                   name="paramName" description="The parameter name. If not specified, then the raw
415      *      content of the tag is returned."
416      * @doc.param                   name="paramNum" description="The zero-based parameter number. It's used if the user
417      *      used the space-separated format for specifying parameters."
418      * @doc.param                   name="values" description="The valid values for the parameter, comma separated. An
419      *      error message is printed if the parameter value is not one of the values."
420      * @doc.param                   name="default" description="The default value is returned if parameter not specified
421      *      by user for the tag."
422      */
423     public String   memberTagValue(Properties attributes) throws XDocletException
424     {
425         if (getCurrentField() != null) {
426             // setting field to true will override the for_class value.
427             attributes.setProperty("field", "true");
428             return getExpandedDelimitedTagValue(attributes, FOR_FIELD);
429         }
430         else if (getCurrentMethod() != null) {
431             return getExpandedDelimitedTagValue(attributes, FOR_METHOD);
432         }
433         else {
434             return null;
435         }
436     }
437 
438     /**
439      * Evaluates the body if value for the member tag equals the specified value.
440      *
441      * @param template              The body of the block tag
442      * @param attributes            The attributes of the template tag
443      * @exception XDocletException  If an error occurs
444      * @doc.tag                     type="block"
445      * @doc.param                   name="tagName" optional="false" description="The tag name."
446      * @doc.param                   name="paramName" description="The parameter name. If not specified, then the raw
447      *      content of the tag is returned."
448      * @doc.param                   name="paramNum" description="The zero-based parameter number. It's used if the user
449      *      used the space-separated format for specifying parameters."
450      * @doc.param                   name="value" optional="false" description="The expected value."
451      */
452     public void ifMemberTagValueEquals(String   template, Properties attributes) throws XDocletException
453     {
454         if (getCurrentField() != null) {
455             if (isTagValueEqual(attributes, FOR_FIELD)) {
456                 generate(template);
457             }
458         }
459         else if (getCurrentMethod() != null) {
460             if (isTagValueEqual(attributes, FOR_METHOD)) {
461                 generate(template);
462             }
463         }
464     }
465 
466     /**
467      * Retrieves the members of the type and of its super types.
468      *
469      * @param memberNames        Will receive the names of the members (for sorting)
470      * @param members            Will receive the members
471      * @param type               The type to process
472      * @param tagName            An optional tag for filtering the types
473      * @param paramName          The feature to be added to the MembersInclSupertypes attribute
474      * @param paramValue         The feature to be added to the MembersInclSupertypes attribute
475      * @throws XDocletException  If an error occurs
476      */
477     private void addMembersInclSupertypes(Collection memberNames, HashMap members, XClass type, String   tagName, String   paramName, String   paramValue) throws XDocletException
478     {
479         addMembers(memberNames, members, type, tagName, paramName, paramValue);
480         if (type.getInterfaces() != null) {
481             for (Iterator it = type.getInterfaces().iterator(); it.hasNext(); ) {
482                 addMembersInclSupertypes(memberNames, members, (XClass)it.next(), tagName, paramName, paramValue);
483             }
484         }
485         if (!type.isInterface() && (type.getSuperclass() != null)) {
486             addMembersInclSupertypes(memberNames, members, type.getSuperclass(), tagName, paramName, paramValue);
487         }
488     }
489 
490     /**
491      * Retrieves the members of the given type.
492      *
493      * @param memberNames        Will receive the names of the members (for sorting)
494      * @param members            Will receive the members
495      * @param type               The type to process
496      * @param tagName            An optional tag for filtering the types
497      * @param paramName          The feature to be added to the Members attribute
498      * @param paramValue         The feature to be added to the Members attribute
499      * @throws XDocletException  If an error occurs
500      */
501     private void addMembers(Collection memberNames, HashMap members, XClass type, String   tagName, String   paramName, String   paramValue) throws XDocletException
502     {
503         if (!type.isInterface() && (type.getFields() != null)) {
504             XField field;
505 
506             for (Iterator it = type.getFields().iterator(); it.hasNext(); ) {
507                 field = (XField)it.next();
508                 if (!field.isFinal() && !field.isStatic() && !field.isTransient()) {
509                     if (checkTagAndParam(field.getDoc(), tagName, paramName, paramValue)) {
510                         // already processed ?
511                         if (!members.containsKey(field.getName())) {
512                             memberNames.add(field.getName());
513                             members.put(field.getName(), field);
514                         }
515                     }
516                 }
517             }
518         }
519 
520         if (type.getMethods() != null) {
521             XMethod method;
522             String   propertyName;
523 
524             for (Iterator it = type.getMethods().iterator(); it.hasNext(); ) {
525                 method = (XMethod)it.next();
526                 if (!method.isConstructor() && !method.isNative() && !method.isStatic()) {
527                     if (checkTagAndParam(method.getDoc(), tagName, paramName, paramValue)) {
528                         if (MethodTagsHandler.isGetterMethod(method) || MethodTagsHandler.isSetterMethod(method)) {
529                             propertyName = MethodTagsHandler.getPropertyNameFor(method);
530                             if (!members.containsKey(propertyName)) {
531                                 memberNames.add(propertyName);
532                                 members.put(propertyName, method);
533                             }
534                         }
535                     }
536                 }
537             }
538         }
539     }
540 
541     /**
542      * Determines whether the given documentation part contains the specified tag with the given parameter having the
543      * given value.
544      *
545      * @param doc         The documentation part
546      * @param tagName     The tag to be searched for
547      * @param paramName   The parameter that the tag is required to have
548      * @param paramValue  The value of the parameter
549      * @return            boolean Whether the documentation part has the tag and parameter
550      */
551     private boolean checkTagAndParam(XDoc doc, String   tagName, String   paramName, String   paramValue)
552     {
553         if (tagName == null) {
554             return true;
555         }
556         if (!doc.hasTag(tagName)) {
557             return false;
558         }
559         if (paramName == null) {
560             return true;
561         }
562         if (!doc.getTag(tagName).getAttributeNames().contains(paramName)) {
563             return false;
564         }
565         return (paramValue == null) || paramValue.equals(doc.getTagAttributeValue(tagName, paramName));
566     }
567 }
568
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags