001 /*
002 * Copyright 2004 The Apache Software Foundation
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package javax.servlet.jsp.tagext;
018
019 /**
020 * Optional class provided by the tag library author to describe additional
021 * translation-time information not described in the TLD.
022 * The TagExtraInfo class is mentioned in the Tag Library Descriptor file (TLD).
023 *
024 * <p>
025 * This class can be used:
026 * <ul>
027 * <li> to indicate that the tag defines scripting variables
028 * <li> to perform translation-time validation of the tag attributes.
029 * </ul>
030 *
031 * <p>
032 * It is the responsibility of the JSP translator that the initial value
033 * to be returned by calls to getTagInfo() corresponds to a TagInfo
034 * object for the tag being translated. If an explicit call to
035 * setTagInfo() is done, then the object passed will be returned in
036 * subsequent calls to getTagInfo().
037 *
038 * <p>
039 * The only way to affect the value returned by getTagInfo()
040 * is through a setTagInfo() call, and thus, TagExtraInfo.setTagInfo() is
041 * to be called by the JSP translator, with a TagInfo object that
042 * corresponds to the tag being translated. The call should happen before
043 * any invocation on validate() and before any invocation on
044 * getVariableInfo().
045 *
046 * <p>
047 * <tt>NOTE:</tt> It is a (translation time) error for a tag definition
048 * in a TLD with one or more variable subelements to have an associated
049 * TagExtraInfo implementation that returns a VariableInfo array with
050 * one or more elements from a call to getVariableInfo().
051 */
052
053 public abstract class TagExtraInfo {
054
055 /**
056 * Sole constructor. (For invocation by subclass constructors,
057 * typically implicit.)
058 */
059 public TagExtraInfo() {
060 }
061
062 /**
063 * information on scripting variables defined by the tag associated with
064 * this TagExtraInfo instance.
065 * Request-time attributes are indicated as such in the TagData parameter.
066 *
067 * @param data The TagData instance.
068 * @return An array of VariableInfo data, or null or a zero length array
069 * if no scripting variables are to be defined.
070 */
071 public VariableInfo[] getVariableInfo(TagData data) {
072 return ZERO_VARIABLE_INFO;
073 }
074
075 /**
076 * Translation-time validation of the attributes.
077 * Request-time attributes are indicated as such in the TagData parameter.
078 * Note that the preferred way to do validation is with the validate()
079 * method, since it can return more detailed information.
080 *
081 * @param data The TagData instance.
082 * @return Whether this tag instance is valid.
083 * @see TagExtraInfo#validate
084 */
085
086 public boolean isValid(TagData data) {
087 return true;
088 }
089
090 /**
091 * Translation-time validation of the attributes.
092 * Request-time attributes are indicated as such in the TagData parameter.
093 * Because of the higher quality validation messages possible,
094 * this is the preferred way to do validation (although isValid()
095 * still works).
096 *
097 * <p>JSP 2.0 and higher containers call validate() instead of isValid().
098 * The default implementation of this method is to call isValid(). If
099 * isValid() returns false, a generic ValidationMessage[] is returned
100 * indicating isValid() returned false.</p>
101 *
102 * @param data The TagData instance.
103 * @return A null object, or zero length array if no errors, an
104 * array of ValidationMessages otherwise.
105 * @since 2.0
106 */
107 public ValidationMessage[] validate(TagData data) {
108 ValidationMessage[] result = null;
109
110 if (!isValid(data)) {
111 result = new ValidationMessage[] { new ValidationMessage(
112 data.getId(), "isValid() == false") };
113 }
114
115 return result;
116 }
117
118 /**
119 * Set the TagInfo for this class.
120 *
121 * @param tagInfo The TagInfo this instance is extending
122 */
123 public final void setTagInfo(TagInfo tagInfo) {
124 this .tagInfo = tagInfo;
125 }
126
127 /**
128 * Get the TagInfo for this class.
129 *
130 * @return the taginfo instance this instance is extending
131 */
132 public final TagInfo getTagInfo() {
133 return tagInfo;
134 }
135
136 // private data
137 private TagInfo tagInfo;
138
139 // zero length VariableInfo array
140 private static final VariableInfo[] ZERO_VARIABLE_INFO = {};
141 }
|