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 }