1 package org.apache.turbine.services.template;
2
3
4 /*
5 * Licensed to the Apache Software Foundation (ASF) under one
6 * or more contributor license agreements. See the NOTICE file
7 * distributed with this work for additional information
8 * regarding copyright ownership. The ASF licenses this file
9 * to you under the Apache License, Version 2.0 (the
10 * "License"); you may not use this file except in compliance
11 * with the License. You may obtain a copy of the License at
12 *
13 * http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing,
16 * software distributed under the License is distributed on an
17 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18 * KIND, either express or implied. See the License for the
19 * specific language governing permissions and limitations
20 * under the License.
21 */
22
23
24 import org.apache.turbine.pipeline.PipelineData;
25 import org.apache.turbine.services.Service;
26
27 /**
28 * This service provides a method for mapping templates to their
29 * appropriate Screens or Navigations. It also allows templates to
30 * define a layout/navigations/screen modularization within the
31 * template structure. It also performs caching if turned on in the
32 * properties file.
33 *
34 * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
35 * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
36 * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
37 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
38 * @version $Id$
39 */
40 public interface TemplateService
41 extends Service
42 {
43 /**
44 * The key under which this service is stored in TurbineServices.
45 */
46 String SERVICE_NAME = "TemplateService";
47
48 /** Default Template Name. */
49 String DEFAULT_TEMPLATE_KEY = "default.template";
50
51 /** Default value for the Template Name */
52 String DEFAULT_TEMPLATE_VALUE = "Default";
53
54 /** Default Extension for the template names. */
55 String DEFAULT_EXTENSION_KEY = "default.extension";
56
57 /** Default value of the Turbine Module Caching */
58 String DEFAULT_EXTENSION_VALUE = "";
59
60 /** Character that separates a Template Name from the Extension */
61 char EXTENSION_SEPARATOR = '.';
62
63 /** Character that separates the various Template Parts */
64 char TEMPLATE_PARTS_SEPARATOR = ',';
65
66 /** "Default" name for Classes and Templates */
67 String DEFAULT_NAME = "Default";
68
69 /**
70 * Returns true if the Template Service has caching activated
71 *
72 * @return true if Caching is active.
73 */
74 boolean isCaching();
75
76 /**
77 * Get the default template name extension specified
78 * in the template service properties.
79 *
80 * @return The default the extension.
81 */
82 String getDefaultExtension();
83
84 /**
85 * Return Extension for a supplied template
86 *
87 * @param template The template name
88 *
89 * @return extension The extension for the supplied template
90 */
91 String getExtension(String template);
92
93 /**
94 * Returns the Default Template Name with the Default Extension.
95 * If the extension is unset, return only the template name
96 *
97 * @return The default template Name
98 */
99 String getDefaultTemplate();
100
101 /**
102 * Get the default page module name of the template engine
103 * service corresponding to the default template name extension.
104 *
105 * @return The default page module name.
106 */
107 String getDefaultPage();
108
109 /**
110 * Get the default screen module name of the template engine
111 * service corresponding to the default template name extension.
112 *
113 * @return The default screen module name.
114 */
115 String getDefaultScreen();
116
117 /**
118 * Get the default layout module name of the template engine
119 * service corresponding to the default template name extension.
120 *
121 * @return The default layout module name.
122 */
123 String getDefaultLayout();
124
125 /**
126 * Get the default navigation module name of the template engine
127 * service corresponding to the default template name extension.
128 *
129 * @return The default navigation module name.
130 */
131 String getDefaultNavigation();
132
133 /**
134 * Get the default layout template name of the template engine
135 * service corresponding to the default template name extension.
136 *
137 * @return The default layout template name.
138 */
139 String getDefaultLayoutTemplate();
140
141 /**
142 * Get the default page module name of the template engine
143 * service corresponding to the template name extension of
144 * the named template.
145 *
146 * @param template The template name.
147 * @return The default page module name.
148 */
149 String getDefaultPageName(String template);
150
151 /**
152 * Get the default screen module name of the template engine
153 * service corresponding to the template name extension of
154 * the named template.
155 *
156 * @param template The template name.
157 * @return The default screen module name.
158 */
159 String getDefaultScreenName(String template);
160
161 /**
162 * Get the default layout module name of the template engine
163 * service corresponding to the template name extension of
164 * the named template.
165 *
166 * @param template The template name.
167 * @return The default layout module name.
168 */
169 String getDefaultLayoutName(String template);
170
171 /**
172 * Get the default navigation module name of the template engine
173 * service corresponding to the template name extension of
174 * the named template.
175 *
176 * @param template The template name.
177 * @return The default navigation module name.
178 */
179 String getDefaultNavigationName(String template);
180
181 /**
182 * Get the default layout template name of the template engine
183 * service corresponding to the template name extension of
184 * the named template.
185 *
186 * @param template The template name.
187 * @return The default layout template name.
188 */
189 String getDefaultLayoutTemplateName(String template);
190
191 /**
192 * Find the default page module name for the given request.
193 *
194 * @param pipelineData The encapsulation of the request to retrieve the
195 * default page for.
196 * @return The default page module name.
197 */
198 String getDefaultPageName(PipelineData pipelineData);
199
200 /**
201 * Find the default layout module name for the given request.
202 *
203 * @param pipelineData The encapsulation of the request to retrieve the
204 * default layout for.
205 * @return The default layout module name.
206 */
207 String getDefaultLayoutName(PipelineData pipelineData);
208
209 /**
210 * Locate and return the name of the screen module to be used
211 * with the named screen template.
212 *
213 * @param template The screen template name.
214 * @return The found screen module name.
215 * @throws Exception a generic exception.
216 */
217 String getScreenName(String template)
218 throws Exception;
219
220 /**
221 * Locate and return the name of the layout module to be used
222 * with the named layout template.
223 *
224 * @param template The layout template name.
225 * @return The found layout module name.
226 * @throws Exception a generic exception.
227 */
228 String getLayoutName(String template)
229 throws Exception;
230
231 /**
232 * Locate and return the name of the navigation module to be used
233 * with the named navigation template.
234 *
235 * @param template The navigation template name.
236 * @return The found navigation module name.
237 * @throws Exception a generic exception.
238 */
239 String getNavigationName(String template)
240 throws Exception;
241
242 /**
243 * Locate and return the name of the screen template corresponding
244 * to the given template name parameter.
245 *
246 * @param template The template name parameter.
247 * @return The found screen template name.
248 * @throws Exception a generic exception.
249 */
250 String getScreenTemplateName(String template)
251 throws Exception;
252
253 /**
254 * Locate and return the name of the layout template corresponding
255 * to the given screen template name parameter.
256 *
257 * @param template The template name parameter.
258 * @return The found screen template name.
259 * @throws Exception a generic exception.
260 */
261 String getLayoutTemplateName(String template)
262 throws Exception;
263
264 /**
265 * Locate and return the name of the navigation template corresponding
266 * to the given template name parameter.
267 *
268 * @param template The template name parameter.
269 * @return The found navigation template name.
270 * @throws Exception a generic exception.
271 */
272 String getNavigationTemplateName(String template)
273 throws Exception;
274
275 /**
276 * Translates the supplied template paths into their Turbine-canonical
277 * equivalent (probably absolute paths).
278 *
279 * @param templatePaths An array of template paths.
280 * @return An array of translated template paths.
281 * @deprecated Each template engine service should know how to translate
282 * a request onto a file.
283 */
284 @Deprecated
285 String[] translateTemplatePaths(String[] templatePaths);
286
287 /**
288 * Delegates to the appropriate {@link
289 * org.apache.turbine.services.template.TemplateEngineService} to
290 * check the existence of the specified template.
291 *
292 * @param template The template to check for the existence of.
293 * @param templatePaths The paths to check for the template.
294 * @return true if the given template exists
295 * @deprecated Use templateExists from the various Templating Engines
296 */
297 @Deprecated
298 boolean templateExists(String template,
299 String[] templatePaths);
300
301
302 /**
303 * The {@link org.apache.turbine.services.template.TemplateEngineService}
304 * associated with the specified template's file extension.
305 *
306 * @param template The template name.
307 * @return The template engine service.
308 */
309 TemplateEngineService getTemplateEngineService(String template);
310
311 /**
312 * Registers the provided template engine for use by the
313 * <code>TemplateService</code>.
314 *
315 * @param service The <code>TemplateEngineService</code> to register.
316 */
317 void registerTemplateEngineService(TemplateEngineService service);
318 }