<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>BodyContent Class</title>
</head>

<body>
<div id="Description">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME"> BodyContent Class</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Class name:</td>
</tr>
<tr>
<td colspan="2" class="description"><p>
<span class="LITERAL">javax.servlet.jsp.tagext.BodyContent</span>
</p></td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Extends:</td>
</tr>
<tr>
<td colspan="2" class="description"><p>
<span class="LITERAL">javax.servlet.jsp.JspWriter</span>
</p></td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Implements:</td>
</tr>
<tr>
<td colspan="2" class="description"><p>
None
</p></td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Implemented by:</td>
</tr>
<tr>
<td colspan="2" class="description"><p>
Internal container-dependent class
</p></td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Description</td>
</tr>
<tr>
<td colspan="2" class="description"><p>
The container creates an instance of the <span class="LITERAL">BodyContent</span> class to hold the result of evaluating the element's body content if the corresponding tag handler implements the <span class="LITERAL">BodyTag</span> interface. The container makes the <span class="LITERAL">BodyContent</span> instance available to the tag handler by calling the <span class="LITERAL">setBodyContent()</span> method, so the tag handler can process the body content.
</p>
<p>
Let's look at a tag handler class that extends the <span class="LITERAL">BodyTagSupport</span> class. The <span class="LITERAL">EncodeHTMLTag</span> class is the tag handler class for a custom action called <span class="LITERAL">&lt;ora:encodeHTML&gt;</span>. This action reads its body; replaces all characters with a special meaning in HTML, such as single quotes, double quotes, less-than symbols, greater-than symbols, and ampersands, with their corresponding HTML character entities (i.e., <span class="LITERAL">&amp;#39;</span>, <span class="LITERAL">&amp;#34;</span>, <span class="LITERAL">&amp;lt;</span>, <span class="LITERAL">&amp;gt;</span>, and <span class="LITERAL">&amp;amp;</span>); and inserts the result in the response body. The following example shows how the action can be used in a JSP page:
</p>
<span class="PROGRAMLISTING"><pre>&lt;%@ page language="java" %&gt;
&lt;%@ taglib uri="/orataglib" prefix="ora" %&gt;
&lt;html&gt;
  &lt;head&gt;
    &lt;title&gt;Encoded HTML Example&lt;/title&gt;
  &lt;/head&gt;
  &lt;body&gt;
    &lt;h1&gt;Encoded HTML Example&lt;/h1&gt;
    The following text is encoded by the 
    &amp;lt;ora:encodeHTML&amp;gt; custom action:
    &lt;pre&gt;
      &lt;ora:encodeHTML&gt;
        HTML 3.2 Documents start with a &lt;!DOCTYPE&gt; 
        declaration followed by an HTML element containing 
        a HEAD and then a BODY element: 

        &lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"&gt;
        &lt;HTML&gt;
        &lt;HEAD&gt;
        &lt;TITLE&gt;A study of population dynamics&lt;/TITLE&gt;
        ... other head elements
        &lt;/HEAD&gt;
        &lt;BODY&gt;
        ... document body
        &lt;/BODY&gt;
        &lt;/HTML&gt;      
      &lt;/ora:encodeHTML&gt;
    &lt;/pre&gt;
  &lt;/body&gt;
&lt;/html&gt;</pre></span>
<p>
Note that the body of the <span class="LITERAL">&lt;ora:encodeHTML&gt;</span> action in the JSP page example contains HTML elements. If the special characters aren't converted to HTML character entities, the browser interprets the HTML and shows the result of that interpretation instead of the elements themselves. Thanks to the conversion performed by the custom action, however, the page is processed correctly.
</p>
<!--
<footitle>HTML processed by the &lt;ora:encodeHTML&gt; action </footitle>
<graphic fileref="figs/JspPR_07.gif"/>-->
<p>
Besides static text, the action body can contain any JSP element. A more realistic example of the use of this action is to insert text from a database into a JSP page, without having to worry about how special characters in the text are interpreted by the browser. The tag handler class is very trivial, as shown here:
</p>
<span class="PROGRAMLISTING"><pre>package com.ora.jsp.tags.generic;

import java.io.*;
import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;
import com.ora.jsp.util.*;

public class EncodeHTMLTag extends BodyTagSupport {
    
    public int doAfterBody() throws JspException {
        BodyContent bc = getBodyContent();
        JspWriter out = getPreviousOut();
        try {
            out.write(toHTMLString(bc.getString()));
        }
        catch (IOException e) {} // Ignore
        return SKIP_BODY;
    }

    private String toHTMLString(String in) {
        StringBuffer out = new StringBuffer();
        for (int i = 0; in != null &amp; i &lt; in.length(); 
          i++) {
            char c = in.charAt(i);
            if (c == '\'') {
                out.append("&amp;#39;");
            }
            else if (c == '\"') {
                out.append("&amp;#34;");
            }
            else if (c == '&lt;') {
                out.append("&amp;lt;");
            }
            else if (c == '&gt;') {
                out.append("&amp;gt;");
            }
            else if (c == '&amp;') {
                out.append("&amp;amp;");
            }
            else {
                out.append(c);
            }
        }
        return out.toString();
    }
}</pre></span>
<p>
The action doesn't have any attributes, so the tag handler doesn't need any instance variables and property access methods. The tag handler can reuse all the <span class="LITERAL">BodyTag</span> methods implemented by the <span class="LITERAL">BodyTagSupport</span> class except the <span class="LITERAL">doAfterBody()</span> method.
</p>
<p>
Two utility methods provided by the <span class="LITERAL">BodyTagSupport</span> class are used in the <span class="LITERAL">doAfterBody()</span> method. The <span class="LITERAL">getBodyContent()</span> method returns a reference to the <span class="LITERAL">BodyContent</span> object that contains the result of processing the action's body. The <span class="LITERAL">getPreviousOut()</span> method returns the <span class="LITERAL">BodyContent</span> of the enclosing action, if any, or the main <span class="LITERAL">JspWriter</span> for the page if the action is at the top level.
</p>
<p>
You may wonder why the method is called <span class="LITERAL">getPreviousOut()</span> and not <span class="LITERAL">getOut()</span>. The name is intended to emphasize the fact that you want to use the object assigned as the output to the <em>enclosing</em> element in a hierarchy of nested action elements. Say you have the following action elements in a page:
</p>
<span class="PROGRAMLISTING"><pre>  &lt;xmp:foo&gt;
    &lt;xmp:bar&gt;
      Some template text
    &lt;/xmp:bar&gt;
&lt;/xmp:foo&gt;</pre></span>
<p>
The web container first creates a <span class="LITERAL">JspWriter</span> and assigns it to the <span class="LITERAL">out</span> variable for the page. When it encounters the <span class="LITERAL">&lt;xmp:foo&gt;</span> action, it creates a <span class="LITERAL">BodyContent</span> object and temporarily assigns it to the <span class="LITERAL">out</span> variable. It then creates another <span class="LITERAL">BodyContent</span> for the <span class="LITERAL">&lt;xmp:bar&gt;</span> action and, again, assigns it to <span class="LITERAL">out</span>. The web container keeps track of this hierarchy of output objects. Template text and output produced by the standard JSP elements end up in the current output object. Each element can access its own <span class="LITERAL">BodyContent</span> object by calling the <span class="LITERAL">getBodyContent()</span> method, then read the content. For the <span class="LITERAL">&lt;xmp:bar&gt;</span> element, the content is the template text. After processing the content, it can write it to the <span class="LITERAL">&lt;xmp:foo&gt;</span> body by getting the <span class="LITERAL">BodyContent</span> for this element through the <span class="LITERAL">getPreviousOut()</span> method. Finally, the <span class="LITERAL">&lt;xmp:foo&gt;</span> element can process the content provided by the <span class="LITERAL">&lt;xmp:bar&gt;</span> element and add it to the top-level output object: the <span class="LITERAL">JspWriter</span> object it gets by calling the <span class="LITERAL">getPreviousOut()</span> method.
</p>
<p>
The tag handler in this example converts all special characters it finds in its <span class="LITERAL">BodyContent</span> object with the <span class="LITERAL">toHTMLString()</span> method. Using the <span class="LITERAL">getString()</span> method, it gets the content of the <span class="LITERAL">BodyContent</span> object and uses it as the argument to the <span class="LITERAL">toHTMLString()</span> method. The result is written to the <span class="LITERAL">JspWriter</span> obtained by calling <span class="LITERAL">getPreviousOut()</span>.
</p>
<p>
The <span class="LITERAL">doAfterBody()</span> method in this example returns <span class="LITERAL">SKIP_BODY</span>, telling the container to continue by calling <span class="LITERAL">doEndTag()</span>. For a tag handler that implements an iterating custom action, <span class="LITERAL">doAfterBody()</span> can instead return <span class="LITERAL">EVAL_BODY_TAG</span>. The container then evaluates the element's body again, writing the result to the <span class="LITERAL">BodyContent</span> for the element, and calls <span class="LITERAL">doAfterBody()</span>. The process is repeated until <span class="LITERAL">doAfterBody()</span> returns <span class="LITERAL">SKIP_BODY</span>.
</p></td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
<div id="clearBody">
<table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
<tr>
<td valign="top" class="NAME">clearBody()</td>
<td valign="top" class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"> </td>
</tr>
<tr>
<td valign="top" colspan="2" class="usage"><span class="LITERAL">public void clearBody()</span></td>
</tr>
<tr>
<td valign="top" colspan="2" class="description"><p>
Removes all buffered content for this instance.
</p></td>
</tr>
</table>
</div>
<div id="flush">
<table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
<tr>
<td valign="top" class="NAME">flush()</td>
<td valign="top" class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"> </td>
</tr>
<tr>
<td valign="top" colspan="2" class="usage"><span class="LITERAL">public void flush() throws java.io.IOException</span></td>
</tr>
<tr>
<td valign="top" colspan="2" class="description"><p>
Overwrites the behavior inherited from <span class="LITERAL">JspWriter</span> to always throw an <span class="LITERAL">IOException</span>, since it's invalid to flush a <span class="LITERAL">BodyContent</span> instance.
</p></td>
</tr>
</table>
</div>
<div id="getEnclosingWriter">
<table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
<tr>
<td valign="top" class="NAME">getEnclosingWriter()</td>
<td valign="top" class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"> </td>
</tr>
<tr>
<td valign="top" colspan="2" class="usage"><span class="LITERAL">public JspWriter getEnclosingWriter()</span></td>
</tr>
<tr>
<td valign="top" colspan="2" class="description"><p>
Returns the enclosing <span class="LITERAL">JspWriter</span>; in other words, either the top-level <span class="LITERAL">JspWriter</span> or the <span class="LITERAL">JspWriter</span> (<span class="LITERAL">BodyContent</span> subclass) of the parent tag handler.
</p></td>
</tr>
</table>
</div>
<div id="getReader">
<table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
<tr>
<td valign="top" class="NAME">getReader()</td>
<td valign="top" class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"> </td>
</tr>
<tr>
<td valign="top" colspan="2" class="usage"><span class="LITERAL">public abstract java.io.Reader getReader()</span></td>
</tr>
<tr>
<td valign="top" colspan="2" class="description"><p>
Returns the value of this <span class="LITERAL">BodyContent</span> object as a <span class="LITERAL">Reader</span> with the content produced by evaluating the element's body.
</p></td>
</tr>
</table>
</div>
<div id="getString">
<table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
<tr>
<td valign="top" class="NAME">getString()</td>
<td valign="top" class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"> </td>
</tr>
<tr>
<td valign="top" colspan="2" class="usage"><span class="LITERAL">public abstract String getString()</span></td>
</tr>
<tr>
<td valign="top" colspan="2" class="description"><p>
Returns the value of this <span class="LITERAL">BodyContent</span> object as a <span class="LITERAL">String</span> with the content produced by evaluating the element's body.
</p></td>
</tr>
</table>
</div>
<div id="writeOut">
<table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
<tr>
<td valign="top" class="NAME">writeOut()</td>
<td valign="top" class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"> </td>
</tr>
<tr>
<td valign="top" colspan="2" class="usage"><span class="LITERAL">public abstract void writeOut(java.io.Writer out)<br>
&nbsp;&nbsp;throws java.io.IOException</span></td>
</tr>
<tr>
<td valign="top" colspan="2" class="description"><p>
Writes the content of this <span class="LITERAL">BodyContent</span> object into a <span class="LITERAL">Writer</span>.
</p></td>
</tr>
</table>
</div>
<div id="BodyContent">
<table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
<tr>
<td valign="top" class="NAME">BodyContent()</td>
<td valign="top" class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"> </td>
</tr>
<tr>
<td valign="top" colspan="2" class="usage"><span class="LITERAL">protected BodyContent(JspWriter e)</span></td>
</tr>
<tr>
<td valign="top" colspan="2" class="description"><p>
Creates a new instance with the specified <span class="LITERAL">JspWriter</span> as the enclosing writer.
</p></td>
</tr>
</table>
</div>
</body>
</html>
