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