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    
030    /**
031     * Interface for defining Simple Tag Handlers.
032     * 
033     * <p>Simple Tag Handlers differ from Classic Tag Handlers in that instead 
034     * of supporting <code>doStartTag()</code> and <code>doEndTag()</code>, 
035     * the <code>SimpleTag</code> interface provides a simple 
036     * <code>doTag()</code> method, which is called once and only once for any 
037     * given tag invocation.  All tag logic, iteration, body evaluations, etc. 
038     * are to be performed in this single method.  Thus, simple tag handlers 
039     * have the equivalent power of <code>BodyTag</code>, but with a much 
040     * simpler lifecycle and interface.</p>
041     *
042     * <p>To support body content, the <code>setJspBody()</code> 
043     * method is provided.  The container invokes the <code>setJspBody()</code> 
044     * method with a <code>JspFragment</code> object encapsulating the body of 
045     * the tag.  The tag handler implementation can call 
046     * <code>invoke()</code> on that fragment to evaluate the body as
047     * many times as it needs.</p>
048     *
049     * <p>A SimpleTag handler must have a public no-args constructor.  Most
050     * SimpleTag handlers should extend SimpleTagSupport.</p>
051     * 
052     * <p><b>Lifecycle</b></p>
053     *
054     * <p>The following is a non-normative, brief overview of the 
055     * SimpleTag lifecycle.  Refer to the JSP Specification for details.</p>
056     *
057     * <ol>
058     *   <li>A new tag handler instance is created each time by the container 
059     *       by calling the provided zero-args constructor.  Unlike classic
060     *       tag handlers, simple tag handlers are never cached and reused by
061     *       the JSP container.</li>
062     *   <li>The <code>setJspContext()</code> and <code>setParent()</code> 
063     *       methods are called by the container.  The <code>setParent()</code>
064     *       method is only called if the element is nested within another tag 
065     *       invocation.</li>
066     *   <li>The setters for each attribute defined for this tag are called
067     *       by the container.</li>
068     *   <li>If a body exists, the <code>setJspBody()</code> method is called 
069     *       by the container to set the body of this tag, as a 
070     *       <code>JspFragment</code>.  If the action element is empty in
071     *       the page, this method is not called at all.</li>
072     *   <li>The <code>doTag()</code> method is called by the container.  All
073     *       tag logic, iteration, body evaluations, etc. occur in this 
074     *       method.</li>
075     *   <li>The <code>doTag()</code> method returns and all variables are
076     *       synchronized.</li>
077     * </ol>
078     * 
079     * @see SimpleTagSupport
080     * @since 2.0
081     */
082    public interface SimpleTag extends JspTag {
083        
084        /** 
085         * Called by the container to invoke this tag.
086         * The implementation of this method is provided by the tag library
087         * developer, and handles all tag processing, body iteration, etc.
088         *
089         * <p>
090         * The JSP container will resynchronize any AT_BEGIN and AT_END
091         * variables (defined by the associated tag file, TagExtraInfo, or TLD)
092         * after the invocation of doTag().
093         * 
094         * @throws javax.servlet.jsp.JspException If an error occurred 
095         *     while processing this tag.
096         * @throws javax.servlet.jsp.SkipPageException If the page that
097         *     (either directly or indirectly) invoked this tag is to
098         *     cease evaluation.  A Simple Tag Handler generated from a 
099         *     tag file must throw this exception if an invoked Classic 
100         *     Tag Handler returned SKIP_PAGE or if an invoked Simple
101         *     Tag Handler threw SkipPageException or if an invoked Jsp Fragment
102         *     threw a SkipPageException.
103         * @throws java.io.IOException If there was an error writing to the
104         *     output stream.
105         */ 
106        public void doTag() 
107            throws javax.servlet.jsp.JspException, java.io.IOException;
108        
109        /**
110         * Sets the parent of this tag, for collaboration purposes.
111         * <p>
112         * The container invokes this method only if this tag invocation is 
113         * nested within another tag invocation.
114         *
115         * @param parent the tag that encloses this tag
116         */
117        public void setParent( JspTag parent );
118        
119        /**
120         * Returns the parent of this tag, for collaboration purposes.
121         *
122         * @return the parent of this tag
123         */ 
124        public JspTag getParent();
125        
126        /**
127         * Called by the container to provide this tag handler with
128         * the <code>JspContext</code> for this invocation.
129         * An implementation should save this value.
130         * 
131         * @param pc the page context for this invocation
132         * @see Tag#setPageContext
133         */
134        public void setJspContext( JspContext pc );
135                    
136        /** 
137         * Provides the body of this tag as a JspFragment object, able to be 
138         * invoked zero or more times by the tag handler. 
139         * <p>
140         * This method is invoked by the JSP page implementation 
141         * object prior to <code>doTag()</code>.  If the action element is
142         * empty in the page, this method is not called at all.
143         * 
144         * @param jspBody The fragment encapsulating the body of this tag.
145         */ 
146        public void setJspBody( JspFragment jspBody );
147    
148        
149    }