    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    }