001 package org.apache.turbine.modules.screens;
002
003 /*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements. See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership. The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License. You may obtain a copy of the License at
011 *
012 * http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied. See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022 import org.apache.commons.logging.Log;
023 import org.apache.commons.logging.LogFactory;
024
025 import org.apache.ecs.ConcreteElement;
026
027 import org.apache.turbine.modules.Screen;
028 import org.apache.turbine.modules.ScreenLoader;
029 import org.apache.turbine.pipeline.PipelineData;
030
031 import org.apache.turbine.services.assemblerbroker.TurbineAssemblerBroker;
032 import org.apache.turbine.services.template.TurbineTemplate;
033
034 import org.apache.turbine.util.RunData;
035
036 /**
037 * Template Screen.
038 *
039 * Base Template Screens should extend this class and override the
040 * buildTemplate() method. Users of the particular service can then
041 * override the doBuildTemplate() for any specific pre-processing.
042 * You can also override the doBuild() method in order to add extra
043 * functionality to your system, but you need to make sure to at least
044 * duplicate the existing functionality in order for things to work.
045 * Look at the code for the doBuild() method to get an idea of what is
046 * going on there (it is quite simple really).
047 *
048 * @author <a href="mailto:mbryson@mont.mindspring.com">Dave Bryson</a>
049 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
050 * @author <a href="mailto:peter@courcoux.biz">Peter Courcoux</a>
051 * @version $Id: TemplateScreen.java 938645 2010-04-27 20:57:51Z tv $
052 */
053 public abstract class TemplateScreen
054 extends Screen
055 {
056 /** Logging */
057 protected Log log = LogFactory.getLog(this.getClass());
058
059 private ScreenLoader screenLoader;
060
061 /**
062 * Default constructor
063 */
064 public TemplateScreen()
065 {
066 super();
067
068 this.screenLoader = (ScreenLoader)TurbineAssemblerBroker.getLoader(NAME);
069 }
070
071 /**
072 * This method should be overidden by subclasses that wish to add
073 * specific business logic.
074 *
075 * @deprecated Use PipelineData version instead.
076 * @param data Turbine information.
077 * @exception Exception A generic exception.
078 */
079 protected abstract void doBuildTemplate(RunData data)
080 throws Exception;
081
082 /**
083 * This method should be overidden by subclasses that wish to add
084 * specific business logic.
085 * Should revert to abstract when RunData has gone.
086 * @param data Turbine information.
087 * @exception Exception A generic exception.
088 */
089 protected void doBuildTemplate(PipelineData pipelineData)
090 throws Exception
091 {
092 RunData data = getRunData(pipelineData);
093 doBuildTemplate(data);
094 }
095
096
097 /**
098 * This method should be implemented by Base template classes. It
099 * 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 }