View Javadoc

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 }