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.cache;
054:
055: import java.io.IOException;
056: import java.io.Reader;
057:
058: /**
059: * A template loader is an object that can find the source stream for a
060: * template, can retrieve its time of last modification as well as the stream
061: * itself. A template loader is plugged into the {@link TemplateCache} to
062: * provide concrete loading of the templates.
063: * The implementations can be coded in a non-threadsafe manner as the natural
064: * user of the template loader, {@link TemplateCache} does the necessary
065: * synchronization.
066: * @author Attila Szegedi, szegedia at freemail dot hu
067: * @version $Id: TemplateLoader.java,v 1.18 2004/03/01 01:13:30 ddekany Exp $
068: */
069: public interface TemplateLoader {
070: /**
071: * Finds the object that acts as the source of the template with the
072: * given name. This method is called by the TemplateCache when a template
073: * is requested, before calling either {@link #getLastModified(Object)} or
074: * {@link #getReader(Object, String)}.
075: *
076: * @param name the name of the template, already localized and normalized by
077: * the {@link freemarker.cache.TemplateCache cache}.
078: * It is completely up to the loader implementation to interpret
079: * the name, however it should expect to receive hierarchical paths where
080: * path components are separated by a slash (not backslash). Backslashes
081: * (or any other OS specific separator character) are not considered as separators by
082: * FreeMarker, and thus they will not be replaced with slash before passing to this method,
083: * so it is up to the template loader to handle them (say, be throwing and exception that
084: * tells the user that the path (s)he has entered is invalid, as (s)he must use slash --
085: * typical mistake of Windows users).
086: * The passed names are always considered relative to some loader-defined root
087: * location (often reffered as the "template root direcotry"), and will never start with
088: * a slash, nor will they contain a path component consisting of either a single or a double
089: * dot -- these are all resolved by the template cache before passing the name to the
090: * loader. As a side effect, paths that trivially reach outside template root directory,
091: * such as <tt>../my.ftl</tt>, will be rejected by the template cache, so they never
092: * reach the template loader. Note again, that if the path uses backslash as path separator
093: * instead of slash as (the template loader should not accept that), the normalisation will
094: * not properly happen, as FreeMarker (the cache) recognizes only the slashes as separators.
095: *
096: * @return an object representing the template source, which can be
097: * supplied in subsequent calls to {@link #getLastModified(Object)} and
098: * {@link #getReader(Object, String)}. Null must be returned if the source
099: * for the template can not be found (do not throw <code>FileNotFoundException</code>!).
100: * The returned object may will be compared with a cached template source
101: * object for equality, using the <code>equals</code> method. Thus,
102: * objects returned for the same physical source must be equivalent
103: * according to <code>equals</code> method, otherwise template caching
104: * can become very ineffective!
105: */
106: public Object findTemplateSource(String name) throws IOException;
107:
108: /**
109: * Returns the time of last modification of the specified template source.
110: * This method is called after <code>findTemplateSource()</code>.
111: * @param templateSource an object representing a template source, obtained
112: * through a prior call to {@link #findTemplateSource(String)}.
113: * @return the time of last modification of the specified template source,
114: * or -1 if the time is not known.
115: */
116: public long getLastModified(Object templateSource);
117:
118: /**
119: * Returns the character stream of a template represented by the specified
120: * template source. This method is called after <code>getLastModified()</code>
121: * if it is determined that a cached copy of the template is unavailable
122: * or stale.
123: * @param templateSource an object representing a template source, obtained
124: * through a prior call to {@link #findTemplateSource(String)}.
125: * @param encoding the character encoding used to translate source bytes
126: * to characters. Some loaders may not have access to the byte
127: * representation of the template stream, and instead directly obtain a
128: * character stream. These loaders will - quite naturally - ignore the
129: * encoding parameter.
130: * @return a reader representing the template character stream. The
131: * framework will call <code>close()</code>.
132: * @throws IOException if an I/O error occurs while accessing the stream.
133: */
134: public Reader getReader(Object templateSource, String encoding)
135: throws IOException;
136:
137: /**
138: * Closes the template source. This is the last method that is called by
139: * the TemplateCache for a templateSource. The framework guarantees that
140: * this method will be called on every object that is returned from
141: * {@link #findTemplateSource(String)}.
142: * @param templateSource the template source that should be closed.
143: */
144: public void closeTemplateSource(Object templateSource)
145: throws IOException;
146: }
|