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 }