001: /*
002: * Copyright (c) 1998-2003 Caucho Technology -- all rights reserved
003: *
004: * This file is part of Resin(R) Open Source
005: *
006: * Each copy or derived work must preserve the copyright notice and this
007: * notice unmodified.
008: *
009: * Resin Open Source is free software; you can redistribute it and/or modify
010: * it under the terms of the GNU General Public License as published by
011: * the Free Software Foundation; either version 2 of the License, or
012: * (at your option) any later version.
013: *
014: * Resin Open Source is distributed in the hope that it will be useful,
015: * but WITHOUT ANY WARRANTY; without even the implied warranty of
016: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, or any warranty
017: * of NON-INFRINGEMENT. See the GNU General Public License for more
018: * details.
019: *
020: * You should have received a copy of the GNU General Public License
021: * along with Resin Open Source; if not, write to the
022: * Free SoftwareFoundation, Inc.
023: * 59 Temple Place, Suite 330
024: * Boston, MA 02111-1307 USA
025: *
026: * @author Scott Ferguson
027: *
028: * $Id: BodyTag.java,v 1.2 2004/09/29 00:12:48 cvs Exp $
029: */
030:
031: package javax.servlet.jsp.tagext;
032:
033: import javax.servlet.jsp.JspException;
034:
035: /**
036: * BodyTag lets tags access the generated tag contents and it allows
037: * tag looping. For example, a SQL tag may use the enclosed SQL to
038: * update a table. A BodyTag must explicitly write the contents the
039: * enclosing stream.
040: *
041: * <pre><code>
042: * if (tag.doStartTag() == EVAL_BODY_TAG) {
043: * out = pageContext.pushBody();
044: * tag.setBodyContent(out);
045: * tag.doInitBody();
046: * do {
047: * ...
048: * } while (tag.doAfterBody() == EVAL_BODY_AGAIN);
049: * out = pageContent.popBody();
050: * }
051: * if (tag.doEndTag() == SKIP_PAGE)
052: * return;
053: * </code><pre>
054: */
055: public interface BodyTag extends IterationTag {
056: /**
057: * Constant returned by doStartTag to evaluate a tag body.
058: *
059: * @deprecated
060: */
061: public final static int EVAL_BODY_TAG = 2;
062: /**
063: * Constant returned by doStartTag to evaluate a tag body.
064: */
065: public final static int EVAL_BODY_BUFFERED = 2;
066:
067: /**
068: * Sets the BodyContent stream. A tag calls setBodyContent before calling
069: * doInitBody()
070: *
071: * @param out The body content for tag and its contents.
072: */
073: public void setBodyContent(BodyContent out);
074:
075: /**
076: * Tags call doInitBody before processing the tag body. doInitBody is
077: * called after setBodyContent. It is called only once for each tag, even
078: * if the tag loops.
079: *
080: * <p>empty tags and tags returning SKIP_BODY do not call
081: * doInitBody and doAfterBody.
082: *
083: * <pre><code>
084: * if (tag.doStartTag() == EVAL_BODY_TAG) {
085: * out = pageContext.pushBody();
086: * tag.setBodyContent(out);
087: * tag.doInitBody();
088: * ...
089: * }
090: * </code></pre>
091: */
092: public void doInitBody() throws JspException;
093:
094: /**
095: * Tags call doAfterBody after processing the tag body. Tags writing
096: * to the output stream must write the body to the enclosing JspWriter.
097: * Tags can loop by returning EVAL_PAGE and stop by returning SKIP_PAGE.
098: *
099: * <p>empty tags and tags returning SKIP_BODY do not call
100: * doInitBody and doAfterBody.
101: *
102: * <p>Here's an example of a tag that copies its contents
103: * to the output (assuming setBodyContent sets bodyOut):
104: * <pre><code>
105: * public int doAfterBody() throws JspException
106: * {
107: * try {
108: * bodyOut.writeOut(bodyOut.getEnclosingWriter());
109: * } catch (IOException e) {
110: * throw JspException(String.valueOf(e));
111: * }
112: *
113: * return SKIP_PAGE;
114: * }
115: * </code></pre>
116: *
117: * @return EVAL_PAGE to repeat the tag and SKIP_PAGE to stop.
118: */
119: public int doAfterBody() throws JspException;
120: }
|