KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > freemarker > template > TransformControl


1 /*
2  * Copyright (c) 2003 The Visigoth Software Society. All rights
3  * reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * 1. Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  *
12  * 2. Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in
14  * the documentation and/or other materials provided with the
15  * distribution.
16  *
17  * 3. The end-user documentation included with the redistribution, if
18  * any, must include the following acknowledgement:
19  * "This product includes software developed by the
20  * Visigoth Software Society (http://www.visigoths.org/)."
21  * Alternately, this acknowledgement may appear in the software itself,
22  * if and wherever such third-party acknowledgements normally appear.
23  *
24  * 4. Neither the name "FreeMarker", "Visigoth", nor any of the names of the
25  * project contributors may be used to endorse or promote products derived
26  * from this software without prior written permission. For written
27  * permission, please contact visigoths@visigoths.org.
28  *
29  * 5. Products derived from this software may not be called "FreeMarker" or "Visigoth"
30  * nor may "FreeMarker" or "Visigoth" appear in their names
31  * without prior written permission of the Visigoth Software Society.
32  *
33  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
34  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
35  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
36  * DISCLAIMED. IN NO EVENT SHALL THE VISIGOTH SOFTWARE SOCIETY OR
37  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
38  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
39  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
40  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
41  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
42  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
43  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
44  * SUCH DAMAGE.
45  * ====================================================================
46  *
47  * This software consists of voluntary contributions made by many
48  * individuals on behalf of the Visigoth Software Society. For more
49  * information on the Visigoth Software Society, please see
50  * http://www.visigoths.org/
51  */

52
53 package freemarker.template;
54
55 import java.io.IOException JavaDoc;
56
57 /**
58  * An interface that can be implemented by writers returned from
59  * {@link TemplateTransformModel#getWriter(java.io.Writer, java.util.Map)}. The
60  * methods on this
61  * interfaces are callbacks that will be called by the template engine and that
62  * give the writer a chance to better control the evaluation of the transform
63  * body. The writer can instruct the engine to skip or to repeat body
64  * evaluation, and gets notified about exceptions that are thrown during the
65  * body evaluation.
66  *
67  * @author Attila Szegedi
68  * @version $Id: TransformControl.java,v 1.11 2005/06/16 18:13:58 ddekany Exp $
69  */

70 public interface TransformControl
71 {
72     /**
73      * Constant returned from {@link #afterBody()} that tells the
74      * template engine to repeat transform body evaluation and feed
75      * it again to the transform.
76      */

77     public static final int REPEAT_EVALUATION = 0;
78
79     /**
80      * Constant returned from {@link #afterBody()} that tells the
81      * template engine to end the transform and close the writer.
82      */

83     public static final int END_EVALUATION = 1;
84  
85     /**
86      * Constant returned from {@link #onStart()} that tells the
87      * template engine to skip evaluation of the body.
88      */

89     public static final int SKIP_BODY = 0;
90     
91     /**
92      * Constant returned from {@link #onStart()} that tells the
93      * template engine to evaluate the body.
94      */

95     public static final int EVALUATE_BODY = 1;
96
97     /**
98      * Called before the body is evaluated for the first time.
99      * @return
100      * <ul>
101      * <li><tt>SKIP_BODY</tt> if the transform wants to ignore the body. In this
102      * case, only {@link java.io.Writer#close()} is called next and processing ends.</li>
103      * <li><tt>EVALUATE_BODY</tt> to normally evaluate the body of the transform
104      * and feed it to the writer</li>
105      * </ul>
106      */

107     public int onStart() throws TemplateModelException, IOException JavaDoc;
108     
109     /**
110      * Called after the body has been evaluated.
111      * @return
112      * <ul>
113      * <li><tt>END_EVALUATION</tt> if the transformation should be ended.</li>
114      * <li><tt>REPEAT_EVALUATION</tt> to have the engine re-evaluate the
115      * transform body and feed it again to the writer.</li>
116      * </ul>
117      */

118     public int afterBody() throws TemplateModelException, IOException JavaDoc;
119     
120     /**
121      * Called if any exception occurs during the transform between the
122      * {@link TemplateTransformModel#getWriter(java.io.Writer, java.util.Map)} call
123      * and the {@link java.io.Writer#close()} call.
124      * @param t the throwable that represents the exception. It can be any
125      * non-checked throwable, as well as {@link TemplateException} and
126      * {@link java.io.IOException}.
127      *
128      * @throws Throwable is recommended that the methods rethrow the received
129      * throwable. If the method wants to throw another throwable, it should
130      * either throw a non-checked throwable, or an instance of
131      * {@link TemplateException} and {@link java.io.IOException}. Throwing any
132      * other checked exception will cause the engine to rethrow it as
133      * a {@link java.lang.reflect.UndeclaredThrowableException}.
134      */

135     public void onError(Throwable JavaDoc t) throws Throwable JavaDoc;
136 }
137
Popular Tags