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    }