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  }