TurbineTemplateService (Apache Turbine 4.0.2-SNAPSHOT API)

java.lang.Object
- org.apache.turbine.services.BaseInitable
- - org.apache.turbine.services.BaseService
  - - org.apache.turbine.services.TurbineBaseService
    - - org.apache.turbine.services.template.TurbineTemplateService

All Implemented Interfaces:: Initable, Service, TemplateService

public class TurbineTemplateService
extends TurbineBaseService
implements TemplateService

This service provides a method for mapping templates to their appropriate Screens or Navigations. It also allows templates to define a layout/navigations/screen modularization within the template structure. It also performs caching if turned on in the properties file. This service is not bound to a specific templating engine but we will use the Velocity templating engine for the examples. It is available by using the VelocityService. This assumes the following properties in the Turbine configuration:

 # Register the VelocityService for the "vm" extension.
 services.VelocityService.template.extension=vm

 # Default Java class for rendering a Page in this service
 # (must be found on the class path (org.apache.turbine.modules.page.VelocityPage))
 services.VelocityService.default.page = VelocityPage

 # Default Java class for rendering a Screen in this service
 # (must be found on the class path (org.apache.turbine.modules.screen.VelocityScreen))
 services.VelocityService.default.screen=VelocityScreen

 # Default Java class for rendering a Layout in this service
 # (must be found on the class path (org.apache.turbine.modules.layout.VelocityOnlyLayout))
 services.VelocityService.default.layout = VelocityOnlyLayout

 # Default Java class for rendering a Navigation in this service
 # (must be found on the class path (org.apache.turbine.modules.navigation.VelocityNavigation))
 services.VelocityService.default.navigation=VelocityNavigation

 # Default Template Name to be used as Layout. If nothing else is
 # found, return this as the default name for a layout
 services.VelocityService.default.layout.template = Default.vm

If you want to render a template, a search path is used to find a Java class which might provide information for the context of this template. If you request e.g. the template screen

 about,directions,Driving.vm

then the following class names are searched (on the module search path):

 1. about.directions.Driving     <- direct matching the template to the class name
 2. about.directions.Default     <- matching the package, class name is Default
 3. about.Default                <- stepping up in the package hierarchy, looking for Default
 4. Default                      <- Class called "Default" without package
 5. VelocityScreen               <- The class configured by the Service (VelocityService) to

And if you have the following module packages configured:

 module.packages = org.apache.turbine.modules, com.mycorp.modules

then the class loader will look for

 org.apache.turbine.modules.screens.about.directions.Driving
 com.mycorp.modules.screens.about.directions.Driving
 org.apache.turbine.modules.screens.about.directions.Default
 com.mycorp.modules.screens.about.directions.Default
 org.apache.turbine.modules.screens.about.Default
 com.mycorp.modules.screens.about.Default
 org.apache.turbine.modules.screens.Default
 com.mycorp.modules.screens.Default
 org.apache.turbine.modules.screens.VelocityScreen
 com.mycorp.modules.screens.VelocityScreen

Most of the times, you don't have any backing Java class for a template screen, so the first match will be org.apache.turbine.modules.screens.VelocityScreen which then renders your screen.

Please note, that your Screen Template (Driving.vm) must exist! If it does not exist, the Template Service will report an error.

Once the screen is found, the template service will look for the Layout and Navigation templates of your Screen. Here, the template service looks for matching template names!

Consider our example:

 about,directions,Driving.vm (Screen Name)

Now the template service will look for the following Navigation and Layout templates:

 1. about,directions,Driving.vm      <- exact match
 2. about,directions,Default.vm      <- package match, Default name
 3. about,Default.vm                 <- stepping up in the hierarchy
 4. Default.vm                       <- The name configured as default.layout.template
                                        in the Velocity service.

And now Hennings' two golden rules for using templates:

Many examples and docs from older Turbine code show template pathes with a slashes. Repeat after me: "TEMPLATE NAMES NEVER CONTAIN SLASHES!"

Many examples and docs from older Turbine code show templates that start with "/". This is not only a violation of the rule above but actively breaks things like loading templates from a jar with the velocity jar loader. Repeat after me: "TEMPLATE NAMES ARE NOT PATHES. THEY'RE NOT ABSOLUTE AND HAVE NO LEADING /".

If you now wonder how a template name is mapped to a file name: This is scope of the templating engine. Velocity e.g. has this wonderful option to load templates from jar archives. There is no single file but you tell velocity "get about,directions,Driving.vm" and it returns the rendered template. This is not the job of the Templating Service but of the Template rendering services like VelocityService.

Version:: $Id: TurbineTemplateService.java 1773378 2016-12-09 13:19:59Z tv $
Author:: John D. McNally, Dave Bryson, Jason van Zyl, Daniel Rall, Ilkka Priha, Henning P. Schmiedehausen

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`LAYOUT_KEY` Represents Layout Objects
`static int`	`LAYOUT_TEMPLATE_KEY` Represents Layout Template Objects
`static String`	`LAYOUT_TEMPLATE_NAME` Represents Layout Template Objects
`static int`	`NAVIGATION_KEY` Represents Navigation Objects
`static int`	`NAVIGATION_TEMPLATE_KEY` Represents Navigation Template Objects
`static String`	`NAVIGATION_TEMPLATE_NAME` Represents Navigation Template Objects
`protected static String`	`NO_FILE_EXT` Deprecated. Use TemplateService.DEFAULT_EXTENSION_VALUE.
`static int`	`PAGE_KEY` Represents Page Objects
`static int`	`SCREEN_KEY` Represents Screen Objects
`static int`	`SCREEN_TEMPLATE_KEY` Represents Screen Template Objects
`static String`	`SCREEN_TEMPLATE_NAME` Represents Screen Template Objects
`static int`	`TEMPLATE_TYPES` Number of different Template Types that we know of

Fields inherited from class org.apache.turbine.services.BaseService
configuration, name, serviceBroker

Fields inherited from class org.apache.turbine.services.BaseInitable
initableBroker, isInitialized

Fields inherited from interface org.apache.turbine.services.template.TemplateService
DEFAULT_EXTENSION_KEY, DEFAULT_EXTENSION_VALUE, DEFAULT_NAME, DEFAULT_TEMPLATE_KEY, DEFAULT_TEMPLATE_VALUE, EXTENSION_SEPARATOR, SERVICE_NAME, TEMPLATE_PARTS_SEPARATOR

Constructor Summary

Constructors
Constructor and Description

TurbineTemplateService()
C'tor

Constructors
Constructor and Description
`TurbineTemplateService()` C'tor

Method Summary

Methods
Modifier and Type	Method and Description
`String`	`getDefaultExtension()` Get the default template name extension specified in the template service properties.
`String`	`getDefaultLayout()` Get the default layout module name of the template engine service corresponding to the default template name extension.
`String`	`getDefaultLayoutName(PipelineData pipelineData)` Find the default layout module name for the given request.
`String`	`getDefaultLayoutName(String template)` Get the default layout module name of the template engine service corresponding to the template name extension of the named template.
`String`	`getDefaultLayoutTemplate()` Get the default layout template name of the template engine service corresponding to the default template name extension.
`String`	`getDefaultLayoutTemplateName(String template)` Get the default layout template name of the template engine service corresponding to the template name extension of the named template.
`String`	`getDefaultNavigation()` Get the default navigation module name of the template engine service corresponding to the default template name extension.
`String`	`getDefaultNavigationName(String template)` Get the default navigation module name of the template engine service corresponding to the template name extension of the named template.
`String`	`getDefaultPage()` Get the default page module name of the template engine service corresponding to the default template name extension.
`String`	`getDefaultPageName(PipelineData pipelineData)` Find the default page module name for the given request.
`String`	`getDefaultPageName(String template)` Get the default page module name of the template engine service corresponding to the template name extension of the named template.
`String`	`getDefaultScreen()` Get the default screen module name of the template engine service corresponding to the default template name extension.
`String`	`getDefaultScreenName(String template)` Get the default screen module name of the template engine service corresponding to the template name extension of the named template.
`String`	`getDefaultTemplate()` Returns the Default Template Name with the Default Extension.
`String`	`getExtension(String template)` Return Extension for a supplied template
`String`	`getLayoutName(String template)` Locate and return the name of the layout module to be used with the named layout template.
`String`	`getLayoutTemplateName(String template)` Locate and return the name of the layout template corresponding to the given screen template name parameter.
`String`	`getNavigationName(String template)` Locate and return the name of the navigation module to be used with the named navigation template.
`String`	`getNavigationTemplateName(String template)` Locate and return the name of the navigation template corresponding to the given template name parameter.
`String`	`getScreenName(String template)` Locate and return the name of the screen module to be used with the named screen template.
`String`	`getScreenTemplateName(String template)` Locate and return the name of the screen template corresponding to the given template name parameter.
`TemplateEngineService`	`getTemplateEngineService(String template)` The `TemplateEngineService` associated with the specified template's file extension.
`void`	`init()` Called the first time the Service is used.
`boolean`	`isCaching()` Returns true if the Template Service has caching activated
`void`	`registerTemplateEngineService(TemplateEngineService service)` Registers the provided template engine for use by the `TemplateService`.
`boolean`	`templateExists(String template, String[] templatePaths)` Deprecated. Use templateExists from the various Templating Engines
`String[]`	`translateTemplatePaths(String[] templatePaths)` Deprecated. Each template engine service should know how to translate a request onto a file.

Methods inherited from class org.apache.turbine.services.TurbineBaseService
init, init, shutdown

Methods inherited from class org.apache.turbine.services.BaseService
getConfiguration, getName, getProperties, getServiceBroker, setName, setServiceBroker

Methods inherited from class org.apache.turbine.services.BaseInitable
getInit, getInitableBroker, setInit, setInitableBroker

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.turbine.services.Service
getConfiguration, getName, getProperties, setName, setServiceBroker

Methods inherited from interface org.apache.turbine.services.Initable
getInit, init, setInitableBroker, shutdown

- Field Detail
  - PAGE_KEY
```
public static final int PAGE_KEY
```
    Represents Page Objects
    
    See Also:
    Constant Field Values
  - SCREEN_KEY
```
public static final int SCREEN_KEY
```
    Represents Screen Objects
    
    See Also:
    Constant Field Values
  - LAYOUT_KEY
```
public static final int LAYOUT_KEY
```
    Represents Layout Objects
    
    See Also:
    Constant Field Values
  - NAVIGATION_KEY
```
public static final int NAVIGATION_KEY
```
    Represents Navigation Objects
    
    See Also:
    Constant Field Values
  - LAYOUT_TEMPLATE_KEY
```
public static final int LAYOUT_TEMPLATE_KEY
```
    Represents Layout Template Objects
    
    See Also:
    Constant Field Values
  - LAYOUT_TEMPLATE_NAME
```
public static final String LAYOUT_TEMPLATE_NAME
```
    Represents Layout Template Objects
    
    See Also:
    Constant Field Values
  - SCREEN_TEMPLATE_KEY
```
public static final int SCREEN_TEMPLATE_KEY
```
    Represents Screen Template Objects
    
    See Also:
    Constant Field Values
  - SCREEN_TEMPLATE_NAME
```
public static final String SCREEN_TEMPLATE_NAME
```
    Represents Screen Template Objects
    
    See Also:
    Constant Field Values
  - NAVIGATION_TEMPLATE_KEY
```
public static final int NAVIGATION_TEMPLATE_KEY
```
    Represents Navigation Template Objects
    
    See Also:
    Constant Field Values
  - NAVIGATION_TEMPLATE_NAME
```
public static final String NAVIGATION_TEMPLATE_NAME
```
    Represents Navigation Template Objects
    
    See Also:
    Constant Field Values
  - TEMPLATE_TYPES
```
public static final int TEMPLATE_TYPES
```
    Number of different Template Types that we know of
    
    See Also:
    Constant Field Values
  - NO_FILE_EXT
```
@Deprecated
protected static final String NO_FILE_EXT
```
    Deprecated. Use TemplateService.DEFAULT_EXTENSION_VALUE.
    
    The default file extension used as a registry key when a template's file extension cannot be determined.
    
    See Also:
    Constant Field Values
- Constructor Detail
  - TurbineTemplateService
```
public TurbineTemplateService()
```
    C'tor
- Method Detail
  - init
```
public void init()
          throws InitializationException
```
    Called the first time the Service is used.
    
    Specified by:
    
    init in interface Initable
    
    Overrides:
    
    init in class TurbineBaseService
    
    Throws:
    
    InitializationException - Something went wrong when setting up the Template Service.
  - isCaching
```
public boolean isCaching()
```
    Returns true if the Template Service has caching activated
    
    Specified by:
    
    isCaching in interface TemplateService
    
    Returns:
    true if Caching is active.
  - getDefaultExtension
```
public String getDefaultExtension()
```
    Get the default template name extension specified in the template service properties. If no extension is defined, return the empty string.
    
    Specified by:
    
    getDefaultExtension in interface TemplateService
    
    Returns:
    The default extension.
  - getExtension
```
public String getExtension(String template)
```
    Return Extension for a supplied template
    
    Specified by:
    
    getExtension in interface TemplateService
    
    Parameters:
    template - The template name
    
    Returns:
    extension The extension for the supplied template
  - getDefaultTemplate
```
public String getDefaultTemplate()
```
    Returns the Default Template Name with the Default Extension. If the extension is unset, return only the template name
    
    Specified by:
    
    getDefaultTemplate in interface TemplateService
    
    Returns:
    The default template Name
  - getDefaultPage
```
public String getDefaultPage()
```
    Get the default page module name of the template engine service corresponding to the default template name extension.
    
    Specified by:
    
    getDefaultPage in interface TemplateService
    
    Returns:
    The default page module name.
  - getDefaultScreen
```
public String getDefaultScreen()
```
    Get the default screen module name of the template engine service corresponding to the default template name extension.
    
    Specified by:
    
    getDefaultScreen in interface TemplateService
    
    Returns:
    The default screen module name.
  - getDefaultLayout
```
public String getDefaultLayout()
```
    Get the default layout module name of the template engine service corresponding to the default template name extension.
    
    Specified by:
    
    getDefaultLayout in interface TemplateService
    
    Returns:
    The default layout module name.
  - getDefaultNavigation
```
public String getDefaultNavigation()
```
    Get the default navigation module name of the template engine service corresponding to the default template name extension.
    
    Specified by:
    
    getDefaultNavigation in interface TemplateService
    
    Returns:
    The default navigation module name.
  - getDefaultLayoutTemplate
```
public String getDefaultLayoutTemplate()
```
    Get the default layout template name of the template engine service corresponding to the default template name extension.
    
    Specified by:
    
    getDefaultLayoutTemplate in interface TemplateService
    
    Returns:
    The default layout template name.
  - getDefaultPageName
```
public String getDefaultPageName(String template)
```
    Get the default page module name of the template engine service corresponding to the template name extension of the named template.
    
    Specified by:
    
    getDefaultPageName in interface TemplateService
    
    Parameters:
    template - The template name.
    
    Returns:
    The default page module name.
  - getDefaultScreenName
```
public String getDefaultScreenName(String template)
```
    Get the default screen module name of the template engine service corresponding to the template name extension of the named template.
    
    Specified by:
    
    getDefaultScreenName in interface TemplateService
    
    Parameters:
    template - The template name.
    
    Returns:
    The default screen module name.
  - getDefaultLayoutName
```
public String getDefaultLayoutName(String template)
```
    Get the default layout module name of the template engine service corresponding to the template name extension of the named template.
    
    Specified by:
    
    getDefaultLayoutName in interface TemplateService
    
    Parameters:
    template - The template name.
    
    Returns:
    The default layout module name.
  - getDefaultNavigationName
```
public String getDefaultNavigationName(String template)
```
    Get the default navigation module name of the template engine service corresponding to the template name extension of the named template.
    
    Specified by:
    
    getDefaultNavigationName in interface TemplateService
    
    Parameters:
    template - The template name.
    
    Returns:
    The default navigation module name.
  - getDefaultLayoutTemplateName
```
public String getDefaultLayoutTemplateName(String template)
```
    Get the default layout template name of the template engine service corresponding to the template name extension of the named template.
    
    Specified by:
    
    getDefaultLayoutTemplateName in interface TemplateService
    
    Parameters:
    template - The template name.
    
    Returns:
    The default layout template name.
  - getDefaultPageName
```
public String getDefaultPageName(PipelineData pipelineData)
```
    Find the default page module name for the given request.
    
    Specified by:
    
    getDefaultPageName in interface TemplateService
    
    Parameters:
    pipelineData - The encapsulation of the request to retrieve the default page for.
    
    Returns:
    The default page module name.
  - getDefaultLayoutName
```
public String getDefaultLayoutName(PipelineData pipelineData)
```
    Find the default layout module name for the given request.
    
    Specified by:
    
    getDefaultLayoutName in interface TemplateService
    
    Parameters:
    pipelineData - The encapsulation of the request to retrieve the default layout for.
    
    Returns:
    The default layout module name.
  - getScreenName
```
public String getScreenName(String template)
                     throws Exception
```
    Locate and return the name of the screen module to be used with the named screen template.
    
    Specified by:
    
    getScreenName in interface TemplateService
    
    Parameters:
    template - The screen template name.
    
    Returns:
    The found screen module name.
    
    Throws:
    
    Exception - a generic exception.
  - getLayoutName
```
public String getLayoutName(String template)
                     throws Exception
```
    Locate and return the name of the layout module to be used with the named layout template.
    
    Specified by:
    
    getLayoutName in interface TemplateService
    
    Parameters:
    template - The layout template name.
    
    Returns:
    The found layout module name.
    
    Throws:
    
    Exception - a generic exception.
  - getNavigationName
```
public String getNavigationName(String template)
                         throws Exception
```
    Locate and return the name of the navigation module to be used with the named navigation template.
    
    Specified by:
    
    getNavigationName in interface TemplateService
    
    Parameters:
    template - The navigation template name.
    
    Returns:
    The found navigation module name.
    
    Throws:
    
    Exception - a generic exception.
  - getScreenTemplateName
```
public String getScreenTemplateName(String template)
                             throws Exception
```
    Locate and return the name of the screen template corresponding to the given template name parameter. This might return null if the screen is not found!
    
    Specified by:
    
    getScreenTemplateName in interface TemplateService
    
    Parameters:
    template - The template name parameter.
    
    Returns:
    The found screen template name.
    
    Throws:
    
    Exception - a generic exception.
  - getLayoutTemplateName
```
public String getLayoutTemplateName(String template)
                             throws Exception
```
    Locate and return the name of the layout template corresponding to the given screen template name parameter.
    
    Specified by:
    
    getLayoutTemplateName in interface TemplateService
    
    Parameters:
    template - The template name parameter.
    
    Returns:
    The found screen template name.
    
    Throws:
    
    Exception - a generic exception.
  - getNavigationTemplateName
```
public String getNavigationTemplateName(String template)
                                 throws Exception
```
    Locate and return the name of the navigation template corresponding to the given template name parameter. This might return null if the navigation is not found!
    
    Specified by:
    
    getNavigationTemplateName in interface TemplateService
    
    Parameters:
    template - The template name parameter.
    
    Returns:
    The found navigation template name.
    
    Throws:
    
    Exception - a generic exception.
  - translateTemplatePaths
```
@Deprecated
public String[] translateTemplatePaths(String[] templatePaths)
```
    Deprecated. Each template engine service should know how to translate a request onto a file.
    
    Translates the supplied template paths into their Turbine-canonical equivalent (probably absolute paths). This is used if the templating engine (e.g. JSP) does not provide any means to load a page but the page path is passed to the servlet container.
    
    Specified by:
    
    translateTemplatePaths in interface TemplateService
    
    Parameters:
    templatePaths - An array of template paths.
    
    Returns:
    An array of translated template paths.
  - templateExists
```
@Deprecated
public boolean templateExists(String template,
                                String[] templatePaths)
```
    Deprecated. Use templateExists from the various Templating Engines
    
    Delegates to the appropriate TemplateEngineService to check the existence of the specified template.
    
    Specified by:
    
    templateExists in interface TemplateService
    
    Parameters:
    template - The template to check for the existence of.
    templatePaths - The paths to check for the template.
    
    Returns:
    true if the given template exists
  - registerTemplateEngineService
```
public void registerTemplateEngineService(TemplateEngineService service)
```
    Registers the provided template engine for use by the TemplateService.
    
    Specified by:
    
    registerTemplateEngineService in interface TemplateService
    
    Parameters:
    service - The TemplateEngineService to register.
  - getTemplateEngineService
```
public TemplateEngineService getTemplateEngineService(String template)
```
    The TemplateEngineService associated with the specified template's file extension.
    
    Specified by:
    
    getTemplateEngineService in interface TemplateService
    
    Parameters:
    template - The template name.
    
    Returns:
    The template engine service.

Class TurbineTemplateService

Field Summary

Fields inherited from class org.apache.turbine.services.BaseService

Fields inherited from class org.apache.turbine.services.BaseInitable

Fields inherited from interface org.apache.turbine.services.template.TemplateService

Constructor Summary

Method Summary

Methods inherited from class org.apache.turbine.services.TurbineBaseService

Methods inherited from class org.apache.turbine.services.BaseService

Methods inherited from class org.apache.turbine.services.BaseInitable

Methods inherited from class java.lang.Object

Methods inherited from interface org.apache.turbine.services.Service

Methods inherited from interface org.apache.turbine.services.Initable

Field Detail

PAGE_KEY

SCREEN_KEY

LAYOUT_KEY

NAVIGATION_KEY

LAYOUT_TEMPLATE_KEY

LAYOUT_TEMPLATE_NAME

SCREEN_TEMPLATE_KEY

SCREEN_TEMPLATE_NAME

NAVIGATION_TEMPLATE_KEY

NAVIGATION_TEMPLATE_NAME

TEMPLATE_TYPES

NO_FILE_EXT

Constructor Detail

TurbineTemplateService

Method Detail

init

isCaching

getDefaultExtension

getExtension

getDefaultTemplate

getDefaultPage

getDefaultScreen

getDefaultLayout

getDefaultNavigation

getDefaultLayoutTemplate

getDefaultPageName

getDefaultScreenName

getDefaultLayoutName

getDefaultNavigationName

getDefaultLayoutTemplateName

getDefaultPageName

getDefaultLayoutName

getScreenName

getLayoutName

getNavigationName

getScreenTemplateName

getLayoutTemplateName

getNavigationTemplateName

translateTemplatePaths

templateExists

registerTemplateEngineService

getTemplateEngineService