View Javadoc

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 }