1 /**
2 *
3 * Copyright 2003-2004 The Apache Software Foundation
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * 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
18 //
19 // This source code implements specifications defined by the Java
20 // Community Process. In order to remain compliant with the specification
21 // DO NOT add / change / or delete method signatures!
22 //
23
24 package javax.servlet.jsp.tagext;
25
26 import java.io.IOException;
27 import java.io.Reader;
28 import java.io.Writer;
29
30 import javax.servlet.jsp.JspWriter;
31
32 /**
33 * An encapsulation of the evaluation of the body of an action so it is
34 * available to a tag handler. BodyContent is a subclass of JspWriter.
35 *
36 * <p>
37 * Note that the _content of BodyContent is the result of evaluation, so
38 * it will not contain actions and the like, but the result of their
39 * invocation.
40 *
41 * <p>
42 * BodyContent has methods to convert its contents into
43 * a String, to read its contents, and to clear the contents.
44 *
45 * <p>
46 * The buffer size of a BodyContent object is unbounded. A
47 * BodyContent object cannot be in autoFlush mode. It is not possible to
48 * invoke flush on a BodyContent object, as there is no backing stream.
49 *
50 * <p>
51 * Instances of BodyContent are created by invoking the pushBody and
52 * popBody methods of the PageContext class. A BodyContent is enclosed
53 * within another JspWriter (maybe another BodyContent object) following
54 * the structure of their associated actions.
55 *
56 * <p>
57 * A BodyContent is made available to a BodyTag through a setBodyContent()
58 * call. The tag handler can use the object until after the call to
59 * doEndTag().
60 */
61
62 public abstract class BodyContent extends JspWriter {
63
64 /**
65 * Protected constructor.
66 *
67 * Unbounded buffer, no autoflushing.
68 *
69 * @param e the enclosing JspWriter
70 */
71
72 protected BodyContent(JspWriter e) {
73 super(UNBOUNDED_BUFFER , false);
74 this.enclosingWriter = e;
75 }
76
77 /**
78 * Redefined flush() so it is not legal.
79 *
80 * <p>
81 * It is not valid to flush a BodyContent because there is no backing
82 * stream behind it.
83 *
84 * @throws IOException always thrown
85 */
86
87 public void flush() throws IOException {
88 throw new IOException("Illegal to flush within a custom tag");
89 }
90
91 /**
92 * Clear the body without throwing any exceptions.
93 */
94
95 public void clearBody() {
96 try {
97 this.clear();
98 } catch (IOException ex) {
99 // TODO -- clean this one up.
100 throw new Error("internal error!;");
101 }
102 }
103
104 /**
105 * Return the value of this BodyContent as a Reader.
106 *
107 * @return the value of this BodyContent as a Reader
108 */
109 public abstract Reader getReader();
110
111
112 /**
113 * Return the value of the BodyContent as a String.
114 *
115 * @return the value of the BodyContent as a String
116 */
117 public abstract String getString();
118
119
120 /**
121 * Write the contents of this BodyContent into a Writer.
122 * Subclasses may optimize common invocation patterns.
123 *
124 * @param out The writer into which to place the contents of
125 * this body evaluation
126 * @throws IOException if an I/O error occurred while writing the
127 * contents of this BodyContent to the given Writer
128 */
129
130 public abstract void writeOut(Writer out) throws IOException;
131
132
133 /**
134 * Get the enclosing JspWriter.
135 *
136 * @return the enclosing JspWriter passed at construction time
137 */
138
139 public JspWriter getEnclosingWriter() {
140 return enclosingWriter;
141 }
142
143
144 // private fields
145
146 private JspWriter enclosingWriter;
147 }