This is an automated email from the ASF dual-hosted git repository. lukaszlenart pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/struts-site.git
The following commit(s) were added to refs/heads/master by this push: new ffd3820 WW-4878 Documents missing interceptors ffd3820 is described below commit ffd382004950c57dd5578132bdf58e288ce1d56a Author: Lukasz Lenart <lukaszlen...@apache.org> AuthorDate: Fri Oct 27 15:36:17 2017 +0200 WW-4878 Documents missing interceptors --- .../annotation-paramter-filter-interceptor.md | 35 ++++++++++++ .../annotation-workflow-interceptor.md | 62 ++++++++-------------- .../core-developers/clear-session-interceptor.md | 29 ++++++++++ .../core-developers/cookie-provider-interceptor.md | 48 +++++------------ .../core-developers/create-session-interceptor.md | 53 ++++-------------- source/core-developers/interceptors.md | 25 +++++---- source/core-developers/logger-interceptor.md | 40 ++++---------- .../parameter-remover-interceptor.md | 42 +++++++++++++++ source/core-developers/parameters-interceptor.md | 5 +- 9 files changed, 179 insertions(+), 160 deletions(-) diff --git a/source/core-developers/annotation-paramter-filter-interceptor.md b/source/core-developers/annotation-paramter-filter-interceptor.md new file mode 100644 index 0000000..2376cb9 --- /dev/null +++ b/source/core-developers/annotation-paramter-filter-interceptor.md @@ -0,0 +1,35 @@ +--- +layout: default +title: Annotation Parameter Filter Interceptor +parent: + title: Interceptors + url: interceptors.html +--- + +# Annotation Parameter Filter Interceptor + +Annotation based version of [Parameter Filter Interceptor](parameter-filter-interceptor.html). + +This interceptor must be placed in the stack before the [Parameters Interceptor](parameters-interceptor.html). +When a parameter matches a field that is marked {@link Blocked} then it is removed from the parameter map. + +If an action class is marked with `BlockByDefault` then all parameters are removed unless a field on the Action exists +and is marked with `Allowed`. + +## Parameters + +There are no parameters for this interceptor. + +## Extending the Interceptor + +There are no obvious extensions to the existing interceptor. + +## Examples + +```xml +<action name="exampleAction" class="com.examples.ExampleAction"> + <interceptor-ref name="annotationParameterFilter"/> + <interceptor-ref name="defaultStack"/> + <result name="success">example.jsp</result> +</action> +``` diff --git a/source/core-developers/annotation-workflow-interceptor.md b/source/core-developers/annotation-workflow-interceptor.md index 46dcf74..97ef2cc 100644 --- a/source/core-developers/annotation-workflow-interceptor.md +++ b/source/core-developers/annotation-workflow-interceptor.md @@ -1,33 +1,26 @@ --- -layout: core-developers -title: AnnotationWorkflowInterceptor +layout: default +title: Annotation Workflow Interceptor +parent: + title: Interceptors + url: interceptors.html --- -# AnnotationWorkflowInterceptor +# Annotation Workflow Interceptor -{% comment %}start snippet id=javadoc|javadoc=true|url=com.opensymphony.xwork2.interceptor.annotations.AnnotationWorkflowInterceptor {% endcomment %} -<p> <p>Invokes any annotated methods on the action. Specifically, it supports the following - annotations:</p> - <ul> - <li> @{@link Before} - will be invoked before the action method. If the returned value is not null, it is - returned as the action result code</li> - <li> @{@link BeforeResult} - will be invoked after the action method but before the result execution</li> - <li> @{@link After} - will be invoked after the action method and result execution</li> - </ul> +Invokes any annotated methods on the action. Specifically, it supports the following annotations + + - `@Before` - will be invoked before the action method. If the returned value is not null, it is returned as the action + result code + - @`BeforeResult` - will be invoked after the action method but before the result execution + - `@After` - will be invoked after the action method and result execution - <p>There can be multiple methods marked with the same annotations, but the order of their execution - is not guaranteed. However, the annotated methods on the superclass chain are guaranteed to be invoked before the - annotated method in the current class in the case of a {@link Before} annotations and after, if the annotations is - {@link After}.</p> -</p> -{% comment %}end snippet id=javadoc|javadoc=true|url=com.opensymphony.xwork2.interceptor.annotations.AnnotationWorkflowInterceptor {% endcomment %} +There can be multiple methods marked with the same annotations, but the order of their execution is not guaranteed. +However, the annotated methods on the superclass chain are guaranteed to be invoked before the annotated method in the current +class in the case of a {@link Before} annotations and after, if the annotations is `After` ## Examples - - -{% comment %}start snippet id=javacode|javadoc=true|lang=java|url=com.opensymphony.xwork2.interceptor.annotations.AnnotationWorkflowInterceptor {% endcomment %} - ```java public class BaseAnnotatedAction { protected String log = ""; @@ -61,40 +54,27 @@ title: AnnotationWorkflowInterceptor log = log + "-after"; } } - ``` -{% comment %}end snippet id=javacode|javadoc=true|lang=java|url=com.opensymphony.xwork2.interceptor.annotations.AnnotationWorkflowInterceptor {% endcomment %} - Configure a stack in struts\.xml that replaces the PrepareInterceptor with the AnnotationWorkflowInterceptor: - -~~~~~~~ - +```xml <interceptor-stack name="annotatedStack"> <interceptor-ref name="static-params"/> <interceptor-ref name="params"/> <interceptor-ref name="conversionError"/> <interceptor-ref name="annotationWorkflow"/> </interceptor-stack> - -~~~~~~~ +``` Given an Action, AnnotatedAction, add a reference to the AnnotationWorkflowInterceptor interceptor\. - -~~~~~~~ - +```xml <action name="AnnotatedAction" class="com.examples.AnnotatedAction"> <interceptor-ref name="annotationWorkflow"/> <result name="success" type="freemarker">good_result.ftl</result> </action> +``` -~~~~~~~ - - -{% comment %}start snippet id=example|javadoc=true|url=com.opensymphony.xwork2.interceptor.annotations.AnnotationWorkflowInterceptor {% endcomment %} -<p> <p>With the interceptor applied and the action executed on <code>AnnotatedAction</code> the log - instance variable will contain <code>baseBefore-before-execute-beforeResult-after</code>.</p> -</p> -{% comment %}end snippet id=example|javadoc=true|url=com.opensymphony.xwork2.interceptor.annotations.AnnotationWorkflowInterceptor {% endcomment %} +With the interceptor applied and the action executed on `AnnotatedAction` the log instance variable will contain +`baseBefore-before-execute-beforeResult-after`. diff --git a/source/core-developers/clear-session-interceptor.md b/source/core-developers/clear-session-interceptor.md new file mode 100644 index 0000000..dfb60fe --- /dev/null +++ b/source/core-developers/clear-session-interceptor.md @@ -0,0 +1,29 @@ +--- +layout: default +title: Create Session Interceptor +parent: + title: Interceptors + url: interceptors.html +--- + +# Clear Session Interceptor + +This interceptor clears the HttpSession. + +## Parameters + +There are no parameters for this interceptor. + +## Extending the Interceptor + +There are no obvious extensions to the existing interceptor. + +## Examples + +```xml +<action name="exampleAction" class="com.examples.ExampleAction"> + <interceptor-ref name="clearSession"/> + <interceptor-ref name="defaultStack"/> + <result name="success">example.jsp</result> +</action> +``` diff --git a/source/core-developers/cookie-provider-interceptor.md b/source/core-developers/cookie-provider-interceptor.md index f04e404..eeb355e 100644 --- a/source/core-developers/cookie-provider-interceptor.md +++ b/source/core-developers/cookie-provider-interceptor.md @@ -1,55 +1,33 @@ --- -layout: core-developers +layout: default title: CookieProvider Interceptor +parent: + title: Interceptors + url: interceptors.html --- -# CookieProvider Interceptor +# Cookie Provider Interceptor +Allows actions to send cookies to client, action must implement `CookieProvider` interface. You must reference this +interceptor in your default stack or in action's stack, see example below. +This interceptor clears the HttpSession. -{% comment %}start snippet id=description|javadoc=true|url=org.apache.struts2.interceptor.CookieProviderInterceptor {% endcomment %} -<p> Allows actions to send cookies to client, action must implement {@link CookieProvider} - You must reference this interceptor in your default stack or in action's stack, see example below. +## Parameters -</p> -{% comment %}end snippet id=description|javadoc=true|url=org.apache.struts2.interceptor.CookieProviderInterceptor {% endcomment %} + - `addCookiesToResponse` - this method applies cookie created by action to response -Parameters +## Extending the Interceptor +There are no obvious extensions to the existing interceptor. -{% comment %}start snippet id=parameters|javadoc=true|url=org.apache.struts2.interceptor.CookieProviderInterceptor {% endcomment %} -<p> - none - -</p> -{% comment %}end snippet id=parameters|javadoc=true|url=org.apache.struts2.interceptor.CookieProviderInterceptor {% endcomment %} - -Extending the Interceptor - - -{% comment %}start snippet id=extending|javadoc=true|url=org.apache.struts2.interceptor.CookieProviderInterceptor {% endcomment %} -<p> - <ul> - <li>addCookiesToResponse - this method applies cookie created by action to response</li> - </ul> - -</p> -{% comment %}end snippet id=extending|javadoc=true|url=org.apache.struts2.interceptor.CookieProviderInterceptor {% endcomment %} - -Examples - - -{% comment %}start snippet id=example|lang=xml|javadoc=true|url=org.apache.struts2.interceptor.CookieProviderInterceptor {% endcomment %} +## Examples ```xml - <action ... > <interceptor-ref name="defaultStack"/> <interceptor-ref name="cookieProvider"/> ... </action> - ``` - -{% comment %}end snippet id=example|lang=xml|javadoc=true|url=org.apache.struts2.interceptor.CookieProviderInterceptor {% endcomment %} diff --git a/source/core-developers/create-session-interceptor.md b/source/core-developers/create-session-interceptor.md index 644c28c..3b6b6f3 100644 --- a/source/core-developers/create-session-interceptor.md +++ b/source/core-developers/create-session-interceptor.md @@ -1,67 +1,32 @@ --- -layout: core-developers +layout: default title: Create Session Interceptor +parent: + title: Interceptors + url: interceptors.html --- # Create Session Interceptor +This interceptor creates the HttpSession if it doesn't exist, also SessionMap is recreated and put in ServletActionContext. - -{% comment %}start snippet id=description|javadoc=true|url=org.apache.struts2.interceptor.CreateSessionInterceptor {% endcomment %} -<p> - <p> - This interceptor creates the HttpSession if it doesn't exist, also SessionMap is recreated and put in ServletActionContext. - </p> - - <p> - This is particular useful when using the <@s.token> tag in freemarker templates. - The tag <b>do</b> require that a HttpSession is already created since freemarker commits - the response to the client immediately. - </p> -</p> -{% comment %}end snippet id=description|javadoc=true|url=org.apache.struts2.interceptor.CreateSessionInterceptor {% endcomment %} +This is particular useful when using the <@s.token> tag in freemarker templates. The tag **do** require that +a HttpSession is already created since freemarker commits the response to the client immediately. ## Parameters - - -{% comment %}start snippet id=parameters|javadoc=true|url=org.apache.struts2.interceptor.CreateSessionInterceptor {% endcomment %} -<p> - <ul> - <li>None</li> - </ul> - -</p> -{% comment %}end snippet id=parameters|javadoc=true|url=org.apache.struts2.interceptor.CreateSessionInterceptor {% endcomment %} +There are no parameters for this interceptor. ## Extending the Interceptor - - -{% comment %}start snippet id=extending|javadoc=true|url=org.apache.struts2.interceptor.CreateSessionInterceptor {% endcomment %} -<p> - <ul> - <li>None</li> - </ul> - -</p> -{% comment %}end snippet id=extending|javadoc=true|url=org.apache.struts2.interceptor.CreateSessionInterceptor {% endcomment %} +There are no obvious extensions to the existing interceptor. ## Examples - - -{% comment %}start snippet id=example|lang=xml|javadoc=true|url=org.apache.struts2.interceptor.CreateSessionInterceptor {% endcomment %} - ```xml - <action name="someAction" class="com.examples.SomeAction"> <interceptor-ref name="createSession"/> <interceptor-ref name="defaultStack"/> <result name="input">input_with_token_tag.ftl</result> </action> - - ``` - -{% comment %}end snippet id=example|lang=xml|javadoc=true|url=org.apache.struts2.interceptor.CreateSessionInterceptor {% endcomment %} diff --git a/source/core-developers/interceptors.md b/source/core-developers/interceptors.md index 64810c0..1aa20ad 100644 --- a/source/core-developers/interceptors.md +++ b/source/core-developers/interceptors.md @@ -1,6 +1,9 @@ --- layout: core-developers title: Interceptors +parent: + title: Core Developer Guide + url: index.html --- # Interceptors @@ -109,35 +112,39 @@ specified in the `<interceptors/>` tag. |Interceptor|Name|Description| |-----------|----|-----------| |[Alias Interceptor](alias-interceptor.html)|alias|Converts similar parameters that may be named differently between requests.| +|[Annotation Parameter Filter Interceptor](annotation-parameter-filter-interceptor.html)|annotationParameterFilter|Annotation based version of [Parameter Filter Interceptor](parameter-filter-interceptor.html).| +|[Annotation Workflow Interceptor](annotation-workflow-interceptor.html)|annotationWorkflow|Invokes any annotated methods on the action.| |[Chaining Interceptor](chaining-interceptor.html)|chain|Makes the previous Action's properties available to the current Action. Commonly used together with <result type="chain"> (in the previous Action).| |[Checkbox Interceptor](checkbox-interceptor.html)|checkbox|Adds automatic checkbox handling code that detect an unchecked checkbox and add it as a parameter with a default (usually 'false') value. Uses a specially named hidden field to detect unsubmitted checkboxes. The default unchecked value is overridable for non-boolean value'd checkboxes.| +|[Conversion Error Interceptor](conversion-error-interceptor.html)|conversionError|Adds conversion errors from the ActionContext to the Action's field errors| |[Cookie Interceptor](cookie-interceptor.html)|cookie|Inject cookie with a certain configurable name / value into action. (Since 2.0.7.)| |[CookieProvider Interceptor](cookie-provider-interceptor.html)|cookieProvider|Transfer cookies from action to response (Since 2.3.15.)| -|[Conversion Error Interceptor](conversion-error-interceptor.html)|conversionError|Adds conversion errors from the ActionContext to the Action's field errors| |[Create Session Interceptor](create-session-interceptor.html)|createSession|Create an HttpSession automatically, useful with certain Interceptors that require a HttpSession to work properly (like the TokenInterceptor)| +|[Clear Session Interceptor](clear-session-interceptor.html)|clearSession|This interceptor clears the HttpSession.| |[DebuggingInterceptor](debugging-interceptor.html)|debugging|Provides several different debugging screens to provide insight into the data behind the page.| -|[Execute and Wait Interceptor](execute-and-wait-interceptor.html)|execAndWait|Executes the Action in the background and then sends the user off to an intermediate waiting page.| +|[Default Workflow Interceptor](default-workflow-interceptor.html)|workflow|Calls the validate method in your Action class. If Action errors are created then it returns the INPUT view.| |[Exception Interceptor](exception-interceptor.html)|exception|Maps exceptions to a result.| +|[Execute and Wait Interceptor](execute-and-wait-interceptor.html)|execAndWait|Executes the Action in the background and then sends the user off to an intermediate waiting page.| |[File Upload Interceptor](file-upload-interceptor.html)|fileUpload|An Interceptor that adds easy access to file upload support.| |[I18n Interceptor](i18n-interceptor.html)|i18n|Remembers the locale selected for a user's session.| -|[Logger Interceptor](logger-interceptor.html)|logger|Outputs the name of the Action.| +|[Logging Interceptor](logger-interceptor.html)|logger|Outputs the name of the Action.| |[Message Store Interceptor](message-store-interceptor.html)|store|Store and retrieve action messages / errors / field errors for action that implements ValidationAware interface into session.| |[Model Driven Interceptor](model-driven-interceptor.htm)|modelDriven|If the Action implements ModelDriven, pushes the getModel Result onto the Value Stack.| -|[Scoped Model Driven Interceptor](scoped-model-driven-interceptor.html)|scopedModelDriven|If the Action implements ScopedModelDriven, the interceptor retrieves and stores the model from a scope and sets it on the action calling setModel.| +|[Multiselect Interceptor](multiselect-interceptor.html)|multiselect|Like the checkbox interceptor detects that no value was selected for a field with multiple values (like a select) and adds an empty parameter| +|[NoOp Interceptor](no-op-interceptor.html)|noop|Does nothing, just passes invocation further, used in empty stack| +|[Parameter Filter Interceptor](parameter-filter-interceptor.html)|N/A|Removes parameters from the list of those available to Actions| |[Parameters Interceptor](parameters-interceptor.html)|params|Sets the request parameters onto the Action.| +|[Parameter Remover Interceptor](parameter-remover-interceptor.html)|paramRemover|Removes a parameter from parameters map.| |[Prepare Interceptor](prepare-interceptor.html)|prepare|If the Action implements Preparable, calls its prepare method.| +|[Roles Interceptor](roles-interceptor.html)|roles|Action will only be executed if the user has the correct JAAS role.| |[Scope Interceptor](scope-interceptor.html)|scope|Simple mechanism for storing Action state in the session or application scope.| +|[Scoped Model Driven Interceptor](scoped-model-driven-interceptor.html)|scopedModelDriven|If the Action implements ScopedModelDriven, the interceptor retrieves and stores the model from a scope and sets it on the action calling setModel.| |[Servlet Config Interceptor](servlet-config-interceptor.html)|servletConfig|Provide access to Maps representing HttpServletRequest and HttpServletResponse.| |[Static Parameters Interceptor](static-parameters-interceptor.html)|staticParams|Sets the struts.xml defined parameters onto the action. These are the <param> tags that are direct children of the <action> tag.| -|[Roles Interceptor](roles-interceptor.html)|roles|Action will only be executed if the user has the correct JAAS role.| |[Timer Interceptor](timer-interceptor.html)|timer|Outputs how long the Action takes to execute (including nested Interceptors and View)| |[Token Interceptor](token-interceptor.html)|token|Checks for valid token presence in Action, prevents duplicate form submission.| |[Token Session Interceptor](token-session-interceptor.html)|tokenSession|Same as Token Interceptor, but stores the submitted data in session when handed an invalid token| |[Validation Interceptor](validation-interceptor.html)|validation|Performs validation using the validators defined in _action_ -validation.xml| -|[Default Workflow Interceptor](default-workflow-interceptor.html)|workflow|Calls the validate method in your Action class. If Action errors are created then it returns the INPUT view.| -|[Parameter Filter Interceptor](parameter-filter-interceptor.html)|N/A|Removes parameters from the list of those available to Actions| -|[Multiselect Interceptor](multiselect-interceptor.html)|multiselect|Like the checkbox interceptor detects that no value was selected for a field with multiple values (like a select) and adds an empty parameter| -|[NoOp Interceptor](no-op-interceptor.html)|noop|Does nothing, just passes invocation further, used in empty stack| Since 2.0.7, Interceptors and Results with hyphenated names were converted to camelCase. (The former model-driven is now modelDriven.) The original hyphenated names are retained as "aliases" until Struts 2.1.0. For clarity, diff --git a/source/core-developers/logger-interceptor.md b/source/core-developers/logger-interceptor.md index a552cb9..d551a72 100644 --- a/source/core-developers/logger-interceptor.md +++ b/source/core-developers/logger-interceptor.md @@ -1,45 +1,27 @@ --- -layout: core-developers +layout: default title: Logger Interceptor +parent: + title: Interceptors + url: interceptors.html --- -# Logger Interceptor +# Logging Interceptor +This interceptor logs the start and end of the execution an action (in English-only, not internationalized). - -{% comment %}start snippet id=description|javadoc=true|url=com.opensymphony.xwork2.interceptor.LoggingInterceptor {% endcomment %} -<p> <p> - This interceptor logs the start and end of the execution an action (in English-only, not internationalized). - <br> - <b>Note:</b>: This interceptor will log at <tt>INFO</tt> level. - </p> -</p> -{% comment %}end snippet id=description|javadoc=true|url=com.opensymphony.xwork2.interceptor.LoggingInterceptor {% endcomment %} +> Note: This interceptor will log at _INFO_ level. ## Parameters - - -{% comment %}start snippet id=parameters|javadoc=true|url=com.opensymphony.xwork2.interceptor.LoggingInterceptor {% endcomment %} -<p> There are no parameters for this interceptor. -</p> -{% comment %}end snippet id=parameters|javadoc=true|url=com.opensymphony.xwork2.interceptor.LoggingInterceptor {% endcomment %} +There are no parameters for this interceptor. ## Extending the Interceptor - - -{% comment %}start snippet id=extending|javadoc=true|url=com.opensymphony.xwork2.interceptor.LoggingInterceptor {% endcomment %} -<p> There are no obvious extensions to the existing interceptor. -</p> -{% comment %}end snippet id=extending|javadoc=true|url=com.opensymphony.xwork2.interceptor.LoggingInterceptor {% endcomment %} +There are no obvious extensions to the existing interceptor. ## Examples - - -{% comment %}start snippet id=example|lang=xml|javadoc=true|url=com.opensymphony.xwork2.interceptor.LoggingInterceptor {% endcomment %} - ```xml <!-- prints out a message before and after the immediate action execution --> <action name="someAction" class="com.examples.SomeAction"> @@ -55,6 +37,4 @@ title: Logger Interceptor <result name="success">good_result.ftl</result> </action> -``` - -{% comment %}end snippet id=example|lang=xml|javadoc=true|url=com.opensymphony.xwork2.interceptor.LoggingInterceptor {% endcomment %} +``` \ No newline at end of file diff --git a/source/core-developers/parameter-remover-interceptor.md b/source/core-developers/parameter-remover-interceptor.md new file mode 100644 index 0000000..ca84545 --- /dev/null +++ b/source/core-developers/parameter-remover-interceptor.md @@ -0,0 +1,42 @@ +--- +layout: default +title: Parameters Interceptor +parent: + title: Interceptors + url: interceptors.html +--- + +# Parameter Remover Interceptor + +This is interceptor allows parameters (matching one of the `paramNames` value) to be removed from the parameter map +if they match a certain value (matching one of the `paramValues` value), before they are set on the action. A typical +usage would be to want a dropdown/select to map onto a boolean value on an action. The select had the options none, +yes and no with values -1, true and false. The true and false would map across correctly. However the -1 would be set to false. + +This was not desired as one might needed the value on the action to stay null. This interceptor fixes this by preventing +the parameter from ever reaching the action. + +## Parameters + + - `paramNames` - a comma separated value indicating the parameter name whose param value should be considered that if + they match any of the comma separated value from `paramValues` attribute, shall be removed from the parameter map such + that they will not be applied to the action + - `paramValues` - a comma separated value indicating the parameter value that if matched shall have its parameter be + removed from the parameter map such that they will not be applied to the action + +## Extending the Interceptor + +There are no obvious extensions to the existing interceptor. + +## Examples + +```xml +<action name="sample" class="org.martingilday.Sample"> + <interceptor-ref name="paramRemover"> + <param name="paramNames">aParam,anotherParam</param> + <param name="paramValues">--,-1</param> + </interceptor-ref> + <interceptor-ref name="defaultStack" /> + ... +</action> +``` diff --git a/source/core-developers/parameters-interceptor.md b/source/core-developers/parameters-interceptor.md index 9f6a428..24995cd 100644 --- a/source/core-developers/parameters-interceptor.md +++ b/source/core-developers/parameters-interceptor.md @@ -1,6 +1,9 @@ --- -layout: core-developers +layout: default title: Parameters Interceptor +parent: + title: Interceptors + url: interceptors.html --- # Parameters Interceptor -- To stop receiving notification emails like this one, please contact ['"commits@struts.apache.org" <commits@struts.apache.org>'].