Package: Tag

Tag

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.JspException;
22: import jakarta.servlet.jsp.PageContext;
23:
24: /**
25: * The interface of a classic tag handler that does not want to manipulate its body. The Tag interface defines the basic
26: * protocol between a Tag handler and JSP page implementation class. It defines the life cycle and the methods to be
27: * invoked at start and end tag.
28: *
29: * <p>
30: * <B>Properties</B>
31: * </p>
32: *
33: * <p>
34: * The Tag interface specifies the setter and getter methods for the core pageContext and parent properties.
35: * </p>
36: *
37: * <p>
38: * The JSP page implementation object invokes setPageContext and setParent, in that order, before invoking doStartTag()
39: * or doEndTag().
40: * </p>
41: *
42: * <p>
43: * <B>Methods</B>
44: * </p>
45: *
46: * <p>
47: * There are two main actions: doStartTag and doEndTag. Once all appropriate properties have been initialized, the
48: * doStartTag and doEndTag methods can be invoked on the tag handler. Between these invocations, the tag handler is
49: * assumed to hold a state that must be preserved. After the doEndTag invocation, the tag handler is available for
50: * further invocations (and it is expected to have retained its properties).
51: * </p>
52: *
53: * <p>
54: * <B>Lifecycle</B>
55: * </p>
56: *
57: * <p>
58: * Lifecycle details are described by the transition diagram below, with the following comments:
59: * </p>
60: * <ul>
61: * <li>[1] This transition is intended to be for releasing long-term data. no guarantees are assumed on whether any
62: * properties have been retained or not.
63: * <li>[2] This transition happens if and only if the tag ends normally without raising an exception
64: * <li>[3] Some setters may be called again before a tag handler is reused. For instance, <code>setParent()</code> is
65: * called if it's reused within the same page but at a different level, <code>setPageContext()</code> is called if it's
66: * used in another page, and attribute setters are called if the values differ or are expressed as request-time
67: * attribute values.
68: * <li>Check the TryCatchFinally interface for additional details related to exception handling and resource management.
69: * </ul>
70: *
71: * <IMG src="doc-files/TagProtocol.gif" alt="Lifecycle Details Transition Diagram for Tag">
72: *
73: * <p>
74: * Once all invocations on the tag handler are completed, the release method is invoked on it. Once a release method is
75: * invoked <em>all</em> properties, including parent and pageContext, are assumed to have been reset to an unspecified
76: * value. The page compiler guarantees that release() will be invoked on the Tag handler before the handler is released
77: * to the GC.
78: * </p>
79: *
80: * <p>
81: * <B>Empty and Non-Empty Action</B>
82: * </p>
83: * <p>
84: * If the TagLibraryDescriptor file indicates that the action must always have an empty action, by an
85: * <body-content> entry of "empty", then the doStartTag() method must return SKIP_BODY.
86: * </p>
87: *
88: * <p>
89: * Otherwise, the doStartTag() method may return SKIP_BODY or EVAL_BODY_INCLUDE.
90: * </p>
91: *
92: * <p>
93: * If SKIP_BODY is returned the body, if present, is not evaluated.
94: * </p>
95: *
96: * <p>
97: * If EVAL_BODY_INCLUDE is returned, the body is evaluated and "passed through" to the current out.
98: * </p>
99: */
100: public interface Tag extends JspTag {
101:
102: /**
103: * Skip body evaluation. Valid return value for doStartTag and doAfterBody.
104: */
105: public final static int SKIP_BODY = 0;
106:
107: /**
108: * Evaluate body into existing out stream. Valid return value for doStartTag.
109: */
110: public final static int EVAL_BODY_INCLUDE = 1;
111:
112: /**
113: * Skip the rest of the page. Valid return value for doEndTag.
114: */
115: public final static int SKIP_PAGE = 5;
116:
117: /**
118: * Continue evaluating the page. Valid return value for doEndTag().
119: */
120: public final static int EVAL_PAGE = 6;
121:
122: // Setters for Tag handler data
123:
124: /**
125: * Set the current page context. This method is invoked by the JSP page implementation object prior to doStartTag().
126: * <p>
127: * This value is *not* reset by doEndTag() and must be explicitly reset by a page implementation if it changes
128: * between calls to doStartTag().
129: *
130: * @param pc The page context for this tag handler.
131: */
132: void setPageContext(PageContext pc);
133:
134: /**
135: * Set the parent (closest enclosing tag handler) of this tag handler. Invoked by the JSP page implementation object
136: * prior to doStartTag().
137: * <p>
138: * This value is *not* reset by doEndTag() and must be explicitly reset by a page implementation.
139: *
140: * @param t The parent tag, or null.
141: */
142: void setParent(Tag t);
143:
144: /**
145: * Get the parent (closest enclosing tag handler) for this tag handler.
146: *
147: * <p>
148: * The getParent() method can be used to navigate the nested tag handler structure at runtime for cooperation among
149: * custom actions; for example, the findAncestorWithClass() method in TagSupport provides a convenient way of doing
150: * this.
151: *
152: * <p>
153: * The current version of the specification only provides one formal way of indicating the observable type of a tag
154: * handler: its tag handler implementation class, described in the tag-class subelement of the tag element. This is
155: * extended in an informal manner by allowing the tag library author to indicate in the description subelement an
156: * observable type. The type should be a subtype of the tag handler implementation class or void. This addititional
157: * constraint can be exploited by a specialized container that knows about that specific tag library, as in the case
158: * of the JSP standard tag library.
159: *
160: * @return the current parent, or null if none.
161: * @see TagSupport#findAncestorWithClass
162: */
163: Tag getParent();
164:
165: // Actions for basic start/end processing.
166:
167: /**
168: * Process the start tag for this instance. This method is invoked by the JSP page implementation object.
169: *
170: * <p>
171: * The doStartTag method assumes that the properties pageContext and parent have been set. It also assumes that any
172: * properties exposed as attributes have been set too. When this method is invoked, the body has not yet been
173: * evaluated.
174: *
175: * <p>
176: * This method returns Tag.EVAL_BODY_INCLUDE or BodyTag.EVAL_BODY_BUFFERED to indicate that the body of the action
177: * should be evaluated or SKIP_BODY to indicate otherwise.
178: *
179: * <p>
180: * When a Tag returns EVAL_BODY_INCLUDE the result of evaluating the body (if any) is included into the current
181: * "out" JspWriter as it happens and then doEndTag() is invoked.
182: *
183: * <p>
184: * BodyTag.EVAL_BODY_BUFFERED is only valid if the tag handler implements BodyTag.
185: *
186: * <p>
187: * The JSP container will resynchronize the values of any AT_BEGIN and NESTED variables (defined by the associated
188: * TagExtraInfo or TLD) after the invocation of doStartTag(), except for a tag handler implementing BodyTag whose
189: * doStartTag() method returns BodyTag.EVAL_BODY_BUFFERED.
190: *
191: * @return EVAL_BODY_INCLUDE if the tag wants to process body, SKIP_BODY if it does not want to process it.
192: * @throws JspException if an error occurred while processing this tag
193: * @see BodyTag
194: */
195: int doStartTag() throws JspException;
196:
197: /**
198: * Process the end tag for this instance. This method is invoked by the JSP page implementation object on all Tag
199: * handlers.
200: *
201: * <p>
202: * This method will be called after returning from doStartTag. The body of the action may or may not have been
203: * evaluated, depending on the return value of doStartTag.
204: *
205: * <p>
206: * If this method returns EVAL_PAGE, the rest of the page continues to be evaluated. If this method returns
207: * SKIP_PAGE, the rest of the page is not evaluated, the request is completed, and the doEndTag() methods of
208: * enclosing tags are not invoked. If this request was forwarded or included from another page (or Servlet), only
209: * the current page evaluation is stopped.
210: *
211: * <p>
212: * The JSP container will resynchronize the values of any AT_BEGIN and AT_END variables (defined by the associated
213: * TagExtraInfo or TLD) after the invocation of doEndTag().
214: *
215: * @return indication of whether to continue evaluating the JSP page.
216: * @throws JspException if an error occurred while processing this tag
217: */
218: int doEndTag() throws JspException;
219:
220: /**
221: * Called on a Tag handler to release state. The page compiler guarantees that JSP page implementation objects will
222: * invoke this method on all tag handlers, but there may be multiple invocations on doStartTag and doEndTag in
223: * between.
224: */
225: void release();
226: }