01: /*
02: * Licensed to the Apache Software Foundation (ASF) under one or more
03: * contributor license agreements. See the NOTICE file distributed with
04: * this work for additional information regarding copyright ownership.
05: * The ASF licenses this file to You under the Apache License, Version 2.0
06: * (the "License"); you may not use this file except in compliance with
07: * the License. You may obtain a copy of the License at
08: *
09: * 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: package org.apache.cocoon.taglib;
18:
19: import org.xml.sax.SAXException;
20:
21: /**
22: * The IterationTag interface extends Tag by defining one additional
23: * method that controls the reevaluation of its body.
24: *
25: * <p> A tag handler that implements IterationTag is treated as one that
26: * implements Tag regarding the doStartTag() and doEndTag() methods.
27: * IterationTag provides a new method: <code>doAfterBody()</code>.
28: *
29: * <p> The doAfterBody() method is invoked after every body evaluation
30: * to control whether the body will be reevaluated or not. If doAfterBody()
31: * returns IterationTag.EVAL_BODY_AGAIN, then the body will be reevaluated.
32: * If doAfterBody() returns Tag.SKIP_BODY, then the body will be skipped
33: * and doEndTag() will be evaluated instead.
34: *
35: * @author <a href="mailto:volker.schmitt@basf-it-services.com">Volker Schmitt</a>
36: * @version CVS $Id: IterationTag.java 433543 2006-08-22 06:22:54Z crossley $
37: */
38: public interface IterationTag extends Tag {
39:
40: /**
41: * Request the reevaluation of some body.
42: * Returned from doAfterBody.
43: */
44: public final static int EVAL_BODY_AGAIN = 2;
45:
46: /**
47: * Process body (re)evaluation. This method is invoked by the
48: * Taglib implementation object after every evaluation of
49: * the body into the BodyEvaluation object. The method is
50: * not invoked if there is no body evaluation.
51: *
52: * <p>
53: * If doAfterBody returns EVAL_BODY_AGAIN, a new evaluation of the
54: * body will happen (followed by another invocation of doAfterBody).
55: * If doAfterBody returns SKIP_BODY no more body evaluations will
56: * occur and then doEndTag will be invoked.
57: *
58: * <p>
59: * The method re-invocations may be lead to different actions because
60: * there might have been some changes to shared state, or because
61: * of external computation.
62: *
63: * @return whether additional evaluations of the body are desired
64: * @throws SAXException
65: */
66: int doAfterBody() throws SAXException;
67: }
|