View Javadoc

    1   package org.apache.turbine.modules.screens;
    2
    3   /*
    4    * Licensed to the Apache Software Foundation (ASF) under one
    5    * or more contributor license agreements.  See the NOTICE file
    6    * distributed with this work for additional information
    7    * regarding copyright ownership.  The ASF licenses this file
    8    * to you under the Apache License, Version 2.0 (the
    9    * "License"); you may not use this file except in compliance
    10   * with the License.  You may obtain a copy of the License at
    11   *
    12   *   http://www.apache.org/licenses/LICENSE-2.0
    13   *
    14   * Unless required by applicable law or agreed to in writing,
    15   * software distributed under the License is distributed on an
    16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    17   * KIND, either express or implied.  See the License for the
    18   * specific language governing permissions and limitations
    19   * under the License.
    20   */
    21
    22  import org.apache.commons.logging.Log;
    23  import org.apache.commons.logging.LogFactory;
    24  import org.apache.turbine.annotation.TurbineLoader;
    25  import org.apache.turbine.annotation.TurbineService;
    26  import org.apache.turbine.modules.Screen;
    27  import org.apache.turbine.modules.ScreenLoader;
    28  import org.apache.turbine.pipeline.PipelineData;
    29  import org.apache.turbine.services.template.TemplateService;
    30  import org.apache.turbine.services.template.TurbineTemplate;
    31  import org.apache.turbine.util.RunData;
    32
    33  /**
    34   * Template Screen.
    35   *
    36   * Base Template Screens should extend this class and override the
    37   * buildTemplate() method.  Users of the particular service can then
    38   * override the doBuildTemplate() for any specific pre-processing.
    39   * You can also override the doBuild() method in order to add extra
    40   * functionality to your system, but you need to make sure to at least
    41   * duplicate the existing functionality in order for things to work.
    42   * Look at the code for the doBuild() method to get an idea of what is
    43   * going on there (it is quite simple really).
    44   *
    45   * @author <a href="mailto:mbryson@mont.mindspring.com">Dave Bryson</a>
    46   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    47   * @author <a href="mailto:peter@courcoux.biz">Peter Courcoux</a>
    48   * @version $Id: TemplateScreen.java 1709648 2015-10-20 17:08:10Z tv $
    49   */
    50  public abstract class TemplateScreen
    51      extends Screen
    52  {
    53      /** Logging */
    54      protected Log log = LogFactory.getLog(this.getClass());
    55
    56      /** Injected service instance */
    57      @TurbineService
    58      private TemplateService templateService;
    59
    60      /** Injected loader instance */
    61      @TurbineLoader( Screen.class )
    62      private ScreenLoader screenLoader;
    63
    64      /**
    65       * This method should be overridden by subclasses that wish to add
    66       * specific business logic.
    67       * @param pipelineData Turbine information.
    68       * @exception Exception A generic exception.
    69       */
    70      protected abstract void doBuildTemplate(PipelineData pipelineData)
    71              throws Exception;
    72
    73      /**
    74       * This method should be implemented by Base template classes.  It
    75       * should contain the specific template service code to generate
    76       * the template.
    77       * @param pipelineData Turbine information.
    78       * @return the content of the screen
    79       * @exception Exception A generic exception.
    80       */
    81      public abstract String buildTemplate(PipelineData pipelineData)
    82              throws Exception;
    83
    84      /**
    85       * This method can be overridden to write code that executes when
    86       * the template has been built (called from a finally clause, so
    87       * executes regardless of whether an exception is thrown or not)
    88       */
    89      protected void doPostBuildTemplate(PipelineData pipelineData)
    90      {
    91          // empty
    92      }
    93
    94      /**
    95       * This method is called by the Screenloader to construct the
    96       * Screen.
    97       *
    98       * @param pipelineData Turbine information.
    99       * @return the content of the screen
    100      * @exception Exception A generic exception.
    101      */
    102     @Override
    103     protected String doBuild(PipelineData pipelineData)
    104             throws Exception
    105     {
    106         String out = null;
    107
    108         try
    109         {
    110             doBuildTemplate(pipelineData);
    111             out = buildTemplate(pipelineData);
    112         }
    113         finally
    114         {
    115             doPostBuildTemplate(pipelineData);
    116         }
    117
    118         return out;
    119     }
    120
    121     /**
    122      * This method is used when you want to short circuit a Screen and
    123      * change the template that will be executed next. <b>Note that the current
    124      * context will be applied to the next template that is executed.
    125      * If you want to have the context executed for the next screen,
    126      * to be the same one as the next screen, then you should use the
    127      * TemplateScreen.doRedirect() method.</b>
    128      *
    129      * @param pipelineData Turbine information.
    130      * @param template The name of the next template.
    131      */
    132     public static void setTemplate(PipelineData pipelineData, String template)
    133     {
    134         RunData data = (RunData)pipelineData;
    135         data.getTemplateInfo().setScreenTemplate(template);
    136         try
    137         {
    138             // We have do call getScreenTemplate because of the path
    139             // separator.
    140             data.getTemplateInfo().setLayoutTemplate(
    141                     TurbineTemplate.getLayoutTemplateName(
    142                             data.getTemplateInfo().getScreenTemplate()));
    143         }
    144         catch (Exception e)
    145         {
    146             // Nothing to do.
    147         }
    148     }
    149
    150     /**
    151      * You can call this within a Screen to cause an internal redirect
    152      * to happen.  It essentially allows you to stop execution in one
    153      * Screen and instantly execute another Screen.  Don't worry, this
    154      * does not do a HTTP redirect and also if you have anything added
    155      * in the Context, it will get carried over.
    156      *
    157      * <p>
    158      *
    159      * This class is useful if you have a Screen that submits to
    160      * another Screen and you want it to do error validation before
    161      * executing the other Screen.  If there is an error, you can
    162      * doRedirect() back to the original Screen.
    163      *
    164      * @param pipelineData Turbine information.
    165      * @param screen Name of screen to redirect to.
    166      * @param template Name of template.
    167      * @exception Exception A generic exception.
    168      */
    169     public void doRedirect(PipelineData pipelineData, String screen, String template)
    170             throws Exception
    171     {
    172         log.debug("doRedirect(data, " + screen + ", " + template + ")");
    173         setTemplate(pipelineData, template);
    174         screenLoader.exec(pipelineData, screen);
    175     }
    176
    177     /**
    178      * You can call this within a Screen to cause an internal redirect
    179      * to happen.  It essentially allows you to stop execution in one
    180      * Screen and instantly execute another Screen.  Don't worry, this
    181      * does not do a HTTP redirect and also if you have anything added
    182      * in the Context, it will get carried over.
    183      *
    184      * <p>
    185      *
    186      * This class is useful if you have a Screen that submits to
    187      * another Screen and you want it to do error validation before
    188      * executing the other Screen.  If there is an error, you can
    189      * doRedirect() back to the original Screen.
    190      *
    191      * @param pipelineData Turbine information.
    192      * @param template Name of template.
    193      * @exception Exception A generic exception.
    194      */
    195     public void doRedirect(PipelineData pipelineData, String template)
    196             throws Exception
    197     {
    198         doRedirect(pipelineData, templateService.getScreenName(template), template);
    199     }
    200 }