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