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  ;
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  ;
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  ;
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   t) throws Throwable  ;
136 }
137
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags