KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > servlet > jsp > tagext > TagSupport


1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. 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 package javax.servlet.jsp.tagext;
18
19 import java.io.Serializable JavaDoc;
20 import java.util.Enumeration JavaDoc;
21 import java.util.Hashtable JavaDoc;
22
23 import javax.servlet.jsp.JspException JavaDoc;
24 import javax.servlet.jsp.PageContext JavaDoc;
25
26 /**
27  * A base class for defining new tag handlers implementing Tag.
28  *
29  * <p> The TagSupport class is a utility class intended to be used as
30  * the base class for new tag handlers. The TagSupport class
31  * implements the Tag and IterationTag interfaces and adds additional
32  * convenience methods including getter methods for the properties in
33  * Tag. TagSupport has one static method that is included to
34  * facilitate coordination among cooperating tags.
35  *
36  * <p> Many tag handlers will extend TagSupport and only redefine a
37  * few methods.
38  */

39
40 public class TagSupport implements IterationTag JavaDoc, Serializable JavaDoc {
41
42     /**
43      * Find the instance of a given class type that is closest to a given
44      * instance.
45      * This method uses the getParent method from the Tag
46      * interface.
47      * This method is used for coordination among cooperating tags.
48      *
49      * <p>
50      * The current version of the specification only provides one formal
51      * way of indicating the observable type of a tag handler: its
52      * tag handler implementation class, described in the tag-class
53      * subelement of the tag element. This is extended in an
54      * informal manner by allowing the tag library author to
55      * indicate in the description subelement an observable type.
56      * The type should be a subtype of the tag handler implementation
57      * class or void.
58      * This addititional constraint can be exploited by a
59      * specialized container that knows about that specific tag library,
60      * as in the case of the JSP standard tag library.
61      *
62      * <p>
63      * When a tag library author provides information on the
64      * observable type of a tag handler, client programmatic code
65      * should adhere to that constraint. Specifically, the Class
66      * passed to findAncestorWithClass should be a subtype of the
67      * observable type.
68      *
69      *
70      * @param from The instance from where to start looking.
71      * @param klass The subclass of Tag or interface to be matched
72      * @return the nearest ancestor that implements the interface
73      * or is an instance of the class specified
74      */

75
76     public static final Tag JavaDoc findAncestorWithClass(Tag JavaDoc from, Class JavaDoc klass) {
77     boolean isInterface = false;
78
79     if (from == null ||
80         klass == null ||
81         (!Tag JavaDoc.class.isAssignableFrom(klass) &&
82          !(isInterface = klass.isInterface()))) {
83         return null;
84     }
85
86     for (;;) {
87         Tag JavaDoc tag = from.getParent();
88
89         if (tag == null) {
90         return null;
91         }
92
93         if ((isInterface && klass.isInstance(tag)) ||
94             klass.isAssignableFrom(tag.getClass()))
95         return tag;
96         else
97         from = tag;
98     }
99     }
100
101     /**
102      * Default constructor, all subclasses are required to define only
103      * a public constructor with the same signature, and to call the
104      * superclass constructor.
105      *
106      * This constructor is called by the code generated by the JSP
107      * translator.
108      */

109
110     public TagSupport() { }
111
112     /**
113      * Default processing of the start tag, returning SKIP_BODY.
114      *
115      * @return SKIP_BODY
116      * @throws JspException if an error occurs while processing this tag
117      *
118      * @see Tag#doStartTag()
119      */

120  
121     public int doStartTag() throws JspException JavaDoc {
122         return SKIP_BODY;
123     }
124
125     /**
126      * Default processing of the end tag returning EVAL_PAGE.
127      *
128      * @return EVAL_PAGE
129      * @throws JspException if an error occurs while processing this tag
130      *
131      * @see Tag#doEndTag()
132      */

133
134     public int doEndTag() throws JspException JavaDoc {
135     return EVAL_PAGE;
136     }
137
138
139     /**
140      * Default processing for a body.
141      *
142      * @return SKIP_BODY
143      * @throws JspException if an error occurs while processing this tag
144      *
145      * @see IterationTag#doAfterBody()
146      */

147     
148     public int doAfterBody() throws JspException JavaDoc {
149     return SKIP_BODY;
150     }
151
152     // Actions related to body evaluation
153

154
155     /**
156      * Release state.
157      *
158      * @see Tag#release()
159      */

160
161     public void release() {
162     parent = null;
163     id = null;
164     if( values != null ) {
165         values.clear();
166     }
167     values = null;
168     }
169
170     /**
171      * Set the nesting tag of this tag.
172      *
173      * @param t The parent Tag.
174      * @see Tag#setParent(Tag)
175      */

176
177     public void setParent(Tag JavaDoc t) {
178     parent = t;
179     }
180
181     /**
182      * The Tag instance most closely enclosing this tag instance.
183      * @see Tag#getParent()
184      *
185      * @return the parent tag instance or null
186      */

187
188     public Tag JavaDoc getParent() {
189     return parent;
190     }
191
192     /**
193      * Set the id attribute for this tag.
194      *
195      * @param id The String for the id.
196      */

197
198     public void setId(String JavaDoc id) {
199     this.id = id;
200     }
201
202     /**
203      * The value of the id attribute of this tag; or null.
204      *
205      * @return the value of the id attribute, or null
206      */

207     
208     public String JavaDoc getId() {
209     return id;
210     }
211
212     /**
213      * Set the page context.
214      *
215      * @param pageContext The PageContext.
216      * @see Tag#setPageContext
217      */

218
219     public void setPageContext(PageContext JavaDoc pageContext) {
220     this.pageContext = pageContext;
221     }
222
223     /**
224      * Associate a value with a String key.
225      *
226      * @param k The key String.
227      * @param o The value to associate.
228      */

229
230     public void setValue(String JavaDoc k, Object JavaDoc o) {
231     if (values == null) {
232         values = new Hashtable JavaDoc<String JavaDoc, Object JavaDoc>();
233     }
234     values.put(k, o);
235     }
236
237     /**
238      * Get a the value associated with a key.
239      *
240      * @param k The string key.
241      * @return The value associated with the key, or null.
242      */

243
244     public Object JavaDoc getValue(String JavaDoc k) {
245     if (values == null) {
246         return null;
247     } else {
248         return values.get(k);
249     }
250     }
251
252     /**
253      * Remove a value associated with a key.
254      *
255      * @param k The string key.
256      */

257
258     public void removeValue(String JavaDoc k) {
259     if (values != null) {
260         values.remove(k);
261     }
262     }
263
264     /**
265      * Enumerate the keys for the values kept by this tag handler.
266      *
267      * @return An enumeration of all the keys for the values set,
268      * or null or an empty Enumeration if no values have been set.
269      */

270
271     public Enumeration JavaDoc<String JavaDoc> getValues() {
272     if (values == null) {
273         return null;
274     }
275     return values.keys();
276     }
277
278     // private fields
279

280     private Tag JavaDoc parent;
281     private Hashtable JavaDoc<String JavaDoc, Object JavaDoc> values;
282     /**
283      * The value of the id attribute of this tag; or null.
284      */

285     protected String JavaDoc id;
286
287     // protected fields
288

289     /**
290      * The PageContext.
291      */

292     protected PageContext JavaDoc pageContext;
293 }
294
295
Popular Tags