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