Package: SimpleTag

SimpleTag

Coverage

1: /*
2: * Copyright (c) 1997, 2020 Oracle and/or its affiliates and others.
3: * All rights reserved.
4: * Copyright 2004 The Apache Software Foundation
5: *
6: * Licensed under the Apache License, Version 2.0 (the "License");
7: * you may not use this file except in compliance with the License.
8: * You may obtain a copy of the License at
9: *
10: * http://www.apache.org/licenses/LICENSE-2.0
11: *
12: * Unless required by applicable law or agreed to in writing, software
13: * distributed under the License is distributed on an "AS IS" BASIS,
14: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15: * See the License for the specific language governing permissions and
16: * limitations under the License.
17: */
18:
19: package jakarta.servlet.jsp.tagext;
20:
21: import jakarta.servlet.jsp.JspContext;
22:
23: /**
24: * Interface for defining Simple Tag Handlers.
25: *
26: * <p>
27: * Simple Tag Handlers differ from Classic Tag Handlers in that instead of supporting <code>doStartTag()</code> and
28: * <code>doEndTag()</code>, the <code>SimpleTag</code> interface provides a simple <code>doTag()</code> method, which is
29: * called once and only once for any given tag invocation. All tag logic, iteration, body evaluations, etc. are to be
30: * performed in this single method. Thus, simple tag handlers have the equivalent power of <code>BodyTag</code>, but
31: * with a much simpler lifecycle and interface.
32: * </p>
33: *
34: * <p>
35: * To support body content, the <code>setJspBody()</code> method is provided. The container invokes the
36: * <code>setJspBody()</code> method with a <code>JspFragment</code> object encapsulating the body of the tag. The tag
37: * handler implementation can call <code>invoke()</code> on that fragment to evaluate the body as many times as it
38: * needs.
39: * </p>
40: *
41: * <p>
42: * A SimpleTag handler must have a public no-args constructor. Most SimpleTag handlers should extend SimpleTagSupport.
43: * </p>
44: *
45: * <p>
46: * <b>Lifecycle</b>
47: * </p>
48: *
49: * <p>
50: * The following is a non-normative, brief overview of the SimpleTag lifecycle. Refer to the JSP Specification for
51: * details.
52: * </p>
53: *
54: * <ol>
55: * <li>A new tag handler instance is created each time by the container by calling the provided zero-args constructor.
56: * Unlike classic tag handlers, simple tag handlers are never cached and reused by the JSP container.</li>
57: * <li>The <code>setJspContext()</code> and <code>setParent()</code> methods are called by the container. The
58: * <code>setParent()</code> method is only called if the element is nested within another tag invocation.</li>
59: * <li>The setters for each attribute defined for this tag are called by the container.</li>
60: * <li>If a body exists, the <code>setJspBody()</code> method is called by the container to set the body of this tag, as
61: * a <code>JspFragment</code>. If the action element is empty in the page, this method is not called at all.</li>
62: * <li>The <code>doTag()</code> method is called by the container. All tag logic, iteration, body evaluations, etc.
63: * occur in this method.</li>
64: * <li>The <code>doTag()</code> method returns and all variables are synchronized.</li>
65: * </ol>
66: *
67: * @see SimpleTagSupport
68: * @since JSP 2.0
69: */
70: public interface SimpleTag extends JspTag {
71:
72: /**
73: * Called by the container to invoke this tag. The implementation of this method is provided by the tag library
74: * developer, and handles all tag processing, body iteration, etc.
75: *
76: * <p>
77: * The JSP container will resynchronize any AT_BEGIN and AT_END variables (defined by the associated tag file,
78: * TagExtraInfo, or TLD) after the invocation of doTag().
79: *
80: * @throws jakarta.servlet.jsp.JspException If an error occurred while processing this tag.
81: * @throws jakarta.servlet.jsp.SkipPageException If the page that (either directly or indirectly) invoked this tag is
82: * to cease evaluation. A Simple Tag Handler generated from a tag file must throw this exception if an
83: * invoked Classic Tag Handler returned SKIP_PAGE or if an invoked Simple Tag Handler threw
84: * SkipPageException or if an invoked Jsp Fragment threw a SkipPageException.
85: * @throws java.io.IOException If there was an error writing to the output stream.
86: */
87: public void doTag() throws jakarta.servlet.jsp.JspException, java.io.IOException;
88:
89: /**
90: * Sets the parent of this tag, for collaboration purposes.
91: * <p>
92: * The container invokes this method only if this tag invocation is nested within another tag invocation.
93: *
94: * @param parent the tag that encloses this tag
95: */
96: public void setParent(JspTag parent);
97:
98: /**
99: * Returns the parent of this tag, for collaboration purposes.
100: *
101: * @return the parent of this tag
102: */
103: public JspTag getParent();
104:
105: /**
106: * Called by the container to provide this tag handler with the <code>JspContext</code> for this invocation. An
107: * implementation should save this value.
108: *
109: * @param pc the page context for this invocation
110: * @see Tag#setPageContext
111: */
112: public void setJspContext(JspContext pc);
113:
114: /**
115: * Provides the body of this tag as a JspFragment object, able to be invoked zero or more times by the tag handler.
116: * <p>
117: * This method is invoked by the JSP page implementation object prior to <code>doTag()</code>. If the action element
118: * is empty in the page, this method is not called at all.
119: *
120: * @param jspBody The fragment encapsulating the body of this tag.
121: */
122: public void setJspBody(JspFragment jspBody);
123:
124: }