KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > servlet > jsp > tagext > BodyContent


1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package javax.servlet.jsp.tagext;
18
19 import java.io.Reader JavaDoc;
20 import java.io.Writer JavaDoc;
21 import java.io.IOException JavaDoc;
22 import javax.servlet.jsp.*;
23
24 /**
25  * An encapsulation of the evaluation of the body of an action so it is
26  * available to a tag handler. BodyContent is a subclass of JspWriter.
27  *
28  * <p>
29  * Note that the content of BodyContent is the result of evaluation, so
30  * it will not contain actions and the like, but the result of their
31  * invocation.
32  *
33  * <p>
34  * BodyContent has methods to convert its contents into
35  * a String, to read its contents, and to clear the contents.
36  *
37  * <p>
38  * The buffer size of a BodyContent object is unbounded. A
39  * BodyContent object cannot be in autoFlush mode. It is not possible to
40  * invoke flush on a BodyContent object, as there is no backing stream.
41  *
42  * <p>
43  * Instances of BodyContent are created by invoking the pushBody and
44  * popBody methods of the PageContext class. A BodyContent is enclosed
45  * within another JspWriter (maybe another BodyContent object) following
46  * the structure of their associated actions.
47  *
48  * <p>
49  * A BodyContent is made available to a BodyTag through a setBodyContent()
50  * call. The tag handler can use the object until after the call to
51  * doEndTag().
52  */
53
54 public abstract class BodyContent extends JspWriter {
55     
56     /**
57      * Protected constructor.
58      *
59      * Unbounded buffer, no autoflushing.
60      *
61      * @param e the enclosing JspWriter
62      */
63
64     protected BodyContent(JspWriter e) {
65     super(UNBOUNDED_BUFFER , false);
66     this.enclosingWriter = e;
67     }
68
69     /**
70      * Redefined flush() so it is not legal.
71      *
72      * <p>
73      * It is not valid to flush a BodyContent because there is no backing
74      * stream behind it.
75      *
76      * @throws IOException always thrown
77      */
78
79     public void flush() throws IOException JavaDoc {
80     throw new IOException JavaDoc("Illegal to flush within a custom tag");
81     }
82
83     /**
84      * Clear the body without throwing any exceptions.
85      */
86     
87     public void clearBody() {
88     try {
89         this.clear();
90     } catch (IOException JavaDoc ex) {
91         // TODO -- clean this one up.
92 throw new Error JavaDoc("internal error!;");
93     }
94     }
95
96     /**
97      * Return the value of this BodyContent as a Reader.
98      *
99      * @return the value of this BodyContent as a Reader
100      */
101     public abstract Reader JavaDoc getReader();
102
103
104     /**
105      * Return the value of the BodyContent as a String.
106      *
107      * @return the value of the BodyContent as a String
108      */
109     public abstract String JavaDoc getString();
110     
111
112     /**
113      * Write the contents of this BodyContent into a Writer.
114      * Subclasses may optimize common invocation patterns.
115      *
116      * @param out The writer into which to place the contents of
117      * this body evaluation
118      * @throws IOException if an I/O error occurred while writing the
119      * contents of this BodyContent to the given Writer
120      */
121
122     public abstract void writeOut(Writer JavaDoc out) throws IOException JavaDoc;
123
124
125     /**
126      * Get the enclosing JspWriter.
127      *
128      * @return the enclosing JspWriter passed at construction time
129      */
130
131     public JspWriter getEnclosingWriter() {
132     return enclosingWriter;
133     }
134
135
136     // private fields
137
138     private JspWriter enclosingWriter;
139  }
140
Popular Tags