TemplateTransformModel


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  import java.io.Writer  ;
57  import java.util.Map  ;
58  
59  /**
60   * Objects that implement this interface can be used in a <code>&lt;transform></code>
61   * block to perform arbitrary transformations on a part of the template
62   * processing output.
63   * <P>Note that, as of FreeMarker 2.1, TemplateTransform Model
64   * has changed. This is a more powerful implementation. 
65   * There is a quick-and-dirty way to patch any legacy
66   * TemplateTransformModel so that it implements the new API.
67   * You simply add the following as your implementation 
68   * of the getWriter() call:
69   * <PRE>
70   * 
71   *    public Writer getWriter(final Writer out, 
72   *                            Map args) 
73   *    {
74   *       final StringBuffer buf = new StringBuffer();
75   *       return new Writer() {
76   *           public void write(char cbuf[], int off, int len) {
77   *               buf.append(cbuf, off, len);
78   *           }
79   *
80   *           public void flush() throws IOException {
81   *               out.flush();
82   *           }
83   * 
84   *           public void close() throws IOException {
85   *               StringReader sr = new StringReader(buf.toString());
86   *               StringWriter sw = new StringWriter();
87   *               transform(sr, sw);
88   *               out.write(sw.toString());
89   *           }
90   *       };
91   *   }
92   *
93   * 
94   * </PRE>
95   * 
96   * <P>Implementions of <tt>TemplateTransformModel</tt> should be thread-safe.
97   *
98   * @version $Id: TemplateTransformModel.java,v 1.36 2003/04/11 20:57:32 revusky Exp $
99   */
100 public interface TemplateTransformModel extends TemplateModel {
101 
102      /**
103       * Returns a writer that will be used by the engine to feed the
104       * transformation input to the transform. Each call to this method
105       * must return a new instance of the writer so that the transformation
106       * is thread-safe.
107       * @param out the character stream to which to write the transformed output
108       * @param args the arguments (if any) passed to the transformation as a 
109       * map of key/value pairs where the keys are strings and the arguments are
110       * TemplateModel instances. This is never null.
111       * @return a writer to which the engine will feed the transformation 
112       * input, or null if the transform does not support nested content (body).
113       * The returned writer can implement the {@link TransformControl}
114       * interface if it needs advanced control over the evaluation of the 
115       * transformation body.
116       */
117      Writer   getWriter(Writer   out, Map   args) 
118          throws TemplateModelException, IOException  ;
119 }
120
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags