001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 */ 019 020 // 021 // This source code implements specifications defined by the Java 022 // Community Process. In order to remain compliant with the specification 023 // DO NOT add / change / or delete method signatures! 024 // 025 026 package javax.servlet.jsp.tagext; 027 028 import java.io.Reader; 029 import java.io.Writer; 030 import java.io.IOException; 031 import javax.servlet.jsp.*; 032 033 /** 034 * An encapsulation of the evaluation of the body of an action so it is 035 * available to a tag handler. BodyContent is a subclass of JspWriter. 036 * 037 * <p> 038 * Note that the content of BodyContent is the result of evaluation, so 039 * it will not contain actions and the like, but the result of their 040 * invocation. 041 * 042 * <p> 043 * BodyContent has methods to convert its contents into 044 * a String, to read its contents, and to clear the contents. 045 * 046 * <p> 047 * The buffer size of a BodyContent object is unbounded. A 048 * BodyContent object cannot be in autoFlush mode. It is not possible to 049 * invoke flush on a BodyContent object, as there is no backing stream. 050 * 051 * <p> 052 * Instances of BodyContent are created by invoking the pushBody and 053 * popBody methods of the PageContext class. A BodyContent is enclosed 054 * within another JspWriter (maybe another BodyContent object) following 055 * the structure of their associated actions. 056 * 057 * <p> 058 * A BodyContent is made available to a BodyTag through a setBodyContent() 059 * call. The tag handler can use the object until after the call to 060 * doEndTag(). 061 */ 062 063 public abstract class BodyContent extends JspWriter { 064 065 /** 066 * Protected constructor. 067 * 068 * Unbounded buffer, no autoflushing. 069 * 070 * @param e the enclosing JspWriter 071 */ 072 073 protected BodyContent(JspWriter e) { 074 super(UNBOUNDED_BUFFER , false); 075 this.enclosingWriter = e; 076 } 077 078 /** 079 * Redefined flush() so it is not legal. 080 * 081 * <p> 082 * It is not valid to flush a BodyContent because there is no backing 083 * stream behind it. 084 * 085 * @throws IOException always thrown 086 */ 087 088 public void flush() throws IOException { 089 throw new IOException("Illegal to flush within a custom tag"); 090 } 091 092 /** 093 * Clear the body without throwing any exceptions. 094 */ 095 096 public void clearBody() { 097 try { 098 this.clear(); 099 } catch (IOException ex) { 100 // TODO -- clean this one up. 101 throw new Error("internal error!;"); 102 } 103 } 104 105 /** 106 * Return the value of this BodyContent as a Reader. 107 * 108 * @return the value of this BodyContent as a Reader 109 */ 110 public abstract Reader getReader(); 111 112 113 /** 114 * Return the value of the BodyContent as a String. 115 * 116 * @return the value of the BodyContent as a String 117 */ 118 public abstract String getString(); 119 120 121 /** 122 * Write the contents of this BodyContent into a Writer. 123 * Subclasses may optimize common invocation patterns. 124 * 125 * @param out The writer into which to place the contents of 126 * this body evaluation 127 * @throws IOException if an I/O error occurred while writing the 128 * contents of this BodyContent to the given Writer 129 */ 130 131 public abstract void writeOut(Writer out) throws IOException; 132 133 134 /** 135 * Get the enclosing JspWriter. 136 * 137 * @return the enclosing JspWriter passed at construction time 138 */ 139 140 public JspWriter getEnclosingWriter() { 141 return enclosingWriter; 142 } 143 144 145 // private fields 146 147 private JspWriter enclosingWriter; 148 }