001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *  http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    
020    //
021    // This source code implements specifications defined by the Java
022    // Community Process. In order to remain compliant with the specification
023    // DO NOT add / change / or delete method signatures!
024    //
025    
026    package javax.servlet.jsp.tagext;
027    
028    import javax.servlet.jsp.JspContext;
029    import javax.servlet.jsp.JspException;
030    import java.io.IOException;
031    
032    /**
033     * A base class for defining tag handlers implementing SimpleTag.
034     * <p>
035     * The SimpleTagSupport class is a utility class intended to be used
036     * as the base class for new simple tag handlers.  The SimpleTagSupport
037     * class implements the SimpleTag interface and adds additional
038     * convenience methods including getter methods for the properties in
039     * SimpleTag.
040     *
041     * @since 2.0
042     */
043    public class SimpleTagSupport 
044        implements SimpleTag
045    {
046        /** Reference to the enclosing tag. */
047        private JspTag parentTag;
048        
049        /** The JSP context for the upcoming tag invocation. */
050        private JspContext jspContext;
051        
052        /** The body of the tag. */
053        private JspFragment jspBody;
054        
055        /**
056         * Sole constructor. (For invocation by subclass constructors, 
057         * typically implicit.)
058         */
059        public SimpleTagSupport() {
060        }
061        
062        /** 
063         * Default processing of the tag does nothing.
064         *
065         * @throws JspException Subclasses can throw JspException to indicate
066         *     an error occurred while processing this tag.
067         * @throws javax.servlet.jsp.SkipPageException If the page that
068         *     (either directly or indirectly) invoked this tag is to
069         *     cease evaluation.  A Simple Tag Handler generated from a 
070         *     tag file must throw this exception if an invoked Classic 
071         *     Tag Handler returned SKIP_PAGE or if an invoked Simple
072         *     Tag Handler threw SkipPageException or if an invoked Jsp Fragment
073         *     threw a SkipPageException.
074         * @throws IOException Subclasses can throw IOException if there was
075         *     an error writing to the output stream
076         * @see SimpleTag#doTag()
077         */ 
078        public void doTag() 
079            throws JspException, IOException
080        {
081        }
082        
083        /**
084         * Sets the parent of this tag, for collaboration purposes.
085         * <p>
086         * The container invokes this method only if this tag invocation is
087         * nested within another tag invocation.
088         *
089         * @param parent the tag that encloses this tag
090         */
091        public void setParent( JspTag parent ) {
092            this.parentTag = parent;
093        }
094        
095        /**
096         * Returns the parent of this tag, for collaboration purposes.
097         *
098         * @return the parent of this tag
099         */ 
100        public JspTag getParent() {
101            return this.parentTag;
102        }
103        
104        /**
105         * Stores the provided JSP context in the private jspContext field.
106         * Subclasses can access the <code>JspContext</code> via 
107         * <code>getJspContext()</code>.
108         * 
109         * @param pc the page context for this invocation
110         * @see SimpleTag#setJspContext
111         */
112        public void setJspContext( JspContext pc ) {
113            this.jspContext = pc;
114        }
115        
116        /**
117         * Returns the page context passed in by the container via 
118         * setJspContext.
119         *
120         * @return the page context for this invocation
121         */
122        protected JspContext getJspContext() {
123            return this.jspContext;
124        }
125                    
126        /** 
127         * Stores the provided JspFragment.
128         *
129         * @param jspBody The fragment encapsulating the body of this tag.
130         *     If the action element is empty in the page, this method is 
131         *     not called at all.
132         * @see SimpleTag#setJspBody
133         */ 
134        public void setJspBody( JspFragment jspBody ) {
135            this.jspBody = jspBody;
136        }
137        
138        /**
139         * Returns the body passed in by the container via setJspBody.
140         *
141         * @return the fragment encapsulating the body of this tag, or
142         *    null if the action element is empty in the page.
143         */
144        protected JspFragment getJspBody() {
145            return this.jspBody;
146        }
147    
148        /**
149         * Find the instance of a given class type that is closest to a given
150         * instance.
151         * This method uses the getParent method from the Tag and/or SimpleTag
152         * interfaces.  This method is used for coordination among 
153         * cooperating tags.
154         *
155         * <p> For every instance of TagAdapter
156         * encountered while traversing the ancestors, the tag handler returned by
157         * <tt>TagAdapter.getAdaptee()</tt> - instead of the TagAdpater itself -
158         * is compared to <tt>klass</tt>. If the tag handler matches, it - and
159         * not its TagAdapter - is returned.
160         *
161         * <p>
162         * The current version of the specification only provides one formal
163         * way of indicating the observable type of a tag handler: its
164         * tag handler implementation class, described in the tag-class
165         * subelement of the tag element.  This is extended in an
166         * informal manner by allowing the tag library author to
167         * indicate in the description subelement an observable type.
168         * The type should be a subtype of the tag handler implementation
169         * class or void.
170         * This addititional constraint can be exploited by a
171         * specialized container that knows about that specific tag library,
172         * as in the case of the JSP standard tag library.
173         *
174         * <p>
175         * When a tag library author provides information on the
176         * observable type of a tag handler, client programmatic code
177         * should adhere to that constraint.  Specifically, the Class
178         * passed to findAncestorWithClass should be a subtype of the
179         * observable type.
180         * 
181         *
182         * @param from The instance from where to start looking.
183         * @param klass The subclass of JspTag or interface to be matched
184         * @return the nearest ancestor that implements the interface
185         * or is an instance of the class specified
186         */
187        public static final JspTag findAncestorWithClass(
188            JspTag from, Class klass) 
189        {
190            boolean isInterface = false;
191    
192            if (from == null || klass == null
193                    || (!JspTag.class.isAssignableFrom(klass)
194                        && !(isInterface = klass.isInterface()))) {
195                return null;
196            }
197    
198            for (;;) {
199                JspTag parent = null;
200                if( from instanceof SimpleTag ) {
201                    parent = ((SimpleTag)from).getParent();
202                }
203                else if( from instanceof Tag ) {
204                    parent = ((Tag)from).getParent();
205                }
206                if (parent == null) {
207                    return null;
208                }
209    
210                if (parent instanceof TagAdapter) {
211                    parent = ((TagAdapter) parent).getAdaptee();
212                }
213    
214                if ((isInterface && klass.isInstance(parent))
215                        || klass.isAssignableFrom(parent.getClass())) {
216                    return parent;
217                }
218    
219                from = parent;
220            }
221        }    
222    }