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  /**
    27   * Optional class provided by the tag library author to describe additional
    28   * translation-time information not described in the TLD.
    29   * The TagExtraInfo class is mentioned in the Tag Library Descriptor file (TLD).
    30   *
    31   * <p>
    32   * This class can be used:
    33   * <ul>
    34   * <li> to indicate that the tag defines scripting variables
    35   * <li> to perform translation-time validation of the tag attributes.
    36   * </ul>
    37   *
    38   * <p>
    39   * It is the responsibility of the JSP translator that the initial value
    40   * to be returned by calls to getTagInfo() corresponds to a TagInfo
    41   * object for the tag being translated. If an explicit call to
    42   * setTagInfo() is done, then the object passed will be returned in
    43   * subsequent calls to getTagInfo().
    44   *
    45   * <p>
    46   * The only way to affect the value returned by getTagInfo()
    47   * is through a setTagInfo() call, and thus, TagExtraInfo.setTagInfo() is
    48   * to be called by the JSP translator, with a TagInfo object that
    49   * corresponds to the tag being translated. The call should happen before
    50   * any invocation on validate() and before any invocation on
    51   * getVariableInfo().
    52   *
    53   * <p>
    54   * <tt>NOTE:</tt> It is a (translation time) error for a tag definition
    55   * in a TLD with one or more variable subelements to have an associated
    56   * TagExtraInfo implementation that returns a VariableInfo array with
    57   * one or more elements from a call to getVariableInfo().
    58   */
    59
    60  public abstract class TagExtraInfo {
    61
    62      /**
    63       * Sole constructor. (For invocation by subclass constructors,
    64       * typically implicit.)
    65       */
    66      public TagExtraInfo() {
    67      }
    68
    69      /**
    70       * information on scripting variables defined by the tag associated with
    71       * this TagExtraInfo instance.
    72       * Request-time attributes are indicated as such in the TagData parameter.
    73       *
    74       * @param data The TagData instance.
    75       * @return An array of VariableInfo data, or null or a zero length array
    76       *         if no scripting variables are to be defined.
    77       */
    78      public VariableInfo[] getVariableInfo(TagData data) {
    79  	return ZERO_VARIABLE_INFO;
    80      }
    81
    82      /**
    83       * Translation-time validation of the attributes.
    84       * Request-time attributes are indicated as such in the TagData parameter.
    85       * Note that the preferred way to do validation is with the validate()
    86       * method, since it can return more detailed information.
    87       *
    88       * @param data The TagData instance.
    89       * @return Whether this tag instance is valid.
    90       * @see TagExtraInfo#validate
    91       */
    92
    93      public boolean isValid(TagData data) {
    94  	return true;
    95      }
    96
    97      /**
    98       * Translation-time validation of the attributes.
    99       * Request-time attributes are indicated as such in the TagData parameter.
    100      * Because of the higher quality validation messages possible,
    101      * this is the preferred way to do validation (although isValid()
    102      * still works).
    103      *
    104      * <p>JSP 2.0 and higher containers call validate() instead of isValid().
    105      * The default implementation of this method is to call isValid().  If
    106      * isValid() returns false, a generic ValidationMessage[] is returned
    107      * indicating isValid() returned false.</p>
    108      *
    109      * @param data The TagData instance.
    110      * @return A null object, or zero length array if no errors, an
    111      *     array of ValidationMessages otherwise.
    112      * @since 2.0
    113      */
    114     public ValidationMessage[] validate( TagData data ) {
    115 	ValidationMessage[] result = null;
    116
    117 	if( !isValid( data ) ) {
    118 	    result = new ValidationMessage[] {
    119 		new ValidationMessage( data.getId(), "isValid() == false" ) };
    120 	}
    121
    122 	return result;
    123     }
    124
    125     /**
    126      * Set the TagInfo for this class.
    127      *
    128      * @param tagInfo The TagInfo this instance is extending
    129      */
    130     public final void setTagInfo(TagInfo tagInfo) {
    131 	this.tagInfo = tagInfo;
    132     }
    133
    134     /**
    135      * Get the TagInfo for this class.
    136      *
    137      * @return the taginfo instance this instance is extending
    138      */
    139     public final TagInfo getTagInfo() {
    140 	return tagInfo;
    141     }
    142
    143     // private data
    144     private TagInfo tagInfo;
    145
    146     // zero length VariableInfo array
    147     private static final VariableInfo[] ZERO_VARIABLE_INFO = { };
    148 }
    149