Package 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
  Description
  `static class`
  `Dispatcher.Locator`
  Provide an accessor class for static XWork utility.

- ## Field Summary

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

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  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(jakarta.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(jakarta.servlet.http.HttpServletRequest request, jakarta.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, jakarta.servlet.http.HttpServletRequest request, jakarta.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, jakarta.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(jakarta.servlet.ServletContext servletContext)`
  `protected Locale`
  `getLocale(jakarta.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(jakarta.servlet.http.HttpServletRequest request)`
  Checks if request is a multipart request (a file upload request)
  `protected boolean`
  `isMultipartSupportEnabled(jakarta.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(jakarta.servlet.http.HttpServletRequest request, ConfigurationException e)`
  Performs logging of missing action/result configuration exception
  `void`
  `prepare(jakarta.servlet.http.HttpServletRequest request, jakarta.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(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response, int code, Exception e)`
  Send an HTTP error response code.
  `void`
  `serviceAction(jakarta.servlet.http.HttpServletRequest request, jakarta.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`
  `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)`
  `jakarta.servlet.http.HttpServletRequest`
  `wrapRequest(jakarta.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 Details

  - ### 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 jakarta.servlet.ServletContext servletContext
    Keeps current reference to external world and must be protected to support class inheritance

  - ### initParams

    protected Map<String,String> initParams

- ## Constructor Details

  - ### Dispatcher

    public Dispatcher(jakarta.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 Details

  - ### 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(jakarta.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

  - ### 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, jakarta.servlet.ServletContext ctx)

  - ### 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(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response, ActionMapping mapping) throws jakarta.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(jakarta.servlet.http.HttpServletRequest, jakarta.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:
      `jakarta.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(jakarta.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(jakarta.servlet.http.HttpServletRequest request, jakarta.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, jakarta.servlet.http.HttpServletRequest request, jakarta.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(jakarta.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(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
    Prepare a request, including setting the encoding and locale.
    Parameters:
      `request` - The request
      `response` - The response

  - ### wrapRequest

    public jakarta.servlet.http.HttpServletRequest wrapRequest(jakarta.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(jakarta.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(jakarta.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(jakarta.servlet.http.HttpServletRequest request)
    Removes all the files created by MultiPartRequestWrapper.
    Parameters:
      `request` - the HttpServletRequest object.
    See Also:
      - `MultiPartRequestWrapper`

  - ### sendError

    public void sendError(jakarta.servlet.http.HttpServletRequest request, jakarta.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