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