org.apache.struts2.dispatcher

## Class Dispatcher

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

- Direct Known Subclasses:
    MockDispatcher

      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

    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.
    `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
    `HashMap<String,Object>` | `createContextMap(Map requestMap, HttpParameters parameters, Map sessionMap, Map 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 XmlConfigurationProvider` | `createStrutsXmlConfigurationProvider(String filename, boolean errorIfMissing, javax.servlet.ServletContext ctx)`
    `ConfigurationManager` | `getConfigurationManager()` Expose the ConfigurationManager instance.
    `Container` | `getContainer()` Expose the dependency injection container.
    `static Dispatcher` | `getInstance()` Provide the dispatcher instance for the current thread.
    `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).
    `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 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.
    `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` | `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` | `setHandleException(String handleException)`
    `static void` | `setInstance(Dispatcher instance)` Store the dispatcher instance for this thread.
    `void` | `setMultipartHandler(String val)`
    `void` | `setMultipartSaveDir(String val)` Modify state of StrutsConstants.STRUTS_MULTIPART_SAVEDIR setting.
    `void` | `setMultipartSupportEnabled(String multipartSupportEnabled)`
    `void` | `setMultipartValidationRegex(String multipartValidationRegex)`
    `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

    - #### 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

    - #### 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

          public void setMultipartHandler(String val)

    - #### setMultipartSupportEnabled

          public void setMultipartSupportEnabled(String multipartSupportEnabled)

    - #### setMultipartValidationRegex

          public void setMultipartValidationRegex(String multipartValidationRegex)

    - #### setValueStackFactory

          public void setValueStackFactory(ValueStackFactory valueStackFactory)

    - #### setHandleException

          public void setHandleException(String handleException)

    - #### isHandleException

          public boolean isHandleException()

    - #### setDispatcherErrorHandler

          public void setDispatcherErrorHandler(DispatcherErrorHandler errorHandler)

    - #### cleanup

          public void cleanup()

      Releases all instances bound to this dispatcher instance.

    - #### createStrutsXmlConfigurationProvider

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

    - #### 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

    - #### 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 HashMap<String,Object> createContextMap(Map requestMap,
                                                HttpParameters parameters,
                                                Map sessionMap,
                                                Map 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()

      Expose the dependency injection container.
      Returns:
        Our dependency injection container

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