1 /*
2 * $Source: /usr/cvsroot/melati/melati/src/main/java/org/melati/template/TemplateEngine.java,v $
3 * $Revision: 1.38 $
4 *
5 * Copyright (C) 2005 Tim Pizey
6 *
7 * Part of Melati (http://melati.org), a framework for the rapid
8 * development of clean, maintainable web applications.
9 *
10 * Melati is free software; Permission is granted to copy, distribute
11 * and/or modify this software under the terms either:
12 *
13 * a) the GNU General Public License as published by the Free Software
14 * Foundation; either version 2 of the License, or (at your option)
15 * any later version,
16 *
17 * or
18 *
19 * b) any version of the Melati Software License, as published
20 * at http://melati.org
21 *
22 * You should have received a copy of the GNU General Public License and
23 * the Melati Software License along with this program;
24 * if not, write to the Free Software Foundation, Inc.,
25 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA to obtain the
26 * GNU General Public License and visit http://melati.org to obtain the
27 * Melati Software License.
28 *
29 * Feel free to contact the Developers of Melati (http://melati.org),
30 * if you would like to work out a different arrangement than the options
31 * outlined here. It is our intention to allow Melati to be used by as
32 * wide an audience as possible.
33 *
34 * This program is distributed in the hope that it will be useful,
35 * but WITHOUT ANY WARRANTY; without even the implied warranty of
36 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
37 * GNU General Public License for more details.
38 *
39 * Contact details for copyright holder:
40 *
41 * Tim Pizey <timp At paneris.org>
42 * http://paneris.org/~timp
43 */
44 package org.melati.template;
45
46 import java.io.IOException;
47 import java.util.Enumeration;
48
49 import org.melati.Melati;
50 import org.melati.MelatiConfig;
51 import org.melati.util.MelatiStringWriter;
52 import org.melati.util.MelatiWriter;
53
54 /**
55 * A TemplateEngine typically evaluates a template containing variables
56 * against a context containing values for those variables.
57 *
58 * The canonical java Template Engines are WebMacro and Velocity.
59 *
60 * @author timp At paneris.org
61 */
62 public interface TemplateEngine {
63
64 /**
65 * Initialise the Engine.
66 *
67 * @param melatiConfig a {@link MelatiConfig}
68 * @throws TemplateEngineException if any problem occurs with the engine
69 */
70 void init(MelatiConfig melatiConfig) throws TemplateEngineException;
71
72 /**
73 * Create a new Context for this engine.
74 *
75 * @param melati the {@link Melati}
76 * @throws TemplateEngineException if any problem occurs with the engine
77 * @return a {@link TemplateContext}
78 */
79 TemplateContext getTemplateContext(Melati melati)
80 throws TemplateEngineException;
81
82 /**
83 * The name of the template engine (used to find the templets).
84 * @return the name of the current configured template engine
85 */
86 String getName();
87
88 /**
89 * @return the extension of the templates used by this template engine,
90 * including the dot.
91 */
92 String templateExtension();
93
94 /**
95 * A root should not end in a slash.
96 *
97 * @return an Enumeration of string roots, always at least the empty string
98 */
99 Enumeration getRoots();
100
101 /**
102 * Add a template root directory.
103 * NOTE A root should not start or end in a slash.
104 *
105 * @param root the root to add
106 */
107 void addRoot(String root);
108
109 /**
110 * Get a template given it's full name.
111 *
112 * @param templateName the name of the template to find
113 * @throws IOException if TemplateEngine does
114 * @throws NotFoundException if template not found
115 * @return a template
116 */
117 Template template(String templateName)
118 throws IOException, NotFoundException;
119
120 /**
121 * The name of a template which exists.
122 *
123 * @param key short name, without path or extension
124 * @param classifier a purpose or database name or similar qualifier
125 * @return the name of a template, null if none found
126 */
127 String getTemplateName(String key, String classifier);
128
129 /**
130 * Expand the Template against the context.
131 *
132 * @param out a {@link MelatiWriter} to output on
133 * @param templateName the name of the template to expand
134 * @param templateContext the {@link ServletTemplateContext} to expand
135 * the template against
136 * @throws IOException if TemplateEngine does
137 * @throws NotFoundException if template not found
138 */
139 void expandTemplate(MelatiWriter out, String templateName,
140 TemplateContext templateContext) throws IOException, NotFoundException;
141
142 /**
143 * Expand the Template against the context.
144 *
145 * @param out a {@link MelatiWriter} to output on
146 * @param template the {@link Template} to expand
147 * @param templateContext the {@link ServletTemplateContext} to expand
148 * the template against
149 * @throws IOException if TemplateEngine does
150 */
151 void expandTemplate(MelatiWriter out, Template template,
152 TemplateContext templateContext) throws IOException;
153
154 /**
155 * Expand the Template against the context and return the expansion as a string.
156 *
157 * @param template the {@link Template} to expand
158 * @param templateContext the {@link ServletTemplateContext} to expand
159 * the template against
160 * @return the interpolated template as a String
161 * @throws IOException if TemplateEngine does
162 */
163 String expandedTemplate(Template template, TemplateContext templateContext)
164 throws IOException;
165
166 /**
167 * @return a {@link MelatiStringWriter}.
168 * @see Melati#getStringWriter()
169 */
170 MelatiStringWriter getStringWriter();
171
172 /**
173 * Get the underlying engine.
174 *
175 * @return the configured template engine
176 */
177 Object getEngine();
178
179 }
180