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 }