1 /*
2 * This file is part of Pease Plate Template Engine.
3 *
4 * Pease Plate Template Engine is free software: you can redistribute
5 * it and/or modify it under the terms of the GNU Lesser General
6 * Public License as published by the Free Software Foundation,
7 * either version 3 of the License, or any later version.
8 *
9 * Pease Plate Template Engine is distributed in the hope that it
10 * will be useful, but WITHOUT ANY WARRANTY; without even the implied
11 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
12 * See the GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with Pease Plate Template Engine. If not, see
16 * <http://www.gnu.org/licenses/>.
17 *
18 * Copyright (c) 2008 Manfred HANTSCHEL
19 */
20 package org.peaseplate;
21
22 import java.io.IOException;
23 import java.io.Writer;
24 import java.util.Collection;
25 import java.util.Locale;
26
27 import org.peaseplate.internal.ResourceKey;
28 import org.peaseplate.internal.locator.InMemoryTemplateLocator;
29 import org.peaseplate.locator.TemplateLocator;
30 import org.peaseplate.resolver.Resolver;
31 import org.peaseplate.service.CacheService;
32 import org.peaseplate.service.ConversionService;
33 import org.peaseplate.service.DesignatorService;
34 import org.peaseplate.service.MacroService;
35 import org.peaseplate.service.ResolverService;
36 import org.peaseplate.service.TransformerService;
37
38 /**
39 * <p>
40 * This class represents the central engine of the Pease Plate engine.
41 * </p>
42 * <p>
43 * Usually just create exactly one instance of this class for all your
44 * rendering duties. It stores all global and reusable settings for
45 * template rendering and is thread safe. It contains a cache that
46 * stores compiled templates.
47 * </p>
48 *
49 * @author Manfred HANTSCHEL
50 */
51 public interface TemplateEngine {
52
53 /**
54 * Adds the specified class loaders to the facotry. The class loader
55 * is used for multiple purposes, like initializing the services.
56 * The there is a new class loader added, the services will
57 * get initialized with it.
58 *
59 * @param classLoaders the class loaders
60 */
61 public void addClassLoader(ClassLoader... classLoaders);
62
63 /**
64 * Returns all the class loaders in an unmodifiable collection.
65 *
66 * @return the classLoaders
67 */
68 public Collection<ClassLoader> getClassLoaders();
69
70 /**
71 * Returns the cache service used to cache templates and messages
72 * @return the cache service
73 */
74 public CacheService getCacheService();
75
76 /**
77 * Returns the resolver service used to resolve templates and messages
78 * @return the resolver service
79 */
80 public ResolverService getResolverService();
81
82 /**
83 * Returns the designator service used to resolve and handle designators
84 * @return the designator service
85 */
86 public DesignatorService getDesignatorService();
87
88 /**
89 * Returns the transformer service used to resolve and handle transformers
90 * @return the transformer service
91 */
92 public TransformerService getTransformerService();
93
94 /**
95 * Returns the macro service used to resolve and handle predefined macros
96 * @return the macro service
97 */
98 public MacroService getMacroService();
99
100 /**
101 * Returns the conversion service used to convert objects from one type to another
102 * @return the conversion service
103 */
104 public ConversionService getConversionService();
105
106 /**
107 * Returns the default locale used when no locale is specified somewhere where needed
108 * @return teh default locale
109 */
110 public Locale getDefaultLocale();
111
112 /**
113 * Sets the default locale used when no locale is specified somewhere where needed
114 * @param defaultLocale the default locale
115 */
116 public void setDefaultLocale(Locale defaultLocale);
117
118 /**
119 * Returns the default encoding used when no encoding is specified somewhere where needed
120 * @return the default encoding
121 */
122 public String getDefaultEncoding();
123
124 /**
125 * Sets the default encoding used when no encoding is specified somewhere where needed
126 * @param defaultEncoding the default encoding
127 */
128 public void setDefaultEncoding(String defaultEncoding);
129
130 /**
131 * Returns the default line separator
132 * @return the default line separator
133 */
134 public LineSeparator getDefaultLineSeparator();
135
136 /**
137 * Sets the default line separator
138 * @param defaultLineSeparator the default line separator
139 */
140 public void setDefaultLineSeparator(LineSeparator defaultLineSeparator);
141
142 /**
143 * Compiles the template defined by the specified locator.
144 * This is the base method for compiling templates.
145 * @param locator the locator
146 * @return the compiled template
147 * @throws TemplateException on occasion
148 */
149 public Template compile(TemplateLocator locator) throws TemplateException;
150
151 /**
152 * Compiles the template defined by the source.
153 * Makes use of the {@link InMemoryTemplateLocator},
154 * which stores the source in memory.
155 * @param source the source
156 * @return the compiled template
157 * @throws TemplateException
158 */
159 public Template compile(String source) throws TemplateException;
160
161 /**
162 * Compiles the template defined by the source.
163 * Makes use of the {@link InMemoryTemplateLocator},
164 * which stores the source in memory.
165 * @param source the source
166 * @return the compiled template
167 * @throws TemplateException
168 */
169 public Template compile(char[] source) throws TemplateException;
170
171 /**
172 * Renders the template with the specified name to the specified writer.
173 * <br/><br/>
174 * The workingObject is just any object or bean, that contains the data
175 * that should be integrated in the template.
176 * <br/><br/>
177 * The name of the template is usually some path on the file system or
178 * the resources but you can enhance this by implementing an own {@link Resolver}.
179 *
180 * @param writer the writer
181 * @param workingObject the working object
182 * @param name the name of the template
183 * @throws TemplateException if anything goes wrong
184 * @throws IOException if it cannot write to the writer
185 */
186 public void render(Writer writer, Object workingObject, String name) throws TemplateException, IOException;
187
188 /**
189 * Renders the template with the specified name to the specified writer.
190 * <br/><br/>
191 * The workingObject is just any object or bean, that contains the data
192 * that should be integrated in the template.
193 * <br/><br/>
194 * The name of the template is usually some path on the file system or
195 * the resources but you can enhance this by implementing an own {@link Resolver}.
196 *
197 * @param writer the writer
198 * @param workingObject the working object
199 * @param name the name of the template
200 * @param locale the locale; uses the default locale if null
201 * @throws TemplateException if anything goes wrong
202 * @throws IOException if it cannot write to the writer
203 */
204 public void render(Writer writer, Object workingObject, String name, Locale locale) throws TemplateException, IOException;
205
206 /**
207 * Renders the template with the specified name to the specified writer.
208 * <br/><br/>
209 * The workingObject is just any object or bean, that contains the data
210 * that should be integrated in the template.
211 * <br/><br/>
212 * The name of the template is usually some path on the file system or
213 * the resources but you can enhance this by implementing an own {@link Resolver}.
214 *
215 * @param writer the writer
216 * @param workingObject the working object
217 * @param name the name of the template
218 * @param encoding the encoding; uses the default encoding if null
219 * @throws TemplateException if anything goes wrong
220 * @throws IOException if it cannot write to the writer
221 */
222 public void render(Writer writer, Object workingObject, String name, String encoding) throws TemplateException, IOException;
223
224 /**
225 * Renders the template with the specified name to the specified writer.
226 * <br/><br/>
227 * The workingObject is just any object or bean, that contains the data
228 * that should be integrated in the template.
229 * <br/><br/>
230 * The name of the template is usually some path on the file system or
231 * the resources but you can enhance this by implementing an own {@link Resolver}.
232 *
233 * @param writer the writer
234 * @param workingObject the working object
235 * @param name the name of the template
236 * @param locale the locale; uses the default locale if null
237 * @param encoding the encoding; uses the default encoding if null
238 * @throws TemplateException if anything goes wrong
239 * @throws IOException if it cannot write to the writer
240 */
241 public void render(Writer writer, Object workingObject, String name, Locale locale, String encoding) throws TemplateException, IOException;
242
243 /**
244 * Renders the template specified by the descriptor
245 * <br/><br/>
246 * The workingObject is just any object or bean, that contains the data
247 * that should be integrated in the template.
248 * <br/><br/>
249 * The name of the template is usually some path on the file system or
250 * the resources but you can enhance this by implementing an own {@link Resolver}.
251 *
252 * @param writer the writer
253 * @param workingObject the working object
254 * @param key the key
255 * @throws TemplateException if anything goes wrong
256 * @throws IOException if it cannot write to the writer
257 */
258 public void render(Writer writer, Object workingObject, ResourceKey key) throws TemplateException, IOException;
259
260 }