View Javadoc

1   /**
2    *
3    * Copyright 2003-2004 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  //
19  // This source code implements specifications defined by the Java
20  // Community Process. In order to remain compliant with the specification
21  // DO NOT add / change / or delete method signatures!
22  //
23  
24  package javax.servlet.jsp.tagext;
25  
26  /**
27   * Tag information for a tag in a Tag Library;
28   * This class is instantiated from the Tag Library Descriptor file (TLD)
29   * and is available only at translation time.
30   *
31   * 
32  */
33  
34  public class TagInfo {
35  
36      /**
37       * Static constant for getBodyContent() when it is JSP.
38       */
39  
40      public static final String BODY_CONTENT_JSP = "JSP";
41  
42      /**
43       * Static constant for getBodyContent() when it is Tag dependent.
44       */
45  
46      public static final String BODY_CONTENT_TAG_DEPENDENT = "TAGDEPENDENT";
47  
48  
49      /**
50       * Static constant for getBodyContent() when it is empty.
51       */
52  
53      public static final String BODY_CONTENT_EMPTY = "EMPTY";
54      
55      /**
56       * Static constant for getBodyContent() when it is scriptless.
57       * 
58       * @since 2.0
59       */ 
60      public static final String BODY_CONTENT_SCRIPTLESS = "SCRIPTLESS";
61  
62      /**
63       * Constructor for TagInfo from data in the JSP 1.1 format for TLD.
64       * This class is to be instantiated only from the TagLibrary code
65       * under request from some JSP code that is parsing a
66       * TLD (Tag Library Descriptor).
67       *
68       * Note that, since TagLibibraryInfo reflects both TLD information
69       * and taglib directive information, a TagInfo instance is
70       * dependent on a taglib directive.  This is probably a
71       * design error, which may be fixed in the future.
72       *
73       * @param tagName The name of this tag
74       * @param tagClassName The name of the tag handler class
75       * @param bodycontent Information on the body _content of these tags
76       * @param infoString The (optional) string information for this tag
77       * @param taglib The instance of the tag library that contains us.
78       * @param tagExtraInfo The instance providing extra Tag info.  May be null
79       * @param attributeInfo An array of AttributeInfo data from descriptor.
80       * May be null;
81       *
82       */
83      public TagInfo(String tagName,
84  	    String tagClassName,
85  	    String bodycontent,
86  	    String infoString,
87  	    TagLibraryInfo taglib,
88  	    TagExtraInfo tagExtraInfo,
89  	    TagAttributeInfo[] attributeInfo) {
90  	this.tagName       = tagName;
91  	this.tagClassName  = tagClassName;
92  	this.bodyContent   = bodycontent;
93  	this.infoString    = infoString;
94  	this.tagLibrary    = taglib;
95  	this.tagExtraInfo  = tagExtraInfo;
96  	this.attributeInfo = attributeInfo;
97  
98  	if (tagExtraInfo != null)
99              tagExtraInfo.setTagInfo(this);
100     }
101 			 
102     /**
103      * Constructor for TagInfo from data in the JSP 1.2 format for TLD.
104      * This class is to be instantiated only from the TagLibrary code
105      * under request from some JSP code that is parsing a
106      * TLD (Tag Library Descriptor).
107      *
108      * Note that, since TagLibibraryInfo reflects both TLD information
109      * and taglib directive information, a TagInfo instance is
110      * dependent on a taglib directive.  This is probably a
111      * design error, which may be fixed in the future.
112      *
113      * @param tagName The name of this tag
114      * @param tagClassName The name of the tag handler class
115      * @param bodycontent Information on the body _content of these tags
116      * @param infoString The (optional) string information for this tag
117      * @param taglib The instance of the tag library that contains us.
118      * @param tagExtraInfo The instance providing extra Tag info.  May be null
119      * @param attributeInfo An array of AttributeInfo data from descriptor.
120      * May be null;
121      * @param displayName A short name to be displayed by tools
122      * @param smallIcon Path to a small icon to be displayed by tools
123      * @param largeIcon Path to a large icon to be displayed by tools
124      * @param tvi An array of a TagVariableInfo (or null)
125      */
126     public TagInfo(String tagName,
127 	    String tagClassName,
128 	    String bodycontent,
129 	    String infoString,
130 	    TagLibraryInfo taglib,
131 	    TagExtraInfo tagExtraInfo,
132 	    TagAttributeInfo[] attributeInfo,
133 	    String displayName,
134 	    String smallIcon,
135 	    String largeIcon,
136 	    TagVariableInfo[] tvi) {
137 	this.tagName       = tagName;
138 	this.tagClassName  = tagClassName;
139 	this.bodyContent   = bodycontent;
140 	this.infoString    = infoString;
141 	this.tagLibrary    = taglib;
142 	this.tagExtraInfo  = tagExtraInfo;
143 	this.attributeInfo = attributeInfo;
144 	this.displayName = displayName;
145 	this.smallIcon = smallIcon;
146 	this.largeIcon = largeIcon;
147 	this.tagVariableInfo = tvi;
148 
149 	if (tagExtraInfo != null)
150             tagExtraInfo.setTagInfo(this);
151     }
152 			 
153     /**
154      * Constructor for TagInfo from data in the JSP 2.0 format for TLD.
155      * This class is to be instantiated only from the TagLibrary code
156      * under request from some JSP code that is parsing a
157      * TLD (Tag Library Descriptor).
158      *
159      * Note that, since TagLibibraryInfo reflects both TLD information
160      * and taglib directive information, a TagInfo instance is
161      * dependent on a taglib directive.  This is probably a
162      * design error, which may be fixed in the future.
163      *
164      * @param tagName The name of this tag
165      * @param tagClassName The name of the tag handler class
166      * @param bodycontent Information on the body _content of these tags
167      * @param infoString The (optional) string information for this tag
168      * @param taglib The instance of the tag library that contains us.
169      * @param tagExtraInfo The instance providing extra Tag info.  May be null
170      * @param attributeInfo An array of AttributeInfo data from descriptor.
171      * May be null;
172      * @param displayName A short name to be displayed by tools
173      * @param smallIcon Path to a small icon to be displayed by tools
174      * @param largeIcon Path to a large icon to be displayed by tools
175      * @param tvi An array of a TagVariableInfo (or null)
176      * @param dynamicAttributes True if supports dynamic attributes
177      *
178      * @since 2.0
179      */
180     public TagInfo(String tagName,
181             String tagClassName,
182             String bodycontent,
183             String infoString,
184             TagLibraryInfo taglib,
185             TagExtraInfo tagExtraInfo,
186             TagAttributeInfo[] attributeInfo,
187             String displayName,
188             String smallIcon,
189             String largeIcon,
190             TagVariableInfo[] tvi,
191             boolean dynamicAttributes) {
192         this.tagName       = tagName;
193         this.tagClassName  = tagClassName;
194         this.bodyContent   = bodycontent;
195         this.infoString    = infoString;
196         this.tagLibrary    = taglib;
197         this.tagExtraInfo  = tagExtraInfo;
198         this.attributeInfo = attributeInfo;
199         this.displayName = displayName;
200         this.smallIcon = smallIcon;
201         this.largeIcon = largeIcon;
202         this.tagVariableInfo = tvi;
203         this.dynamicAttributes = dynamicAttributes;
204 
205         if (tagExtraInfo != null)
206             tagExtraInfo.setTagInfo(this);
207     }
208 
209     /**
210      * The name of the Tag.
211      *
212      * @return The (short) name of the tag.
213      */
214 
215     public String getTagName() {
216 	return tagName;
217     }
218 
219     /**
220      * Attribute information (in the TLD) on this tag.
221      * The return is an array describing the attributes of this tag, as
222      * indicated in the TLD.
223      *
224      * @return The array of TagAttributeInfo for this tag, or a
225      *         zero-length array if the tag has no attributes.
226      */
227 
228    public TagAttributeInfo[] getAttributes() {
229        return attributeInfo;
230    }
231 
232     /**
233      * Information on the scripting objects created by this tag at runtime.
234      * This is a convenience method on the associated TagExtraInfo class.
235      *
236      * @param data TagData describing this action.
237      * @return if a TagExtraInfo object is associated with this TagInfo, the
238      *     result of getTagExtraInfo().getVariableInfo( data ), otherwise
239      *     null.
240      */
241    public VariableInfo[] getVariableInfo(TagData data) {
242        VariableInfo[] result = null;
243        TagExtraInfo tei = getTagExtraInfo();
244        if (tei != null) {
245 	   result = tei.getVariableInfo( data );
246        }
247        return result;
248    }
249 
250     /**
251      * Translation-time validation of the attributes. 
252      * This is a convenience method on the associated TagExtraInfo class.
253      *
254      * @param data The translation-time TagData instance.
255      * @return Whether the data is valid.
256      */
257     public boolean isValid(TagData data) {
258         TagExtraInfo tei = getTagExtraInfo();
259         if (tei == null) {
260 	    return true;
261         }
262         return tei.isValid(data);
263     }
264 
265     /**
266      * Translation-time validation of the attributes.
267      * This is a convenience method on the associated TagExtraInfo class.
268      *
269      * @param data The translation-time TagData instance.
270      * @return A null object, or zero length array if no errors, an
271      *     array of ValidationMessages otherwise.
272      * @since 2.0
273      */
274     public ValidationMessage[] validate( TagData data ) {
275 	TagExtraInfo tei = getTagExtraInfo();
276 	if( tei == null ) {
277 	    return null;
278 	}
279 	return tei.validate( data );
280     }
281 
282     /**
283      * Set the instance for extra tag information.
284      * 
285      * @param tei the TagExtraInfo instance
286      */
287     public void setTagExtraInfo(TagExtraInfo tei) {
288 	tagExtraInfo = tei;
289     }
290 
291 
292     /**
293      * The instance (if any) for extra tag information.
294      * 
295      * @return The TagExtraInfo instance, if any.
296      */
297     public TagExtraInfo getTagExtraInfo() {
298 	return tagExtraInfo;
299     }
300 
301 
302     /**
303      * Name of the class that provides the handler for this tag.
304      *
305      * @return The name of the tag handler class.
306      */
307     
308     public String getTagClassName() {
309 	return tagClassName;
310     }
311 
312 
313     /**
314      * The bodycontent information for this tag.
315      * If the bodycontent is not defined for this
316      * tag, the default of JSP will be returned.
317      *
318      * @return the body _content string.
319      */
320 
321     public String getBodyContent() {
322 	return bodyContent;
323     }
324 
325 
326     /**
327      * The information string for the tag.
328      *
329      * @return the info string, or null if 
330      *         not defined
331      */
332 
333     public String getInfoString() {
334 	return infoString;
335     }
336 
337 
338     /**
339      * Set the TagLibraryInfo property.
340      *
341      * Note that a TagLibraryInfo element is dependent
342      * not just on the TLD information but also on the
343      * specific taglib instance used.  This means that
344      * a fair amount of work needs to be done to construct
345      * and initialize TagLib objects.
346      *
347      * If used carefully, this setter can be used to avoid having to
348      * create new TagInfo elements for each taglib directive.
349      *
350      * @param tl the TagLibraryInfo to assign
351      */
352 
353     public void setTagLibrary(TagLibraryInfo tl) {
354 	tagLibrary = tl;
355     }
356 
357     /**
358      * The instance of TabLibraryInfo we belong to.
359      *
360      * @return the tag library instance we belong to
361      */
362 
363     public TagLibraryInfo getTagLibrary() {
364 	return tagLibrary;
365     }
366 
367 
368     // ============== JSP 2.0 TLD Information ========
369 
370 
371     /**
372      * Get the displayName.
373      *
374      * @return A short name to be displayed by tools,
375      *         or null if not defined
376      */
377 
378     public String getDisplayName() {
379 	return displayName;
380     }
381 
382     /**
383      * Get the path to the small icon.
384      *
385      * @return Path to a small icon to be displayed by tools,
386      *         or null if not defined
387      */
388 
389     public String getSmallIcon() {
390 	return smallIcon;
391     }
392 
393     /**
394      * Get the path to the large icon.
395      *
396      * @return Path to a large icon to be displayed by tools,
397      *         or null if not defined
398      */
399 
400     public String getLargeIcon() {
401 	return largeIcon;
402     }
403 
404     /**
405      * Get TagVariableInfo objects associated with this TagInfo.
406      *
407      * @return Array of TagVariableInfo objects corresponding to
408      *         variables declared by this tag, or a zero length
409      *         array if no variables have been declared
410      */
411 
412     public TagVariableInfo[] getTagVariableInfos() {
413 	return tagVariableInfo;
414     }
415 
416 
417     // ============== JSP 2.0 TLD Information ========
418 
419     /**
420      * Get dynamicAttributes associated with this TagInfo.
421      *
422      * @return True if tag handler supports dynamic attributes
423      * @since 2.0
424      */
425     public boolean hasDynamicAttributes() {
426         return dynamicAttributes;
427     }
428 
429     /*
430      * private fields for 1.1 info
431      */
432     private String             tagName; // the name of the tag
433     private String             tagClassName;
434     private String             bodyContent;
435     private String             infoString;
436     private TagLibraryInfo     tagLibrary;
437     private TagExtraInfo       tagExtraInfo; // instance of TagExtraInfo
438     private TagAttributeInfo[] attributeInfo;
439 
440     /*
441      * private fields for 1.2 info
442      */
443     private String             displayName;
444     private String             smallIcon;
445     private String             largeIcon;
446     private TagVariableInfo[]  tagVariableInfo;
447 
448     /*
449      * Additional private fields for 2.0 info
450      */
451     private boolean dynamicAttributes;
452 }