001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package javax.servlet.jsp.tagext;
018:
019: import java.io.Reader;
020: import java.io.Writer;
021: import java.io.IOException;
022: import javax.servlet.jsp.*;
023:
024: /**
025: * An encapsulation of the evaluation of the body of an action so it is
026: * available to a tag handler. BodyContent is a subclass of JspWriter.
027: *
028: * <p>
029: * Note that the content of BodyContent is the result of evaluation, so
030: * it will not contain actions and the like, but the result of their
031: * invocation.
032: *
033: * <p>
034: * BodyContent has methods to convert its contents into
035: * a String, to read its contents, and to clear the contents.
036: *
037: * <p>
038: * The buffer size of a BodyContent object is unbounded. A
039: * BodyContent object cannot be in autoFlush mode. It is not possible to
040: * invoke flush on a BodyContent object, as there is no backing stream.
041: *
042: * <p>
043: * Instances of BodyContent are created by invoking the pushBody and
044: * popBody methods of the PageContext class. A BodyContent is enclosed
045: * within another JspWriter (maybe another BodyContent object) following
046: * the structure of their associated actions.
047: *
048: * <p>
049: * A BodyContent is made available to a BodyTag through a setBodyContent()
050: * call. The tag handler can use the object until after the call to
051: * doEndTag().
052: */
053:
054: public abstract class BodyContent extends JspWriter {
055:
056: /**
057: * Protected constructor.
058: *
059: * Unbounded buffer, no autoflushing.
060: *
061: * @param e the enclosing JspWriter
062: */
063:
064: protected BodyContent(JspWriter e) {
065: super (UNBOUNDED_BUFFER, false);
066: this .enclosingWriter = e;
067: }
068:
069: /**
070: * Redefined flush() so it is not legal.
071: *
072: * <p>
073: * It is not valid to flush a BodyContent because there is no backing
074: * stream behind it.
075: *
076: * @throws IOException always thrown
077: */
078:
079: public void flush() throws IOException {
080: throw new IOException("Illegal to flush within a custom tag");
081: }
082:
083: /**
084: * Clear the body without throwing any exceptions.
085: */
086:
087: public void clearBody() {
088: try {
089: this .clear();
090: } catch (IOException ex) {
091: // TODO -- clean this one up.
092: throw new Error("internal error!;");
093: }
094: }
095:
096: /**
097: * Return the value of this BodyContent as a Reader.
098: *
099: * @return the value of this BodyContent as a Reader
100: */
101: public abstract Reader getReader();
102:
103: /**
104: * Return the value of the BodyContent as a String.
105: *
106: * @return the value of the BodyContent as a String
107: */
108: public abstract String getString();
109:
110: /**
111: * Write the contents of this BodyContent into a Writer.
112: * Subclasses may optimize common invocation patterns.
113: *
114: * @param out The writer into which to place the contents of
115: * this body evaluation
116: * @throws IOException if an I/O error occurred while writing the
117: * contents of this BodyContent to the given Writer
118: */
119:
120: public abstract void writeOut(Writer out) throws IOException;
121:
122: /**
123: * Get the enclosing JspWriter.
124: *
125: * @return the enclosing JspWriter passed at construction time
126: */
127:
128: public JspWriter getEnclosingWriter() {
129: return enclosingWriter;
130: }
131:
132: // private fields
133:
134: private JspWriter enclosingWriter;
135: }
|