Package org.apache.struts2.interceptor

# Class ChainingInterceptor

java.lang.Object
org.apache.struts2.interceptor.AbstractInterceptor
org.apache.struts2.interceptor.ChainingInterceptor

All Implemented Interfaces:
  `Serializable`, `ConditionalInterceptor`, `Interceptor`

public class ChainingInterceptor extends AbstractInterceptor

An interceptor that copies all the properties of every object in the value stack to the currently executing object, except for any object that implements `Unchainable`. A collection of optional includes and excludes may be provided to control how and which parameters are copied. Only includes or excludes may be specified. Specifying both results in undefined behavior. See the javadocs for `ReflectionProvider.copy(Object, Object, java.util.Map, java.util.Collection, java.util.Collection)` for more information.

Note: It is important to remember that this interceptor does nothing if there are no objects already on the stack.
This means two things:
One, you can safely apply it to all your actions without any worry of adverse affects.
Two, it is up to you to ensure an object exists in the stack prior to invoking this action. The most typical way this is done is through the use of the chain result type, which combines with this interceptor to make up the action chaining feature.

Note: By default Errors, Field errors and Message aren't copied during chaining, to change the behaviour you can specify the below three constants in struts.properties or struts.xml:

- struts.chaining.copyErrors - set to true to copy Action Errors
- struts.chaining.copyFieldErrors - set to true to copy Field Errors
- struts.chaining.copyMessages - set to true to copy Action Messages

Example:

     <constant name="struts.xwork.chaining.copyErrors" value="true"/>

Note: By default actionErrors and actionMessages are excluded when copping object's properties.

Interceptor parameters:

- excludes (optional) - the list of parameter names to exclude from copying (all others will be included).
- includes (optional) - the list of parameter names to include when copying (all others will be excluded).

Extending the interceptor:

There are no known extension points to this interceptor.

Example code:

     <action name="someAction" class="com.examples.SomeAction">
         <interceptor-ref name="basicStack"/>
         <result name="success" type="chain">otherAction</result>
     </action>

     <action name="otherAction" class="com.examples.OtherAction">
         <interceptor-ref name="chain"/>
         <interceptor-ref name="basicStack"/>
         <result name="success">good_result.ftl</result>
     </action>

Author:
  mrdon, tm_jee ( tm_jee(at)yahoo.co.uk )
See Also:
  - `ActionChainResult`
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected Collection<String>`
  `excludes`
  `protected Collection<String>`
  `includes`
  `protected ReflectionProvider`
  `reflectionProvider`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ChainingInterceptor()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Collection<String>`
  `getExcludes()`
  Gets list of parameter names to exclude
  `Collection<String>`
  `getIncludes()`
  Gets list of parameter names to include
  `String`
  `intercept(ActionInvocation invocation)`
  Override to handle interception
  `void`
  `setCopyErrors(String copyErrors)`
  `void`
  `setCopyFieldErrors(String copyFieldErrors)`
  `void`
  `setCopyMessages(String copyMessages)`
  `void`
  `setExcludes(String excludes)`
  Sets the list of parameter names to exclude from copying (all others will be included).
  `void`
  `setExcludesCollection(Collection<String> excludes)`
  Sets the list of parameter names to exclude from copying (all others will be included).
  `void`
  `setIncludes(String includes)`
  Sets the list of parameter names to include when copying (all others will be excluded).
  `void`
  `setIncludesCollection(Collection<String> includes)`
  Sets the list of parameter names to include when copying (all others will be excluded).
  `void`
  `setReflectionProvider(ReflectionProvider prov)`

  ### Methods inherited from class org.apache.struts2.interceptor.AbstractInterceptor

  `destroy, init, setDisabled, shouldIntercept`

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

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

- ## Field Details

  - ### excludes

    protected Collection<String> excludes

  - ### includes

    protected Collection<String> includes

  - ### reflectionProvider

    protected ReflectionProvider reflectionProvider

- ## Constructor Details

  - ### ChainingInterceptor

    public ChainingInterceptor()

- ## Method Details

  - ### setReflectionProvider

    public void setReflectionProvider(ReflectionProvider prov)

  - ### setCopyErrors

    public void setCopyErrors(String copyErrors)

  - ### setCopyFieldErrors

    public void setCopyFieldErrors(String copyFieldErrors)

  - ### setCopyMessages

    public void setCopyMessages(String copyMessages)

  - ### intercept

    public String intercept(ActionInvocation invocation) throws Exception
    Description copied from class: `AbstractInterceptor`
    Override to handle interception
    Specified by:
      `intercept` in interface `Interceptor`
    Specified by:
      `intercept` in class `AbstractInterceptor`
    Parameters:
      `invocation` - the action invocation
    Returns:
      the return code, either returned from `ActionInvocation.invoke()`, or from the interceptor itself.
    Throws:
      `Exception` - any system-level error, as defined in `Action.execute()`.

  - ### getExcludes

    public Collection<String> getExcludes()
    Gets list of parameter names to exclude
    Returns:
      the exclude list

  - ### setExcludes

    public void setExcludes(String excludes)
    Sets the list of parameter names to exclude from copying (all others will be included).
    Parameters:
      `excludes` - the excludes list as comma separated String

  - ### setExcludesCollection

    public void setExcludesCollection(Collection<String> excludes)
    Sets the list of parameter names to exclude from copying (all others will be included).
    Parameters:
      `excludes` - the excludes list

  - ### getIncludes

    public Collection<String> getIncludes()
    Gets list of parameter names to include
    Returns:
      the include list

  - ### setIncludes

    public void setIncludes(String includes)
    Sets the list of parameter names to include when copying (all others will be excluded).
    Parameters:
      `includes` - the includes list as comma separated String

  - ### setIncludesCollection

    public void setIncludesCollection(Collection<String> includes)
    Sets the list of parameter names to include when copying (all others will be excluded).
    Parameters:
      `includes` - the includes list