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