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 }