1   /*
    2   * Licensed to the Apache Software Foundation (ASF) under one or more
    3   * contributor license agreements.  See the NOTICE file distributed with
    4   * this work for additional information regarding copyright ownership.
    5   * The ASF licenses this file to You under the Apache License, Version 2.0
    6   * (the "License"); you may not use this file except in compliance with
    7   * the License.  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   package javax.servlet.jsp.tagext;
   18   
   19   import java.io.Reader;
   20   import java.io.Writer;
   21   import java.io.IOException;
   22   import javax.servlet.jsp;
   23   
   24   /**
   25    * An encapsulation of the evaluation of the body of an action so it is
   26    * available to a tag handler.  BodyContent is a subclass of JspWriter.
   27    *
   28    * <p>
   29    * Note that the content of BodyContent is the result of evaluation, so
   30    * it will not contain actions and the like, but the result of their
   31    * invocation.
   32    * 
   33    * <p>
   34    * BodyContent has methods to convert its contents into
   35    * a String, to read its contents, and to clear the contents.
   36    *
   37    * <p>
   38    * The buffer size of a BodyContent object is unbounded.  A
   39    * BodyContent object cannot be in autoFlush mode.  It is not possible to
   40    * invoke flush on a BodyContent object, as there is no backing stream.
   41    *
   42    * <p>
   43    * Instances of BodyContent are created by invoking the pushBody and
   44    * popBody methods of the PageContext class.  A BodyContent is enclosed
   45    * within another JspWriter (maybe another BodyContent object) following
   46    * the structure of their associated actions.
   47    *
   48    * <p>
   49    * A BodyContent is made available to a BodyTag through a setBodyContent()
   50    * call.  The tag handler can use the object until after the call to
   51    * doEndTag().
   52    */
   53   
   54   public abstract class BodyContent extends JspWriter {
   55       
   56       /**
   57        * Protected constructor.
   58        *
   59        * Unbounded buffer, no autoflushing.
   60        *
   61        * @param e the enclosing JspWriter
   62        */
   63   
   64       protected BodyContent(JspWriter e) {
   65   	super(UNBOUNDED_BUFFER , false);
   66   	this.enclosingWriter = e;
   67       }
   68   
   69       /**
   70        * Redefined flush() so it is not legal.
   71        *
   72        * <p>
   73        * It is not valid to flush a BodyContent because there is no backing
   74        * stream behind it.
   75        *
   76        * @throws IOException always thrown
   77        */
   78   
   79       public void flush() throws IOException {
   80   	throw new IOException("Illegal to flush within a custom tag");
   81       }
   82   
   83       /**
   84        * Clear the body without throwing any exceptions.
   85        */
   86       
   87       public void clearBody() {
   88   	try {
   89   	    this.clear();
   90   	} catch (IOException ex) {
   91   	    // TODO -- clean this one up.
   92   	    throw new Error("internal error!;");
   93   	}
   94       }
   95   
   96       /**
   97        * Return the value of this BodyContent as a Reader.
   98        *
   99        * @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    }