1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
5 *
6 * Portions Copyright Apache Software Foundation.
7 *
8 * The contents of this file are subject to the terms of either the GNU
9 * General Public License Version 2 only ("GPL") or the Common Development
10 * and Distribution License("CDDL") (collectively, the "License"). You
11 * may not use this file except in compliance with the License. You can obtain
12 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
13 * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
14 * language governing permissions and limitations under the License.
15 *
16 * When distributing the software, include this License Header Notice in each
17 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
18 * Sun designates this particular file as subject to the "Classpath" exception
19 * as provided by Sun in the GPL Version 2 section of the License file that
20 * accompanied this code. If applicable, add the following below the License
21 * Header, with the fields enclosed by brackets [] replaced by your own
22 * identifying information: "Portions Copyrighted [year]
23 * [name of copyright owner]"
24 *
25 * Contributor(s):
26 *
27 * If you wish your version of this file to be governed by only the CDDL or
28 * only the GPL Version 2, indicate your decision by adding "[Contributor]
29 * elects to include this software in this distribution under the [CDDL or GPL
30 * Version 2] license." If you don't indicate a single choice of license, a
31 * recipient has the option to distribute your version of this file under
32 * either the CDDL, the GPL Version 2 or to extend the choice of license to
33 * its licensees as provided above. However, if you add GPL Version 2 code
34 * and therefore, elected the GPL Version 2 license, then the option applies
35 * only if the new code is made subject to such option by the copyright
36 * holder.
37 */
38
39 package javax.servlet.jsp.tagext;
40
41 /**
42 * Optional class provided by the tag library author to describe additional
43 * translation-time information not described in the TLD.
44 * The TagExtraInfo class is mentioned in the Tag Library Descriptor file (TLD).
45 *
46 * <p>
47 * This class can be used:
48 * <ul>
49 * <li> to indicate that the tag defines scripting variables
50 * <li> to perform translation-time validation of the tag attributes.
51 * </ul>
52 *
53 * <p>
54 * It is the responsibility of the JSP translator that the initial value
55 * to be returned by calls to getTagInfo() corresponds to a TagInfo
56 * object for the tag being translated. If an explicit call to
57 * setTagInfo() is done, then the object passed will be returned in
58 * subsequent calls to getTagInfo().
59 *
60 * <p>
61 * The only way to affect the value returned by getTagInfo()
62 * is through a setTagInfo() call, and thus, TagExtraInfo.setTagInfo() is
63 * to be called by the JSP translator, with a TagInfo object that
64 * corresponds to the tag being translated. The call should happen before
65 * any invocation on validate() and before any invocation on
66 * getVariableInfo().
67 *
68 * <p>
69 * <tt>NOTE:</tt> It is a (translation time) error for a tag definition
70 * in a TLD with one or more variable subelements to have an associated
71 * TagExtraInfo implementation that returns a VariableInfo array with
72 * one or more elements from a call to getVariableInfo().
73 */
74
75 public abstract class TagExtraInfo {
76
77 /**
78 * Sole constructor. (For invocation by subclass constructors,
79 * typically implicit.)
80 */
81 public TagExtraInfo() {
82 }
83
84 /**
85 * information on scripting variables defined by the tag associated with
86 * this TagExtraInfo instance.
87 * Request-time attributes are indicated as such in the TagData parameter.
88 *
89 * @param data The TagData instance.
90 * @return An array of VariableInfo data, or null or a zero length array
91 * if no scripting variables are to be defined.
92 */
93 public VariableInfo[] getVariableInfo(TagData data) {
94 return ZERO_VARIABLE_INFO;
95 }
96
97 /**
98 * Translation-time validation of the attributes.
99 * Request-time attributes are indicated as such in the TagData parameter.
100 * Note that the preferred way to do validation is with the validate()
101 * method, since it can return more detailed information.
102 *
103 * @param data The TagData instance.
104 * @return Whether this tag instance is valid.
105 * @see TagExtraInfo#validate
106 */
107
108 public boolean isValid(TagData data) {
109 return true;
110 }
111
112 /**
113 * Translation-time validation of the attributes.
114 * Request-time attributes are indicated as such in the TagData parameter.
115 * Because of the higher quality validation messages possible,
116 * this is the preferred way to do validation (although isValid()
117 * still works).
118 *
119 * <p>JSP 2.0 and higher containers call validate() instead of isValid().
120 * The default implementation of this method is to call isValid(). If
121 * isValid() returns false, a generic ValidationMessage[] is returned
122 * indicating isValid() returned false.</p>
123 *
124 * @param data The TagData instance.
125 * @return A null object, or zero length array if no errors, an
126 * array of ValidationMessages otherwise.
127 * @since 2.0
128 */
129 public ValidationMessage[] validate( TagData data ) {
130 ValidationMessage[] result = null;
131
132 if( !isValid( data ) ) {
133 result = new ValidationMessage[] {
134 new ValidationMessage( data.getId(), "isValid() == false" ) };
135 }
136
137 return result;
138 }
139
140 /**
141 * Set the TagInfo for this class.
142 *
143 * @param tagInfo The TagInfo this instance is extending
144 */
145 public final void setTagInfo(TagInfo tagInfo) {
146 this.tagInfo = tagInfo;
147 }
148
149 /**
150 * Get the TagInfo for this class.
151 *
152 * @return the taginfo instance this instance is extending
153 */
154 public final TagInfo getTagInfo() {
155 return tagInfo;
156 }
157
158 // private data
159 private TagInfo tagInfo;
160
161 // zero length VariableInfo array
162 private static final VariableInfo[] ZERO_VARIABLE_INFO = { };
163 }
164
Save This Page