org.apache.struts2.dispatcher

## Class Dispatcher

- java.lang.Object
- - org.apache.struts2.dispatcher.Dispatcher

-     public class Dispatcher
      extends Object

  A utility class the actual dispatcher delegates most of its tasks to. Each instance of the primary dispatcher holds an instance of this dispatcher to be shared for all requests.
  See Also:
    `InitOperations`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Dispatcher.Locator` Provide an accessor class for static XWork utility.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected ConfigurationManager` | `configurationManager` Store ConfigurationManager instance, set on init.
    `protected Map<String,String>` | `initParams`
    `static String` | `MULTIPART_FORM_DATA_REGEX`
    `static String` | `REQUEST_POST_METHOD` `HttpServletRequest.getMethod()`
    `protected javax.servlet.ServletContext` | `servletContext` Keeps current reference to external world and must be protected to support class inheritance

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Dispatcher(javax.servlet.ServletContext servletContext, Map<String,String> initParams)` Create the Dispatcher instance for a given ServletContext and set of initialization parameters.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `addDispatcherListener(DispatcherListener listener)` Add a dispatcher lifecycle listener.
    `void` | `cleanup()` Releases all instances bound to this dispatcher instance.
    `void` | `cleanUpAfterInit()` Cleanup any resources used to initialise Dispatcher
    `void` | `cleanUpRequest(javax.servlet.http.HttpServletRequest request)` Removes all the files created by MultiPartRequestWrapper.
    `static void` | `clearInstance()` Removes the dispatcher instance for this thread.
    `protected ActionProxy` | `createActionProxy(String namespace, String name, String method, Map<String,Object> extraContext)`
    `protected ConfigurationManager` | `createConfigurationManager(String name)`
    `Map<String,Object>` | `createContextMap(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, ActionMapping mapping)` Create a context map containing all the wrapped request objects
    `Map<String,Object>` | `createContextMap(Map<String,Object> requestMap, HttpParameters parameters, Map<String,Object> sessionMap, Map<String,Object> applicationMap, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Merge all application and servlet attributes into a single `HashMap` to represent the entire `Action` context.
    `protected StrutsJavaConfigurationProvider` | `createJavaConfigurationProvider(StrutsJavaConfiguration config)`
    `protected XmlConfigurationProvider` | `createStrutsXmlConfigurationProvider(String filename, boolean errorIfMissing, javax.servlet.ServletContext ctx)` Deprecated. since 6.2.0, use `createStrutsXmlConfigurationProvider(String, ServletContext)`
    `protected XmlConfigurationProvider` | `createStrutsXmlConfigurationProvider(String filename, javax.servlet.ServletContext ctx)`
    `List<Pattern>` | `getActionExcludedPatterns()`
    `ActionMapper` | `getActionMapper()`
    `ActionProxyFactory` | `getActionProxyFactory()`
    `ConfigurationManager` | `getConfigurationManager()` Expose the ConfigurationManager instance.
    `Container` | `getContainer()` Exposes a thread-cached reference of the dependency injection container.
    `static Dispatcher` | `getInstance()` Provide the dispatcher instance for the current thread.
    `static Dispatcher` | `getInstance(javax.servlet.ServletContext servletContext)`
    `protected Locale` | `getLocale(javax.servlet.http.HttpServletRequest request)`
    `protected MultiPartRequest` | `getMultiPartRequest()` On each request it must return a new instance as implementation could be not thread safe and thus ensure of resource clean up
    `protected String` | `getSaveDir()` Return the path to save uploaded files to (this is configurable).
    `StaticContentLoader` | `getStaticContentLoader()`
    `ValueStackFactory` | `getValueStackFactory()`
    `void` | `init()` Load configurations, including both XML and zero-configuration strategies, and update optional settings, including whether to reload configurations and resource files.
    `boolean` | `isDevMode()`
    `boolean` | `isHandleException()`
    `protected boolean` | `isMultipartRequest(javax.servlet.http.HttpServletRequest request)` Checks if request is a multipart request (a file upload request)
    `protected boolean` | `isMultipartSupportEnabled(javax.servlet.http.HttpServletRequest request)` Checks if support to parse multipart requests is enabled
    `protected boolean` | `isSameAction(ActionProxy actionProxy, String namespace, String actionName, String method)`
    `protected void` | `logConfigurationException(javax.servlet.http.HttpServletRequest request, ConfigurationException e)` Performs logging of missing action/result configuration exception
    `void` | `prepare(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Prepare a request, including setting the encoding and locale.
    `protected ActionProxy` | `prepareActionProxy(Map<String,Object> extraContext, String actionNamespace, String actionName, String actionMethod)`
    `static void` | `removeDispatcherListener(DispatcherListener listener)` Remove a specific dispatcher lifecycle listener.
    `void` | `sendError(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, int code, Exception e)` Send an HTTP error response code.
    `void` | `serviceAction(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, ActionMapping mapping)` Load Action class for mapping and invoke the appropriate Action method, or go directly to the Result.
    `void` | `setActionExcludedPatterns(String excludedPatterns)`
    `void` | `setActionExcludedPatternsSeparator(String separator)`
    `void` | `setActionMapper(ActionMapper actionMapper)`
    `void` | `setActionProxyFactory(ActionProxyFactory actionProxyFactory)`
    `void` | `setDefaultEncoding(String val)` Modify state of StrutsConstants.STRUTS_I18N_ENCODING setting.
    `void` | `setDefaultLocale(String val)` Modify state of StrutsConstants.STRUTS_LOCALE setting.
    `void` | `setDevMode(String mode)` Modify state of StrutsConstants.STRUTS_DEVMODE setting.
    `void` | `setDisableRequestAttributeValueStackLookup(String disableRequestAttributeValueStackLookup)` Modify state of StrutsConstants.DISABLE_REQUEST_ATTRIBUTE_VALUE_STACK_LOOKUP setting.
    `void` | `setDispatcherErrorHandler(DispatcherErrorHandler errorHandler)`
    `void` | `setDispatchersParametersWorkaround(String dispatchersParametersWorkaround)`
    `void` | `setHandleException(String handleException)`
    `static void` | `setInstance(Dispatcher instance)` Store the dispatcher instance for this thread.
    `void` | `setLocaleProviderFactory(LocaleProviderFactory localeProviderFactory)`
    `void` | `setMultipartHandler(String val)` Deprecated. since 6.4.0, no replacement.
    `void` | `setMultipartSaveDir(String val)` Modify state of StrutsConstants.STRUTS_MULTIPART_SAVEDIR setting.
    `void` | `setMultipartSupportEnabled(String multipartSupportEnabled)`
    `void` | `setMultipartValidationRegex(String multipartValidationRegex)`
    `void` | `setObjectFactory(ObjectFactory objectFactory)`
    `void` | `setStaticContentLoader(StaticContentLoader staticContentLoader)`
    `void` | `setThreadAllowlist(ThreadAllowlist threadAllowlist)`
    `void` | `setValueStackFactory(ValueStackFactory valueStackFactory)`
    `javax.servlet.http.HttpServletRequest` | `wrapRequest(javax.servlet.http.HttpServletRequest request)` Wrap and return the given request or return the original request object.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### REQUEST_POST_METHOD

          public static final String REQUEST_POST_METHOD

      `HttpServletRequest.getMethod()`
      See Also:
        Constant Field Values

    - #### MULTIPART_FORM_DATA_REGEX

          public static final String MULTIPART_FORM_DATA_REGEX

      See Also:
        Constant Field Values

    - #### configurationManager

          protected ConfigurationManager configurationManager

      Store ConfigurationManager instance, set on init.

    - #### servletContext

          protected javax.servlet.ServletContext servletContext

      Keeps current reference to external world and must be protected to support class inheritance

    - #### initParams

          protected Map<String,String> initParams

  - ### Constructor Detail

    - #### Dispatcher

          public Dispatcher(javax.servlet.ServletContext servletContext,
                            Map<String,String> initParams)

      Create the Dispatcher instance for a given ServletContext and set of initialization parameters.
      Parameters:
        `servletContext` - Our servlet context
        `initParams` - The set of initialization parameters

  - ### Method Detail

    - #### getInstance

          public static Dispatcher getInstance()

      Provide the dispatcher instance for the current thread.
      Returns:
        The dispatcher instance

    - #### setInstance

          public static void setInstance(Dispatcher instance)

      Store the dispatcher instance for this thread.
      Parameters:
        `instance` - The instance

    - #### clearInstance

          public static void clearInstance()

      Removes the dispatcher instance for this thread.

    - #### addDispatcherListener

          public static void addDispatcherListener(DispatcherListener listener)

      Add a dispatcher lifecycle listener.
      Parameters:
        `listener` - The listener to add

    - #### removeDispatcherListener

          public static void removeDispatcherListener(DispatcherListener listener)

      Remove a specific dispatcher lifecycle listener.
      Parameters:
        `listener` - The listener

    - #### getInstance

          public static Dispatcher getInstance(javax.servlet.ServletContext servletContext)

    - #### setDevMode

          public void setDevMode(String mode)

      Modify state of StrutsConstants.STRUTS_DEVMODE setting.
      Parameters:
        `mode` - New setting

    - #### isDevMode

          public boolean isDevMode()

    - #### setDisableRequestAttributeValueStackLookup

          public void setDisableRequestAttributeValueStackLookup(String disableRequestAttributeValueStackLookup)

      Modify state of StrutsConstants.DISABLE_REQUEST_ATTRIBUTE_VALUE_STACK_LOOKUP setting.
      Parameters:
        `disableRequestAttributeValueStackLookup` - New setting

    - #### setDefaultLocale

          public void setDefaultLocale(String val)

      Modify state of StrutsConstants.STRUTS_LOCALE setting.
      Parameters:
        `val` - New setting

    - #### setDefaultEncoding

          public void setDefaultEncoding(String val)

      Modify state of StrutsConstants.STRUTS_I18N_ENCODING setting.
      Parameters:
        `val` - New setting

    - #### setMultipartSaveDir

          public void setMultipartSaveDir(String val)

      Modify state of StrutsConstants.STRUTS_MULTIPART_SAVEDIR setting.
      Parameters:
        `val` - New setting

    - #### setMultipartHandler

          @Deprecated
          public void setMultipartHandler(String val)

      Deprecated. since 6.4.0, no replacement.

    - #### setMultipartSupportEnabled

          public void setMultipartSupportEnabled(String multipartSupportEnabled)

    - #### setMultipartValidationRegex

          public void setMultipartValidationRegex(String multipartValidationRegex)

    - #### setActionExcludedPatternsSeparator

          public void setActionExcludedPatternsSeparator(String separator)

    - #### setActionExcludedPatterns

          public void setActionExcludedPatterns(String excludedPatterns)

    - #### getActionExcludedPatterns

          public List<Pattern> getActionExcludedPatterns()

    - #### setValueStackFactory

          public void setValueStackFactory(ValueStackFactory valueStackFactory)

    - #### getValueStackFactory

          public ValueStackFactory getValueStackFactory()

    - #### setHandleException

          public void setHandleException(String handleException)

    - #### setDispatchersParametersWorkaround

          public void setDispatchersParametersWorkaround(String dispatchersParametersWorkaround)

    - #### isHandleException

          public boolean isHandleException()

    - #### setDispatcherErrorHandler

          public void setDispatcherErrorHandler(DispatcherErrorHandler errorHandler)

    - #### setObjectFactory

          public void setObjectFactory(ObjectFactory objectFactory)

    - #### setActionProxyFactory

          public void setActionProxyFactory(ActionProxyFactory actionProxyFactory)

    - #### getActionProxyFactory

          public ActionProxyFactory getActionProxyFactory()

    - #### setLocaleProviderFactory

          public void setLocaleProviderFactory(LocaleProviderFactory localeProviderFactory)

    - #### setStaticContentLoader

          public void setStaticContentLoader(StaticContentLoader staticContentLoader)

    - #### getStaticContentLoader

          public StaticContentLoader getStaticContentLoader()

    - #### setActionMapper

          public void setActionMapper(ActionMapper actionMapper)

    - #### getActionMapper

          public ActionMapper getActionMapper()

    - #### setThreadAllowlist

          public void setThreadAllowlist(ThreadAllowlist threadAllowlist)

    - #### cleanup

          public void cleanup()

      Releases all instances bound to this dispatcher instance.

    - #### createStrutsXmlConfigurationProvider

          protected XmlConfigurationProvider createStrutsXmlConfigurationProvider(String filename,
                                                                                  javax.servlet.ServletContext ctx)

    - #### createStrutsXmlConfigurationProvider

          @Deprecated
          protected XmlConfigurationProvider createStrutsXmlConfigurationProvider(String filename,
                                                                                              boolean errorIfMissing,
                                                                                              javax.servlet.ServletContext ctx)

      Deprecated. since 6.2.0, use `createStrutsXmlConfigurationProvider(String, ServletContext)`

    - #### createJavaConfigurationProvider

          protected StrutsJavaConfigurationProvider createJavaConfigurationProvider(StrutsJavaConfiguration config)

    - #### init

          public void init()

      Load configurations, including both XML and zero-configuration strategies, and update optional settings, including whether to reload configurations and resource files.

    - #### createConfigurationManager

          protected ConfigurationManager createConfigurationManager(String name)

    - #### serviceAction

          public void serviceAction(javax.servlet.http.HttpServletRequest request,
                                    javax.servlet.http.HttpServletResponse response,
                                    ActionMapping mapping)
                             throws javax.servlet.ServletException

      Load Action class for mapping and invoke the appropriate Action method, or go directly to the Result.

      This method first creates the action context from the given parameters, and then loads an `ActionProxy` from the given action name and namespace. After that, the Action method is executed and output channels through the response object. Actions not found are sent back to the user via the `sendError(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, int, java.lang.Exception)` method, using the 404 return code. All other errors are reported by throwing a ServletException.

      Parameters:
        `request` - the HttpServletRequest object
        `response` - the HttpServletResponse object
        `mapping` - the action mapping object
      Throws:
        `javax.servlet.ServletException` - when an unknown error occurs (not a 404, but typically something that would end up as a 5xx by the servlet container)
      Since:
        2.3.17

    - #### prepareActionProxy

          protected ActionProxy prepareActionProxy(Map<String,Object> extraContext,
                                                   String actionNamespace,
                                                   String actionName,
                                                   String actionMethod)

    - #### createActionProxy

          protected ActionProxy createActionProxy(String namespace,
                                                  String name,
                                                  String method,
                                                  Map<String,Object> extraContext)

    - #### isSameAction

          protected boolean isSameAction(ActionProxy actionProxy,
                                         String namespace,
                                         String actionName,
                                         String method)

    - #### logConfigurationException

          protected void logConfigurationException(javax.servlet.http.HttpServletRequest request,
                                                   ConfigurationException e)

      Performs logging of missing action/result configuration exception
      Parameters:
        `request` - current `HttpServletRequest`
        `e` - `ConfigurationException` that occurred

    - #### createContextMap

          public Map<String,Object> createContextMap(javax.servlet.http.HttpServletRequest request,
                                                     javax.servlet.http.HttpServletResponse response,
                                                     ActionMapping mapping)

      Create a context map containing all the wrapped request objects
      Parameters:
        `request` - The servlet request
        `response` - The servlet response
        `mapping` - The action mapping
      Returns:
        A map of context objects
      Since:
        2.3.17

    - #### createContextMap

          public Map<String,Object> createContextMap(Map<String,Object> requestMap,
                                                     HttpParameters parameters,
                                                     Map<String,Object> sessionMap,
                                                     Map<String,Object> applicationMap,
                                                     javax.servlet.http.HttpServletRequest request,
                                                     javax.servlet.http.HttpServletResponse response)

      Merge all application and servlet attributes into a single `HashMap` to represent the entire `Action` context.
      Parameters:
        `requestMap` - a Map of all request attributes.
        `parameters` - an Object of all request parameters.
        `sessionMap` - a Map of all session attributes.
        `applicationMap` - a Map of all servlet context attributes.
        `request` - the HttpServletRequest object.
        `response` - the HttpServletResponse object.
      Returns:
        a HashMap representing the `Action` context.
      Since:
        2.3.17

    - #### getLocale

          protected Locale getLocale(javax.servlet.http.HttpServletRequest request)

    - #### getSaveDir

          protected String getSaveDir()

      Return the path to save uploaded files to (this is configurable).
      Returns:
        the path to save uploaded files to

    - #### prepare

          public void prepare(javax.servlet.http.HttpServletRequest request,
                              javax.servlet.http.HttpServletResponse response)

      Prepare a request, including setting the encoding and locale.
      Parameters:
        `request` - The request
        `response` - The response

    - #### wrapRequest

          public javax.servlet.http.HttpServletRequest wrapRequest(javax.servlet.http.HttpServletRequest request)
                                                            throws IOException

      Wrap and return the given request or return the original request object.

      This method transparently handles multipart data as a wrapped class around the given request. Override this method to handle multipart requests in a special way or to handle other types of requests. Note, `MultiPartRequestWrapper` is flexible - look first to that object before overriding this method to handle multipart data.

      Parameters:
        `request` - the HttpServletRequest object.
      Returns:
        a wrapped request or original request.
      Throws:
        `IOException` - on any error.
      Since:
        2.3.17
      See Also:
        `MultiPartRequestWrapper`

    - #### isMultipartSupportEnabled

          protected boolean isMultipartSupportEnabled(javax.servlet.http.HttpServletRequest request)

      Checks if support to parse multipart requests is enabled
      Parameters:
        `request` - current servlet request
      Returns:
        false if disabled
      Since:
        2.5.11

    - #### isMultipartRequest

          protected boolean isMultipartRequest(javax.servlet.http.HttpServletRequest request)

      Checks if request is a multipart request (a file upload request)
      Parameters:
        `request` - current servlet request
      Returns:
        true if it is a multipart request
      Since:
        2.5.11

    - #### getMultiPartRequest

          protected MultiPartRequest getMultiPartRequest()

      On each request it must return a new instance as implementation could be not thread safe and thus ensure of resource clean up
      Returns:
        a multi part request object

    - #### cleanUpRequest

          public void cleanUpRequest(javax.servlet.http.HttpServletRequest request)

      Removes all the files created by MultiPartRequestWrapper.
      Parameters:
        `request` - the HttpServletRequest object.
      See Also:
        `MultiPartRequestWrapper`

    - #### sendError

          public void sendError(javax.servlet.http.HttpServletRequest request,
                                javax.servlet.http.HttpServletResponse response,
                                int code,
                                Exception e)

      Send an HTTP error response code.
      Parameters:
        `request` - the HttpServletRequest object.
        `response` - the HttpServletResponse object.
        `code` - the HttpServletResponse error code (see `HttpServletResponse` for possible error codes).
        `e` - the Exception that is reported.
      Since:
        2.3.17

    - #### cleanUpAfterInit

          public void cleanUpAfterInit()

      Cleanup any resources used to initialise Dispatcher

    - #### getConfigurationManager

          public ConfigurationManager getConfigurationManager()

      Expose the ConfigurationManager instance.
      Returns:
        The instance

    - #### getContainer

          public Container getContainer()

      Exposes a thread-cached reference of the dependency injection container. If the container is found to have changed since the last time it was cached, this Dispatcher instance is re-injected to ensure no stale configuration/dependencies persist.

      A non-cached reference can be obtained by calling `getConfigurationManager()`.

      Returns:
        Our dependency injection container

Copyright © 2000–2025 Apache Software Foundation. All rights reserved.