001package 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
024import org.apache.turbine.pipeline.PipelineData;
025import org.apache.turbine.services.Service;
026
027/**
028 * This service provides a method for mapping templates to their
029 * appropriate Screens or Navigations.  It also allows templates to
030 * define a layout/navigations/screen modularization within the
031 * template structure.  It also performs caching if turned on in the
032 * properties file.
033 *
034 * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
035 * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
036 * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
037 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
038 * @version $Id$
039 */
040public interface TemplateService
041    extends Service
042{
043    /**
044     * The key under which this service is stored in TurbineServices.
045     */
046    String SERVICE_NAME = "TemplateService";
047
048    /** Default Template Name. */
049    String DEFAULT_TEMPLATE_KEY = "default.template";
050
051    /** Default value for the Template Name */
052    String DEFAULT_TEMPLATE_VALUE = "Default";
053
054    /** Default Extension for the template names. */
055    String DEFAULT_EXTENSION_KEY = "default.extension";
056
057    /** Default value of the Turbine Module Caching */
058    String DEFAULT_EXTENSION_VALUE = "";
059
060    /** Character that separates a Template Name from the Extension */
061    char EXTENSION_SEPARATOR = '.';
062
063    /** Character that separates the various Template Parts */
064    char TEMPLATE_PARTS_SEPARATOR = ',';
065
066    /** "Default" name for Classes and Templates */
067    String DEFAULT_NAME = "Default";
068
069    /**
070     * Returns true if the Template Service has caching activated
071     *
072     * @return true if Caching is active.
073     */
074    boolean isCaching();
075
076    /**
077     * Get the default template name extension specified
078     * in the template service properties.
079     *
080     * @return The default the extension.
081     */
082    String getDefaultExtension();
083
084    /**
085     * Return Extension for a supplied template
086     *
087     * @param template The template name
088     *
089     * @return extension The extension for the supplied template
090     */
091    String getExtension(String template);
092
093    /**
094     * Returns the Default Template Name with the Default Extension.
095     * If the extension is unset, return only the template name
096     *
097     * @return The default template Name
098     */
099    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}