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
    25  import org.apache.ecs.ConcreteElement;
    26
    27  import org.apache.turbine.modules.Screen;
    28  import org.apache.turbine.modules.ScreenLoader;
    29  import org.apache.turbine.pipeline.PipelineData;
    30
    31  import org.apache.turbine.services.assemblerbroker.TurbineAssemblerBroker;
    32  import org.apache.turbine.services.template.TurbineTemplate;
    33
    34  import org.apache.turbine.util.RunData;
    35
    36  /**
    37   * Template Screen.
    38   *
    39   * Base Template Screens should extend this class and override the
    40   * buildTemplate() method.  Users of the particular service can then
    41   * override the doBuildTemplate() for any specific pre-processing.
    42   * You can also override the doBuild() method in order to add extra
    43   * functionality to your system, but you need to make sure to at least
    44   * duplicate the existing functionality in order for things to work.
    45   * Look at the code for the doBuild() method to get an idea of what is
    46   * going on there (it is quite simple really).
    47   *
    48   * @author <a href="mailto:mbryson@mont.mindspring.com">Dave Bryson</a>
    49   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    50   * @author <a href="mailto:peter@courcoux.biz">Peter Courcoux</a>
    51   * @version $Id: TemplateScreen.java 938645 2010-04-27 20:57:51Z tv $
    52   */
    53  public abstract class TemplateScreen
    54      extends Screen
    55  {
    56      /** Logging */
    57      protected Log log = LogFactory.getLog(this.getClass());
    58
    59      private ScreenLoader screenLoader;
    60
    61      /**
    62       * Default constructor
    63       */
    64      public TemplateScreen()
    65      {
    66          super();
    67
    68          this.screenLoader = (ScreenLoader)TurbineAssemblerBroker.getLoader(NAME);
    69      }
    70
    71      /**
    72       * This method should be overidden by subclasses that wish to add
    73       * specific business logic.
    74       *
    75       * @deprecated Use PipelineData version instead.
    76       * @param data Turbine information.
    77       * @exception Exception A generic exception.
    78       */
    79      protected abstract void doBuildTemplate(RunData data)
    80              throws Exception;
    81
    82      /**
    83       * This method should be overidden by subclasses that wish to add
    84       * specific business logic.
    85       * Should revert to abstract when RunData has gone.
    86       * @param data Turbine information.
    87       * @exception Exception A generic exception.
    88       */
    89      protected void doBuildTemplate(PipelineData pipelineData)
    90      throws Exception
    91      {
    92          RunData data = getRunData(pipelineData);
    93          doBuildTemplate(data);
    94      }
    95
    96
    97      /**
    98       * This method should be implemented by Base template classes.  It
    99       * should contain the specific template service code to generate
    100      * the template.
    101      *
    102      * @deprecated Use PipelineData version instead.
    103      * @param data Turbine information.
    104      * @return A ConcreteElement.
    105      * @exception Exception A generic exception.
    106      */
    107     public abstract ConcreteElement buildTemplate(RunData data)
    108             throws Exception;
    109
    110     /**
    111      * This method should be implemented by Base template classes.  It
    112      * should contain the specific template service code to generate
    113      * the template.
    114      * Should revert to abstract when RunData goes.
    115      * @param data Turbine information.
    116      * @return A ConcreteElement.
    117      * @exception Exception A generic exception.
    118      */
    119     public ConcreteElement buildTemplate(PipelineData pipelineData)
    120     throws Exception
    121     {
    122         RunData data = getRunData(pipelineData);
    123         return buildTemplate(data);
    124     }
    125
    126
    127     /**
    128      * This method can be overridden to write code that executes when
    129      * the template has been built (called from a finally clause, so
    130      * executes regardless of whether an exception is thrown or not)
    131      *
    132      * @deprecated Use PipelineData version instead.
    133      */
    134     protected void doPostBuildTemplate(RunData data)
    135     {
    136         // empty
    137     }
    138
    139     /**
    140      * This method can be overridden to write code that executes when
    141      * the template has been built (called from a finally clause, so
    142      * executes regardless of whether an exception is thrown or not)
    143      */
    144     protected void doPostBuildTemplate(PipelineData pipelineData)
    145     {
    146         // empty
    147     }
    148
    149
    150     /**
    151      * This method is called by the Screenloader to construct the
    152      * Screen.
    153      *
    154      * @deprecated Use PipelineData version instead.
    155      * @param data Turbine information.
    156      * @return A ConcreteElement.
    157      * @exception Exception A generic exception.
    158      */
    159     protected ConcreteElement doBuild(RunData data)
    160             throws Exception
    161     {
    162         ConcreteElement out = null;
    163
    164         try
    165         {
    166             doBuildTemplate(data);
    167             out = buildTemplate(data);
    168         }
    169         finally
    170         {
    171             doPostBuildTemplate(data);
    172         }
    173
    174         return out;
    175     }
    176
    177     /**
    178      * This method is called by the Screenloader to construct the
    179      * Screen.
    180      *
    181      * @param data Turbine information.
    182      * @return A ConcreteElement.
    183      * @exception Exception A generic exception.
    184      */
    185     protected ConcreteElement doBuild(PipelineData pipelineData)
    186             throws Exception
    187     {
    188         ConcreteElement out = null;
    189
    190         try
    191         {
    192             doBuildTemplate(pipelineData);
    193             out = buildTemplate(pipelineData);
    194         }
    195         finally
    196         {
    197             doPostBuildTemplate(pipelineData);
    198         }
    199
    200         return out;
    201     }
    202
    203
    204
    205     /**
    206      * This method is used when you want to short circuit a Screen and
    207      * change the template that will be executed next. <b>Note that the current
    208      * context will be applied to the next template that is executed.
    209      * If you want to have the context executed for the next screen,
    210      * to be the same one as the next screen, then you should use the
    211      * TemplateScreen.doRedirect() method.</b>
    212      *
    213      * @deprecated Use PipelineData version instead.
    214      * @param data Turbine information.
    215      * @param template The name of the next template.
    216      */
    217     public static void setTemplate(RunData data, String template)
    218     {
    219         data.getTemplateInfo().setScreenTemplate(template);
    220         try
    221         {
    222             // We have do call getScreenTemplate because of the path
    223             // separator.
    224             data.getTemplateInfo().setLayoutTemplate(
    225                     TurbineTemplate.getLayoutTemplateName(
    226                             data.getTemplateInfo().getScreenTemplate()));
    227         }
    228         catch (Exception e)
    229         {
    230             // Nothing to do.
    231         }
    232     }
    233
    234     /**
    235      * This method is used when you want to short circuit a Screen and
    236      * change the template that will be executed next. <b>Note that the current
    237      * context will be applied to the next template that is executed.
    238      * If you want to have the context executed for the next screen,
    239      * to be the same one as the next screen, then you should use the
    240      * TemplateScreen.doRedirect() method.</b>
    241      *
    242      * @param data Turbine information.
    243      * @param template The name of the next template.
    244      */
    245     public static void setTemplate(PipelineData pipelineData, String template)
    246     {
    247         //Map runDataMap = (Map) pipelineData.get(RunData.class);
    248         //RunData data = (RunData)runDataMap.get(RunData.class);
    249         RunData data = (RunData)pipelineData;
    250         setTemplate(data, template);
    251     }
    252
    253     /**
    254      * You can call this within a Screen to cause an internal redirect
    255      * to happen.  It essentially allows you to stop execution in one
    256      * Screen and instantly execute another Screen.  Don't worry, this
    257      * does not do a HTTP redirect and also if you have anything added
    258      * in the Context, it will get carried over.
    259      *
    260      * <p>
    261      *
    262      * This class is useful if you have a Screen that submits to
    263      * another Screen and you want it to do error validation before
    264      * executing the other Screen.  If there is an error, you can
    265      * doRedirect() back to the original Screen.
    266      *
    267      * @deprecated Use PipelineData version instead.
    268      * @param data Turbine information.
    269      * @param screen Name of screen to redirect to.
    270      * @param template Name of template.
    271      * @exception Exception A generic exception.
    272      */
    273     public void doRedirect(RunData data, String screen, String template)
    274             throws Exception
    275     {
    276         log.debug("doRedirect(data, " + screen + ", " + template + ")");
    277         setTemplate(data, template);
    278         screenLoader.exec(data, screen);
    279     }
    280
    281     /**
    282      * You can call this within a Screen to cause an internal redirect
    283      * to happen.  It essentially allows you to stop execution in one
    284      * Screen and instantly execute another Screen.  Don't worry, this
    285      * does not do a HTTP redirect and also if you have anything added
    286      * in the Context, it will get carried over.
    287      *
    288      * <p>
    289      *
    290      * This class is useful if you have a Screen that submits to
    291      * another Screen and you want it to do error validation before
    292      * executing the other Screen.  If there is an error, you can
    293      * doRedirect() back to the original Screen.
    294      *
    295      * @param data Turbine information.
    296      * @param screen Name of screen to redirect to.
    297      * @param template Name of template.
    298      * @exception Exception A generic exception.
    299      */
    300     public void doRedirect(PipelineData pipelineData, String screen, String template)
    301             throws Exception
    302     {
    303         RunData data = getRunData(pipelineData);
    304         log.debug("doRedirect(data, " + screen + ", " + template + ")");
    305         setTemplate(data, template);
    306         screenLoader.exec(pipelineData, screen);
    307     }
    308
    309
    310     /**
    311      * You can call this within a Screen to cause an internal redirect
    312      * to happen.  It essentially allows you to stop execution in one
    313      * Screen and instantly execute another Screen.  Don't worry, this
    314      * does not do a HTTP redirect and also if you have anything added
    315      * in the Context, it will get carried over.
    316      *
    317      * <p>
    318      *
    319      * This class is useful if you have a Screen that submits to
    320      * another Screen and you want it to do error validation before
    321      * executing the other Screen.  If there is an error, you can
    322      * doRedirect() back to the original Screen.
    323      *
    324      * @deprecated Use PipelineData version instead.
    325      * @param data Turbine information.
    326      * @param template Name of template.
    327      * @exception Exception A generic exception.
    328      */
    329     public void doRedirect(RunData data, String template)
    330             throws Exception
    331     {
    332         doRedirect(data, TurbineTemplate.getScreenName(template), template);
    333     }
    334
    335     /**
    336      * You can call this within a Screen to cause an internal redirect
    337      * to happen.  It essentially allows you to stop execution in one
    338      * Screen and instantly execute another Screen.  Don't worry, this
    339      * does not do a HTTP redirect and also if you have anything added
    340      * in the Context, it will get carried over.
    341      *
    342      * <p>
    343      *
    344      * This class is useful if you have a Screen that submits to
    345      * another Screen and you want it to do error validation before
    346      * executing the other Screen.  If there is an error, you can
    347      * doRedirect() back to the original Screen.
    348      *
    349      * @param data Turbine information.
    350      * @param template Name of template.
    351      * @exception Exception A generic exception.
    352      */
    353     public void doRedirect(PipelineData pipelineData, String template)
    354             throws Exception
    355     {
    356         doRedirect(pipelineData, template);
    357     }
    358
    359
    360 }