001 package echopoint.template;
002
003 /*
004 * This file is part of the Echo Point Project. This project is a collection
005 * of Components that have extended the Echo Web Application Framework.
006 *
007 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
008 *
009 * The contents of this file are subject to the Mozilla Public License Version
010 * 1.1 (the "License"); you may not use this file except in compliance with
011 * the License. You may obtain a copy of the License at
012 * http://www.mozilla.org/MPL/
013 *
014 * Software distributed under the License is distributed on an "AS IS" basis,
015 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
016 * for the specific language governing rights and limitations under the
017 * License.
018 *
019 * Alternatively, the contents of this file may be used under the terms of
020 * either the GNU General Public License Version 2 or later (the "GPL"), or
021 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
022 * in which case the provisions of the GPL or the LGPL are applicable instead
023 * of those above. If you wish to allow use of your version of this file only
024 * under the terms of either the GPL or the LGPL, and not to allow others to
025 * use your version of this file under the terms of the MPL, indicate your
026 * decision by deleting the provisions above and replace them with the notice
027 * and other provisions required by the GPL or the LGPL. If you do not delete
028 * the provisions above, a recipient may use your version of this file under
029 * the terms of any one of the MPL, the GPL or the LGPL.
030 */
031 import java.io.IOException;
032 import java.io.InputStream;
033
034 /**
035 * <code>TemplateDataSource</code> is used to return template source data and
036 * encoding information for this data.
037 * <p>
038 * A single <code>TemplateDataSource</code> can be used as the source for
039 * multiple TemplatePanels. This helps reduce the memory footprint of the
040 * template data. An implementation of this interface must keep the requirement
041 * in mind.
042 */
043 public interface TemplateDataSource {
044 /**
045 * Returns a canonical name of this <code>TemplateDataSource</code>.
046 * <p>
047 * The name returned here is used to look up the parsing result of the
048 * internal caching, so it should differ for all different
049 * <code>TemplateDataSource</code> objects :-)
050 * <p>
051 * May return <code>null</code> if this TemplateDataSource is supposed to
052 * be parsed each time. The canonical name would be something like a
053 * filename or an URL.
054 *
055 * @return a unique name of the <code>TemplateDataSource</code>
056 */
057 public String getCanonicalName();
058
059 /**
060 * This content type of the template data is used by the rendering framework
061 * to find an appropriate template compiler.
062 * <p>
063 * An example content type is text/xhtml and cause a template compiler to be
064 * found for XHTML template data.
065 *
066 * @return the content type of the template data
067 */
068 public String getContentType();
069
070 /**
071 * This returns the character encoding of the
072 * <code>TemplateDataSource</code>.
073 * <p>
074 * This will be used to create a
075 * <code>new InputStreamReader(stream,characterEncoding)</code> from the
076 * <code>InputStream</code> return by <code>getInputStream()</code>.
077 *
078 * @return the character encoding of the <code>TemplateDataSource</code>
079 * as defined by the <code>java.io.InputStreamReader()</code>
080 * specification.
081 *
082 * @see java.io.InputStreamReader#InputStreamReader(java.io.InputStream,
083 * java.lang.String)
084 */
085 public String getCharacterEncoding();
086
087 /**
088 * Gets an <code>InputStream</code> of this
089 * <code>TemplateDataSource</code>.
090 * <p>
091 * <em>Note</em> that this method may be called multiple times in the life
092 * of the <code>TemplateDataSource</code>. So you probably have to
093 * implement a buffer if your underlying data source is transient ..
094 *
095 * @return a InputStream containing the template data
096 */
097 public InputStream getInputStream() throws IOException;
098
099 /**
100 * This returns a hint to the template rendering mechanism as to whether
101 * this template data can be cached. If <code>null</code> is returned then
102 * the template data will never be cached.
103 * <p>
104 * However the inverse is not necessarily the case. You may return a
105 * <code>TemplateCachingHints</code>, however this does not mean the
106 * rendering mechanism will cache the template data.
107 * <p>
108 * You might return <code>null</code> if the template data is especially
109 * large and you dont want it retained in cache memory.
110 *
111 * @return null if the template data should not be cached or a
112 * <code>TemplateCachingHints</code> to say how it <i>might</i>
113 * be cached.
114 */
115 public TemplateCachingHints getCachingHints();
116
117 /**
118 * This returns a hint to the underlying template compiler mechanism as to
119 * how the template data should be compiled into XHTML.
120 * <p>
121 * Most of the <code>TemplateCompilerHints</code> properties are really
122 * aimed as JAXP XML parser implementations but you can provide generic
123 * values via the getAttribute() mechanism.
124 *
125 * @return a <code>TemplateCompilerHints</code> implementation or null
126 * if there are no compiler hints
127 */
128 public TemplateCompilerHints getCompilerHints();
129 }