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 }