    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    }