001    package org.apache.turbine.modules.actions;
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.turbine.modules.screens.TemplateScreen;
023    import org.apache.turbine.pipeline.PipelineData;
024    import org.apache.turbine.services.velocity.TurbineVelocity;
025    import org.apache.turbine.util.RunData;
026    import org.apache.turbine.util.velocity.VelocityActionEvent;
027    import org.apache.velocity.context.Context;
028    
029    /**
030     * This class provides a convenience methods for Velocity Actions to use. Since
031     * this class is abstract, it should only be extended and not used directly.
032     * 
033     * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
034     * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
035     * @author <a href="mailto:peter@courcoux.biz">Peter Courcoux</a>
036     * @version $Id: VelocityAction.java 1066529 2011-02-02 17:01:46Z ludwig $
037     */
038    public abstract class VelocityAction extends VelocityActionEvent
039    {
040        /**
041         * You SHOULD NOT override this method and implement it in your action.
042         * 
043         * @deprecated Use PipelineData version instead.
044         * @param data Turbine information.
045         * @throws Exception a generic exception.
046         */
047        @Override
048        @Deprecated
049        public void doPerform(RunData data) throws Exception
050        {
051            doPerform(data, getContext(data));
052        }
053    
054        /**
055         * You SHOULD NOT override this method and implement it in your action.
056         * 
057         * @param data Turbine information.
058         * @throws Exception a generic exception.
059         */
060        @Override
061        public void doPerform(PipelineData pipelineData) throws Exception
062        {
063            doPerform(pipelineData, getContext(pipelineData));
064        }
065    
066        /**
067         * Initialize the module.
068         * 
069         * @throws Exception a generic exception.
070         */
071        @Override
072        public void initialize() throws Exception
073        {
074            initialized = true;
075        }
076    
077        /**
078         * You SHOULD override this method and implement it in your action.
079         * 
080         * @deprecated Use PipelineData version instead.
081         * @param data Turbine information.
082         * @param context Context for web pages.
083         * @throws Exception a generic exception.
084         */
085        @Deprecated
086        public abstract void doPerform(RunData data, Context context)
087                throws Exception;
088    
089        /**
090         * You SHOULD override this method and implement it in your action.
091         * 
092         * This should become abstract when the RunData version is removed. For
093         * compatibility reasons this method will default to using the RunData
094         * method unles it is overidden, which it should be.
095         * 
096         * @param data Turbine information.
097         * @param context Context for web pages.
098         * @throws Exception a generic exception.
099         */
100        public void doPerform(PipelineData pipelineData, Context context)
101                throws Exception
102        {
103            RunData data = getRunData(pipelineData);
104            doPerform(data, context);
105        }
106    
107        /**
108         * Sets up the context and then calls super.perform(); thus, subclasses
109         * don't have to worry about getting a context themselves! If a subclass
110         * throws an exception then depending on whether
111         * action.event.bubbleexception is true, then it bubbles it farther up, or
112         * traps it there.
113         * 
114         * @deprecated Use PipelineData version instead.
115         * @param data Turbine information.
116         * @throws Exception a generic exception.
117         */
118        @Deprecated
119        @Override
120        protected void perform(RunData data) throws Exception
121        {
122            try
123            {
124                super.perform(data);
125            } catch (Exception e)
126            {
127                if (bubbleUpException)
128                {
129                    throw e;
130                }
131    
132            }
133        }
134    
135        /**
136         * Sets up the context and then calls super.perform(); thus, subclasses
137         * don't have to worry about getting a context themselves! If a subclass
138         * throws an exception then depending on whether
139         * action.event.bubbleexception is true, then it bubbles it farther up, or
140         * traps it there.
141         * 
142         * @param data Turbine information.
143         * @throws Exception a generic exception.
144         */
145        @Override
146        protected void perform(PipelineData pipelineData) throws Exception
147        {
148            try
149            {
150                super.perform(pipelineData);
151            } catch (Exception e)
152            {
153                if (bubbleUpException)
154                {
155                    throw e;
156                }
157    
158            }
159        }
160    
161        /**
162         * This method is used when you want to short circuit an Action and change
163         * the template that will be executed next.
164         * 
165         * @deprecated Use PipelineData version instead.
166         * @param data Turbine information.
167         * @param template The template that will be executed next.
168         */
169        @Deprecated
170        public void setTemplate(RunData data, String template)
171        {
172            TemplateScreen.setTemplate(data, template);
173        }
174    
175        /**
176         * This method is used when you want to short circuit an Action and change
177         * the template that will be executed next.
178         * 
179         * @param data Turbine information.
180         * @param template The template that will be executed next.
181         */
182        public void setTemplate(PipelineData pipelineData, String template)
183        {
184            TemplateScreen.setTemplate(pipelineData, template);
185        }
186    
187        /**
188         * Return the Context needed by Velocity.
189         * 
190         * @deprecated Use PipelineData version instead.
191         * @param data Turbine information.
192         * @return Context, a context for web pages.
193         */
194        @Deprecated
195        protected Context getContext(RunData data)
196        {
197            return TurbineVelocity.getContext(data);
198        }
199    
200        /**
201         * Return the Context needed by Velocity.
202         * 
203         * @param data Turbine information.
204         * @return Context, a context for web pages.
205         */
206        protected Context getContext(PipelineData pipelineData)
207        {
208            return TurbineVelocity.getContext(pipelineData);
209        }
210    
211    }