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        /**
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 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 out) throws IOException;
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     }