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/04/03 10:50:40 UTC
[1/6] struts-site git commit: cleaned up annotations page
Repository: struts-site
Updated Branches:
refs/heads/master 30412c4dd -> 44c0a2a44
cleaned up annotations page
Project: http://git-wip-us.apache.org/repos/asf/struts-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/struts-site/commit/b72962e3
Tree: http://git-wip-us.apache.org/repos/asf/struts-site/tree/b72962e3
Diff: http://git-wip-us.apache.org/repos/asf/struts-site/diff/b72962e3
Branch: refs/heads/master
Commit: b72962e39f6d65a931dfae9dad9a5d3f251948a9
Parents: 30412c4
Author: Stefaan Dutry <st...@gmail.com>
Authored: Sun Apr 2 15:18:28 2017 +0200
Committer: Stefaan Dutry <st...@gmail.com>
Committed: Sun Apr 2 15:18:28 2017 +0200
----------------------------------------------------------------------
source/getting-started/annotations.md | 341 +++--------------------------
1 file changed, 36 insertions(+), 305 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/struts-site/blob/b72962e3/source/getting-started/annotations.md
----------------------------------------------------------------------
diff --git a/source/getting-started/annotations.md b/source/getting-started/annotations.md
index 36f3ebb..67c2b29 100644
--- a/source/getting-started/annotations.md
+++ b/source/getting-started/annotations.md
@@ -6,66 +6,44 @@ title: Annotations
The example code for this tutorial, annotations, is available for checkout at [https://github.com/apache/struts-examples](https://github.com/apache/struts-examples)
->
+__Introduction__
-#####Introduction#####
+In our previous tutorials we've been using an XML file (`struts.xml`) to configure our applications. The XML file wires up the action names (register), with ActionSupport classes (`RegisterAction.java`), and with the result to render back to the browser (`register.jsp`). Struts 2 provides an alternative to using XML to configure your application by using standard naming conventions and annotations for your action names, `ActionSupport` classes, and results.
-In our previous tutorials we've been using an XML file (struts.xml) to configure our applications. The XML file wires up the action names (register), with ActionSupport classes (RegisterAction.java), and with the result to render back to the browser (register.jsp). Struts 2 provides an alternative to using XML to configure your application by using standard naming conventions and annotations for your action names, ActionSupport classes, and results.
+This tutorial assumes you understand how to apply annotations to Java classes and methods. If you're not familiar with annotations, consult the [Java online tutorial](http://download.oracle.com/javase/tutorial/java/javaOO/annotations.html).
+The [Struts 2 user mailing list](http://struts.apache.org/mail.html) is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list.
->
-
->
-
-> This tutorial assumes you understand how to apply annotations to Java classes and methods. If you're not familiar with annotations, consult the [Java online tutorial](http://download.oracle.com/javase/tutorial/java/javaOO/annotations.html)^[http://download.oracle.com/javase/tutorial/java/javaOO/annotations.html].
-
->
-
-
-|
-
-| The [Struts 2 user mailing list](http://struts.apache.org/mail.html)^[http://struts.apache.org/mail.html] is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list.
-
-|
-
-#####Struts 2 Convention Plugin#####
+__Struts 2 Convention Plugin__
Struts 2 enables the use of standard naming conventions and annotations when you include the Convention plugin in your application's class path. If you're using Maven you'll need to add a dependency:
**Convention Plugin Dependency**
-
-~~~~~~~
+```xml
<dependency>
- <groupId>org.apache.struts</groupId>
- <artifactId>struts2-convention-plugin</artifactId>
- <version>2.2.1</version>
+ <groupId>org.apache.struts</groupId>
+ <artifactId>struts2-convention-plugin</artifactId>
+ <version>2.5.10.1</version>
</dependency>
-
-
-~~~~~~~
-
+```
If you're using Ant then copy the struts2-convention-plugin jar file from the Struts 2 download to your WEB-INF/lib folder.
+The convention plugin provide several different ways you can configure your Struts 2 application without using XML. Consult the [Convention Plugin](//struts.apache.org/docs/convention-plugin.html) documentation for complete details. This tutorial only examines one simple way of following the conventions provided by the Convention plugin.
+When you run the example application you'll see on the `index.jsp` page a link to Get your hello. This URL for the link is hello.action. When you click on this link, the execute method of class `HelloAction.java` (which is a Struts 2 `ActionSupport` class) is run. The view page rendered back to the browser after the execute method returns success is `hello-success.jsp`.
-| The convention plugin provide several different ways you can configure your Struts 2 application without using XML. Consult the _Convention Plugin_ documentation for complete details. This tutorial only examines one simple way of following the conventions provided by the Convention plugin.
+None of the above is wired up using XML but rather happens because the application follows the standard naming conventions expected by the Convention plugin. The first convention is that the ActionSupport class, `HelloAction.java`, is in package org.apache.struts.struts2annotations.action. One of the Convention plugin's defaults is to look for ActionSupport classes that are in package structure that ends in action. The next convention the application follows is that HelloAction.java extends the ActionSupport class and defines an execute method. The link is hello.action. When the Struts 2 filter sees a request for hello.action it will map that request to the HelloAction class's execute method due to the Convention plugin being used.
-|
+So a link of hello.action causes the execute method of class HelloAction to be run. That method returns "success." Because the application is using the Convention plugin, Struts 2 will render back to the browser a view page named `hello-success.jsp` that is located in WEB-INF/content (by default the Convention plugin expects all view pages to be in this location). If the execute method returns "input" or "error" then the view page rendered would have been `hello-input.jsp` or `hello-error.jsp`.
-When you run the example application you'll see on the index.jsp page a link to Get your hello. This URL for the link is hello.action. When you click on this link, the execute method of class HelloAction.java (which is a Struts 2 ActionSupport class) is run. The view page rendered back to the browser after the execute method returns success is hello-success.jsp.
+__Struts 2 Configuration Plugin__
-None of the above is wired up using XML but rather happens because the application follows the standard naming conventions expected by the Convention plugin. The first convention is that the ActionSupport class, HelloAction.java, is in package org.apache.struts.struts2annotations.action. One of the Convention plugin's defaults is to look for ActionSupport classes that are in package structure that ends in action. The next convention the application follows is that HelloAction.java extends the ActionSupport class and defines an execute method. The link is hello.action. When the Struts 2 filter sees a request for hello.action it will map that request to the HelloAction class's execute method due to the Convention plugin being used.
-
-So a link of hello.action causes the execute method of class HelloAction to be run. That method returns "success." Because the application is using the Convention plugin, Struts 2 will render back to the browser a view page named hello-success.jsp that is located in WEB-INF/content (by default the Convention plugin expects all view pages to be in this location). If the execute method returns "input" or "error" then the view page rendered would have been hello-input.jsp or hello-error.jsp.
-
-#####Struts 2 Configuration Plugin#####
-
-In a [previous tutorial](#PAGE_16941310) we reviewed how to use the Struts 2 Configuration plugin to view the details of how Struts 2 has configured your application. When using the Convention plugin, it's very handy to also use the Configuration plugin during development. On the example application's home page is a link to the application's configuration. Click on that link and then the hello link on the left menu (under Actions in default). You'll see the configuration for the hello action including it's Action class, result, and view page.
+In a [previous tutorial](debugging-struts.html) we reviewed how to use the Struts 2 Configuration plugin to view the details of how Struts 2 has configured your application. When using the Convention plugin, it's very handy to also use the Configuration plugin during development. On the example application's home page is a link to the application's configuration. Click on that link and then the hello link on the left menu (under Actions in default). You'll see the configuration for the hello action including it's Action class, result, and view page.
-#####Annotations#####
+__Annotations__
If you want to go beyond the simple naming conventions provided by the Convention plugin, you can use the Struts 2 annotations also provided by the plugin. For example, a common work-flow for a Struts 2 application is to first execute the ActionSupport class's input method to setup form field default values and then to run the execute method of the same ActionSupport class when the form is submitted (to validate and save the user's input).
@@ -73,291 +51,44 @@ The link to Register for the drawing on the example application's home page foll
**Action Annotation**
-
-~~~~~~~
+```java
@Action("register-input")
public String input() throws Exception {
+ logger.info("In input method of class Register");
- logger.info("In input method of class Register");
-
- return INPUT;
+ return INPUT;
}
+```
+The Action annotation tells Struts 2 to execute the annotated method when the action link value equals the Action annotation's value ("register-input"). So a link of register-input.action will call the input method of class `RegisterAction`. On the example application's home page is a link to Register for the drawing with a URL of register-input.action.
-~~~~~~~
+The input method above returns "input". By the standards of the Convention plugin, the view page rendered will be register-input.jsp (from WEB-INF/content). On that view page is a Struts 2 form tag with an action attribute value of register. When submitting the form, the execute method of class RegisterAction will be run. Since the execute method returns success, the view page rendered is `register-success.jsp`.
-The Action annotation tells Struts 2 to execute the annotated method when the action link value equals the Action annotation's value ("register-input"). So a link of register-input.action will call the input method of class RegisterAction. On the example application's home page is a link to Register for the drawing with a URL of register-input.action.
-
-The input method above returns "input". By the standards of the Convention plugin, the view page rendered will be register-input.jsp (from WEB-INF/content). On that view page is a Struts 2 form tag with an action attribute value of register. When submitting the form, the execute method of class RegisterAction will be run. Since the execute method returns success, the view page rendered is register-success.jsp.
-
-#####Struts 2 Configuration Values#####
+__Struts 2 Configuration Values__
In previous examples, we included in struts.xml values for some of the Struts 2 configuration parameters.
**struts.xml parameter configuration**
-
-~~~~~~~
+```xml
<constant name="struts.devMode" value="true" />
-
-
-~~~~~~~
+```
When we don't use a struts.xml file, we can set the value of these Struts 2 parameters by using filter parameters in web.xml:
-**Struts 2 Parameter Configurate web.xml**
-
+**Struts 2 Parameter Configuration web.xml**
-~~~~~~~
+```xml
<filter>
- <filter-name>struts2</filter-name>
+ <filter-name>struts2</filter-name>
<filter-class>org.apache.struts2.dispatcher.ng.filter.StrutsPrepareAndExecuteFilter</filter-class>
- <init-param>
- <param-name>struts.devMode</param-name>
- <param-value>true</param-value>
- </init-param>
+ <init-param>
+ <param-name>struts.devMode</param-name>
+ <param-value>true</param-value>
+ </init-param>
</filter>
+```
+__Summary__
-~~~~~~~
-
-#####Summary#####
-
-We've just scratched the surface of what the Struts 2 convention plugin provides to reduce or eliminate the need to use an XML file to configure your Struts 2 application. The Struts 2 Convention plugin provides ways to map multiple actions to the same method, map results to different view pages, map errors to view pages, and much more. Be sure to read through the _Convention Plugin_ documentation for alternative ways to configure your Struts 2 application.
-
-##Struts 2 Form Tags## {#PAGE_19300595}
-
-The example code for this tutorial, form_tags, can be checked out from [https://github.com/apache/struts-examples](https://github.com/apache/struts-examples).
-
->
-
-#####Introduction#####
-
-In this tutorial we'll explore some of the other Struts 2 form controls. In our previous tutorials that explained how to use Struts 2 forms (_Processing Forms_ , _Form Validation_ , and _Message Resource Files_ ) we covered how to use the Struts 2 head, form, textfield controls and the key attribute. This tutorial will explore using the Struts 2 select, radio, checkbox, and checkboxlist form controls.
-
-
-
-| The [Struts 2 user mailing list](http://struts.apache.org/mail.html)^[http://struts.apache.org/mail.html] is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list.
-
-|
-
-#####Example Application#####
-
-The example application that supports this tutorial shows how to use Struts 2 form tags so that a user can edit his information. The information that can be edited is encapsulated in an object of class Person. A Person object knows these things: first name, last name, favorite sport, gender, state of residency, is or is not over 21, and car models owned.
-
-To enable the user to edit his information that is stored in the Person object, we need to create a form like this one:
-
-
-
-The form allows the user to make changes. After submitting the form, the Struts 2 framework will update the state of the Person object.
-
-The first and last names are shown on the form (see edit.jsp) using the Struts 2 textfield tag, which we've discussed in previous tutorials.
-
-#####Struts 2 Select Tag#####
-
-A user can select one favorite sport from several choices. The example application uses the Struts 2 select tag to provide the list of options for the select box.
-
-**Struts 2 Select Tag**
-
-
-~~~~~~~
-<s:select key="personBean.sport" list="sports" />
-
-
-~~~~~~~
-
-In these form tags, we are using the key attribute as discussed in the _Message Resource Files_ tutorial. The key attribute is used by the Struts 2 framework to determine values for the other attributes (e.g. label and value). We are also using a property file associated with the EditAction class to provide the label values based on the key attribute value (see the _Message Resource Files_ tutorial for information on using Struts 2 property files).
-
-
->
-
->
-
-> Note that there are many attributes for the Struts 2 form tags, most of which mirror the HTML attributes associated with the tags. You can read about all the attributes for a Struts 2 form tag by consulting the Struts 2 documentation.
-
->
-
-The value of the list attribute of the Struts 2 select tag is used by the framework to determine what method of the action class to call in order to create the option values. In our example application, the list attribute value of "sports" results in the framework calling the getSports method of class EditAction. That method returns a String array containing "football", "baseball", and "basketball". Those values are used to create the option tags inside the select tag.
-
-The Struts 2 framework determines which option is preselected by using the key attribute's value to call a method on the personBean object. Since the key attribute's value is "personBean.sport", the framework calls the personBean object's getSport method. If the value returned by that method matches one of the option values, that option will be marked as "selected".
-
-Here is the HTML that results from using the above Struts 2 select tag.
-
-**HTML Created By Struts 2 Select Tag**
-
-
-~~~~~~~
-<tr>
-<td class="tdLabel">
-<label for="save_personBean_sport" class="label">Favorite sport:</label>
-</td>
-<td>
-<select name="personBean.sport" id="save_personBean_sport">
- <option value="football">football</option>
- <option value="baseball">baseball</option>
- <option value="basketball" selected="selected">basketball</option>
-</select>
-</td>
-</tr>
-
-
-~~~~~~~
-
-Note the table formatting created by the Struts 2 framework when using the Struts 2 select tag. The CSS classes are defined in style sheets included by the Struts 2 s:head tag. The Struts 2 s:head tag is placed inside the edit.jsp's head section.
-
-Since the personBean's getSport method returns "baskeball", the basketball option value is marked as selected.
-
-#####Struts 2 Radio Tag#####
-
-The Struts 2 radio tag\u2014like its standard HTML counterpart\u2014is used to display 2 or more choices, only one of which can be selected by the user. Here is the code for the Struts 2 radio button from the example application.
-
-**Struts 2 Radio Tag**
-
-
-~~~~~~~
-<s:radio key="personBean.gender" list="genders" />
-
-
-~~~~~~~
-
-Again the key attribute's value determines the value for the label and value attributes. The label's text is derived from the EditAction.properties file (key personBean.gender). Just like the Struts 2 select tag, the list attribute of the Struts 2 radio tag causes the framework to call the getGenders method of the EditAction class. The Array of String objects returned are used to create the individual radio buttons.
-
-**HTML Created By Struts 2 Radio Tag**
-
-
-~~~~~~~
-<tr>
-<td class="tdLabel">
-<label for="save_personBean_gender" class="label">Gender:</label></td>
-<td>
-<input type="radio" name="personBean.gender" id="save_personBean_gendermale" value="male"/><label for="save_personBean_gendermale">male</label>
-<input type="radio" name="personBean.gender" id="save_personBean_genderfemale" value="female"/><label for="save_personBean_genderfemale">female</label>
-<input type="radio" name="personBean.gender" id="save_personBean_gendernot sure" checked="checked" value="not sure"/><label for="save_personBean_gendernot sure">not sure</label>
-</td>
-</tr>
-
-
-~~~~~~~
-
-Also just like the Struts 2 select tag the result returned by calling the personBean object's getGender method is used to determine which of the radio buttons is checked.
-
-#####Struts 2 Select Tag - Object Backed#####
-
-You may need to create a Struts 2 select tag where the options displayed to the user each have their own value that is different then what is displayed. In the example application, the user's residency is stored as a two-letter abbreviation (e.g. KS), but the form select box should display the full state name (e.g. Kansas). To create such a select box in Struts 2, you would use this code
-
-**Struts 2 Select Tag Object Backed**
-
-
-~~~~~~~
-<s:select key="personBean.residency" list="states" listKey="stateAbbr" listValue="stateName" />
-
-
-~~~~~~~
-
-The list value tells the framework to call the getStates method of the EditAction class. That method returns an ArrayList of State objects. Each State object has getStateAbbr and getStateName methods.
-
-The listKey attribute tells the framework to use the value returned by calling the getStateAbbr method as the value for the value attribute of the HTML option tag and the value returned by calling the getStateName method as the value displayed to the user. So the above Struts 2 select tag code results in this HTML.
-
-**HTML Created By Struts 2 Select Tag**
-
-
-~~~~~~~
-<tr>
-<td class="tdLabel">
-<label for="save_personBean_residency" class="label">State resident:</label></td>
-<td>
-<select name="personBean.residency" id="save_personBean_residency">
- <option value="AZ">Arizona</option>
- <option value="CA">California</option>
- <option value="FL">Florida</option>
- <option value="KS" selected="selected">Kansas</option>
- <option value="NY">New York</option>
-</select>
-</td>
-</tr>
-
-
-~~~~~~~
-
-The value returned by calling the personBean object's getResidency method determines which of the select tag's option tags is marked as selected. In our example, since getResidency returns "KS", the option tag whose value attribute equals "KS" is marked as selected.
-
-#####Struts 2 Checkbox Tag#####
-
-The Struts 2 checkbox tag is used to create the HTML input type equals checkbox tag. The value for the key attribute tells the framework what method to call to determine if the checkbox is checked or not checked. The method called should return a Boolean value (true or false). A return value of true will cause the checkbox to be checked and false the checkbox will not be checked.
-
-**Struts 2 Checkbox Tag**
-
-
-~~~~~~~
-<s:checkbox key="personBean.over21" />
-
-
-~~~~~~~
-
-Since the method getOver21 returns true, the checkbox is checked.
-
-**HTML Created By Struts 2 Checkbox Tag**
-
-
-~~~~~~~
-<tr>
-<td valign="top" align="right">
-</td>
-<td valign="top" align="left">
-<input type="checkbox" name="personBean.over21" value="true" checked="checked" id="save_personBean_over21"/>
-<input type="hidden" id="__checkbox_save_personBean_over21" name="__checkbox_personBean.over21" value="true" /> <label for="save_personBean_over21" class="checkboxLabel">21 or older</label>
-</td>
-</tr>
-
-
-~~~~~~~
-
-When the form is submitted and the checkbox is not checked, no value will be posted for the checkbox (this is how HTML forms work). Since the Struts 2 framework will need to update the value of the personBean's over21 instance field to false\u2014given that the check box was not checked\u2014the framework needs a way to determine if the checkbox was not checked after form submission.
-
-If you examine the HTML code created by the Struts 2 checkbox tag, you'll see that it created a hidden field associated with the personBean.over21 checkbox. When the Struts 2 framework intercepts the submission of this form it will use this hidden form field to check if the associated checkbox field exists in the posted form data. If that checkbox field doesn't exist then the Struts 2 framework will know to update the value of the personBean object's over21 instance variable to false.
-
-#####Struts 2 checkboxlist Tag#####
-
-The Struts 2 framework provides a unique form field control that creates a series of associated check boxes, one or more of which can be checked. In the example application, the Person class has an Array of Strings, which is used to store car models owned by a person.
-
-Using the Struts 2 checkbox tag, we can create a series of checkboxes, one for each possible car model the user may own. The value of each String in the personBean's carModels Array will determine which checkboxes are checked.
-
-**Struts 2 Checkboxlist Tag**
-
-
-~~~~~~~
-<s:checkboxlist key="personBean.carModels" list="carModelsAvailable" />
-
-
-~~~~~~~
-
-The list attributes value in the checkboxlist tag tells the Struts 2 framework which method to call to get the possible car models. In the example application, the framework will call the EditAction class's getCarModelsAvailable method. That method returns an Array of Strings. For each element of the Array, the Struts 2 framework creates a checkbox (including the associated hidden field described above).
-
-The key attribute value in the checkboxlist tag tells the Struts 2 framework which method to call on the personBean object to determine which checkboxes should be checked. In the example application, the framework will call the personBean object's getCarModels method. The getCarModels method returns an Array of Strings. For each String value in that Array that matches a String value in the Array returned by the EditAction class's getCarModelsAvailable, the checkbox will be checked.
-
-**HTML Created By Struts 2 Checkboxlist Tag**
-
-
-~~~~~~~
-<tr>
-<td class="tdLabel">
-<label for="save_personBean_carModels" class="label">Car models owned:</label></td>
-<td>
-<input type="checkbox" name="personBean.carModels" value="Ford" id="personBean.carModels-1" checked="checked"/>
-<label for="personBean.carModels-1" class="checkboxLabel">Ford</label>
-<input type="checkbox" name="personBean.carModels" value="Chrysler" id="personBean.carModels-2"/>
-<label for="personBean.carModels-2" class="checkboxLabel">Chrysler</label>
-<input type="checkbox" name="personBean.carModels" value="Toyota" id="personBean.carModels-3"/>
-<label for="personBean.carModels-3" class="checkboxLabel">Toyota</label>
-<input type="checkbox" name="personBean.carModels" value="Nissan" id="personBean.carModels-4" checked="checked"/>
-<label for="personBean.carModels-4" class="checkboxLabel">Nissan</label>
-<input type="hidden" id="__multiselect_save_personBean_carModels" name="__multiselect_personBean.carModels" value="" />
-</td>
-</tr>
-
-
-~~~~~~~
-
-Summary
- There are several other Struts 2 form controls you should explore. If you need more information about the Struts 2 form tags consult the Struts 2 documentation at [http://struts.apache.org](http://struts.apache.org).
-
+We've just scratched the surface of what the Struts 2 convention plugin provides to reduce or eliminate the need to use an XML file to configure your Struts 2 application. The Struts 2 Convention plugin provides ways to map multiple actions to the same method, map results to different view pages, map errors to view pages, and much more. Be sure to read through the [Convention Plugin](//struts.apache.org/docs/convention-plugin.html) documentation for alternative ways to configure your Struts 2 application.
[2/6] struts-site git commit: cleaned up introducing-interceptors page
Posted by lu...@apache.org.
cleaned up introducing-interceptors page
Project: http://git-wip-us.apache.org/repos/asf/struts-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/struts-site/commit/f73b9c7c
Tree: http://git-wip-us.apache.org/repos/asf/struts-site/tree/f73b9c7c
Diff: http://git-wip-us.apache.org/repos/asf/struts-site/diff/f73b9c7c
Branch: refs/heads/master
Commit: f73b9c7c63282fb9036388e8c91a58e536a1f32d
Parents: b72962e
Author: Stefaan Dutry <st...@gmail.com>
Authored: Sun Apr 2 15:34:13 2017 +0200
Committer: Stefaan Dutry <st...@gmail.com>
Committed: Sun Apr 2 15:34:13 2017 +0200
----------------------------------------------------------------------
.../getting-started/introducing-interceptors.md | 145 +++++--------------
1 file changed, 35 insertions(+), 110 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/struts-site/blob/f73b9c7c/source/getting-started/introducing-interceptors.md
----------------------------------------------------------------------
diff --git a/source/getting-started/introducing-interceptors.md b/source/getting-started/introducing-interceptors.md
index 9fe1a6f..4c2a503 100644
--- a/source/getting-started/introducing-interceptors.md
+++ b/source/getting-started/introducing-interceptors.md
@@ -6,9 +6,7 @@ title: Introducing Interceptors
The example code for this tutorial, interceptors, is available at [https://github.com/apache/struts-examples](https://github.com/apache/struts-examples)
->
-
-#####Introduction#####
+__Introduction__
So far our tutorials have not delved into the inner workings of the Struts 2 framework. But in this tutorial we'll introduce a key set of classes the Struts 2 framework relies upon to do most of the work whenever an Action is executed. In this tutorial's example project there is a register link that is mapped in the Struts XML configuration file (struts.xml) to the execute method of class Register. Before that execute method is called much work is done behind the scenes by the Struts 2 framework. For example:
@@ -22,166 +20,93 @@ After the execute method is completed more work must be done
1. Handling any exceptions generated
-2. Converting the Register class's instance fields to String values for display in the view page
+2. Converting the `Register` class's instance fields to String values for display in the view page
3. Forwarding to the correct view page depending on the result String returned by the execute method
The above list of tasks are not complete - several other tasks are done before and after the execution of the Action.
-|
-
The benefit of using Struts 2 is all this work happens automatically. You can focus on the logic of the controller (the Struts 2 ActionSupport class), the Service layer, the data access layer, your domain models, etc.
+The [Struts 2 user mailing list](http://struts.apache.org/mail.html) is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list.
-
-| The [Struts 2 user mailing list](http://struts.apache.org/mail.html)^[http://struts.apache.org/mail.html] is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list.
-
-|
-
-#####Introducing Interceptors#####
+__Introducing Interceptors__
The tasks that are done by the Struts 2 framework before and after an Action is executed are done by Struts 2 interceptors. Interceptors are standard Java classes included in the Struts 2 core jar which are executed in a specific order.
In our example application there is a package node in struts.xml. The package node has an attribute of extends with a value of "struts-default." The value "struts-default" identifies to the framework the specific stack of interceptors that will be executed before and after the Actions in that package.
-If you want to learn more about the inner workings of interceptors, what interceptors belong to the struts default stack, and what are all the interceptors included with Struts 2, visit _Understanding Interceptors_ .
+If you want to learn more about the inner workings of interceptors, what interceptors belong to the struts default stack, and what are all the interceptors included with Struts 2, visit [Understanding Interceptors](//struts.apache.org/docs/interceptors.html) .
-Sometime the Struts 2 default stack of interceptors are not exactly what you need for a particular action. You may want to use interceptors that are not part of the Struts 2 default stack. For an individual Action or for the entire package of Actions, you can specify a different stack of interceptors that the Action or package should use. Below is how you would specify that the register Action should use both the _logger_ and _timer_ interceptors in addition to the interceptors provided by the default stack.
+Sometime the Struts 2 default stack of interceptors are not exactly what you need for a particular action. You may want to use interceptors that are not part of the Struts 2 default stack. For an individual Action or for the entire package of Actions, you can specify a different stack of interceptors that the Action or package should use. Below is how you would specify that the register Action should use both the [logger](//struts.apache.org/docs/logger-interceptor.html) and [timer](//struts.apache.org/docs/logger-interceptor.html) interceptors in addition to the interceptors provided by the default stack.
**Specify Specific Interceptors For An Action**
-
-~~~~~~~
+```xml
<action name="register" class="org.apache.struts.register.action.Register" method="execute">
- <interceptor-ref name="timer" />
- <interceptor-ref name="logger" />
- <interceptor-ref name="defaultStack">
- <param name="exception.logEnabled">true</param>
- <param name="exception.logLevel">ERROR</param>
- </interceptor-ref>
- <result name="success">thankyou.jsp</result>
- <result name="input">register.jsp</result>
+ <interceptor-ref name="timer" />
+ <interceptor-ref name="logger" />
+ <interceptor-ref name="defaultStack">
+ <param name="exception.logEnabled">true</param>
+ <param name="exception.logLevel">ERROR</param>
+ </interceptor-ref>
+ <result name="success">thankyou.jsp</result>
+ <result name="input">register.jsp</result>
</action>
-
-
-~~~~~~~
+```
The logger interceptor logs the start and end of the execution of an Action. The timer interceptor logs the amount of time (in milliseconds) for execution of the Action. These two interceptors used together can provide developers useful feedback.
In the code example above note the three interceptor-ref nodes. Each one has a value for the name attribute. For the register Action we are instructing the framework to use the timer, logger, and defaultStack interceptors. The defaultStack are all the interceptors normally executed for an Action.
-How did I know to use the value of timer for the name attribute and even that there is a timer interceptor? On the _Interceptors_ web page in the Struts 2 documentation are a list of interceptors that come with the Struts 2 framework and what the name value is for each interceptor.
+How did I know to use the value of timer for the name attribute and even that there is a timer interceptor? On the [Interceptors](//struts.apache.org/docs/interceptors.html) web page in the Struts 2 documentation are a list of interceptors that come with the Struts 2 framework and what the name value is for each interceptor.
How did I know that the timer interceptor isn't part of the defaultStack of interceptors already? Again on the Interceptors documentation web page is a list of which interceptors belong to the defaultStack.
-Note the param nodes. These nodes are used to provide a value to the setLogEnabled and setLogLevel methods of the _Exception Interceptor_ . Providing the values of true and ERROR will cause the Struts 2 framework to log any exceptions not caught by the application's code and to log those exceptions at the ERROR level.
+Note the param nodes. These nodes are used to provide a value to the setLogEnabled and setLogLevel methods of the [Exception Interceptor](//struts.apache.org/docs/exception-interceptor.html) . Providing the values of true and ERROR will cause the Struts 2 framework to log any exceptions not caught by the application's code and to log those exceptions at the ERROR level.
-#####Run The Example#####
+__Run The Example__
In the example application follow the README instructions to build, deploy, and run the application. View the output sent to the JVM console to see the log messages generated by the logger and timer interceptors. You should see log messages similar to the following:
+```
INFO: Starting execution stack for action //register
- Nov 20, 2010 9:55:48 AM com.opensymphony.xwork2.util.logging.jdk.JdkLogger info
-
+Nov 20, 2010 9:55:48 AM com.opensymphony.xwork2.util.logging.jdk.JdkLogger info
INFO: Finishing execution stack for action //register
-
Nov 20, 2010 9:55:48 AM com.opensymphony.xwork2.util.logging.jdk.JdkLogger info
+INFO: Executed action /register!execute took 177 ms.
+```
-INFO: Executed action [//register\!execute](https://cwiki.apache.org/register\!execute)^[https://cwiki.apache.org/register\!execute] took 177 ms.
-
-If you wanted to have the logger and timer interceptors executed for all Actions in a package you would use the following in struts.xml:
+If you wanted to have the logger and timer interceptors executed for all Actions in a package you would use the following in `struts.xml`:
**Specify Specific Interceptors For A Package**
-
-~~~~~~~
+```xml
<package name="basicstruts2" extends="struts-default" >
-
-
- <interceptors>
-
- <interceptor-stack name="appDefault">
-
+ <interceptors>
+ <interceptor-stack name="appDefault">
<interceptor-ref name="timer" />
-
<interceptor-ref name="logger" />
-
<interceptor-ref name="defaultStack" />
+ </interceptor-stack>
+ </interceptors>
- </interceptor-stack>
+ <default-interceptor-ref name="appDefault" />
- </interceptors>
-
- <default-interceptor-ref name="appDefault" />
-
- <!-- rest of package omitted -->
+ <!-- rest of package omitted -->
</package>
-
-
-~~~~~~~
+```
In the code above we use the interceptors node to define a new stack of interceptors that includes the timer, logger, and defaultStack interceptors. We give this new interceptor stack a name of appDefault. Then we use the default-interceptor-ref node to specify that for all Actions defined inside this package node the appDefault stack of interceptors are to be used. Thus the timer and logger interceptor will be executed for each Action in this package.
Note that in both examples we are still executing all the other interceptors by including the defaultStack as one of the interceptor-ref nodes. When you specify what interceptors you want to use for an Action or a package then only those interceptors are executed. So if in the example we had left out the interceptor-ref for defaultStack only the logger and timer interceptors would have executed.
-#####Create Your Own Interceptor#####
+__Create Your Own Interceptor__
-In addition to specifying your own stack of interceptors, you can also write your own new interceptor and add it to the stack that is executed. The Struts _Writing Interceptors_ guide explains how to do this. For example, you could create your own interceptor to handle authentication and authorization.
+In addition to specifying your own stack of interceptors, you can also write your own new interceptor and add it to the stack that is executed. The Struts [Writing Interceptors](//struts.apache.org/docs/writing-interceptors.html) guide explains how to do this. For example, you could create your own interceptor to handle authentication and authorization.
-#####Summary#####
+__Summary__
Interceptors provide the Struts 2 framework with both power and flexibility. Developers may add additional interceptors (either ones provided by Struts 2 or ones they create) to the stack of interceptors executed when an Action class is called.
-
-For more information about interceptors consult the Struts 2 _Interceptor_ documentation.
-
-##Preparable Interface## {#PAGE_27839279}
-
-The example code for this tutorial, preparable_interface, is available at [https://github.com/apache/struts-examples](https://github.com/apache/struts-examples).
-
->
-
-#####Introduction#####
-
-Often the data used to populate a form control is dynamically generated, perhaps from a database. When the user submits the form, the Struts 2 validation interceptor attempts to validate the user's form input. If validation fails the Struts 2 framework returns the value "input" but the "input" action is not re-executed. Rather the view associated with the "input" result is rendered to the user. Usually this view is the page that displayed the original form.
-
-This work-flow can cause a problem if one or more of the form fields or some other data displayed depends on a dynamic look-up that that is accomplished in the Action class's input method. Since the Action class's input method is not re-executed when validation fails, the view page may no longer have access to the correct information to create the form or other display information.
-
-
-
-| The [Struts 2 user mailing list](http://struts.apache.org/mail.html)^[http://struts.apache.org/mail.html] is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list.
-
-|
-
-#####Preparable Interface#####
-
-Struts 2 provides the [Preparable interface](http://struts.apache.org/2.3.1/xwork-core/apidocs/com/opensymphony/xwork2/Preparable.html)^[http://struts.apache.org/2.3.1/xwork-core/apidocs/com/opensymphony/xwork2/Preparable.html] to overcome this problem. An Action class that implements this interface must override the prepare method. The prepare method will always be called by the Struts 2 framework's [prepare interceptor](http://struts.apache.org/2.3.1.2/docs/prepare-interceptor.html)^[http://struts.apache.org/2.3.1.2/docs/prepare-interceptor.html] whenever any method is called for the Action class and also when validation fails before the view is rendered.
-
-In the prepare method you should put any statements that must be executed no matter what other Action class method will be called and also statements that should be executed if validation fails. Usually statements in the prepare method set the value for Action class instance fields that will be used to populate form controls and get the values that will be used to set the initial form field values.
-
-In addition to automatically running the prepare method the [prepare interceptor](http://struts.apache.org/2.3.1.2/docs/prepare-interceptor.html)^[http://struts.apache.org/2.3.1.2/docs/prepare-interceptor.html] will also call a method named prepare\[ActionMethodName\]. For example, define a prepare method and a prepareInput method in the Action class that implements preparable. When the Struts 2 framework calls the input method, the prepare interceptor will call the prepareInput and the prepare methods before calling the input method.
-
-#####Example Application#####
-
-If you examine class EditAction in the example application (see above) you'll see that it implements the Preparable Interface. In the prepare method is this code:
-
-**EditAction.java prepare Method**
-
-
-~~~~~~~
-
- carModelsAvailable = carModelsService.getCarModels() ;
-
- setPersonBean( editService.getPerson() );
-
-
-~~~~~~~
-
-The above statements get the car model values used to populate the car model check boxes displayed in the form and also get the information about the Person object being edited.
-
-When you run the example application, look in the log to see when the prepare method is called in relation to the input and execute methods. Running the example application and examining the log should help you understand the impact of implementing the Preparable Interface and the prepare method.
-
-#####Summary#####
-
-When your application requires specific statements to be executed no matter which method of the Action class is called or when validation fails, you should implement the Preparable interface and override the prepare method.
[6/6] struts-site git commit: cleaned up exclued-parameters page
Posted by lu...@apache.org.
cleaned up exclued-parameters page
Project: http://git-wip-us.apache.org/repos/asf/struts-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/struts-site/commit/44c0a2a4
Tree: http://git-wip-us.apache.org/repos/asf/struts-site/tree/44c0a2a4
Diff: http://git-wip-us.apache.org/repos/asf/struts-site/diff/44c0a2a4
Branch: refs/heads/master
Commit: 44c0a2a447300cc7f44d43d41f1ec43d0827a05c
Parents: d797f52
Author: Stefaan Dutry <st...@gmail.com>
Authored: Sun Apr 2 16:11:51 2017 +0200
Committer: Stefaan Dutry <st...@gmail.com>
Committed: Sun Apr 2 16:11:51 2017 +0200
----------------------------------------------------------------------
source/getting-started/exclude-parameters.md | 86 +++++++++--------------
1 file changed, 35 insertions(+), 51 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/struts-site/blob/44c0a2a4/source/getting-started/exclude-parameters.md
----------------------------------------------------------------------
diff --git a/source/getting-started/exclude-parameters.md b/source/getting-started/exclude-parameters.md
index ae93530..1b87a31 100644
--- a/source/getting-started/exclude-parameters.md
+++ b/source/getting-started/exclude-parameters.md
@@ -6,17 +6,13 @@ title: Exclude parameters
The example code for this tutorial, exclude_parameters, is available at [https://github.com/apache/struts-examples](https://github.com/apache/struts-examples).
-#####Introduction#####
+__Introduction__
-When [Struts development mode is set to true](http://struts.apache.org/2.3.8/docs/strutsproperties.html)^[http://struts.apache.org/2.3.8/docs/strutsproperties.html] (also see [Debugging Struts](#PAGE_16941310)) the framework writes many informative messages to the log file. These messages include ones that indicate whether or not a specific parameter will be handled by the parameter interceptor and made available to the Action class. These log messages can be helpful in clearly identifying parameters that you do not want the parameter interceptor to process for security or other reasons. This article discusses how to exclude parameters from being handled by the parameter interceptor.
+When [Struts development mode is set to true](//struts.apache.org/docs/strutsproperties.html) (also see [Debugging Struts](debugging-struts.html)) the framework writes many informative messages to the log file. These messages include ones that indicate whether or not a specific parameter will be handled by the parameter interceptor and made available to the Action class. These log messages can be helpful in clearly identifying parameters that you do not want the parameter interceptor to process for security or other reasons. This article discusses how to exclude parameters from being handled by the parameter interceptor.
+The [Struts 2 user mailing list](http://struts.apache.org/mail.html) is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list.
-
-| The [Struts 2 user mailing list](http://struts.apache.org/mail.html)^[http://struts.apache.org/mail.html] is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list.
-
-|
-
-#####Processing Request Parameters#####
+__Processing Request Parameters__
Most request parameters are by default processed by the parameter interceptor and Struts 2 will attempt to modify the state of those Action class fields that match up to a parameter name by calling a corresponding public set method. For example if the request includes a parameter of lastName with a value of Phillips, Struts 2 will try to call a public method with a signature of setLastName(String lastName). However, there may be request parameters that you do not want Struts 2 to try to set the value of in the Action class.
@@ -24,30 +20,26 @@ Consider this code which creates a form:
**Struts 2 Form Tags**
-
-~~~~~~~
+```html
<s:form action="save" method="post">
-<s:textfield key="personBean.firstName" />
-<s:textfield key="personBean.lastName" />
-<s:textfield key="personBean.email" />
-<s:textfield key="personBean.phoneNumber" />
-<s:select key="personBean.sport" list="sports" />
-<s:radio key="personBean.gender" list="genders" />
-<s:select key="personBean.residency" list="states" listKey="stateAbbr" listValue="stateName" />
-<s:checkbox key="personBean.over21" />
-<s:checkboxlist key="personBean.carModels" list="carModelsAvailable" />
-<s:submit key="submit" />
+ <s:textfield key="personBean.firstName" />
+ <s:textfield key="personBean.lastName" />
+ <s:textfield key="personBean.email" />
+ <s:textfield key="personBean.phoneNumber" />
+ <s:select key="personBean.sport" list="sports" />
+ <s:radio key="personBean.gender" list="genders" />
+ <s:select key="personBean.residency" list="states" listKey="stateAbbr" listValue="stateName" />
+ <s:checkbox key="personBean.over21" />
+ <s:checkboxlist key="personBean.carModels" list="carModelsAvailable" />
+ <s:submit key="submit" />
</s:form>
-
-
-~~~~~~~
+```
The s:submit tag will create a submit button with a name of submit. Since the Action class probably doesn't have a setSubmit(String name) method you will see the following log messages (only if Struts development mode is set to true):
**Log Messages**
-
-~~~~~~~
+```
Dec 31, 2012 3:43:53 PM
com.opensymphony.xwork2.util.logging.commons.CommonsLogger warn
WARNING: Parameter [submit] is not on the excludeParams list of patterns and will be appended to action!
@@ -55,48 +47,40 @@ WARNING: Parameter [submit] is not on the excludeParams list of patterns and wil
Dec 31, 2012 3:43:53 PM com.opensymphony.xwork2.util.logging.commons.CommonsLogger error
SEVERE: Developer Notification (set struts.devMode to false to disable this message):
Unexpected Exception caught setting 'submit' on 'class org.apache.struts.edit.action.EditAction: Error setting expression 'submit' with value ['Save Changes', ]
+```
+__Excluding Request Parameters From Struts 2 Processing__
-~~~~~~~
-
-#####Excluding Request Parameters From Struts 2 Processing#####
-
-
-If you're not familiar with setting up a custom interceptor stack for your Struts 2 application review [Introducing Interceptors](#PAGE_24187261).
-
-|
+If you're not familiar with setting up a custom interceptor stack for your Struts 2 application review [Introducing Interceptors](introducing-interceptors.html).
To exclude specific parameters from being processed by the Struts 2 framework you need to add those parameter names to the list of excluded parameters. One way to do this is by adding those parameter names to the collection of excludedParams for the Parameters interceptor. You can do this by modifying the Parameters interceptor in setting up the stack of interceptors used by your Struts 2 application. For example:
**Setup Interceptor Stack To Exclude submit Parameter**
-
-~~~~~~~
+```xml
<interceptors>
- <interceptor-stack name="appDefault">
- <interceptor-ref name="defaultStack">
- <param name="exception.logEnabled">true</param>
- <param name="exception.logLevel">ERROR</param>
- <param name="params.excludeParams">dojo..*,^struts..*,^session..*,^request..*,^application..*,^servlet(Request|Response)..*,parameters...*,submit</param>
- </interceptor-ref>
- </interceptor-stack>
+ <interceptor-stack name="appDefault">
+ <interceptor-ref name="defaultStack">
+ <param name="exception.logEnabled">true</param>
+ <param name="exception.logLevel">ERROR</param>
+ <param name="params.excludeParams">dojo..*,^struts..*,^session..*,^request..*,^application..*,^servlet(Request|Response)..*,parameters...*,submit</param>
+ </interceptor-ref>
+ </interceptor-stack>
</interceptors>
<default-interceptor-ref name="appDefault" />
+```
+The value of node `<param name="params.excludeParams">` is a comma-delimited list of regular expressions or simple Strings that identify request parameters that should NOT be processed by the Parameters interceptor. To exclude the submit parameter (which is the name of the submit button in the form code above), I just added submit to the list.
-~~~~~~~
-
-The value of node \<param name="params.excludeParams"\> is a comma-delimited list of regular expressions or simple Strings that identify request parameters that should NOT be processed by the Parameters interceptor. To exclude the submit parameter (which is the name of the submit button in the form code above), I just added submit to the list.
-
-See the [Basic Stack of Interceptors described here](http://struts.apache.org/2.3.8/docs/struts-defaultxml.html)^[http://struts.apache.org/2.3.8/docs/struts-defaultxml.html] to view the initial set of parameter names/regular expressions to exclude. Be sure to copy over the list of parameters already being excluded and then add your own parameters to the end separated by commas.
+See the [Basic Stack of Interceptors described here](//struts.apache.org/docs/struts-defaultxml.html) to view the initial set of parameter names/regular expressions to exclude. Be sure to copy over the list of parameters already being excluded and then add your own parameters to the end separated by commas.
-#####Example Application#####
+__Example Application__
-Download the example application, [Exclude_Params_Struts2_Mvn](http://code.google.com/p/struts2-examples/downloads/list)^[http://code.google.com/p/struts2-examples/downloads/list] that demonstrates excluding a request parameter. The download is a zipped Maven project. You should be able to unzip it and import the project into any Maven-aware Java IDE. See the project's README.txt file for how to build and run the application.
+Download the example application, [Exclude_Params_Struts2_Mvn](http://code.google.com/p/struts2-examples/downloads/list) that demonstrates excluding a request parameter. The download is a zipped Maven project. You should be able to unzip it and import the project into any Maven-aware Java IDE. See the project's README.txt file for how to build and run the application.
To see the log messages written when not excluding the submit parameter remove the ",submit" from the list of excluded parameter values in the struts.xml file. Then rebuild and redeploy the application and view the console when running the application.
-#####Summary#####
+__Summary__
-It's a nice feature of the Struts 2 framework that it logs during development which request parameters will and will not be processed. During development of a Struts 2 web application it's a good practice to review these log messages to determine if there are any parameters that the framework should not process. For those parameters the Struts 2 framework should not process add the parameter name (or a regular expression that can be used to identify multiple parameter names) to the comma-delimited list that is the value for the \<param name="params.excludeParams"\> node.
+It's a nice feature of the Struts 2 framework that it logs during development which request parameters will and will not be processed. During development of a Struts 2 web application it's a good practice to review these log messages to determine if there are any parameters that the framework should not process. For those parameters the Struts 2 framework should not process add the parameter name (or a regular expression that can be used to identify multiple parameter names) to the comma-delimited list that is the value for the `<param name="params.excludeParams">` node.
[5/6] struts-site git commit: cleaned up preperable-interface page
Posted by lu...@apache.org.
cleaned up preperable-interface page
Project: http://git-wip-us.apache.org/repos/asf/struts-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/struts-site/commit/d797f52c
Tree: http://git-wip-us.apache.org/repos/asf/struts-site/tree/d797f52c
Diff: http://git-wip-us.apache.org/repos/asf/struts-site/diff/d797f52c
Branch: refs/heads/master
Commit: d797f52cd6f08749b990b90169a9f29056707825
Parents: dc2f4cc
Author: Stefaan Dutry <st...@gmail.com>
Authored: Sun Apr 2 16:05:13 2017 +0200
Committer: Stefaan Dutry <st...@gmail.com>
Committed: Sun Apr 2 16:05:13 2017 +0200
----------------------------------------------------------------------
source/getting-started/preperable-interface.md | 30 +++++++--------------
1 file changed, 10 insertions(+), 20 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/struts-site/blob/d797f52c/source/getting-started/preperable-interface.md
----------------------------------------------------------------------
diff --git a/source/getting-started/preperable-interface.md b/source/getting-started/preperable-interface.md
index 02da81e..0571572 100644
--- a/source/getting-started/preperable-interface.md
+++ b/source/getting-started/preperable-interface.md
@@ -6,48 +6,38 @@ title: Preperable Interface
The example code for this tutorial, preparable_interface, is available at [https://github.com/apache/struts-examples](https://github.com/apache/struts-examples).
->
-
-#####Introduction#####
+__Introduction__
Often the data used to populate a form control is dynamically generated, perhaps from a database. When the user submits the form, the Struts 2 validation interceptor attempts to validate the user's form input. If validation fails the Struts 2 framework returns the value "input" but the "input" action is not re-executed. Rather the view associated with the "input" result is rendered to the user. Usually this view is the page that displayed the original form.
This work-flow can cause a problem if one or more of the form fields or some other data displayed depends on a dynamic look-up that that is accomplished in the Action class's input method. Since the Action class's input method is not re-executed when validation fails, the view page may no longer have access to the correct information to create the form or other display information.
+The [Struts 2 user mailing list](http://struts.apache.org/mail.html) is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list.
+__Preparable Interface__
-| The [Struts 2 user mailing list](http://struts.apache.org/mail.html)^[http://struts.apache.org/mail.html] is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list.
-
-|
-
-#####Preparable Interface#####
-
-Struts 2 provides the [Preparable interface](http://struts.apache.org/2.3.1/xwork-core/apidocs/com/opensymphony/xwork2/Preparable.html)^[http://struts.apache.org/2.3.1/xwork-core/apidocs/com/opensymphony/xwork2/Preparable.html] to overcome this problem. An Action class that implements this interface must override the prepare method. The prepare method will always be called by the Struts 2 framework's [prepare interceptor](http://struts.apache.org/2.3.1.2/docs/prepare-interceptor.html)^[http://struts.apache.org/2.3.1.2/docs/prepare-interceptor.html] whenever any method is called for the Action class and also when validation fails before the view is rendered.
+Struts 2 provides the [Preparable interface](http://struts.apache.org/2.3.1/xwork-core/apidocs/com/opensymphony/xwork2/Preparable.html)^[http://struts.apache.org/2.3.1/xwork-core/apidocs/com/opensymphony/xwork2/Preparable.html] to overcome this problem. An Action class that implements this interface must override the prepare method. The prepare method will always be called by the Struts 2 framework's [prepare interceptor](//struts.apache.org/docs/prepare-interceptor.html) whenever any method is called for the Action class and also when validation fails before the view is rendered.
In the prepare method you should put any statements that must be executed no matter what other Action class method will be called and also statements that should be executed if validation fails. Usually statements in the prepare method set the value for Action class instance fields that will be used to populate form controls and get the values that will be used to set the initial form field values.
-In addition to automatically running the prepare method the [prepare interceptor](http://struts.apache.org/2.3.1.2/docs/prepare-interceptor.html)^[http://struts.apache.org/2.3.1.2/docs/prepare-interceptor.html] will also call a method named prepare\[ActionMethodName\]. For example, define a prepare method and a prepareInput method in the Action class that implements preparable. When the Struts 2 framework calls the input method, the prepare interceptor will call the prepareInput and the prepare methods before calling the input method.
+In addition to automatically running the prepare method the [prepare interceptor](//struts.apache.org/docs/prepare-interceptor.html) will also call a method named prepare[ActionMethodName]. For example, define a prepare method and a prepareInput method in the Action class that implements preparable. When the Struts 2 framework calls the input method, the prepare interceptor will call the prepareInput and the prepare methods before calling the input method.
-#####Example Application#####
+__Example Application__
If you examine class EditAction in the example application (see above) you'll see that it implements the Preparable Interface. In the prepare method is this code:
**EditAction.java prepare Method**
-
-~~~~~~~
-
+```java
carModelsAvailable = carModelsService.getCarModels() ;
- setPersonBean( editService.getPerson() );
-
-
-~~~~~~~
+ setPersonBean(editService.getPerson());
+```
The above statements get the car model values used to populate the car model check boxes displayed in the form and also get the information about the Person object being edited.
When you run the example application, look in the log to see when the prepare method is called in relation to the input and execute methods. Running the example application and examining the log should help you understand the impact of implementing the Preparable Interface and the prepare method.
-#####Summary#####
+__Summary__
When your application requires specific statements to be executed no matter which method of the Action class is called or when validation fails, you should implement the Preparable interface and override the prepare method.
[3/6] struts-site git commit: cleaned up unit-testing page
Posted by lu...@apache.org.
cleaned up unit-testing page
Project: http://git-wip-us.apache.org/repos/asf/struts-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/struts-site/commit/c7614476
Tree: http://git-wip-us.apache.org/repos/asf/struts-site/tree/c7614476
Diff: http://git-wip-us.apache.org/repos/asf/struts-site/diff/c7614476
Branch: refs/heads/master
Commit: c7614476981b5fca3041bd572c5b2ee55c649898
Parents: f73b9c7
Author: Stefaan Dutry <st...@gmail.com>
Authored: Sun Apr 2 15:50:17 2017 +0200
Committer: Stefaan Dutry <st...@gmail.com>
Committed: Sun Apr 2 15:50:17 2017 +0200
----------------------------------------------------------------------
source/getting-started/unit-testing.md | 94 +++++++++--------------------
1 file changed, 30 insertions(+), 64 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/struts-site/blob/c7614476/source/getting-started/unit-testing.md
----------------------------------------------------------------------
diff --git a/source/getting-started/unit-testing.md b/source/getting-started/unit-testing.md
index 8fbf911..0a9d8a8 100644
--- a/source/getting-started/unit-testing.md
+++ b/source/getting-started/unit-testing.md
@@ -6,54 +6,38 @@ title: Unit testing
The example code for this tutorial, unit_testing, is available at [https://github.com/apache/struts-examples](https://github.com/apache/struts-examples)
->
+__Introduction__
-#####Introduction#####
+Struts 2 supports running unit tests of methods in the Struts Action class with the [Struts 2 JUnit plugin](//struts.apache.org/docs/junit-plugin.html). The JUnit plugin allows you to test methods of an Action class from within the Struts 2 framework. The Struts Servlet filter and interceptors fire just as if your application was running on a Servlet container.
-Struts 2 supports running unit tests of methods in the Struts Action class with the [Struts 2 JUnit plugin](http://struts.apache.org/2.3.1.2/docs/junit-plugin.html)^[http://struts.apache.org/2.3.1.2/docs/junit-plugin.html]. The JUnit plugin allows you to test methods of an Action class from within the Struts 2 framework. The Struts Servlet filter and interceptors fire just as if your application was running on a Servlet container.
+The [Struts 2 user mailing list](http://struts.apache.org/mail.html) is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list.
-
-
-| The [Struts 2 user mailing list](http://struts.apache.org/mail.html)^[http://struts.apache.org/mail.html] is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list.
-
-|
-
-#####Setup#####
+__Setup__
The Struts 2 JUnit plugin jar file must be on your application's class path. In the example application (see info above) the pom.xml includes a dependency for the struts2-junit-plugin. There are numerous transitive dependencies, including to JUnit and the Spring framework.
-#####Writing A Unit Test#####
+__Writing A Unit Test__
In the example application, the Register Action class includes using the validate method. This method is automatically executed by the Struts 2 framework prior to the execute method. Additionally, this method needs the values from the user's input on the form to already have been provided to the instance fields of the Action class (this work is done by another Struts 2 interceptor). So it would be difficult to test the validate method without the overall Struts 2 framework running.
To use the Struts 2 plugin to ensure the Strut 2 framework runs as part of the test, you need to have your JUnit test class extend StrutsTestCase (see RegisterTest class in the example application).
-
->
-
->
-
-> Note that the Struts 2 JUnit plugin can be used to design unit tests of other Action class methods such as the input method and also to test methods of a custom interceptor you add to the interceptor stack. Also in this example, the test is for validation performed in the _validate method_ . But the same type of test would work if the validation was done using [XML file validation](#PAGE_20644608).
-
->
+Note that the Struts 2 JUnit plugin can be used to design unit tests of other Action class methods such as the input method and also to test methods of a custom interceptor you add to the interceptor stack. Also in this example, the test is for validation performed in the [validate method](form-validation.html) . But the same type of test would work if the validation was done using [XML file validation](form-validation-using-xml.html).
To test the validate method we want Struts to call the Struts action that will cause the Action class's validate and execute methods to be run. In the example application this action is register.
**struts.xml**
-
-~~~~~~~
- <action name="register" class="org.apache.struts.register.action.Register" method="execute">
- <result name="success">/thankyou.jsp</result>
- <result name="input">/register.jsp</result>
- </action>
-
-
-~~~~~~~
+```xml
+ <action name="register" class="org.apache.struts.register.action.Register" method="execute">
+ <result name="success">/thankyou.jsp</result>
+ <result name="input">/register.jsp</result>
+ </action>
+```
Remember the validate method will be called automatically by the framework before calling the execute method. If validation fails the Struts framework will return "input". If there are no validation errors then the framework will call the execute method and return whatever String the execute method returns.
-#####Test Validation Should Pass#####
+__Test Validation Should Pass__
For our first test we'll test that there should be no validation errors. In the normal flow of this application the user would first enter the form data shown on the register.jsp page.
@@ -63,33 +47,24 @@ The input fields for the form have the following name values: personBean.firstNa
**testExecuteValidationPasses method from RegisterTest class**
-
-~~~~~~~
+```java
@Test
public void testExecuteValidationPasses() throws Exception() {
+ request.setParameter("personBean.firstName", "Bruce");
+ request.setParameter("personBean.lastName", "Phillips");
+ request.setParameter("personBean.email", "bphillips@ku.edu");
+ request.setParameter("personBean.age", "19");
- request.setParameter("personBean.firstName", "Bruce");
+ ActionProxy actionProxy = getActionProxy("/register.action");
+ Register action = (Register) actionProxy.getAction() ;
- request.setParameter("personBean.lastName", "Phillips");
-
- request.setParameter("personBean.email", "bphillips@ku.edu");
-
- request.setParameter("personBean.age", "19");
+ assertNotNull("The action is null but should not be.", action);
- ActionProxy actionProxy = getActionProxy("/register.action");
-
- Register action = (Register) actionProxy.getAction() ;
+ String result = actionProxy.execute();
- assertNotNull("The action is null but should not be.", action);
-
- String result - actionProxy.execute();
-
- assertEquals("The execute method did not return " + ActionSupport.SUCCESS + " but should have.", ActionSupport.SUCCESS, result);
-
+ assertEquals("The execute method did not return " + ActionSupport.SUCCESS + " but should have.", ActionSupport.SUCCESS, result);
}
-
-
-~~~~~~~
+```
The first statements in the test method use the request object to set the values of any request parameters. These simulate the values the user would enter into the form fields. Note how the first argument to setParameter is the same as the value of the name attribute in the Struts textfield tag in the register.jsp page.
@@ -103,42 +78,33 @@ After that I can call actionProxy.execute(). This causes the Struts 2 framework
So in the next statement, I check that success was returned.
-#####Test Validation Should Fail#####
+__Test Validation Should Fail__
To test that validation should fail, I just need to have a test method that doesn't provide input for a form field. For example, in the validate method of the Register Action class, is a test to ensure the user has entered some information for the personBean.firstName input field. In the test method I would just not use the request object to set a parameter for that field.
**testExecuteValidationFailsMissingFirstName method from RegisterTest class**
-
-~~~~~~~
+```java
@Test
public void testExecuteValidationFailsMissingFirstName() throws Exception() {
-
//request.setParameter("personBean.firstName", "Bruce");
-
request.setParameter("personBean.lastName", "Phillips");
-
request.setParameter("personBean.email", "bphillips@ku.edu");
-
request.setParameter("personBean.age", "19");
ActionProxy actionProxy = getActionProxy("/register.action");
-
Register action = (Register) actionProxy.getAction() ;
assertNotNull("The action is null but should not be.", action);
- String result - actionProxy.execute();
+ String result = actionProxy.execute();
assertEquals("The execute method did not return " + ActionSupport.INPUT + " but should have.", ActionSupport.INPUT, result);
-
}
-
-
-~~~~~~~
+```
In the last assertEquals statement my test checks that the Struts 2 framework returned "input" as that is what the Struts 2 framework will return if the validation adds a field or action error.
-#####Summary#####
+__Summary__
-There is much more you can do with the Struts 2 JUnit plugin to help you test the methods of your Action class in conjunction with the Struts 2 fraemwork. If your Struts 2 application uses Spring to inject dependencies into the Action class then the Struts 2 JUnit Plugin has a StrutsSpringTestCase that your test class should extend. Please read [Testing Actions](http://struts.apache.org/2.3.1.2/docs/testing-actions.html)^[http://struts.apache.org/2.3.1.2/docs/testing-actions.html] to learn more.
+There is much more you can do with the Struts 2 JUnit plugin to help you test the methods of your Action class in conjunction with the Struts 2 framemwork. If your Struts 2 application uses Spring to inject dependencies into the Action class then the Struts 2 JUnit Plugin has a StrutsSpringTestCase that your test class should extend. Please read [Testing Actions](//struts.apache.org/docs/testing-actions.html) to learn more.
[4/6] struts-site git commit: cleaned up http-session page
Posted by lu...@apache.org.
cleaned up http-session page
Project: http://git-wip-us.apache.org/repos/asf/struts-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/struts-site/commit/dc2f4ccb
Tree: http://git-wip-us.apache.org/repos/asf/struts-site/tree/dc2f4ccb
Diff: http://git-wip-us.apache.org/repos/asf/struts-site/diff/dc2f4ccb
Branch: refs/heads/master
Commit: dc2f4ccb7a2f5a4de460785b96d5e7875ab9bcc9
Parents: c761447
Author: Stefaan Dutry <st...@gmail.com>
Authored: Sun Apr 2 16:00:37 2017 +0200
Committer: Stefaan Dutry <st...@gmail.com>
Committed: Sun Apr 2 16:00:37 2017 +0200
----------------------------------------------------------------------
source/getting-started/http-session.md | 129 ++++++++++------------------
1 file changed, 46 insertions(+), 83 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/struts-site/blob/dc2f4ccb/source/getting-started/http-session.md
----------------------------------------------------------------------
diff --git a/source/getting-started/http-session.md b/source/getting-started/http-session.md
index fba68cf..ccd598f 100644
--- a/source/getting-started/http-session.md
+++ b/source/getting-started/http-session.md
@@ -6,113 +6,83 @@ title: Http Session
The example code for this tutorial, http_session, is available at [https://github.com/apache/struts-examples](https://github.com/apache/struts-examples)
->
+__Introduction__
-#####Introduction#####
+Your Struts 2 application may need to access the HTTP session object. Struts 2 provides an interface, [SessionAware](https://struts.apache.org/maven/struts2-core/apidocs/org/apache/struts2/interceptor/SessionAware.html), that your Action class should implement to obtain a reference to the HTTP session object.
-Your Struts 2 application may need to access the HTTP session object. Struts 2 provides an interface, [SessionAware](http://struts.apache.org/2.3.1.2/struts2-core/apidocs/org/apache/struts2/interceptor/SessionAware.html)^[http://struts.apache.org/2.3.1.2/struts2-core/apidocs/org/apache/struts2/interceptor/SessionAware.html], that your Action class should implement to obtain a reference to the HTTP session object.
+The [Struts 2 user mailing list](http://struts.apache.org/mail.html) is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list.
-
-
-| The [Struts 2 user mailing list](http://struts.apache.org/mail.html)^[http://struts.apache.org/mail.html] is an excellent place to get help. If you are having a problem getting the tutorial example applications to work search the Struts 2 mailing list. If you don't find an answer to your problem, post a question on the mailing list.
-
-|
-
-#####SessionAware Interface#####
+__SessionAware Interface__
The SessionAware interface has one method, setSession, that your Action class will need to override. In the example application (see above), the HelloWorldAction class implements the SessionAware interface and includes this code:
**HelloWorldAction.java setSession Method**
-
-~~~~~~~
+```java
private Map<String, Object> userSession ;
public void setSession(Map<String, Object) session) {
-
userSession = session ;
-
}
-
-
-~~~~~~~
+```
The Struts 2 framework has an interceptor that will inject the HTTP session object into the Action class by calling the setSession method.
-#####Using the HTTP Session Object In The Action Class#####
+__Using the HTTP Session Object In The Action Class__
The example application keeps track of how many times the user clicks on a Hello link or submits the hello form. It stores this count in the HTTP session object in the increaseHelloCount method.
**HelloWorldAction.java increaseHelloCount Method**
-
-~~~~~~~
+```java
private void increaseHelloCount() {
-
- Integer helloCount = (Integer) userSession.get(HELLO_COUNT);
+ Integer helloCount = (Integer) userSession.get(HELLO_COUNT);
- if (helloCount == null ) {
-
- helloCount = 1;
-
- } else {
-
- helloCount++;
+ if (helloCount == null ) {
+ helloCount = 1;
+ } else {
+ helloCount++;
+ }
- }
-
- userSession.put(HELLO_COUNT, helloCount);
-
+ userSession.put(HELLO_COUNT, helloCount);
}
-
-
-
-~~~~~~~
+```
When the increaseHelloCount method is called from within the execute method, the userSession object is a reference to the HTTP session object injected by the Struts 2 framework. So any objects stored in the HTTP session can be retrieved using the userSession object and any objects stored in the userSession object will be stored in the HTTP session object.
-#####Accessing HTTP Session Objects In The View#####
+__Accessing HTTP Session Objects In The View__
Struts 2 provides an easy way to get an object stored in the HTTP session from within the view page. In the example application is HelloWorld.jsp with this markup:
**HelloWorld.jsp Get helloCount Value From HTTP Session**
-
-~~~~~~~
- <p>I've said hello to you <s:property value="#session.helloCount" /> times!</p>
-
-
-~~~~~~~
+```html
+ <p>I've said hello to you <s:property value="#session.helloCount" /> times!</p>
+```
The s:property tag's value attribute has a value of \#session.helloCount. The "\#" before the word session tells the Struts framework to look in the session scope for a key of "helloCount" (which is the value of the String constant HELLO_COUNT referenced in method increaseHelloCount). Struts will get the object mapped to helloCount key and then call that object's toString method to determine what to display in the view page.
-#####Best Practices When Using SessionAware#####
+__Best Practices When Using SessionAware__
Using SessionAware does introduce a potential security vulnerability that you should mitigate by also following these practices in the Action class that implements the SessionAware interface.
1. Do not have a public Map<String, Object) getSession method in the Action class. You only need a public void setSession method to implement the SessionAware interface.
-2. Also have the Action class implement the [ParameterNameAware interface](http://struts.apache.org/2.3.1.2/xwork-core/apidocs/com/opensymphony/xwork2/interceptor/ParameterNameAware.html)^[http://struts.apache.org/2.3.1.2/xwork-core/apidocs/com/opensymphony/xwork2/interceptor/ParameterNameAware.html] and override its acceptableParameterName method:
+2. Also have the Action class implement the [ParameterNameAware interface](https://struts.apache.org/maven/struts2-core/apidocs/com/opensymphony/xwork2/interceptor/ParameterNameAware.html) and override its acceptableParameterName method:
**HelloWorldAction.java acceptableParameterName Method**
+```java
+ public boolean acceptableParameterName(String parameterName) {
+ boolean allowedParameterName = true ;
-~~~~~~~
- public boolean acceptableParameterName(String parameterName) {
-
- boolean allowedParameterName = true ;
+ if ( parameterName.contains("session") || parameterName.contains("request") ) {
+ allowedParameterName = false ;
+ }
- if ( parameterName.contains("session") || parameterName.contains("request") ) {
-
- allowedParameterName = false ;
-
- }
-
- return allowedParameterName;
- }
-
-
-~~~~~~~
+ return allowedParameterName;
+ }
+```
This method will be called by the Struts 2 framework for each parameter in the request scope. By returning false if the parameter name contains "session" we are telling the Struts 2 framework to ignore that parameter. This will prevent a malicious user from trying to hack the HTTP session object.
@@ -120,35 +90,28 @@ Instead of having each action that implements SessionAware also implement the Pa
**struts.xml configure params interceptor**
-
-~~~~~~~
- <package name="basicstruts2" extends="struts-default">
-
- <interceptors>
- <interceptor-stack name="appDefault">
- <interceptor-ref name="defaultStack">
- <param name="exception.logEnabled">true</param>
- <param name="exception.logLevel">ERROR</param>
- <param name="params.excludeParams">dojo..*,^struts..*,^session..*,^request..*,^application..*,^servlet(Request|Response)..*,parameters...*</param>
- </interceptor-ref>
- </interceptor-stack>
- </interceptors>
+```xml
+ <package name="basicstruts2" extends="struts-default">
+ <interceptors>
+ <interceptor-stack name="appDefault">
+ <interceptor-ref name="defaultStack">
+ <param name="exception.logEnabled">true</param>
+ <param name="exception.logLevel">ERROR</param>
+ <param name="params.excludeParams">dojo..*,^struts..*,^session..*,^request..*,^application..*,^servlet(Request|Response)..*,parameters...*</param>
+ </interceptor-ref>
+ </interceptor-stack>
+ </interceptors>
- <default-interceptor-ref name="appDefault" />
-
-
-~~~~~~~
+ <default-interceptor-ref name="appDefault" />
+...
+```
The above code will ensure that every action in the "basicstruts2" package that implements the SessionAware interface will exclude from processing parameters that starts with the strings provided in the params.excludeParams noded.
The example project includes both methods for mitigating the SessionAware security vulnerability.
-
-
| Note the same issue exists if you implement the ServletRequestAware interface, which is why the above method returns false if the parameter name contains "request".
-|
-
-#####Summary#####
+__Summary__
When your Action class needs to access the HTTP session object implement the SessionAware interface and override the setSession method. Be sure to also implement the ParameterNameAware interface and override the acceptableParameterName method to mitigate a potential security vulnerability. If you have multiple actions that implement SessionAware then consider modifying the params interceptor's excludeParams value as part of your Struts 2 package setup.