com.opensymphony.xwork2.interceptor

## Class ChainingInterceptor

- java.lang.Object
- - com.opensymphony.xwork2.interceptor.AbstractInterceptor
  - - com.opensymphony.xwork2.interceptor.ChainingInterceptor

- All Implemented Interfaces:
    ConditionalInterceptor, Interceptor, Serializable

      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 and Description
    --- | ---
    `protected Collection<String>` | `excludes`
    `protected Collection<String>` | `includes`
    `protected ReflectionProvider` | `reflectionProvider`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ChainingInterceptor()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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 com.opensymphony.xwork2.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 Detail

    - #### excludes

          protected Collection<String> excludes

    - #### includes

          protected Collection<String> includes

    - #### reflectionProvider

          protected ReflectionProvider reflectionProvider

  - ### Constructor Detail

    - #### ChainingInterceptor

          public ChainingInterceptor()

  - ### Method Detail

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

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