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 import java.util.Map; 021 022 /** 023 * Translation-time validator class for a JSP page. 024 * A validator operates on the XML view associated with the JSP page. 025 * 026 * <p> 027 * The TLD file associates a TagLibraryValidator class and some init 028 * arguments with a tag library. 029 * 030 * <p> 031 * The JSP container is reponsible for locating an appropriate 032 * instance of the appropriate subclass by 033 * 034 * <ul> 035 * <li> new a fresh instance, or reuse an available one 036 * <li> invoke the setInitParams(Map) method on the instance 037 * </ul> 038 * 039 * once initialized, the validate(String, String, PageData) method will 040 * be invoked, where the first two arguments are the prefix 041 * and uri for this tag library in the XML View. The prefix is intended 042 * to make it easier to produce an error message. However, it is not 043 * always accurate. In the case where a single URI is mapped to more 044 * than one prefix in the XML view, the prefix of the first URI is provided. 045 * Therefore, to provide high quality error messages in cases where the 046 * tag elements themselves are checked, the prefix parameter should be 047 * ignored and the actual prefix of the element should be used instead. 048 * TagLibraryValidators should always use the uri to identify elements 049 * as beloning to the tag library, not the prefix. 050 * 051 * <p> 052 * A TagLibraryValidator instance 053 * may create auxiliary objects internally to perform 054 * the validation (e.g. an XSchema validator) and may reuse it for all 055 * the pages in a given translation run. 056 * 057 * <p> 058 * The JSP container is not guaranteed to serialize invocations of 059 * validate() method, and TagLibraryValidators should perform any 060 * synchronization they may require. 061 * 062 * <p> 063 * As of JSP 2.0, a JSP container must provide a jsp:id attribute to 064 * provide higher quality validation errors. 065 * The container will track the JSP pages 066 * as passed to the container, and will assign to each element 067 * a unique "id", which is passed as the value of the jsp:id 068 * attribute. Each XML element in the XML view available will 069 * be extended with this attribute. The TagLibraryValidator 070 * can then use the attribute in one or more ValidationMessage 071 * objects. The container then, in turn, can use these 072 * values to provide more precise information on the location 073 * of an error. 074 * 075 * <p> 076 * The actual prefix of the <code>id</code> attribute may or may not be 077 * <code>jsp</code> but it will always map to the namespace 078 * <code>http://java.sun.com/JSP/Page</code>. A TagLibraryValidator 079 * implementation must rely on the uri, not the prefix, of the <code>id</code> 080 * attribute. 081 */ 082 083 abstract public class TagLibraryValidator { 084 085 /** 086 * Sole constructor. (For invocation by subclass constructors, 087 * typically implicit.) 088 */ 089 public TagLibraryValidator() { 090 } 091 092 /** 093 * Set the init data in the TLD for this validator. 094 * Parameter names are keys, and parameter values are the values. 095 * 096 * @param map A Map describing the init parameters 097 */ 098 public void setInitParameters(Map<String, Object> map) { 099 initParameters = map; 100 } 101 102 103 /** 104 * Get the init parameters data as an immutable Map. 105 * Parameter names are keys, and parameter values are the values. 106 * 107 * @return The init parameters as an immutable map. 108 */ 109 public Map<String, Object> getInitParameters() { 110 return initParameters; 111 } 112 113 /** 114 * Validate a JSP page. 115 * This will get invoked once per unique tag library URI in the 116 * XML view. This method will return null if the page is valid; otherwise 117 * the method should return an array of ValidationMessage objects. 118 * An array of length zero is also interpreted as no errors. 119 * 120 * @param prefix the first prefix with which the tag library is 121 * associated, in the XML view. Note that some tags may use 122 * a different prefix if the namespace is redefined. 123 * @param uri the tag library's unique identifier 124 * @param page the JspData page object 125 * @return A null object, or zero length array if no errors, an array 126 * of ValidationMessages otherwise. 127 */ 128 public ValidationMessage[] validate(String prefix, String uri, 129 PageData page) 130 { 131 return null; 132 } 133 134 /** 135 * Release any data kept by this instance for validation purposes. 136 */ 137 public void release() { 138 initParameters = null; 139 } 140 141 // Private data 142 private Map<String, Object> initParameters; 143 144 }