TemplateLoader


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.cache;
54  
55  import java.io.IOException  ;
56  import java.io.Reader  ;
57  
58  /**
59   * A template loader is an object that can find the source stream for a 
60   * template, can retrieve its time of last modification as well as the stream
61   * itself. A template loader is plugged into the {@link TemplateCache} to
62   * provide concrete loading of the templates.
63   * The implementations can be coded in a non-threadsafe manner as the natural
64   * user of the template loader, {@link TemplateCache} does the necessary
65   * synchronization.
66   * @author Attila Szegedi, szegedia at freemail dot hu
67   * @version $Id: TemplateLoader.java,v 1.18 2004/03/01 01:13:30 ddekany Exp $
68   */
69  public interface TemplateLoader
70  {
71      /**
72       * Finds the object that acts as the source of the template with the
73       * given name. This method is called by the TemplateCache when a template
74       * is requested, before calling either {@link #getLastModified(Object)} or
75       * {@link #getReader(Object, String)}.
76       *
77       * @param name the name of the template, already localized and normalized by
78       * the {@link freemarker.cache.TemplateCache cache}.
79       * It is completely up to the loader implementation to interpret
80       * the name, however it should expect to receive hierarchical paths where
81       * path components are separated by a slash (not backslash). Backslashes
82       * (or any other OS specific separator character) are not considered as separators by
83       * FreeMarker, and thus they will not be replaced with slash before passing to this method,
84       * so it is up to the template loader to handle them (say, be throwing and exception that
85       * tells the user that the path (s)he has entered is invalid, as (s)he must use slash --
86       * typical mistake of Windows users).
87       * The passed names are always considered relative to some loader-defined root
88       * location (often reffered as the "template root direcotry"), and will never start with
89       * a slash, nor will they contain a path component consisting of either a single or a double
90       * dot -- these are all resolved by the template cache before passing the name to the
91       * loader. As a side effect, paths that trivially reach outside template root directory,
92       * such as <tt>../my.ftl</tt>, will be rejected by the template cache, so they never
93       * reach the template loader. Note again, that if the path uses backslash as path separator
94       * instead of slash as (the template loader should not accept that), the normalisation will
95       * not properly happen, as FreeMarker (the cache) recognizes only the slashes as separators.
96       *
97       * @return an object representing the template source, which can be
98       * supplied in subsequent calls to {@link #getLastModified(Object)} and
99       * {@link #getReader(Object, String)}. Null must be returned if the source
100      * for the template can not be found (do not throw <code>FileNotFoundException</code>!).
101      * The returned object may will be compared with a cached template source
102      * object for equality, using the <code>equals</code> method. Thus,
103      * objects returned for the same physical source must be equivalent
104      * according to <code>equals</code> method, otherwise template caching
105      * can become very ineffective!
106      */
107     public Object   findTemplateSource(String   name)
108     throws
109         IOException  ;
110         
111     /**
112      * Returns the time of last modification of the specified template source.
113      * This method is called after <code>findTemplateSource()</code>.
114      * @param templateSource an object representing a template source, obtained
115      * through a prior call to {@link #findTemplateSource(String)}.
116      * @return the time of last modification of the specified template source,
117      * or -1 if the time is not known.
118      */
119     public long getLastModified(Object   templateSource);
120     
121     /**
122      * Returns the character stream of a template represented by the specified
123      * template source. This method is called after <code>getLastModified()</code>
124      * if it is determined that a cached copy of the template is unavailable
125      * or stale.
126      * @param templateSource an object representing a template source, obtained
127      * through a prior call to {@link #findTemplateSource(String)}.
128      * @param encoding the character encoding used to translate source bytes
129      * to characters. Some loaders may not have access to the byte
130      * representation of the template stream, and instead directly obtain a 
131      * character stream. These loaders will - quite naturally - ignore the 
132      * encoding parameter.
133      * @return a reader representing the template character stream. The
134      * framework will call <code>close()</code>.
135      * @throws IOException if an I/O error occurs while accessing the stream.
136      */
137     public Reader   getReader(Object   templateSource, String   encoding)
138     throws
139         IOException  ;
140     
141     /**
142      * Closes the template source. This is the last method that is called by
143      * the TemplateCache for a templateSource. The framework guarantees that
144      * this method will be called on every object that is returned from
145      * {@link #findTemplateSource(String)}.
146      * @param templateSource the template source that should be closed.
147      */
148     public void closeTemplateSource(Object   templateSource)
149     throws
150         IOException  ;
151 }
152
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags