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 }