    001package 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
    024import org.apache.turbine.pipeline.PipelineData;
    025import org.apache.turbine.services.Service;
    026
    027/**
    028 * This service provides a method for mapping templates to their
    029 * appropriate Screens or Navigations.  It also allows templates to
    030 * define a layout/navigations/screen modularization within the
    031 * template structure.  It also performs caching if turned on in the
    032 * properties file.
    033 *
    034 * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
    035 * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
    036 * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
    037 * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
    038 * @version $Id: TemplateService.java 1709648 2015-10-20 17:08:10Z tv $
    039 */
    040public interface TemplateService
    041    extends Service
    042{
    043    /**
    044     * The key under which this service is stored in TurbineServices.
    045     */
    046    static final String SERVICE_NAME = "TemplateService";
    047
    048    /** Default Template Name. */
    049    String DEFAULT_TEMPLATE_KEY = "default.template";
    050
    051    /** Default value for the Template Name */
    052    String DEFAULT_TEMPLATE_VALUE = "Default";
    053
    054    /** Default Extension for the template names. */
    055    String DEFAULT_EXTENSION_KEY = "default.extension";
    056
    057    /** Default value of the Turbine Module Caching */
    058    String DEFAULT_EXTENSION_VALUE = "";
    059
    060    /** Character that separates a Template Name from the Extension */
    061    char EXTENSION_SEPARATOR = '.';
    062
    063    /** Character that separates the various Template Parts */
    064    char TEMPLATE_PARTS_SEPARATOR = ',';
    065
    066    /** "Default" name for Classes and Templates */
    067    String DEFAULT_NAME = "Default";
    068
    069    /**
    070     * Returns true if the Template Service has caching activated
    071     *
    072     * @return true if Caching is active.
    073     */
    074    boolean isCaching();
    075
    076    /**
    077     * Get the default template name extension specified
    078     * in the template service properties.
    079     *
    080     * @return The default the extension.
    081     */
    082    String getDefaultExtension();
    083
    084    /**
    085     * Return Extension for a supplied template
    086     *
    087     * @param template The template name
    088     *
    089     * @return extension The extension for the supplied template
    090     */
    091    String getExtension(String template);
    092
    093    /**
    094     * Returns the Default Template Name with the Default Extension.
    095     * If the extension is unset, return only the template name
    096     *
    097     * @return The default template Name
    098     */
    099    String getDefaultTemplate();
    100
    101    /**
    102     * Get the default page module name of the template engine
    103     * service corresponding to the default template name extension.
    104     *
    105     * @return The default page module name.
    106     */
    107    String getDefaultPage();
    108
    109    /**
    110     * Get the default screen module name of the template engine
    111     * service corresponding to the default template name extension.
    112     *
    113     * @return The default screen module name.
    114     */
    115    String getDefaultScreen();
    116
    117    /**
    118     * Get the default layout module name of the template engine
    119     * service corresponding to the default template name extension.
    120     *
    121     * @return The default layout module name.
    122     */
    123    String getDefaultLayout();
    124
    125    /**
    126     * Get the default navigation module name of the template engine
    127     * service corresponding to the default template name extension.
    128     *
    129     * @return The default navigation module name.
    130     */
    131    String getDefaultNavigation();
    132
    133    /**
    134     * Get the default layout template name of the template engine
    135     * service corresponding to the default template name extension.
    136     *
    137     * @return The default layout template name.
    138     */
    139    String getDefaultLayoutTemplate();
    140
    141    /**
    142     * Get the default page module name of the template engine
    143     * service corresponding to the template name extension of
    144     * the named template.
    145     *
    146     * @param template The template name.
    147     * @return The default page module name.
    148     */
    149    String getDefaultPageName(String template);
    150
    151    /**
    152     * Get the default screen module name of the template engine
    153     * service corresponding to the template name extension of
    154     * the named template.
    155     *
    156     * @param template The template name.
    157     * @return The default screen module name.
    158     */
    159    String getDefaultScreenName(String template);
    160
    161    /**
    162     * Get the default layout module name of the template engine
    163     * service corresponding to the template name extension of
    164     * the named template.
    165     *
    166     * @param template The template name.
    167     * @return The default layout module name.
    168     */
    169    String getDefaultLayoutName(String template);
    170
    171    /**
    172     * Get the default navigation module name of the template engine
    173     * service corresponding to the template name extension of
    174     * the named template.
    175     *
    176     * @param template The template name.
    177     * @return The default navigation module name.
    178     */
    179    String getDefaultNavigationName(String template);
    180
    181    /**
    182     * Get the default layout template name of the template engine
    183     * service corresponding to the template name extension of
    184     * the named template.
    185     *
    186     * @param template The template name.
    187     * @return The default layout template name.
    188     */
    189    String getDefaultLayoutTemplateName(String template);
    190
    191    /**
    192     * Find the default page module name for the given request.
    193     *
    194     * @param pipelineData The encapsulation of the request to retrieve the
    195     *             default page for.
    196     * @return The default page module name.
    197     */
    198    String getDefaultPageName(PipelineData pipelineData);
    199
    200    /**
    201     * Find the default layout module name for the given request.
    202     *
    203     * @param pipelineData The encapsulation of the request to retrieve the
    204     *             default layout for.
    205     * @return The default layout module name.
    206     */
    207    String getDefaultLayoutName(PipelineData pipelineData);
    208
    209    /**
    210     * Locate and return the name of the screen module to be used
    211     * with the named screen template.
    212     *
    213     * @param template The screen template name.
    214     * @return The found screen module name.
    215     * @exception Exception, a generic exception.
    216     */
    217    String getScreenName(String template)
    218            throws Exception;
    219
    220    /**
    221     * Locate and return the name of the layout module to be used
    222     * with the named layout template.
    223     *
    224     * @param template The layout template name.
    225     * @return The found layout module name.
    226     * @exception Exception, a generic exception.
    227     */
    228    String getLayoutName(String template)
    229            throws Exception;
    230
    231    /**
    232     * Locate and return the name of the navigation module to be used
    233     * with the named navigation template.
    234     *
    235     * @param template The navigation template name.
    236     * @return The found navigation module name.
    237     * @exception Exception, a generic exception.
    238     */
    239    String getNavigationName(String template)
    240            throws Exception;
    241
    242    /**
    243     * Locate and return the name of the screen template corresponding
    244     * to the given template name parameter.
    245     *
    246     * @param template The template name parameter.
    247     * @return The found screen template name.
    248     * @exception Exception, a generic exception.
    249     */
    250    String getScreenTemplateName(String template)
    251            throws Exception;
    252
    253    /**
    254     * Locate and return the name of the layout template corresponding
    255     * to the given screen template name parameter.
    256     *
    257     * @param template The template name parameter.
    258     * @return The found screen template name.
    259     * @exception Exception, a generic exception.
    260     */
    261    String getLayoutTemplateName(String template)
    262            throws Exception;
    263
    264    /**
    265     * Locate and return the name of the navigation template corresponding
    266     * to the given template name parameter.
    267     *
    268     * @param template The template name parameter.
    269     * @return The found navigation template name.
    270     * @exception Exception, a generic exception.
    271     */
    272    String getNavigationTemplateName(String template)
    273            throws Exception;
    274
    275    /**
    276     * Translates the supplied template paths into their Turbine-canonical
    277     * equivalent (probably absolute paths).
    278     *
    279     * @param templatePaths An array of template paths.
    280     * @return An array of translated template paths.
    281     * @deprecated Each template engine service should know how to translate
    282     *             a request onto a file.
    283     */
    284    @Deprecated
    285    String[] translateTemplatePaths(String[] templatePaths);
    286
    287    /**
    288     * Delegates to the appropriate {@link
    289     * org.apache.turbine.services.template.TemplateEngineService} to
    290     * check the existence of the specified template.
    291     *
    292     * @param template      The template to check for the existence of.
    293     * @param templatePaths The paths to check for the template.
    294     * @return true if the given template exists
    295     * @deprecated Use templateExists from the various Templating Engines
    296     */
    297    @Deprecated
    298    boolean templateExists(String template,
    299                           String[] templatePaths);
    300
    301
    302    /**
    303     * The {@link org.apache.turbine.services.template.TemplateEngineService}
    304     * associated with the specified template's file extension.
    305     *
    306     * @param template The template name.
    307     * @return The template engine service.
    308     */
    309    TemplateEngineService getTemplateEngineService(String template);
    310
    311    /**
    312     * Registers the provided template engine for use by the
    313     * <code>TemplateService</code>.
    314     *
    315     * @param service The <code>TemplateEngineService</code> to register.
    316     */
    317    void registerTemplateEngineService(TemplateEngineService service);
    318}