View Javadoc

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