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