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:
030: import org.apache.turbine.services.template.TurbineTemplate;
031:
032: import org.apache.turbine.util.RunData;
033:
034: /**
035: * Template Screen.
036: *
037: * Base Template Screens should extend this class and override the
038: * buildTemplate() method. Users of the particular service can then
039: * override the doBuildTemplate() for any specific pre-processing.
040: * You can also override the doBuild() method in order to add extra
041: * functionality to your system, but you need to make sure to at least
042: * duplicate the existing functionality in order for things to work.
043: * Look at the code for the doBuild() method to get an idea of what is
044: * going on there (it is quite simple really).
045: *
046: * @author <a href="mailto:mbryson@mont.mindspring.com">Dave Bryson</a>
047: * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
048: * @version $Id: TemplateScreen.java 534527 2007-05-02 16:10:59Z tv $
049: */
050: public abstract class TemplateScreen extends Screen {
051: /** Logging */
052: protected Log log = LogFactory.getLog(this .getClass());
053:
054: /**
055: * This method should be overidden by subclasses that wish to add
056: * specific business logic.
057: *
058: * @param data Turbine information.
059: * @exception Exception A generic exception.
060: */
061: protected abstract void doBuildTemplate(RunData data)
062: throws Exception;
063:
064: /**
065: * This method should be implemented by Base template classes. It
066: * should contain the specific template service code to generate
067: * the template.
068: *
069: * @param data Turbine information.
070: * @return A ConcreteElement.
071: * @exception Exception A generic exception.
072: */
073: public abstract ConcreteElement buildTemplate(RunData data)
074: throws Exception;
075:
076: /**
077: * This method can be overridden to write code that executes when
078: * the template has been built (called from a finally clause, so
079: * executes regardless of whether an exception is thrown or not)
080: */
081: protected void doPostBuildTemplate(RunData data) {
082: // empty
083: }
084:
085: /**
086: * This method is called by the Screenloader to construct the
087: * Screen.
088: *
089: * @param data Turbine information.
090: * @return A ConcreteElement.
091: * @exception Exception A generic exception.
092: */
093: protected ConcreteElement doBuild(RunData data) throws Exception {
094: ConcreteElement out = null;
095:
096: try {
097: doBuildTemplate(data);
098: out = buildTemplate(data);
099: } finally {
100: doPostBuildTemplate(data);
101: }
102:
103: return out;
104: }
105:
106: /**
107: * This method is used when you want to short circuit a Screen and
108: * change the template that will be executed next. <b>Note that the current
109: * context will be applied to the next template that is executed.
110: * If you want to have the context executed for the next screen,
111: * to be the same one as the next screen, then you should use the
112: * TemplateScreen.doRedirect() method.</b>
113: *
114: * @param data Turbine information.
115: * @param template The name of the next template.
116: */
117: public static void setTemplate(RunData data, String template) {
118: data.getTemplateInfo().setScreenTemplate(template);
119: try {
120: // We have do call getScreenTemplate because of the path
121: // separator.
122: data.getTemplateInfo().setLayoutTemplate(
123: TurbineTemplate.getLayoutTemplateName(data
124: .getTemplateInfo().getScreenTemplate()));
125: } catch (Exception e) {
126: // Nothing to do.
127: }
128: }
129:
130: /**
131: * You can call this within a Screen to cause an internal redirect
132: * to happen. It essentially allows you to stop execution in one
133: * Screen and instantly execute another Screen. Don't worry, this
134: * does not do a HTTP redirect and also if you have anything added
135: * in the Context, it will get carried over.
136: *
137: * <p>
138: *
139: * This class is useful if you have a Screen that submits to
140: * another Screen and you want it to do error validation before
141: * executing the other Screen. If there is an error, you can
142: * doRedirect() back to the original Screen.
143: *
144: * @param data Turbine information.
145: * @param screen Name of screen to redirect to.
146: * @param template Name of template.
147: * @exception Exception A generic exception.
148: */
149: public void doRedirect(RunData data, String screen, String template)
150: throws Exception {
151: log.debug("doRedirect(data, " + screen + ", " + template + ")");
152: setTemplate(data, template);
153: ScreenLoader.getInstance().exec(data, screen);
154: }
155:
156: /**
157: * You can call this within a Screen to cause an internal redirect
158: * to happen. It essentially allows you to stop execution in one
159: * Screen and instantly execute another Screen. Don't worry, this
160: * does not do a HTTP redirect and also if you have anything added
161: * in the Context, it will get carried over.
162: *
163: * <p>
164: *
165: * This class is useful if you have a Screen that submits to
166: * another Screen and you want it to do error validation before
167: * executing the other Screen. If there is an error, you can
168: * doRedirect() back to the original Screen.
169: *
170: * @param data Turbine information.
171: * @param template Name of template.
172: * @exception Exception A generic exception.
173: */
174: public void doRedirect(RunData data, String template)
175: throws Exception {
176: doRedirect(data, TurbineTemplate.getScreenName(template),
177: template);
178: }
179: }
|