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