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 019 package javax.servlet.jsp.tagext; 020 021 /** 022 * Optional class provided by the tag library author to describe additional 023 * translation-time information not described in the TLD. 024 * The TagExtraInfo class is mentioned in the Tag Library Descriptor file (TLD). 025 * 026 * <p> 027 * This class can be used: 028 * <ul> 029 * <li> to indicate that the tag defines scripting variables 030 * <li> to perform translation-time validation of the tag attributes. 031 * </ul> 032 * 033 * <p> 034 * It is the responsibility of the JSP translator that the initial value 035 * to be returned by calls to getTagInfo() corresponds to a TagInfo 036 * object for the tag being translated. If an explicit call to 037 * setTagInfo() is done, then the object passed will be returned in 038 * subsequent calls to getTagInfo(). 039 * 040 * <p> 041 * The only way to affect the value returned by getTagInfo() 042 * is through a setTagInfo() call, and thus, TagExtraInfo.setTagInfo() is 043 * to be called by the JSP translator, with a TagInfo object that 044 * corresponds to the tag being translated. The call should happen before 045 * any invocation on validate() and before any invocation on 046 * getVariableInfo(). 047 * 048 * <p> 049 * <tt>NOTE:</tt> It is a (translation time) error for a tag definition 050 * in a TLD with one or more variable subelements to have an associated 051 * TagExtraInfo implementation that returns a VariableInfo array with 052 * one or more elements from a call to getVariableInfo(). 053 */ 054 055 public abstract class TagExtraInfo { 056 057 /** 058 * Sole constructor. (For invocation by subclass constructors, 059 * typically implicit.) 060 */ 061 public TagExtraInfo() { 062 } 063 064 /** 065 * information on scripting variables defined by the tag associated with 066 * this TagExtraInfo instance. 067 * Request-time attributes are indicated as such in the TagData parameter. 068 * 069 * @param data The TagData instance. 070 * @return An array of VariableInfo data, or null or a zero length array 071 * if no scripting variables are to be defined. 072 */ 073 public VariableInfo[] getVariableInfo(TagData data) { 074 return ZERO_VARIABLE_INFO; 075 } 076 077 /** 078 * Translation-time validation of the attributes. 079 * Request-time attributes are indicated as such in the TagData parameter. 080 * Note that the preferred way to do validation is with the validate() 081 * method, since it can return more detailed information. 082 * 083 * @param data The TagData instance. 084 * @return Whether this tag instance is valid. 085 * @see TagExtraInfo#validate 086 */ 087 088 public boolean isValid(TagData data) { 089 return true; 090 } 091 092 /** 093 * Translation-time validation of the attributes. 094 * Request-time attributes are indicated as such in the TagData parameter. 095 * Because of the higher quality validation messages possible, 096 * this is the preferred way to do validation (although isValid() 097 * still works). 098 * 099 * <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