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   * Optional class provided by the tag library author to describe additional
28   * translation-time information not described in the TLD.
29   * The TagExtraInfo class is mentioned in the Tag Library Descriptor file (TLD).
30   *
31   * <p>
32   * This class can be used:
33   * <ul>
34   * <li> to indicate that the tag defines scripting variables
35   * <li> to perform translation-time validation of the tag attributes.
36   * </ul>
37   *
38   * <p>
39   * It is the responsibility of the JSP translator that the initial value
40   * to be returned by calls to getTagInfo() corresponds to a TagInfo
41   * object for the tag being translated. If an explicit call to
42   * setTagInfo() is done, then the object passed will be returned in
43   * subsequent calls to getTagInfo().
44   * 
45   * <p>
46   * The only way to affect the value returned by getTagInfo()
47   * is through a setTagInfo() call, and thus, TagExtraInfo.setTagInfo() is
48   * to be called by the JSP translator, with a TagInfo object that
49   * corresponds to the tag being translated. The call should happen before
50   * any invocation on validate() and before any invocation on
51   * getVariableInfo().
52   *
53   * <p>
54   * <tt>NOTE:</tt> It is a (translation time) error for a tag definition
55   * in a TLD with one or more variable subelements to have an associated
56   * TagExtraInfo implementation that returns a VariableInfo array with
57   * one or more elements from a call to getVariableInfo().
58   */
59  
60  public abstract class TagExtraInfo {
61  
62      /**
63       * Sole constructor. (For invocation by subclass constructors, 
64       * typically implicit.)
65       */
66      public TagExtraInfo() {
67      }
68      
69      /**
70       * information on scripting variables defined by the tag associated with
71       * this TagExtraInfo instance.
72       * Request-time attributes are indicated as such in the TagData parameter.
73       *
74       * @param data The TagData instance.
75       * @return An array of VariableInfo data, or null or a zero length array
76       *         if no scripting variables are to be defined.
77       */
78      public VariableInfo[] getVariableInfo(TagData data) {
79  	return ZERO_VARIABLE_INFO;
80      }
81  
82      /**
83       * Translation-time validation of the attributes. 
84       * Request-time attributes are indicated as such in the TagData parameter.
85       * Note that the preferred way to do validation is with the validate()
86       * method, since it can return more detailed information.
87       *
88       * @param data The TagData instance.
89       * @return Whether this tag instance is valid.
90       * @see TagExtraInfo#validate
91       */
92  
93      public boolean isValid(TagData data) {
94  	return true;
95      }
96  
97      /**
98       * Translation-time validation of the attributes.
99       * Request-time attributes are indicated as such in the TagData parameter.
100      * Because of the higher quality validation messages possible, 
101      * this is the preferred way to do validation (although isValid() 
102      * still works).  
103      * 
104      * <p>JSP 2.0 and higher containers call validate() instead of isValid().
105      * The default implementation of this method is to call isValid().  If 
106      * isValid() returns false, a generic ValidationMessage[] is returned
107      * indicating isValid() returned false.</p>
108      *
109      * @param data The TagData instance.
110      * @return A null object, or zero length array if no errors, an 
111      *     array of ValidationMessages otherwise.
112      * @since 2.0
113      */
114     public ValidationMessage[] validate( TagData data ) {
115 	ValidationMessage[] result = null;
116 
117 	if( !isValid( data ) ) {
118 	    result = new ValidationMessage[] {
119 		new ValidationMessage( data.getId(), "isValid() == false" ) };
120 	}
121 
122 	return result;
123     }
124 
125     /**
126      * Set the TagInfo for this class.
127      *
128      * @param tagInfo The TagInfo this instance is extending
129      */
130     public final void setTagInfo(TagInfo tagInfo) {
131 	this.tagInfo = tagInfo;
132     }
133 
134     /**
135      * Get the TagInfo for this class.
136      *
137      * @return the taginfo instance this instance is extending
138      */
139     public final TagInfo getTagInfo() {
140 	return tagInfo;
141     }
142     
143     // private data
144     private TagInfo tagInfo;
145 
146     // zero length VariableInfo array
147     private static final VariableInfo[] ZERO_VARIABLE_INFO = { };
148 }
149