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 }