1 /** 2 * 3 * Copyright 2003-2004 The Apache Software Foundation 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 // 19 // This source code implements specifications defined by the Java 20 // Community Process. In order to remain compliant with the specification 21 // DO NOT add / change / or delete method signatures! 22 // 23 24 package javax.servlet.jsp.tagext; 25 26 import java.util.Map; 27 28 /** 29 * Translation-time validator class for a JSP page. 30 * A validator operates on the XML view associated with the JSP page. 31 * 32 * <p> 33 * The TLD file associates a TagLibraryValidator class and some init 34 * arguments with a tag library. 35 * 36 * <p> 37 * The JSP container is reponsible for locating an appropriate 38 * instance of the appropriate subclass by 39 * 40 * <ul> 41 * <li> new a fresh instance, or reuse an available one 42 * <li> invoke the setInitParams(Map) method on the instance 43 * </ul> 44 * 45 * once initialized, the validate(String, String, PageData) method will 46 * be invoked, where the first two arguments are the prefix 47 * and uri for this tag library in the XML View. The prefix is intended 48 * to make it easier to produce an error message. However, it is not 49 * always accurate. In the case where a single URI is mapped to more 50 * than one prefix in the XML view, the prefix of the first URI is provided. 51 * Therefore, to provide high quality error messages in cases where the 52 * tag elements themselves are checked, the prefix parameter should be 53 * ignored and the actual prefix of the element should be used instead. 54 * TagLibraryValidators should always use the uri to identify elements 55 * as beloning to the tag library, not the prefix. 56 * 57 * <p> 58 * A TagLibraryValidator instance 59 * may create auxiliary objects internally to perform 60 * the validation (e.g. an XSchema validator) and may reuse it for all 61 * the pages in a given translation run. 62 * 63 * <p> 64 * The JSP container is not guaranteed to serialize invocations of 65 * validate() method, and TagLibraryValidators should perform any 66 * synchronization they may require. 67 * 68 * <p> 69 * As of JSP 2.0, a JSP container must provide a jsp:id attribute to 70 * provide higher quality validation errors. 71 * The container will track the JSP pages 72 * as passed to the container, and will assign to each element 73 * a unique "id", which is passed as the value of the jsp:id 74 * attribute. Each XML element in the XML view available will 75 * be extended with this attribute. The TagLibraryValidator 76 * can then use the attribute in one or more ValidationMessage 77 * objects. The container then, in turn, can use these 78 * values to provide more precise information on the location 79 * of an error. 80 * 81 * <p> 82 * The actual prefix of the <code>id</code> attribute may or may not be 83 * <code>jsp</code> but it will always map to the namespace 84 * <code>http://java.sun.com/JSP/Page</code>. A TagLibraryValidator 85 * implementation must rely on the uri, not the prefix, of the <code>id</code> 86 * attribute. 87 */ 88 89 abstract public class TagLibraryValidator { 90 91 /** 92 * Sole constructor. (For invocation by subclass constructors, 93 * typically implicit.) 94 */ 95 public TagLibraryValidator() { 96 } 97 98 /** 99 * Set the init data in the TLD for this validator. 100 * Parameter names are keys, and parameter values are the values. 101 * 102 * @param map A Map describing the init parameters 103 */ 104 public void setInitParameters(Map map) { 105 initParameters = map; 106 } 107 108 109 /** 110 * Get the init parameters data as an immutable Map. 111 * Parameter names are keys, and parameter values are the values. 112 * 113 * @return The init parameters as an immutable map. 114 */ 115 public Map getInitParameters() { 116 return initParameters; 117 } 118 119 /** 120 * Validate a JSP page. 121 * This will get invoked once per unique tag library URI in the 122 * XML view. This method will return null if the page is valid; otherwise 123 * the method should return an array of ValidationMessage objects. 124 * An array of length zero is also interpreted as no errors. 125 * 126 * @param prefix the first prefix with which the tag library is 127 * associated, in the XML view. Note that some tags may use 128 * a different prefix if the namespace is redefined. 129 * @param uri the tag library's unique identifier 130 * @param page the JspData page object 131 * @return A null object, or zero length array if no errors, an array 132 * of ValidationMessages otherwise. 133 */ 134 public ValidationMessage[] validate(String prefix, String uri, 135 PageData page) 136 { 137 return null; 138 } 139 140 /** 141 * Release any data kept by this instance for validation purposes. 142 */ 143 public void release() { 144 initParameters = null; 145 } 146 147 // Private data 148 private Map initParameters; 149 150 }