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    }