View Javadoc

    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.pipeline.PipelineData;
    25  import org.apache.turbine.services.Service;
    26
    27  /**
    28   * This service provides a method for mapping templates to their
    29   * appropriate Screens or Navigations.  It also allows templates to
    30   * define a layout/navigations/screen modularization within the
    31   * template structure.  It also performs caching if turned on in the
    32   * properties file.
    33   *
    34   * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
    35   * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
    36   * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
    37   * @author <a href="mailto:ilkka.priha@simsoft.fi">Ilkka Priha</a>
    38   * @version $Id: TemplateService.java 1709648 2015-10-20 17:08:10Z tv $
    39   */
    40  public interface TemplateService
    41      extends Service
    42  {
    43      /**
    44       * The key under which this service is stored in TurbineServices.
    45       */
    46      static final String SERVICE_NAME = "TemplateService";
    47
    48      /** Default Template Name. */
    49      String DEFAULT_TEMPLATE_KEY = "default.template";
    50
    51      /** Default value for the Template Name */
    52      String DEFAULT_TEMPLATE_VALUE = "Default";
    53
    54      /** Default Extension for the template names. */
    55      String DEFAULT_EXTENSION_KEY = "default.extension";
    56
    57      /** Default value of the Turbine Module Caching */
    58      String DEFAULT_EXTENSION_VALUE = "";
    59
    60      /** Character that separates a Template Name from the Extension */
    61      char EXTENSION_SEPARATOR = '.';
    62
    63      /** Character that separates the various Template Parts */
    64      char TEMPLATE_PARTS_SEPARATOR = ',';
    65
    66      /** "Default" name for Classes and Templates */
    67      String DEFAULT_NAME = "Default";
    68
    69      /**
    70       * Returns true if the Template Service has caching activated
    71       *
    72       * @return true if Caching is active.
    73       */
    74      boolean isCaching();
    75
    76      /**
    77       * Get the default template name extension specified
    78       * in the template service properties.
    79       *
    80       * @return The default the extension.
    81       */
    82      String getDefaultExtension();
    83
    84      /**
    85       * Return Extension for a supplied template
    86       *
    87       * @param template The template name
    88       *
    89       * @return extension The extension for the supplied template
    90       */
    91      String getExtension(String template);
    92
    93      /**
    94       * Returns the Default Template Name with the Default Extension.
    95       * If the extension is unset, return only the template name
    96       *
    97       * @return The default template Name
    98       */
    99      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 }