001 package org.apache.turbine.services.template;
002
003
004 /*
005 * Licensed to the Apache Software Foundation (ASF) under one
006 * or more contributor license agreements. See the NOTICE file
007 * distributed with this work for additional information
008 * regarding copyright ownership. The ASF licenses this file
009 * to you under the Apache License, Version 2.0 (the
010 * "License"); you may not use this file except in compliance
011 * with the License. You may obtain a copy of the License at
012 *
013 * http://www.apache.org/licenses/LICENSE-2.0
014 *
015 * Unless required by applicable law or agreed to in writing,
016 * software distributed under the License is distributed on an
017 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
018 * KIND, either express or implied. See the License for the
019 * specific language governing permissions and limitations
020 * under the License.
021 */
022
023
024 import org.apache.turbine.services.Service;
025
026 import org.apache.turbine.util.RunData;
027
028 /**
029 * This service provides a method for mapping templates to their
030 * appropriate Screens or Navigations. It also allows templates to
031 * define a layout/navigations/screen modularization within the
032 * template structure. It also performs caching if turned on in the
033 * properties file.
034 *
035 * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
036 * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
037 * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
038 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
039 * @version $Id: TemplateService.java 615328 2008-01-25 20:25:05Z tv $
040 */
041 public interface TemplateService
042 extends Service
043 {
044 /**
045 * The key under which this service is stored in TurbineServices.
046 */
047 static final String SERVICE_NAME = "TemplateService";
048
049 /** Default Template Name. */
050 String DEFAULT_TEMPLATE_KEY = "default.template";
051
052 /** Default value for the Template Name */
053 String DEFAULT_TEMPLATE_VALUE = "Default";
054
055 /** Default Extension for the template names. */
056 String DEFAULT_EXTENSION_KEY = "default.extension";
057
058 /** Default value of the Turbine Module Caching */
059 String DEFAULT_EXTENSION_VALUE = "";
060
061 /** Character that separates a Template Name from the Extension */
062 char EXTENSION_SEPARATOR = '.';
063
064 /** Character that separates the various Template Parts */
065 char TEMPLATE_PARTS_SEPARATOR = ',';
066
067 /** "Default" name for Classes and Templates */
068 String DEFAULT_NAME = "Default";
069
070 /**
071 * Returns true if the Template Service has caching activated
072 *
073 * @return true if Caching is active.
074 */
075 boolean isCaching();
076
077 /**
078 * Get the default template name extension specified
079 * in the template service properties.
080 *
081 * @return The default the extension.
082 */
083 String getDefaultExtension();
084
085 /**
086 * Return Extension for a supplied template
087 *
088 * @param template The template name
089 *
090 * @return extension The extension for the supplied template
091 */
092 String getExtension(String template);
093
094 /**
095 * Returns the Default Template Name with the Default Extension.
096 * If the extension is unset, return only the template name
097 *
098 * @return The default template Name
099 */
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 }