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 javax.servlet.jsp.JspException;
    27  import javax.servlet.jsp.PageContext;
    28
    29
    30  /**
    31   * Wraps any SimpleTag and exposes it using a Tag interface.  This is used
    32   * to allow collaboration between classic Tag handlers and SimpleTag
    33   * handlers.
    34   * <p>
    35   * Because SimpleTag does not extend Tag, and because Tag.setParent()
    36   * only accepts a Tag instance, a classic tag handler (one
    37   * that implements Tag) cannot have a SimpleTag as its parent.  To remedy
    38   * this, a TagAdapter is created to wrap the SimpleTag parent, and the
    39   * adapter is passed to setParent() instead.  A classic Tag EventHandler can
    40   * call getAdaptee() to retrieve the encapsulated SimpleTag instance.
    41   *
    42   * @since 2.0
    43   */
    44  public class TagAdapter
    45      implements Tag
    46  {
    47      /** The simple tag that's being adapted. */
    48      private SimpleTag simpleTagAdaptee;
    49
    50      /** The parent, of this tag, converted (if necessary) to be of type Tag. */
    51      private Tag parent;
    52
    53      // Flag indicating whether we have already determined the parent
    54      private boolean parentDetermined;
    55
    56      /**
    57       * Creates a new TagAdapter that wraps the given SimpleTag and
    58       * returns the parent tag when getParent() is called.
    59       *
    60       * @param adaptee The SimpleTag being adapted as a Tag.
    61       */
    62      public TagAdapter( SimpleTag adaptee ) {
    63          if( adaptee == null ) {
    64  	    // Cannot wrap a null adaptee.
    65  	    throw new IllegalArgumentException();
    66          }
    67          this.simpleTagAdaptee = adaptee;
    68      }
    69
    70      /**
    71       * Must not be called.
    72       *
    73       * @param pc ignored.
    74       * @throws UnsupportedOperationException Must not be called
    75       */
    76      public void setPageContext(PageContext pc) {
    77          throw new UnsupportedOperationException(
    78              "Illegal to invoke setPageContext() on TagAdapter wrapper" );
    79      }
    80
    81
    82      /**
    83       * Must not be called.  The parent of this tag is always
    84       * getAdaptee().getParent().
    85       *
    86       * @param parentTag ignored.
    87       * @throws UnsupportedOperationException Must not be called.
    88       */
    89      public void setParent( Tag parentTag ) {
    90          throw new UnsupportedOperationException(
    91              "Illegal to invoke setParent() on TagAdapter wrapper" );
    92      }
    93
    94
    95      /**
    96       * Returns the parent of this tag, which is always
    97       * getAdaptee().getParent().
    98       *
    99       * This will either be the enclosing Tag (if getAdaptee().getParent()
    100      * implements Tag), or an adapter to the enclosing Tag (if
    101      * getAdaptee().getParent() does not implement Tag).
    102      *
    103      * @return The parent of the tag being adapted.
    104      */
    105     public Tag getParent() {
    106 	if (!parentDetermined) {
    107 	    JspTag adapteeParent = simpleTagAdaptee.getParent();
    108 	    if (adapteeParent != null) {
    109 		if (adapteeParent instanceof Tag) {
    110 		    this.parent = (Tag) adapteeParent;
    111 		} else {
    112 		    // Must be SimpleTag - no other types defined.
    113 		    this.parent = new TagAdapter((SimpleTag) adapteeParent);
    114 		}
    115 	    }
    116 	    parentDetermined = true;
    117 	}
    118
    119 	return this.parent;
    120     }
    121
    122     /**
    123      * Gets the tag that is being adapted to the Tag interface.
    124      * This should be an instance of SimpleTag in JSP 2.0, but room
    125      * is left for other kinds of tags in future spec versions.
    126      *
    127      * @return the tag that is being adapted
    128      */
    129     public JspTag getAdaptee() {
    130         return this.simpleTagAdaptee;
    131     }
    132
    133     /**
    134      * Must not be called.
    135      *
    136      * @return always throws UnsupportedOperationException
    137      * @throws UnsupportedOperationException Must not be called
    138      * @throws JspException never thrown
    139      */
    140     public int doStartTag() throws JspException {
    141         throw new UnsupportedOperationException(
    142             "Illegal to invoke doStartTag() on TagAdapter wrapper" );
    143     }
    144
    145     /**
    146      * Must not be called.
    147      *
    148      * @return always throws UnsupportedOperationException
    149      * @throws UnsupportedOperationException Must not be called
    150      * @throws JspException never thrown
    151      */
    152     public int doEndTag() throws JspException {
    153         throw new UnsupportedOperationException(
    154             "Illegal to invoke doEndTag() on TagAdapter wrapper" );
    155     }
    156
    157     /**
    158      * Must not be called.
    159      *
    160      * @throws UnsupportedOperationException Must not be called
    161      */
    162     public void release() {
    163         throw new UnsupportedOperationException(
    164             "Illegal to invoke release() on TagAdapter wrapper" );
    165     }
    166 }