org.apache.struts.chain.contexts.ActionContext Maven / Gradle / Ivy
/*
* $Id: ActionContext.java 471754 2006-11-06 14:55:09Z husted $
*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.struts.chain.contexts;
import org.apache.commons.chain.Context;
import org.apache.struts.action.Action;
import org.apache.struts.action.ActionForm;
import org.apache.struts.action.ActionMessages;
import org.apache.struts.config.ActionConfig;
import org.apache.struts.config.ForwardConfig;
import org.apache.struts.config.ModuleConfig;
import org.apache.struts.util.MessageResources;
import java.util.Locale;
import java.util.Map;
/**
* An ActionContext represents a view of a commons-chain
* Context which encapsulates access to request and
* session-scoped resources and services
*/
public interface ActionContext extends Context {
public static final String APPLICATION_SCOPE = "application";
public static final String SESSION_SCOPE = "session";
public static final String REQUEST_SCOPE = "request";
// -------------------------------
// General Application Support
// -------------------------------
/**
* Signal to the instance that it will not be used any more, so that any
* resources which should be cleaned up can be cleaned up.
*/
void release();
/**
* Return a Map of Application scoped values.
*
* This is implemented in analogy with the Application scope in the
* Servlet API, but it seems reasonable to expect that any Struts
* implementation will have an equivalent concept.
*
* The ultimate meaning of "application scope" is an implementation
* detail left unspecified by Struts.
*
* @return A Map of "application scope" attributes.
*/
Map getApplicationScope();
/**
* Return a Map of Session scoped values. A session is
* understood as a sequence of requests made by the same user.
*
* This is implemented in analogy with the Session scope in the Servlet
* API, but it seems reasonable to expect that any Struts implementation
* will have an equivalent concept.
*
* The ultimate meaning of "session scope" is an implementation detail
* left unspecified by Struts.
*
* @return A Map of "session scope" attributes.
*/
Map getSessionScope();
/**
* Return a Map of request scoped values. A request is
* understood as the fundamental motivation for any particular instance of
* an ActionContext.
*
* This is implemented in analogy with the Request Context in the
* Servlet API, but it seems reasonable to expect that any Struts
* implementation will have an equivalent concept.
*
* The ultimate meaning of "request scope" is an implementation detail
* left unspecified by Struts.
*
* @return a Map of "request scope" attributes.
*/
Map getRequestScope();
/**
* Return the Map representing the scope identified by
* scopeName. Implementations should support at minimum the
* names associated with the constants APPLICATION_SCOPE,
* SESSION_SCOPE, and REQUEST_SCOPE, but are
* permitted to support others as well.
*
* @param scopeName A token identifying a scope, including but not limited
* to APPLICATION_SCOPE, SESSION_SCOPE,
* REQUEST_SCOPE.
* @return A Map of attributes for the specified scope.
*/
Map getScope(String scopeName);
/**
* Return a Map of parameters submitted by the user as
* part of this request. The keys to this map will be request parameter
* names (of type String), and the values will be
* String[].
*
* This is implemented in analogy with the Request parameters of the
* Servlet API, but it seems reasonable to expect that any Struts
* implementation will have an equivalent concept.
*
* @return A map of the request parameter attributes
*/
Map getParameterMap();
// -------------------------------
// General Struts properties
// -------------------------------
/**
* Set the action which has been identified to be executed as part of
* processing this request.
*
* @param action
*/
void setAction(Action action);
/**
* Get the action which has been identified to be executed as part of
* processing this request.
*
* @return The action to be executed with this request
*/
Action getAction();
/**
* Set the ActionForm instance which will carry any data submitted as
* part of this request.
*
* @param form The ActionForm instance to use with this request
*/
void setActionForm(ActionForm form);
/**
* Get the ActionForm instance which will carry any data submitted as
* part of this request.
*
* @return The ActionForm being used with this request
*/
ActionForm getActionForm();
/**
* Set the ActionConfig class contains the details for processing this
* request.
*
* @param config The ActionConfig class to use with this request
*/
void setActionConfig(ActionConfig config);
/**
* Get the ActionConfig which contains the details for processing this
* request.
*
* @return The ActionConfig class being used with this request
*/
ActionConfig getActionConfig();
/**
* Set the ForwardConfig which should be used as the basis of the view
* segment of the overall processing. This is the primary method of
* "communication" with the "view" sub-chain.
*
* @param forward The ForwardConfig to use with this request
*/
void setForwardConfig(ForwardConfig forward);
/**
* Get the ForwardConfig which has been identified as the basis for
* view-processing.
*
* @return The ForwardConfig being used with this request
*/
ForwardConfig getForwardConfig();
/**
* Set the include path which should be processed as part of
* processing this request.
*
* @param include The include path to be used with this request
*/
void setInclude(String include);
/**
* Get the include path which should be processed as part of
* processing this request.
*
* @return The include path being used with this request
*/
String getInclude();
/**
* Set the ModuleConfig which is operative for the current request.
*
*
* @param config The ModuleConfig to be used with this request
*/
void setModuleConfig(ModuleConfig config);
/**
* Get the ModuleConfig which is operative for the current request.
*
*
* @return The MooduleConfig being used with this request
*/
ModuleConfig getModuleConfig();
/**
* Is the ActionForm for this context valid? This method does
* not actually perform form validation. It is simply a holder
* property where processes which perform validation can store the results
* of the validation for other processes' benefit.
*
* @return Boolean.TRUE if the form passed validation;
* Boolean.FALSE if the form failed validation; null
* if the form has not yet been validated
*/
Boolean getFormValid();
/**
* Store the result of the validation of the Context's ActionForm.
*
*
* @param valid Whether the ActionForm for this request passes validation
*/
void setFormValid(Boolean valid);
/**
* Retrieve an exception which may have been caught by some code using
* this ActionContext, usually by an exception handler.
*
* @return Any exception that may have been caught by this ActionContext
*/
Exception getException();
/**
* Store an exception in this context for use by other handling code.
*
*
* @param e An exception to be stored for handling by another member
*/
void setException(Exception e);
// -------------------------------
// ActionMessage Processing
// -------------------------------
/**
* Append the given messages keys to an internal cache, creating the
* cache if one is not already present.
*
* @param messages New ActionMessages to cache
*/
void addMessages(ActionMessages messages);
/**
* Append the given errors keys to an internal cache, creating the
* cache if one is not already present.
*
* @param errors New ActionMessages to cache as errors
*/
void addErrors(ActionMessages errors);
/**
* Retrieve error messages from an internal cache, creating an empty
* cache if one is not already present.
*
* @return The ActionMessage cache for errors
*/
ActionMessages getErrors();
/**
* Retrieve messages from an internal cache, creating an empty cache
* if one is not already present.
*
* @return The ActionMessage cache for errors
*/
ActionMessages getMessages();
/**
* Save the given error messages to the internal cache, clearing any
* previous messages in the cache.
If the parameter is null or
* empty, the internal cache is removed.
*
* @param errors ActionMesssages to cache as errors
*/
void saveErrors(ActionMessages errors);
/**
* Save the given messages to the internal cache, clearing any
* previous messages in the cache.
If the parameter is null or
* empty, the internal cache is removed.
*
* @param messages ActionMesssages to cache
*/
void saveMessages(ActionMessages messages);
/**
* Save the given messages to the internal cache, clearing any
* previous messages in the cache, but only for the specified scope.
* If the parameter is null or empty, the internal cache is removed.
*
*
* @param scope The scope for the internal cache
* @param messages ActionMesssages to cache
*/
void saveMessages(String scope, ActionMessages messages);
// -------------------------------
// Token Processing
// -------------------------------
/**
* Generate a new transaction token, to be used for enforcing a single
* request for a particular transaction.
*/
String generateToken();
/**
* Indicate whether a transaction token for this context is valid.
*
A typical implementation will place a transaction token in the
* session" scope Map and a matching value in the "parameter" Map. If the
* "session" token does not match the "parameter" attribute, or the
* session token is missing, then the transactional token is deemed
* invalid.
*/
boolean isTokenValid();
/**
* Indicate whether a transaction token is stored in the "session"
* scope for this context, optionally clearing the token, so that the next
* check would return false.
*
* @param reset On true, clear the transactional token
*/
boolean isTokenValid(boolean reset);
/**
* Clear any transactional token stored in the "session" scope for
* this context, so that the next check would return false.
*/
void resetToken();
/**
* Save a new transaction token in the "session" scope for this
* context, creating new resources, if needed.
*/
void saveToken();
// -------------------------------
// Cancel Processing
// -------------------------------
/**
* Indicate if the "cancel event" state is set for for this context,
*
*
* @see ActionContextBase.CANCEL_KEY
*/
Boolean getCancelled();
/**
* Set the "cancel event" state for this context.
*
* @param cancelled On true, set the cancel event state to true. On false,
* set the cancel event state to false.
* @see ActionContextBase.CANCEL_KEY
*/
void setCancelled(Boolean cancelled);
// -------------------------------
// MessageResources Processing
// -------------------------------
/**
*
Return the default message resources for the current module.
*/
MessageResources getMessageResources();
/**
* Set the default message resources for the current module.
*/
void setMessageResources(MessageResources resources);
/**
* Return the specified message resources for the current module.
*
* @param key The key specified in the <message-resources>
* element for the requested bundle
*/
MessageResources getMessageResources(String key);
// -------------------------------
// Locale Processing
// -------------------------------
/**
* Return the user's currently selected Locale.
*/
Locale getLocale();
/**
* Set the user's currently selected Locale.
*
* @param locale The user's selected Locale to be set, or null to select
* the server's default Locale
*/
void setLocale(Locale locale);
}