javax.servlet.jsp.tagext.BodyContent Maven / Gradle / Ivy
/*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the "License"). You may not use this file except
* in compliance with the License.
*
* You can obtain a copy of the license at
* glassfish/bootstrap/legal/CDDLv1.0.txt or
* https://glassfish.dev.java.net/public/CDDLv1.0.html.
* See the License for the specific language governing
* permissions and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* HEADER in each file and include the License file at
* glassfish/bootstrap/legal/CDDLv1.0.txt. If applicable,
* add the following below this CDDL HEADER, with the
* fields enclosed by brackets "[]" replaced with your
* own identifying information: Portions Copyright [yyyy]
* [name of copyright owner]
*
* Copyright 2005 Sun Microsystems, Inc. All rights reserved.
*
* Portions Copyright Apache Software Foundation.
*/
package javax.servlet.jsp.tagext;
import java.io.Reader;
import java.io.Writer;
import java.io.IOException;
import javax.servlet.jsp.*;
/**
* An encapsulation of the evaluation of the body of an action so it is
* available to a tag handler. BodyContent is a subclass of JspWriter.
*
*
* Note that the content of BodyContent is the result of evaluation, so
* it will not contain actions and the like, but the result of their
* invocation.
*
*
* BodyContent has methods to convert its contents into
* a String, to read its contents, and to clear the contents.
*
*
* The buffer size of a BodyContent object is unbounded. A
* BodyContent object cannot be in autoFlush mode. It is not possible to
* invoke flush on a BodyContent object, as there is no backing stream.
*
*
* Instances of BodyContent are created by invoking the pushBody and
* popBody methods of the PageContext class. A BodyContent is enclosed
* within another JspWriter (maybe another BodyContent object) following
* the structure of their associated actions.
*
*
* A BodyContent is made available to a BodyTag through a setBodyContent()
* call. The tag handler can use the object until after the call to
* doEndTag().
*/
public abstract class BodyContent extends JspWriter {
/**
* Protected constructor.
*
* Unbounded buffer, no autoflushing.
*
* @param e the enclosing JspWriter
*/
protected BodyContent(JspWriter e) {
super(UNBOUNDED_BUFFER , false);
this.enclosingWriter = e;
}
/**
* Redefined flush() so it is not legal.
*
*
* It is not valid to flush a BodyContent because there is no backing
* stream behind it.
*
* @throws IOException always thrown
*/
public void flush() throws IOException {
throw new IOException("Illegal to flush within a custom tag");
}
/**
* Clear the body without throwing any exceptions.
*/
public void clearBody() {
try {
this.clear();
} catch (IOException ex) {
// TODO -- clean this one up.
throw new Error("internal error!;");
}
}
/**
* Return the value of this BodyContent as a Reader.
*
* @return the value of this BodyContent as a Reader
*/
public abstract Reader getReader();
/**
* Return the value of the BodyContent as a String.
*
* @return the value of the BodyContent as a String
*/
public abstract String getString();
/**
* Write the contents of this BodyContent into a Writer.
* Subclasses may optimize common invocation patterns.
*
* @param out The writer into which to place the contents of
* this body evaluation
* @throws IOException if an I/O error occurred while writing the
* contents of this BodyContent to the given Writer
*/
public abstract void writeOut(Writer out) throws IOException;
/**
* Get the enclosing JspWriter.
*
* @return the enclosing JspWriter passed at construction time
*/
public JspWriter getEnclosingWriter() {
return enclosingWriter;
}
// private fields
private JspWriter enclosingWriter;
}