001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package javax.servlet.jsp.tagext;
018:
019: import javax.servlet.jsp.JspContext;
020:
021: /**
022: * Interface for defining Simple Tag Handlers.
023: *
024: * <p>Simple Tag Handlers differ from Classic Tag Handlers in that instead
025: * of supporting <code>doStartTag()</code> and <code>doEndTag()</code>,
026: * the <code>SimpleTag</code> interface provides a simple
027: * <code>doTag()</code> method, which is called once and only once for any
028: * given tag invocation. All tag logic, iteration, body evaluations, etc.
029: * are to be performed in this single method. Thus, simple tag handlers
030: * have the equivalent power of <code>BodyTag</code>, but with a much
031: * simpler lifecycle and interface.</p>
032: *
033: * <p>To support body content, the <code>setJspBody()</code>
034: * method is provided. The container invokes the <code>setJspBody()</code>
035: * method with a <code>JspFragment</code> object encapsulating the body of
036: * the tag. The tag handler implementation can call
037: * <code>invoke()</code> on that fragment to evaluate the body as
038: * many times as it needs.</p>
039: *
040: * <p>A SimpleTag handler must have a public no-args constructor. Most
041: * SimpleTag handlers should extend SimpleTagSupport.</p>
042: *
043: * <p><b>Lifecycle</b></p>
044: *
045: * <p>The following is a non-normative, brief overview of the
046: * SimpleTag lifecycle. Refer to the JSP Specification for details.</p>
047: *
048: * <ol>
049: * <li>A new tag handler instance is created each time by the container
050: * by calling the provided zero-args constructor. Unlike classic
051: * tag handlers, simple tag handlers are never cached and reused by
052: * the JSP container.</li>
053: * <li>The <code>setJspContext()</code> and <code>setParent()</code>
054: * methods are called by the container. The <code>setParent()</code>
055: * method is only called if the element is nested within another tag
056: * invocation.</li>
057: * <li>The setters for each attribute defined for this tag are called
058: * by the container.</li>
059: * <li>If a body exists, the <code>setJspBody()</code> method is called
060: * by the container to set the body of this tag, as a
061: * <code>JspFragment</code>. If the action element is empty in
062: * the page, this method is not called at all.</li>
063: * <li>The <code>doTag()</code> method is called by the container. All
064: * tag logic, iteration, body evaluations, etc. occur in this
065: * method.</li>
066: * <li>The <code>doTag()</code> method returns and all variables are
067: * synchronized.</li>
068: * </ol>
069: *
070: * @see SimpleTagSupport
071: * @since 2.0
072: */
073: public interface SimpleTag extends JspTag {
074:
075: /**
076: * Called by the container to invoke this tag.
077: * The implementation of this method is provided by the tag library
078: * developer, and handles all tag processing, body iteration, etc.
079: *
080: * <p>
081: * The JSP container will resynchronize any AT_BEGIN and AT_END
082: * variables (defined by the associated tag file, TagExtraInfo, or TLD)
083: * after the invocation of doTag().
084: *
085: * @throws javax.servlet.jsp.JspException If an error occurred
086: * while processing this tag.
087: * @throws javax.servlet.jsp.SkipPageException If the page that
088: * (either directly or indirectly) invoked this tag is to
089: * cease evaluation. A Simple Tag Handler generated from a
090: * tag file must throw this exception if an invoked Classic
091: * Tag Handler returned SKIP_PAGE or if an invoked Simple
092: * Tag Handler threw SkipPageException or if an invoked Jsp Fragment
093: * threw a SkipPageException.
094: * @throws java.io.IOException If there was an error writing to the
095: * output stream.
096: */
097: public void doTag() throws javax.servlet.jsp.JspException,
098: java.io.IOException;
099:
100: /**
101: * Sets the parent of this tag, for collaboration purposes.
102: * <p>
103: * The container invokes this method only if this tag invocation is
104: * nested within another tag invocation.
105: *
106: * @param parent the tag that encloses this tag
107: */
108: public void setParent(JspTag parent);
109:
110: /**
111: * Returns the parent of this tag, for collaboration purposes.
112: *
113: * @return the parent of this tag
114: */
115: public JspTag getParent();
116:
117: /**
118: * Called by the container to provide this tag handler with
119: * the <code>JspContext</code> for this invocation.
120: * An implementation should save this value.
121: *
122: * @param pc the page context for this invocation
123: * @see Tag#setPageContext
124: */
125: public void setJspContext(JspContext pc);
126:
127: /**
128: * Provides the body of this tag as a JspFragment object, able to be
129: * invoked zero or more times by the tag handler.
130: * <p>
131: * This method is invoked by the JSP page implementation
132: * object prior to <code>doTag()</code>. If the action element is
133: * empty in the page, this method is not called at all.
134: *
135: * @param jspBody The fragment encapsulating the body of this tag.
136: */
137: public void setJspBody(JspFragment jspBody);
138:
139: }
|