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