View Javadoc

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