View Javadoc

    1   /**
    2    *
    3    * Copyright 2003-2004 The Apache Software Foundation
    4    *
    5    *  Licensed under the Apache License, Version 2.0 (the "License");
    6    *  you may not use this file except in compliance with the License.
    7    *  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
    18  //
    19  // This source code implements specifications defined by the Java
    20  // Community Process. In order to remain compliant with the specification
    21  // DO NOT add / change / or delete method signatures!
    22  //
    23
    24  package javax.servlet.jsp.tagext;
    25
    26  import java.io.IOException;
    27  import java.io.Reader;
    28  import java.io.Writer;
    29
    30  import javax.servlet.jsp.JspWriter;
    31
    32  /**
    33   * An encapsulation of the evaluation of the body of an action so it is
    34   * available to a tag handler.  BodyContent is a subclass of JspWriter.
    35   *
    36   * <p>
    37   * Note that the _content of BodyContent is the result of evaluation, so
    38   * it will not contain actions and the like, but the result of their
    39   * invocation.
    40   *
    41   * <p>
    42   * BodyContent has methods to convert its contents into
    43   * a String, to read its contents, and to clear the contents.
    44   *
    45   * <p>
    46   * The buffer size of a BodyContent object is unbounded.  A
    47   * BodyContent object cannot be in autoFlush mode.  It is not possible to
    48   * invoke flush on a BodyContent object, as there is no backing stream.
    49   *
    50   * <p>
    51   * Instances of BodyContent are created by invoking the pushBody and
    52   * popBody methods of the PageContext class.  A BodyContent is enclosed
    53   * within another JspWriter (maybe another BodyContent object) following
    54   * the structure of their associated actions.
    55   *
    56   * <p>
    57   * A BodyContent is made available to a BodyTag through a setBodyContent()
    58   * call.  The tag handler can use the object until after the call to
    59   * doEndTag().
    60   */
    61
    62  public abstract class BodyContent extends JspWriter {
    63
    64      /**
    65       * Protected constructor.
    66       *
    67       * Unbounded buffer, no autoflushing.
    68       *
    69       * @param e the enclosing JspWriter
    70       */
    71
    72      protected BodyContent(JspWriter e) {
    73  	super(UNBOUNDED_BUFFER , false);
    74  	this.enclosingWriter = e;
    75      }
    76
    77      /**
    78       * Redefined flush() so it is not legal.
    79       *
    80       * <p>
    81       * It is not valid to flush a BodyContent because there is no backing
    82       * stream behind it.
    83       *
    84       * @throws IOException always thrown
    85       */
    86
    87      public void flush() throws IOException {
    88  	throw new IOException("Illegal to flush within a custom tag");
    89      }
    90
    91      /**
    92       * Clear the body without throwing any exceptions.
    93       */
    94
    95      public void clearBody() {
    96  	try {
    97  	    this.clear();
    98  	} catch (IOException ex) {
    99  	    // TODO -- clean this one up.
    100 	    throw new Error("internal error!;");
    101 	}
    102     }
    103
    104     /**
    105      * Return the value of this BodyContent as a Reader.
    106      *
    107      * @return the value of this BodyContent as a Reader
    108      */
    109     public abstract Reader getReader();
    110
    111
    112     /**
    113      * Return the value of the BodyContent as a String.
    114      *
    115      * @return the value of the BodyContent as a String
    116      */
    117     public abstract String getString();
    118
    119
    120     /**
    121      * Write the contents of this BodyContent into a Writer.
    122      * Subclasses may optimize common invocation patterns.
    123      *
    124      * @param out The writer into which to place the contents of
    125      *     this body evaluation
    126      * @throws IOException if an I/O error occurred while writing the
    127      *     contents of this BodyContent to the given Writer
    128      */
    129
    130     public abstract void writeOut(Writer out) throws IOException;
    131
    132
    133     /**
    134      * Get the enclosing JspWriter.
    135      *
    136      * @return the enclosing JspWriter passed at construction time
    137      */
    138
    139     public JspWriter getEnclosingWriter() {
    140 	return enclosingWriter;
    141     }
    142
    143
    144     // private fields
    145
    146     private JspWriter enclosingWriter;
    147  }