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 }