/*
* $Header: /home/cvs/jakarta-struts/src/share/org/apache/struts/action/Action.java,v 1.61 2003/06/28 06:16:34 dgraham Exp $
* $Revision: 1.61 $
* $Date: 2003/06/28 06:16:34 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
* Copyright (c) 1999-2003 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Struts", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* perform
method.
Actions must be programmed in a thread-safe manner, because the * controller will share the same instance for multiple simultaneous * requests. This means you should design with the following items in mind: *
*When an Action
instance is first created, the controller
* servlet will call setServlet()
with a non-null argument to
* identify the controller servlet instance to which this Action is attached.
* When the controller servlet is to be shut down (or restarted), the
* setServlet()
method will be called with a null
* argument, which can be used to clean up any allocated resources in use
* by this Action.
ActionServlet
* instance will be stored.
* @deprecated Use Globals.ACTION_SERVLET_KEY instead.
* @since Struts 1.1
*/
public static final String ACTION_SERVLET_KEY = Globals.ACTION_SERVLET_KEY;
/**
* The base of the context attributes key under which our
* ModuleConfig
data structure will be stored. This
* will be suffixed with the actual module prefix (including the
* leading "/" character) to form the actual attributes key.
For each request processed by the controller servlet, the
* ModuleConfig
object for the module selected by
* the request URI currently being processed will also be exposed under
* this key as a request attribute.
javax.sql.DataSource
) is stored,
* if one is configured for this module.
* @deprecated Replaced by {@link org.apache.struts.Globals#DATA_SOURCE_KEY}
*/
public static final String DATA_SOURCE_KEY = Globals.DATA_SOURCE_KEY;
/**
* The request attributes key under which your action should store an
* org.apache.struts.action.ActionErrors
object, if you
* are using the corresponding custom tag library elements.
* @deprecated Replaced by {@link org.apache.struts.Globals#ERROR_KEY}
*/
public static final String ERROR_KEY = Globals.ERROR_KEY;
/**
* The request attributes key under which Struts custom tags might store a
* Throwable
that caused them to report a JspException at
* runtime. This value can be used on an error page to provide more
* detailed information about what really went wrong.
* @deprecated Replaced by {@link org.apache.struts.Globals#EXCEPTION_KEY}
*/
public static final String EXCEPTION_KEY = Globals.EXCEPTION_KEY;
/**
* The context attributes key under which our
* org.apache.struts.action.ActionFormBeans
collection
* is normally stored, unless overridden when initializing our
* ActionServlet.
*
* @deprecated Replaced by collection in ModuleConfig
*/
public static final String FORM_BEANS_KEY = Globals.FORM_BEANS_KEY;
/**
* The context attributes key under which our
* org.apache.struts.action.ActionForwards
collection
* is normally stored, unless overridden when initializing our
* ActionServlet.
*
* @deprecated Replaced by collection in ModuleConfig.
*/
public static final String FORWARDS_KEY = Globals.FORWARDS_KEY;
/**
* The session attributes key under which the user's selected
* java.util.Locale
is stored, if any. If no such
* attribute is found, the system default locale
* will be used when retrieving internationalized messages. If used, this
* attribute is typically set during user login processing.
* @deprecated Replaced by {@link org.apache.struts.Globals#LOCALE_KEY}
*/
public static final String LOCALE_KEY = Globals.LOCALE_KEY;
/**
* The request attributes key under which our
* org.apache.struts.ActionMapping
instance
* is passed.
* @deprecated Replaced by {@link org.apache.struts.Globals#MAPPING_KEY}
*/
public static final String MAPPING_KEY = Globals.MAPPING_KEY;
/**
* The context attributes key under which our
* org.apache.struts.action.ActionMappings
collection
* is normally stored, unless overridden when initializing our
* ActionServlet.
*
* @deprecated Replaced by collection in ModuleConfig
*/
public static final String MAPPINGS_KEY = Globals.MAPPINGS_KEY;
/**
* The request attributes key under which your action should store an
* org.apache.struts.action.ActionMessages
object, if you
* are using the corresponding custom tag library elements.
*
* @since Struts 1.1
* @deprecated Replaced by {@link org.apache.struts.Globals#MESSAGE_KEY}
*/
public static final String MESSAGE_KEY = Globals.MESSAGE_KEY;
/**
* The base of the context attributes key under which our
* module MessageResources
will be stored. This
* will be suffixed with the actual module prefix (including the
* leading "/" character) to form the actual resources key.
For each request processed by the controller servlet, the
* MessageResources
object for the module selected by
* the request URI currently being processed will also be exposed under
* this key as a request attribute.
The base of the context attributes key under which an array of
* PlugIn
instances will be stored. This
* will be suffixed with the actual module prefix (including the
* leading "/" character) to form the actual attributes key.
The base of the context attributes key under which our
* RequestProcessor
instance will be stored. This
* will be suffixed with the actual module prefix (including the
* leading "/" character) to form the actual attributes key.
/action/*
) or an extension mapped pattern
* (*.do
).
* @deprecated Use Globals.SERVLET_KEY instead.
*/
public static final String SERVLET_KEY = Globals.SERVLET_KEY;
/**
* The session attributes key under which our transaction token is
* stored, if it is used.
* @deprecated Use Globals.TRANSACTION_TOKEN_KEY instead.
*/
public static final String TRANSACTION_TOKEN_KEY =
Globals.TRANSACTION_TOKEN_KEY;
/**
* An instance of TokenProcessor to use for token functionality.
* @TODO We can make this variable protected and remove Action's token methods
* or leave it private and allow the token methods to delegate their calls.
*/
private static TokenProcessor token = TokenProcessor.getInstance();
// ----------------------------------------------------- Instance Variables
/**
* The system default Locale.
*/
protected static Locale defaultLocale = Locale.getDefault();
/**
* The controller servlet to which we are attached.
*/
protected ActionServlet servlet = null;
// ------------------------------------------------------------- Properties
/**
* Return the controller servlet instance to which we are attached.
*/
public ActionServlet getServlet() {
return (this.servlet);
}
/**
* Set the controller servlet instance to which we are attached (if
* servlet
is non-null), or release any allocated resources
* (if servlet
is null).
*
* @param servlet The new controller servlet, if any
*/
public void setServlet(ActionServlet servlet) {
this.servlet = servlet;
}
// --------------------------------------------------------- Public Methods
/**
* Process the specified non-HTTP request, and create the
* corresponding non-HTTP response (or forward to another web
* component that will create it), with provision for handling
* exceptions thrown by the business logic.
* Return an {@link ActionForward} instance describing where and how
* control should be forwarded, or null
if the response has
* already been completed.
*
* The default implementation attempts to forward to the HTTP
* version of this method.
*
* @param mapping The ActionMapping used to select this instance
* @param form The optional ActionForm bean for this request (if any)
* @param request The non-HTTP request we are processing
* @param response The non-HTTP response we are creating
*
* @exception Exception if the application business logic throws
* an exception
* @since Struts 1.1
*/
public ActionForward execute(ActionMapping mapping,
ActionForm form,
ServletRequest request,
ServletResponse response)
throws Exception {
// Call the deprecated method for backwards compatibility
return (perform(mapping, form, request, response));
}
/**
* Process the specified HTTP request, and create the corresponding HTTP
* response (or forward to another web component that will create it),
* with provision for handling exceptions thrown by the business logic.
* Return an {@link ActionForward} instance describing where and how
* control should be forwarded, or null
if the response
* has already been completed.
*
* @param mapping The ActionMapping used to select this instance
* @param form The optional ActionForm bean for this request (if any)
* @param request The HTTP request we are processing
* @param response The HTTP response we are creating
*
* @exception Exception if the application business logic throws
* an exception
* @since Struts 1.1
*/
public ActionForward execute(ActionMapping mapping,
ActionForm form,
HttpServletRequest request,
HttpServletResponse response)
throws Exception {
// Call the deprecated method for backwards compatibility
return (perform(mapping, form, request, response));
}
/**
* Process the specified non-HTTP request, and create the corresponding
* non-HTTP response (or forward to another web component that will create
* it). Return an ActionForward
instance describing where
* and how control should be forwarded, or null
if the
* response has already been completed.
*
* The default implementation attempts to forward to the HTTP version of
* this method.
*
* @param mapping The ActionMapping used to select this instance
* @param form The optional ActionForm bean for this request (if any)
* @param request The non-HTTP request we are processing
* @param response The non-HTTP response we are creating
*
* @exception IOException if an input/output error occurs
* @exception ServletException if a servlet exception occurs
*
* @deprecated Use the execute()
method instead
*/
public ActionForward perform(ActionMapping mapping,
ActionForm form,
ServletRequest request,
ServletResponse response)
throws IOException, ServletException {
try {
return (perform(mapping, form,
(HttpServletRequest) request,
(HttpServletResponse) response));
} catch (ClassCastException e) {
return (null);
}
}
/**
* Process the specified HTTP request, and create the corresponding HTTP
* response (or forward to another web component that will create it).
* Return an ActionForward
instance describing where and how
* control should be forwarded, or null
if the response has
* already been completed.
*
* @param mapping The ActionMapping used to select this instance
* @param form The optional ActionForm bean for this request (if any)
* @param request The HTTP request we are processing
* @param response The HTTP response we are creating
*
* @exception IOException if an input/output error occurs
* @exception ServletException if a servlet exception occurs
*
* @deprecated Use the execute()
method instead
*/
public ActionForward perform(ActionMapping mapping,
ActionForm form,
HttpServletRequest request,
HttpServletResponse response)
throws IOException, ServletException {
return (null); // Override this method to provide functionality
}
// ---------------------------------------------------- Protected Methods
/**
* Generate a new transaction token, to be used for enforcing a single
* request for a particular transaction.
*
* @param request The request we are processing
*/
protected String generateToken(HttpServletRequest request) {
return token.generateToken(request);
}
/**
* Return the default data source for the current module.
*
* @param request The servlet request we are processing
*
* @since Struts 1.1
*/
protected DataSource getDataSource(HttpServletRequest request) {
return (getDataSource(request, Globals.DATA_SOURCE_KEY));
}
/**
* Return the specified data source for the current module.
*
* @param request The servlet request we are processing
* @param key The key specified in the
* <message-resources>
element for the
* requested bundle
*
* @since Struts 1.1
*/
protected DataSource getDataSource(HttpServletRequest request, String key) {
// Identify the current module
ServletContext context = getServlet().getServletContext();
ModuleConfig moduleConfig = RequestUtils.getModuleConfig(request,context);
// Return the requested data source instance
return ((DataSource) context.getAttribute(key + moduleConfig.getPrefix()));
}
/**
* Return the user's currently selected Locale.
*
* @param request The request we are processing
*/
protected Locale getLocale(HttpServletRequest request) {
HttpSession session = request.getSession();
Locale locale = (Locale) session.getAttribute(Globals.LOCALE_KEY);
if (locale == null) {
locale = defaultLocale;
}
return (locale);
}
/**
* Return the message resources for the default module.
*
* @deprecated This method can only return the resources for the default
* module. Use getResources(HttpServletRequest) to get the
* resources for the current module.
*/
protected MessageResources getResources() {
return ((MessageResources)
servlet.getServletContext().getAttribute(Globals.MESSAGES_KEY));
}
/**
* Return the default message resources for the current module.
*
* @param request The servlet request we are processing
* @since Struts 1.1
*/
protected MessageResources getResources(HttpServletRequest request) {
return ((MessageResources) request.getAttribute(Globals.MESSAGES_KEY));
}
/**
* Return the specified message resources for the current module.
*
* @param request The servlet request we are processing
* @param key The key specified in the
* <message-resources>
element for the
* requested bundle
*
* @since Struts 1.1
*/
protected MessageResources getResources(HttpServletRequest request,
String key) {
// Identify the current module
ServletContext context = getServlet().getServletContext();
ModuleConfig moduleConfig = RequestUtils.getModuleConfig(request,context);
// Return the requested message resources instance
return ((MessageResources) context.getAttribute
(key + moduleConfig.getPrefix()));
}
/**
*
Returns true
if the current form's cancel button was
* pressed. This method will check if the Globals.CANCEL_KEY
* request attribute has been set, which normally occurs if the cancel
* button generated by CancelTag was pressed by the user
* in the current request. If true
, validation performed
* by an ActionForm's validate()
method
* will have been skipped by the controller servlet.
true
if there is a transaction token stored in
* the user's current session, and the value submitted as a request
* parameter with this action matches it. Returns false
* under any of the following circumstances:
* true
if there is a transaction token stored in
* the user's current session, and the value submitted as a request
* parameter with this action matches it. Returns false
*