KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > xdoclet > modules > doc > AntdocTagsHandler


1 /*
2  * Copyright (c) 2001, 2002 The XDoclet team
3  * All rights reserved.
4  */
5 package xdoclet.modules.doc;
6
7 import java.util.*;
8
9 import org.apache.tools.ant.types.EnumeratedAttribute;
10
11 import xjavadoc.XClass;
12 import xjavadoc.XTag;
13
14 import xdoclet.DocletContext;
15 import xdoclet.DocletTask;
16 import xdoclet.XDocletException;
17 import xdoclet.XDocletTagSupport;
18
19 /**
20  * This tag handler is used to generate Ant documentation
21  *
22  * @author Aslak Hellesoy
23  * @created 13. juni 2002
24  * @xdoclet.taghandler namespace="Antdoc"
25  * @version $Revision: 1.10 $
26  */
27 public class AntdocTagsHandler extends XDocletTagSupport
28 {
29     /**
30      * The element being documented
31      */
32     protected AntdocSubTask.Element docElement;
33     /**
34      * Current parent or child element
35      */
36     protected AntdocSubTask.SubElement subElement;
37
38     public void setDocElement(AntdocSubTask.Element antElement)
39     {
40         docElement = antElement;
41         setCurrentClass(antElement.getXClass());
42     }
43
44     /**
45      * The name of the current sub-element.
46      *
47      * @return name
48      * @exception XDocletException
49      * @doc.tag type="content"
50      */
51     public String JavaDoc subElementName() throws XDocletException
52     {
53         return subElement.getName();
54     }
55
56     /**
57      * The name of the current element.
58      *
59      * @return name
60      * @exception XDocletException
61      * @doc.tag type="content"
62      */
63     public String JavaDoc elementName() throws XDocletException
64     {
65         return docElement.getName();
66     }
67
68     /**
69      * Generate the tag's body if the current element has any sub-elements.
70      *
71      * @param template The body of the block tag
72      * @exception XDocletException
73      * @doc.tag type="block"
74      */
75     public void ifHasSubElements(String JavaDoc template) throws XDocletException
76     {
77         if (docElement.getSubElements() != null && docElement.getSubElements().size() > 0) {
78             generate(template);
79         }
80     }
81
82     /**
83      * Generate the tag's body for each of the current element's sub-elements.
84      *
85      * @param template The body of the block tag
86      * @exception XDocletException
87      * @doc.tag type="block"
88      */
89     public void forAllSubElements(String JavaDoc template) throws XDocletException
90     {
91         XClass old_cur_class = getCurrentClass();
92
93         for (Iterator i = docElement.getSubElements().iterator(); i.hasNext(); ) {
94             subElement = (AntdocSubTask.SubElement) i.next();
95
96             setCurrentClass(subElement.getXClass());
97
98             generate(template);
99         }
100
101         setCurrentClass(old_cur_class);
102     }
103
104     /**
105      * The description of the current sub-element.
106      *
107      * @return description
108      * @doc.tag type="content"
109      */
110     public String JavaDoc subElementDescription()
111     {
112         return subElement.getDescription();
113     }
114
115     /**
116      * The Required status (i.e. is it mandatory or optional) of an attribute. Uses the value text if it is present,
117      * otherwise defaults to "Yes." or "No." depending on whether an \@ant.required or \@ant.not-required tag is found.
118      *
119      * @return required
120      * @doc.tag type="content"
121      */
122     public String JavaDoc required()
123     {
124         // default value
125 String JavaDoc result = null;
126         XTag required = getCurrentMethod().getDoc().getTag("ant.required");
127
128         if (required != null) {
129             result = required.getValue().trim();
130             if (result.equals("")) {
131                 result = "Yes.";
132             }
133         }
134         else {
135             XTag not_required = getCurrentMethod().getDoc().getTag("ant.not-required");
136
137             if (not_required != null) {
138                 result = not_required.getValue().trim();
139                 if (result.equals("")) {
140                     result = "No.";
141                 }
142             }
143             else
144                 result = "No.";
145         }
146
147         return result;
148     }
149
150     /**
151      * Links to the root folder. Only required to generate links to CSS.
152      *
153      * @return link
154      * @todo refactor this. It's copied more or less from InfoTagsHandler
155      * @doc.tag type="content"
156      */
157     public String JavaDoc rootlink()
158     {
159         return getRootlinkFor(getCurrentClass());
160     }
161
162     /**
163      * Links to the documentation page of a nested sub-element.
164      *
165      * @return link
166      * @doc.tag type="content"
167      */
168     public String JavaDoc subElementLink()
169     {
170         XClass subElementClass = subElement.getSubject().getXClass();
171
172         // see if there is a link from config params
173 AntdocSubTask subtask = ((AntdocSubTask) DocletContext.getInstance().getSubTaskBy(DocletTask.getSubTaskName(AntdocSubTask.class)));
174         String JavaDoc link = (String JavaDoc) subtask.getConfigParamsAsMap().get(subElementClass.getQualifiedName());
175
176         if (link == null) {
177             // we only replace . with / in package. Dots in inner class names are replaced by $
178 link = getRootlinkFor(docElement.getXClass()) + subElementClass.getContainingPackage().getName().replace('.', '/')
179                 + '/' + subElementClass.getTransformedName() + ".html";
180         }
181         return link;
182     }
183
184     /**
185      * List the possible values for the current method. The property must be an Ant {@link EnumeratedAttribute}.
186      *
187      * @return Comma-separated list of values
188      * @exception XDocletException
189      * @doc.tag type="content"
190      */
191     public String JavaDoc enumerateValues() throws XDocletException
192     {
193         String JavaDoc ret = "";
194         xjavadoc.XMethod method = getCurrentMethod();
195
196         if (method != null) {
197             xjavadoc.Type type = method.getPropertyType();
198
199             if (type != null) {
200                 try {
201                     StringBuffer JavaDoc sb = new StringBuffer JavaDoc();
202
203                     String JavaDoc className = type.getType().getTransformedQualifiedName();
204                     EnumeratedAttribute enumClass = (EnumeratedAttribute) Class.forName(className).newInstance();
205                     String JavaDoc[] values = enumClass.getValues();
206
207                     for (int i = 0; i < values.length; i++) {
208                         if (i > 0)
209                             sb.append(", ");
210                         sb.append(values[i]);
211                     }
212                     ret = sb.toString();
213                 }
214                 catch (ClassCastException JavaDoc e) {
215                     throw new XDocletException(e, e.getMessage());
216                     //ignore
217 }
218                 catch (ClassNotFoundException JavaDoc e) {
219                     throw new XDocletException(e, e.getMessage());
220                     //ignore
221 }
222                 catch (IllegalAccessException JavaDoc e) {
223                     throw new XDocletException(e, e.getMessage());
224                     //ignore
225 }
226                 catch (InstantiationException JavaDoc e) {
227                     throw new XDocletException(e, e.getMessage());
228                     //ignore
229 }
230             }
231         }
232         return ret;
233     }
234
235     private String JavaDoc getRootlinkFor(XClass clazz)
236     {
237         StringTokenizer st = new StringTokenizer(clazz.getQualifiedName(), ".");
238         int n = st.countTokens() - 1;
239         StringBuffer JavaDoc sbuf = new StringBuffer JavaDoc();
240
241         for (int i = 0; i < n; i++) {
242             sbuf.append("../");
243         }
244
245         return sbuf.toString();
246     }
247
248 }
249
Popular Tags