001: /*
002: * Copyright (c) 2003 The Visigoth Software Society. All rights
003: * reserved.
004: *
005: * Redistribution and use in source and binary forms, with or without
006: * modification, are permitted provided that the following conditions
007: * are met:
008: *
009: * 1. Redistributions of source code must retain the above copyright
010: * notice, this list of conditions and the following disclaimer.
011: *
012: * 2. Redistributions in binary form must reproduce the above copyright
013: * notice, this list of conditions and the following disclaimer in
014: * the documentation and/or other materials provided with the
015: * distribution.
016: *
017: * 3. The end-user documentation included with the redistribution, if
018: * any, must include the following acknowledgement:
019: * "This product includes software developed by the
020: * Visigoth Software Society (http://www.visigoths.org/)."
021: * Alternately, this acknowledgement may appear in the software itself,
022: * if and wherever such third-party acknowledgements normally appear.
023: *
024: * 4. Neither the name "FreeMarker", "Visigoth", nor any of the names of the
025: * project contributors may be used to endorse or promote products derived
026: * from this software without prior written permission. For written
027: * permission, please contact visigoths@visigoths.org.
028: *
029: * 5. Products derived from this software may not be called "FreeMarker" or "Visigoth"
030: * nor may "FreeMarker" or "Visigoth" appear in their names
031: * without prior written permission of the Visigoth Software Society.
032: *
033: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
034: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
035: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
036: * DISCLAIMED. IN NO EVENT SHALL THE VISIGOTH SOFTWARE SOCIETY OR
037: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
038: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
039: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
040: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
041: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
042: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
043: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
044: * SUCH DAMAGE.
045: * ====================================================================
046: *
047: * This software consists of voluntary contributions made by many
048: * individuals on behalf of the Visigoth Software Society. For more
049: * information on the Visigoth Software Society, please see
050: * http://www.visigoths.org/
051: */
052:
053: package freemarker.template;
054:
055: import java.io.IOException;
056:
057: /**
058: * An interface that can be implemented by writers returned from
059: * {@link TemplateTransformModel#getWriter(java.io.Writer, java.util.Map)}. The
060: * methods on this
061: * interfaces are callbacks that will be called by the template engine and that
062: * give the writer a chance to better control the evaluation of the transform
063: * body. The writer can instruct the engine to skip or to repeat body
064: * evaluation, and gets notified about exceptions that are thrown during the
065: * body evaluation.
066: *
067: * @author Attila Szegedi
068: * @version $Id: TransformControl.java,v 1.11 2005/06/16 18:13:58 ddekany Exp $
069: */
070: public interface TransformControl {
071: /**
072: * Constant returned from {@link #afterBody()} that tells the
073: * template engine to repeat transform body evaluation and feed
074: * it again to the transform.
075: */
076: public static final int REPEAT_EVALUATION = 0;
077:
078: /**
079: * Constant returned from {@link #afterBody()} that tells the
080: * template engine to end the transform and close the writer.
081: */
082: public static final int END_EVALUATION = 1;
083:
084: /**
085: * Constant returned from {@link #onStart()} that tells the
086: * template engine to skip evaluation of the body.
087: */
088: public static final int SKIP_BODY = 0;
089:
090: /**
091: * Constant returned from {@link #onStart()} that tells the
092: * template engine to evaluate the body.
093: */
094: public static final int EVALUATE_BODY = 1;
095:
096: /**
097: * Called before the body is evaluated for the first time.
098: * @return
099: * <ul>
100: * <li><tt>SKIP_BODY</tt> if the transform wants to ignore the body. In this
101: * case, only {@link java.io.Writer#close()} is called next and processing ends.</li>
102: * <li><tt>EVALUATE_BODY</tt> to normally evaluate the body of the transform
103: * and feed it to the writer</li>
104: * </ul>
105: */
106: public int onStart() throws TemplateModelException, IOException;
107:
108: /**
109: * Called after the body has been evaluated.
110: * @return
111: * <ul>
112: * <li><tt>END_EVALUATION</tt> if the transformation should be ended.</li>
113: * <li><tt>REPEAT_EVALUATION</tt> to have the engine re-evaluate the
114: * transform body and feed it again to the writer.</li>
115: * </ul>
116: */
117: public int afterBody() throws TemplateModelException, IOException;
118:
119: /**
120: * Called if any exception occurs during the transform between the
121: * {@link TemplateTransformModel#getWriter(java.io.Writer, java.util.Map)} call
122: * and the {@link java.io.Writer#close()} call.
123: * @param t the throwable that represents the exception. It can be any
124: * non-checked throwable, as well as {@link TemplateException} and
125: * {@link java.io.IOException}.
126: *
127: * @throws Throwable is recommended that the methods rethrow the received
128: * throwable. If the method wants to throw another throwable, it should
129: * either throw a non-checked throwable, or an instance of
130: * {@link TemplateException} and {@link java.io.IOException}. Throwing any
131: * other checked exception will cause the engine to rethrow it as
132: * a {@link java.lang.reflect.UndeclaredThrowableException}.
133: */
134: public void onError(Throwable t) throws Throwable;
135: }
|