01 /*
02 * Copyright 2004 The Apache Software Foundation
03 *
04 * Licensed under the Apache License, Version 2.0 (the "License");
05 * you may not use this file except in compliance with the License.
06 * You may obtain a copy of the License at
07 *
08 * http://www.apache.org/licenses/LICENSE-2.0
09 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package javax.servlet.jsp.tagext;
18
19 import java.io.IOException;
20 import java.io.Writer;
21 import javax.servlet.jsp.*;
22
23 /**
24 * Encapsulates a portion of JSP code in an object that
25 * can be invoked as many times as needed. JSP Fragments are defined
26 * using JSP syntax as the body of a tag for an invocation to a SimpleTag
27 * handler, or as the body of a <jsp:attribute> standard action
28 * specifying the value of an attribute that is declared as a fragment,
29 * or to be of type JspFragment in the TLD.
30 * <p>
31 * The definition of the JSP fragment must only contain template
32 * text and JSP action elements. In other words, it must not contain
33 * scriptlets or scriptlet expressions. At translation time, the
34 * container generates an implementation of the JspFragment abstract class
35 * capable of executing the defined fragment.
36 * <p>
37 * A tag handler can invoke the fragment zero or more times, or
38 * pass it along to other tags, before returning. To communicate values
39 * to/from a JSP fragment, tag handlers store/retrieve values in
40 * the JspContext associated with the fragment.
41 * <p>
42 * Note that tag library developers and page authors should not generate
43 * JspFragment implementations manually.
44 * <p>
45 * <i>Implementation Note</i>: It is not necessary to generate a
46 * separate class for each fragment. One possible implementation is
47 * to generate a single helper class for each page that implements
48 * JspFragment. Upon construction, a discriminator can be passed to
49 * select which fragment that instance will execute.
50 *
51 * @since 2.0
52 */
53 public abstract class JspFragment {
54
55 /**
56 * Executes the fragment and directs all output to the given Writer,
57 * or the JspWriter returned by the getOut() method of the JspContext
58 * associated with the fragment if out is null.
59 *
60 * @param out The Writer to output the fragment to, or null if
61 * output should be sent to JspContext.getOut().
62 * @throws javax.servlet.jsp.JspException Thrown if an error occured
63 * while invoking this fragment.
64 * @throws javax.servlet.jsp.SkipPageException Thrown if the page
65 * that (either directly or indirectly) invoked the tag handler that
66 * invoked this fragment is to cease evaluation. The container
67 * must throw this exception if a Classic Tag Handler returned
68 * Tag.SKIP_PAGE or if a Simple Tag Handler threw SkipPageException.
69 * @throws java.io.IOException If there was an error writing to the
70 * stream.
71 */
72 public abstract void invoke(Writer out) throws JspException,
73 IOException;
74
75 /**
76 * Returns the JspContext that is bound to this JspFragment.
77 *
78 * @return The JspContext used by this fragment at invocation time.
79 */
80 public abstract JspContext getJspContext();
81
82 }
|