Java tutorial
/* * $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; /** * <p>An ActionContext represents a view of a commons-chain * <code>Context</code> which encapsulates access to request and * session-scoped resources and services</p> */ 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(); /** * <p>Return a <code>Map</code> of Application scoped values.</p> * * <p>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.</p> * * <p>The ultimate meaning of "application scope" is an implementation * detail left unspecified by Struts.</p> * * @return A Map of "application scope" attributes. */ Map getApplicationScope(); /** * <p>Return a <code>Map</code> of Session scoped values. A session is * understood as a sequence of requests made by the same user.</p> * * <p>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.</p> * * <p>The ultimate meaning of "session scope" is an implementation detail * left unspecified by Struts.</p> * * @return A Map of "session scope" attributes. */ Map getSessionScope(); /** * <p>Return a <code>Map</code> of request scoped values. A request is * understood as the fundamental motivation for any particular instance of * an <code>ActionContext</code>.</p> * * <p>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.</p> * * <p>The ultimate meaning of "request scope" is an implementation detail * left unspecified by Struts.</p> * * @return a Map of "request scope" attributes. */ Map getRequestScope(); /** * Return the Map representing the scope identified by * <code>scopeName</code>. Implementations should support at minimum the * names associated with the constants <code>APPLICATION_SCOPE</code>, * <code>SESSION_SCOPE</code>, and <code>REQUEST_SCOPE</code>, but are * permitted to support others as well. * * @param scopeName A token identifying a scope, including but not limited * to <code>APPLICATION_SCOPE</code>, <code>SESSION_SCOPE</code>, * <code>REQUEST_SCOPE</code>. * @return A Map of attributes for the specified scope. */ Map getScope(String scopeName); /** * <p>Return a <code>Map</code> of parameters submitted by the user as * part of this request. The keys to this map will be request parameter * names (of type <code>String</code>), and the values will be * <code>String[]</code>.</p> * * <p>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.</p> * * @return A map of the request parameter attributes */ Map getParameterMap(); // ------------------------------- // General Struts properties // ------------------------------- /** * <p> Set the action which has been identified to be executed as part of * processing this request. </p> * * @param action */ void setAction(Action action); /** * <p> Get the action which has been identified to be executed as part of * processing this request. </p> * * @return The action to be executed with this request */ Action getAction(); /** * <p> Set the ActionForm instance which will carry any data submitted as * part of this request. </p> * * @param form The ActionForm instance to use with this request */ void setActionForm(ActionForm form); /** * <p> Get the ActionForm instance which will carry any data submitted as * part of this request. </p> * * @return The ActionForm being used with this request */ ActionForm getActionForm(); /** * <p> Set the ActionConfig class contains the details for processing this * request. </p> * * @param config The ActionConfig class to use with this request */ void setActionConfig(ActionConfig config); /** * <p> Get the ActionConfig which contains the details for processing this * request. * * @return The ActionConfig class being used with this request </p> */ ActionConfig getActionConfig(); /** * <p> 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. </p> * * @param forward The ForwardConfig to use with this request */ void setForwardConfig(ForwardConfig forward); /** * <p> Get the ForwardConfig which has been identified as the basis for * view-processing. </p> * * @return The ForwardConfig being used with this request */ ForwardConfig getForwardConfig(); /** * <p> Set the include path which should be processed as part of * processing this request. </p> * * @param include The include path to be used with this request */ void setInclude(String include); /** * <p> Get the include path which should be processed as part of * processing this request. </p> * * @return The include path being used with this request */ String getInclude(); /** * <p> Set the ModuleConfig which is operative for the current request. * </p> * * @param config The ModuleConfig to be used with this request */ void setModuleConfig(ModuleConfig config); /** * <p> Get the ModuleConfig which is operative for the current request. * </p> * * @return The MooduleConfig being used with this request */ ModuleConfig getModuleConfig(); /** * <p> Is the ActionForm for this context valid? This method <em>does * not</em> 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. </p> * * @return <code>Boolean.TRUE</code> if the form passed validation; * <code>Boolean.FALSE</code> if the form failed validation; null * if the form has not yet been validated */ Boolean getFormValid(); /** * <p> Store the result of the validation of the Context's ActionForm. * </p> * * @param valid Whether the ActionForm for this request passes validation */ void setFormValid(Boolean valid); /** * <p> Retrieve an exception which may have been caught by some code using * this ActionContext, usually by an exception handler. </p> * * @return Any exception that may have been caught by this ActionContext */ Exception getException(); /** * <p> Store an exception in this context for use by other handling code. * </p> * * @param e An exception to be stored for handling by another member */ void setException(Exception e); // ------------------------------- // ActionMessage Processing // ------------------------------- /** * <p> Append the given messages keys to an internal cache, creating the * cache if one is not already present. </p> * * @param messages New ActionMessages to cache */ void addMessages(ActionMessages messages); /** * <p> Append the given errors keys to an internal cache, creating the * cache if one is not already present. </p> * * @param errors New ActionMessages to cache as errors */ void addErrors(ActionMessages errors); /** * <p> Retrieve error messages from an internal cache, creating an empty * cache if one is not already present. </p> * * @return The ActionMessage cache for errors */ ActionMessages getErrors(); /** * <p> Retrieve messages from an internal cache, creating an empty cache * if one is not already present. </p> * * @return The ActionMessage cache for errors */ ActionMessages getMessages(); /** * <p> Save the given error messages to the internal cache, clearing any * previous messages in the cache. </p> <p> If the parameter is null or * empty, the internal cache is removed. </p> * * @param errors ActionMesssages to cache as errors */ void saveErrors(ActionMessages errors); /** * <p> Save the given messages to the internal cache, clearing any * previous messages in the cache. </p> <p> If the parameter is null or * empty, the internal cache is removed. </p> * * @param messages ActionMesssages to cache */ void saveMessages(ActionMessages messages); /** * <p> Save the given messages to the internal cache, clearing any * previous messages in the cache, but only for the specified scope. </p> * <p> If the parameter is null or empty, the internal cache is removed. * </p> * * @param scope The scope for the internal cache * @param messages ActionMesssages to cache */ void saveMessages(String scope, ActionMessages messages); // ------------------------------- // Token Processing // ------------------------------- /** * <p>Generate a new transaction token, to be used for enforcing a single * request for a particular transaction.</p> */ String generateToken(); /** * <p> Indicate whether a transaction token for this context is valid. * </p> <p> 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. </p> */ boolean isTokenValid(); /** * <p> 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. </p> * * @param reset On true, clear the transactional token */ boolean isTokenValid(boolean reset); /** * <p> Clear any transactional token stored in the "session" scope for * this context, so that the next check would return false. </p> */ void resetToken(); /** * <p> Save a new transaction token in the "session" scope for this * context, creating new resources, if needed. </p> */ void saveToken(); // ------------------------------- // Cancel Processing // ------------------------------- /** * <p> Indicate if the "cancel event" state is set for for this context, * </p> * * @see ActionContextBase.CANCEL_KEY */ Boolean getCancelled(); /** * <p> Set the "cancel event" state for this context. </p> <p> * * @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 // ------------------------------- /** * <p>Return the default message resources for the current module.</p> */ MessageResources getMessageResources(); /** * <p>Set the default message resources for the current module.</p> */ void setMessageResources(MessageResources resources); /** * <p>Return the specified message resources for the current module.</p> * * @param key The key specified in the <code><message-resources></code> * element for the requested bundle */ MessageResources getMessageResources(String key); // ------------------------------- // Locale Processing // ------------------------------- /** * <p>Return the user's currently selected Locale.</p> */ Locale getLocale(); /** * <p>Set the user's currently selected <code>Locale</code>.</p> * * @param locale The user's selected Locale to be set, or null to select * the server's default Locale */ void setLocale(Locale locale); }