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