You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@struts.apache.org by lu...@apache.org on 2017/10/05 07:38:32 UTC
[struts-site] branch master updated: Cleans up results pages
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 afec3bd Cleans up results pages
afec3bd is described below
commit afec3bdfc662f4621d324fdfcf64492843d79114
Author: Lukasz Lenart <lu...@apache.org>
AuthorDate: Thu Oct 5 09:38:24 2017 +0200
Cleans up results pages
---
source/core-developers/chain-result.md | 5 +-
source/core-developers/dispatcher-result.md | 23 ++-
source/core-developers/freemarker-result.md | 22 +--
source/core-developers/httpheader-result.md | 19 ++-
source/core-developers/plaintext-result.md | 5 +-
source/core-developers/redirect-action-result.md | 26 ++--
source/core-developers/redirect-result.md | 24 +--
source/core-developers/result-types.md | 5 +-
source/core-developers/stream-result.md | 50 ++++---
source/core-developers/xsl-result.md | 181 ++++++++---------------
10 files changed, 171 insertions(+), 189 deletions(-)
diff --git a/source/core-developers/chain-result.md b/source/core-developers/chain-result.md
index afe0608..27f28b0 100644
--- a/source/core-developers/chain-result.md
+++ b/source/core-developers/chain-result.md
@@ -1,6 +1,9 @@
---
-layout: core-developers
+layout: default
title: Chain Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# Chain Result
diff --git a/source/core-developers/dispatcher-result.md b/source/core-developers/dispatcher-result.md
index 67f05ad..bae8a6a 100644
--- a/source/core-developers/dispatcher-result.md
+++ b/source/core-developers/dispatcher-result.md
@@ -1,24 +1,33 @@
---
-layout: core-developers
+layout: default
title: Dispatcher Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# Dispatcher Result
-Includes or forwards to a view (usually a jsp). Behind the scenes Struts will use a `RequestDispatcher`, where the target servlet/JSP receives the same request/response objects as the original servlet/JSP. Therefore, you can pass data between them using `request.setAttribute()` - the Struts action is available.
+Includes or forwards to a view (usually a jsp). Behind the scenes Struts will use a `RequestDispatcher`, where
+the target servlet/JSP receives the same request/response objects as the original servlet/JSP. Therefore, you can pass
+data between them using `request.setAttribute()` - the Struts action is available.
There are three possible ways the result can be executed:
-- If we are in the scope of a JSP (a PageContext is available), PageContext's `{@link PageContext#include(String) include}` method is called.
-- If there is no PageContext and we're not in any sort of include (there is no "javax.servlet.include.servlet_path" in the request attributes), then a call to `{@link RequestDispatcher#forward(javax.servlet.ServletRequest, javax.servlet.ServletResponse) forward}` is made.
-- Otherwise, `{@link RequestDispatcher#include(javax.servlet.ServletRequest, javax.servlet.ServletResponse) include}` is called.
+- If we are in the scope of a JSP (a PageContext is available), PageContext's `{@link PageContext#include(String) include}`
+ method is called.
+- If there is no PageContext and we're not in any sort of include (there is no `javax.servlet.include.servlet_path`
+ in the request attributes), then a call to `{@link RequestDispatcher#forward(javax.servlet.ServletRequest, javax.servlet.ServletResponse) forward}`
+ is made.
+- Otherwise, `{@link RequestDispatcher#include(javax.servlet.ServletRequest, javax.servlet.ServletResponse) include}`
+ is called.
-#### Parameters
+## Parameters
- `location` (default) - the location to go to after execution (ex. jsp).
- `parse` - true by default. If set to false, the location param will not be parsed for OGNL expressions.
-#### Examples
+## Examples
```xml
<result name="success" type="dispatcher">
diff --git a/source/core-developers/freemarker-result.md b/source/core-developers/freemarker-result.md
index d456eb4..d87f77c 100644
--- a/source/core-developers/freemarker-result.md
+++ b/source/core-developers/freemarker-result.md
@@ -1,31 +1,31 @@
---
-layout: core-developers
+layout: default
title: FreeMarker Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# FreeMarker Result
-Renders a view using the Freemarker template engine. The `FreemarkarManager` class configures the template loaders so that the template location can be either
+Renders a view using the Freemarker template engine. The `FreemarkarManager` class configures the template loaders
+so that the template location can be either
- relative to the web root folder, e.g.: `/WEB-INF/views/home.ftl`
-
- a classpath resource, e.g.: `/com/company/web/views/home.ftl`
-
Also see [Freemarker Support](freemarker-support.html).
-#### Parameters
+## Parameters
- `location` (default) - the location of the template to process.
-
- `parse`- true by default. If set to false, the location param will not be parsed for expressions.
-
- `contentType` - defaults to `text/html` unless specified.
+- `writeIfCompleted` - `false` by default, write to stream only if there isn't any error processing the template.
+ Setting `template_exception_handler=rethrow` in `freemarker.properties` will have the same effect.
-- `writeIfCompleted` - `false` by default, write to stream only if there isn't any error processing the template. Setting `template_exception_handler=rethrow` in `freemarker.properties` will have the same effect.
-
-#### Examples
+## Examples
-```
+```xml
<result name="success" type="freemarker">foo.ftl</result>
```
diff --git a/source/core-developers/httpheader-result.md b/source/core-developers/httpheader-result.md
index 0fda09d..8621e1e 100644
--- a/source/core-developers/httpheader-result.md
+++ b/source/core-developers/httpheader-result.md
@@ -1,28 +1,27 @@
---
-layout: core-developers
+layout: default
title: HttpHeader Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# HttpHeader Result
-A custom Result type for setting HTTP headers and status by optionally evaluating against the ValueStack. This result can also be used to send an error to the client. All the parameters can be evaluated against the ValueStack.
-
-### Parameters
+A custom Result type for setting HTTP headers and status by optionally evaluating against the ValueStack. This result
+can also be used to send an error to the client. All the parameters can be evaluated against the ValueStack.
+## Parameters
- `status` - the http servlet response status code that should be set on a response.
-
- `parse` - true by default. If set to false, the headers param will not be parsed for OGNL expressions.
-
- `headers` - header values.
-
- `error` - the http servlet response error code that should be set on a response.
-
- `errorMessage` - error message to be set on response if 'error' is set.
-### Examples
+## Examples
-```
+```xml
<result name="success" type="httpheader">
<param name="status">204</param>
<param name="headers.a">a custom header value</param>
diff --git a/source/core-developers/plaintext-result.md b/source/core-developers/plaintext-result.md
index 8bfae9d..a2242ad 100644
--- a/source/core-developers/plaintext-result.md
+++ b/source/core-developers/plaintext-result.md
@@ -1,6 +1,9 @@
---
-layout: core-developers
+layout: default
title: PlainText Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# PlainText Result
diff --git a/source/core-developers/redirect-action-result.md b/source/core-developers/redirect-action-result.md
index b951575..1200fcc 100644
--- a/source/core-developers/redirect-action-result.md
+++ b/source/core-developers/redirect-action-result.md
@@ -1,28 +1,36 @@
---
-layout: core-developers
+layout: default
title: Redirect Action Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# Redirect Action Result
-This result uses the `ActionMapper` provided by the `ActionMapperFactory` to redirect the browser to a URL that invokes the specified action and (optional) namespace. This is better than the `ServletRedirectResult` because it does not require you to encode the URL patterns processed by the `ActionMapper` in to your struts.xml configuration files. This means you can change your URL patterns at any point and your application will still work. It is strongly recommended that if you are redir [...]
+This result uses the `ActionMapper` provided by the `ActionMapperFactory` to redirect the browser to a URL that invokes
+the specified action and (optional) namespace. This is better than the `ServletRedirectResult` because it does not require
+you to encode the URL patterns processed by the `ActionMapper` in to your struts.xml configuration files. This means
+you can change your URL patterns at any point and your application will still work. It is strongly recommended that if you
+are redirecting to another action, you use this result rather than the standard redirect result.
See examples below for an example of how request parameters could be passed in.
See [ActionMapper](action-mapper.html) for more details
-
-### Parameters
+## Parameters
- `actionName` (default) - The name of the action that will be redirected to.
-- `namespace` - Used to determine which namespace the action is in that we're redirecting to. If namespace is null, the default will be the current namespace.
-- `suppressEmptyParameters` - Optional boolean (defaults to false) that can prevent parameters with no values from being included in the redirect URL.
+- `namespace` - Used to determine which namespace the action is in that we're redirecting to. If namespace is null,
+ the default will be the current namespace.
+- `suppressEmptyParameters` - Optional boolean (defaults to false) that can prevent parameters with no values from being
+ included in the redirect URL.
- `parse` - Boolean, true by default. If set to false, the actionName param will not be parsed for OGNL expressions.
- `anchor` - Optional. Also known as "fragment" or colloquially as "hash". You can specify an anchor for a result.
-### Examples
+## Examples
-```
+```xml
<package name="public" extends="struts-default">
<action name="login" class="...">
<!-- Redirect to another namespace -->
@@ -66,7 +74,7 @@ See [ActionMapper](action-mapper.html) for more details
</package>
```
-```
+```xml
<!--
Example of "anchor" param usage in conjunction with "redirectAction" result-type.
diff --git a/source/core-developers/redirect-result.md b/source/core-developers/redirect-result.md
index 9461e8e..d1e633d 100644
--- a/source/core-developers/redirect-result.md
+++ b/source/core-developers/redirect-result.md
@@ -1,26 +1,30 @@
---
-layout: core-developers
+layout: default
title: Redirect Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# Redirect Result
-Calls the `{@link HttpServletResponse#sendRedirect(String) sendRedirect}` method to the location specified. The response is told to redirect the browser to the specified location (a new request from the client). The consequence of doing this means that the action (action instance, action errors, field errors, etc) that was just executed is lost and no longer available. This is because actions are built on a single-thread model. The only way to pass data is through the session or with web [...]
+Calls the `{@link HttpServletResponse#sendRedirect(String) sendRedirect}` method to the location specified. The response
+is told to redirect the browser to the specified location (a new request from the client). The consequence of doing this
+means that the action (action instance, action errors, field errors, etc) that was just executed is lost and no longer
+available. This is because actions are built on a single-thread model. The only way to pass data is through the session
+or with web parameters (`url?name=value`) which can be OGNL expressions.
-### Parameters
+## Parameters
- `location` (default) - the location to go to after execution.
-
- `parse` - true by default. If set to false, the location param will not be parsed for OGNL expressions.
-
- `anchor` - Optional. Also known as "fragment" or colloquially as "hash". You can specify an anchor for a result.
-This result follows the same rules from StrutsResultSupport.
-
+This result follows the same rules from `StrutsResultSupport`.
-### Examples
+## Examples
-```
+```xml
<!--
The redirect URL generated will be:
/foo.jsp#FRAGMENT
@@ -32,7 +36,7 @@ This result follows the same rules from StrutsResultSupport.
</result>
```
-```
+```xml
<package name="passingRequestParameters" extends="struts-default" namespace="/passingRequestParameters">
<-- Pass parameters (reportType, width and height) -->
<!--
diff --git a/source/core-developers/result-types.md b/source/core-developers/result-types.md
index 8c0d502..21fd12f 100644
--- a/source/core-developers/result-types.md
+++ b/source/core-developers/result-types.md
@@ -24,9 +24,10 @@ own applications.
|[Velocity Result](velocity-result.html)|Used for _Velocity_ integration|
|[XSL Result](xsl-result.html)|Used for XML/XSLT integration|
|[PlainText Result](plaintext-result.html)|Used to display the raw content of a particular page (i.e jsp, HTML)|
-|[Tiles Result](tiles-result.html)|Used to provide Tiles integration|
+|[Tiles Result](../plugins/tiles/)|Used to provide Tiles integration|
+|[Tiles 3 Result](../plugins/tiles-3/)|Used to provide Tiles 3 integration|
|[Postback Result](postback-result.html)|Used to postback request parameters as a form to the specified destination|
-|[JSON Result](json-result.html) |Used to serialize actions into JSON|
+|[JSON Result](../plugins/json/) |Used to serialize actions into JSON|
## Optional
diff --git a/source/core-developers/stream-result.md b/source/core-developers/stream-result.md
index 2402cd5..cac1460 100644
--- a/source/core-developers/stream-result.md
+++ b/source/core-developers/stream-result.md
@@ -1,35 +1,47 @@
---
-layout: core-developers
+layout: default
title: Stream Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# Stream Result
-A custom Result type for sending raw data (via an InputStream) directly to the HttpServletResponse. Very useful for allowing users to download content.
-If you are running your app server under HTTPS and having issues with PDF's or other file streams you should take a look at [HTTPS and IE Issues](https-and-ie-issues.html)
+A custom Result type for sending raw data (via an InputStream) directly to the HttpServletResponse. Very useful for
+allowing users to download content. If you are running your app server under HTTPS and having issues with PDF's or other
+file streams you should take a look at [HTTPS and IE Issues](https-and-ie-issues.html)
-### Parameters
+## Parameters
-- `contentType` - the stream mime-type as sent to the web browser (default = text/plain).
+- `contentType` - the stream mime-type as sent to the web browser (default = `text/plain`).
- `contentLength` - the stream length in bytes (the browser displays a progress bar).
-- `contentDisposition` - the content disposition header value for specifying the file name (default = inline, values are typically attachment;filename="document.pdf".
-- `inputName` - the name of the InputStream property from the chained action (default = inputStream).
-- `bufferSize` - the size of the buffer to copy from input to output (default = 1024).
-- `allowCaching` - if set to 'false' it will set the headers `Pragma` and `Cache-Control` to `no-cahce`, and prevent client from caching the content (default = true).
-- `contentCharSet` - if set to a string, ';charset=value' will be added to the content-type header, where value is the string set. If set to an expression, the result of evaluating the expression will be used. If not set, then no charset will be set on the header
+- `contentDisposition` - the content disposition header value for specifying the file name (default = `inline`, values
+ are typically `attachment;filename="document.pdf"`.
+- `inputName` - the name of the InputStream property from the chained action (default = `inputStream`).
+- `bufferSize` - the size of the buffer to copy from input to output (default = `1024`).
+- `allowCaching` - if set to 'false' it will set the headers `Pragma` and `Cache-Control` to `no-cahce`, and prevent
+ client from caching the content (default = `true`).
+- `contentCharSet` - if set to a string, ';charset=value' will be added to the content-type header, where value is the string
+ set. If set to an expression, the result of evaluating the expression will be used. If not set, then no charset will
+ be set on the header
-These parameters can also be set by exposing a similarly named getter method on your Action. For example, you can provide `getContentType()` to override that parameter for the current action. To do it you you must explicitly define this param as an expression i.e. `<param name="contentType">${contentType}</param>`
+These parameters can also be set by exposing a similarly named getter method on your Action. For example, you can provide
+`getContentType()` to override that parameter for the current action. To do it you you must explicitly define this param
+as an expression i.e. `<param name="contentType">${contentType}</param>`
-Please be aware that this was changed since Struts 2.5.2, previously each parameter was automagically resolved by looking throughout the `ValueStack`, now you must explicitly define which parameter must be evaluated, even `inputName`.
+Please be aware that this was changed since Struts 2.5.2, previously each parameter was automatically resolved by looking
+throughout the `ValueStack`, now you must explicitly define which parameter must be evaluated, even `inputName`.
+{:.alert .alert-success}
-### Examples
+## Examples
-#### Annotation based Configuration
+### Annotation based Configuration
-To configure Actions and Results with Annotations you need to activate the Struts2 _Convention Plugin_ in your Struts2 application.
+To configure Actions and Results with Annotations you need to activate the Struts2 [Convention Plugin](../plugins/convention/)
+in your Struts2 application.
-
-```
+```java
package com.mycompany.webapp.actions;
import java.io.File;
@@ -80,9 +92,9 @@ public class FileDisplay extends ActionSupport {
}
```
-#### XML based Configuration
+### XML based Configuration
-```
+```xml
<result name="success" type="stream">
<param name="contentType">image/jpeg</param>
<param name="inputName">${imageStream}</param>
diff --git a/source/core-developers/xsl-result.md b/source/core-developers/xsl-result.md
index e6798f8..27ca532 100644
--- a/source/core-developers/xsl-result.md
+++ b/source/core-developers/xsl-result.md
@@ -1,168 +1,111 @@
---
-layout: core-developers
+layout: default
title: XSL Result
+parent:
+ title: Core Developer Guide
+ url: index.html
---
# XSL Result
+## Description
-####Description####
+XSLTResult uses XSLT to transform an action object to XML. The recent version has been specifically modified to deal
+with Xalan flaws. When using Xalan you may notice that even though you have a very minimal stylesheet like this one
-XSLTResult uses XSLT to transform an action object to XML\. The recent version has been specifically modified to deal with Xalan flaws\. When using Xalan you may notice that even though you have a very minimal stylesheet like this one
-
-
-~~~~~~~
+```xml
<xsl:template match="/result">
<result/>
</xsl:template>
-~~~~~~~
-
-Xalan would still iterate through every property of your action and all its descendants\.
+```
-If you had double\-linked objects, Xalan would work forever analysing an infinite object tree\. Even if your stylesheet was not constructed to process them all\. It's because the current Xalan eagerly and extensively converts
-everything to its internal DTM model before further processing\.
+Xalan would still iterate through every property of your action and all its descendants.
-That's why there's a loop eliminator added that works by indexing every object\-property combination during processing\. If it notices that some object's property was already walked through, it doesn't go any deeper\. Say you have two objects, x and y, with the following properties set (pseudocode):
+If you had double-linked objects, Xalan would work forever analysing an infinite object tree. Even if your stylesheet
+was not constructed to process them all. It's because the current Xalan eagerly and extensively converts everything
+to its internal DTM model before further processing.
+That's why there's a loop eliminator added that works by indexing every object-property combination during processing.
+If it notices that some object's property was already walked through, it doesn't go any deeper. Say you have two objects,
+x and y, with the following properties set (pseudocode):
-~~~~~~~
+```
x.y = y;
and
y.x = x;
action.x=x;
-~~~~~~~
+```
Due to that modification, the resulting XML document based on x would be:
-
-~~~~~~~
+```xml
<result>
<x>
<y/>
</x>
</result>
-~~~~~~~
-
-Without it there would be endless
-
-~~~~~~~
-x/y/x/y/x/y/...
-~~~~~~~
- elements\.
-
-The
-
-~~~~~~~
-XSLTResult
-~~~~~~~
- code tries also to deal with the fact that DTM model is built in a manner that children are processed before siblings\. The result is that if there is object x that is both set in action's x property, and very deeply under action's a property then it would only appear under a, not under x\. That's not what we expect, and that's why
-
-~~~~~~~
-XSLTResult
-~~~~~~~
- allows objects to repeat in various places to some extent\.
-
-Sometimes the object mesh is still very dense and you may notice that even though you have a relatively simple stylesheet, execution takes a tremendous amount of time\. To help you to deal with that obstacle of Xalan, you may attach regexp filters to elements paths (xpath)\.
-
-
-
-| In your \.xsl file the root match must be named **result**\. This example will output the username by using **getUsername** on your action class:
-
-| \<xsl:template match="result"\>
- \<html\>
- \<body\>
- Hello \<xsl:value\-of select="username"/\> how are you?
- \</body\>
- \</html\>
- \</xsl:template\>
-
-In the following example the XSLT result would only walk through action's properties without their childs\. It would also skip every property that has
-
-~~~~~~~
-hugeCollection
-~~~~~~~
- in their name\. Element's path is first compared to
-
-~~~~~~~
-excludingPattern
-~~~~~~~
- \- if it matches it's no longer processed\. Then it is compared to
-
-~~~~~~~
-matchingPattern
-~~~~~~~
- and processed only if there's a match\.
+```
+
+Without it there would be endless `x/y/x/y/x/y/...` elements. The `XSLTResult` code tries also to deal with the fact
+that DTM model is built in a manner that children are processed before siblings. The result is that if there is object
+`x` that is both set in action's `x` property, and very deeply under action's a property then it would only appear under
+`a`, not under `x`. That's not what we expect, and that's why `XSLTResult` allows objects to repeat in various places
+to some extent.
+
+Sometimes the object mesh is still very dense and you may notice that even though you have a relatively simple stylesheet,
+execution takes a tremendous amount of time. To help you to deal with that obstacle of Xalan, you may attach regexp filters
+to elements paths (xpath).
+
+> In your .xsl file the root match must be named `result`. This example will output the username by using `getUsername` on your action class:
+```xml
+<xsl:template match="result">
+ <html>
+ <body>
+ Hello <xsl:value-of select="username"/> how are you?
+ </body>
+ </html>
+</xsl:template>
+```
+In the following example the XSLT result would only walk through action's properties without their childs. It would also
+skip every property that has `hugeCollection` in their name. Element's path is first compared to `excludingPattern` -
+if it matches it's no longer processed. Then it is compared to `matchingPattern` and processed only if there's a match.
-~~~~~~~
+```xml
<result name="success" type="xslt">
<param name="stylesheetLocation">foo.xslt</param>
<param name="matchingPattern">^/result/[^/*]$</param>
<param name="excludingPattern">.*(hugeCollection).*</param>
</result>
-~~~~~~~
-
-In the following example the XSLT result would use the action's user property instead of the action as it's base document and walk through it's properties\. The
+```
-~~~~~~~
-exposedValue
-~~~~~~~
- uses an OGNL expression to derive it's value\.
+In the following example the XSLT result would use the action's user property instead of the action as it's base document
+and walk through it's properties. The `exposedValue` uses an OGNL expression to derive it's value.
-
-~~~~~~~
+```xml
<result name="success" type="xslt">
<param name="stylesheetLocation">foo.xslt</param>
<param name="exposedValue">${user}</param>
</result>
-~~~~~~~
+```
-####Parameters####
+## Parameters
This result type takes the following parameters:
-+ **stylesheetLocation** (default) \- the location to go to after execution\.
-
-+ **location** (deprecated) \- the same as **stylesheetLocation** but it was dropped since Struts 2\.5\.
-
-+ **encoding **\- character encoding used in XML, default UTF\-8\.
-
-+ **parse** \-
-
-~~~~~~~
-true
-~~~~~~~
- by default\. If set to false, the location param will not be parsed for Ognl expressions\.
-
-+ **matchingPattern **\-
+- `stylesheetLocation` (default) - the location to go to after execution.
+- `location` (deprecated) - the same as `stylesheetLocation` but it was dropped since Struts 2.5.
+- `encoding` - character encoding used in XML, default UTF-8.
+- `parse` - `true` by default. If set to false, the location param will not be parsed for Ognl expressions.
+- `matchingPattern` - a `Pattern` that matches only desired elements, by default it matches everything.
+- `excludingPattern` - a `Pattern` that eliminates unwanted elements, by default it matches none.
-~~~~~~~
-Pattern
-~~~~~~~
- that matches only desired elements, by default it matches everything\.
+`struts.xml` related configuration:
-+ **excludingPattern** \-
+- `struts.xslt.nocache` - Defaults to `false`. If set to true, disables stylesheet caching. Good for development, bad for production.
-~~~~~~~
-Pattern
-~~~~~~~
- that eliminates unwanted elements, by default it matches none\.
+## Examples
-
-
-~~~~~~~
-struts.properties
-~~~~~~~
- related configuration:
-
-+ **struts\.xslt\.nocache** \- Defaults to false\. If set to true, disables stylesheet caching\. Good for development, bad for production\.
-
-####Examples####
-
-
-
-~~~~~~~
+```xml
<result name="success" type="xslt">foo.xslt</result>
-~~~~~~~
-
-
\ No newline at end of file
+```
--
To stop receiving notification emails like this one, please contact
['"commits@struts.apache.org" <co...@struts.apache.org>'].