http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/multiselect-interceptor.md ---------------------------------------------------------------------- diff --git a/source/core-developers/multiselect-interceptor.md b/source/core-developers/multiselect-interceptor.md new file mode 100644 index 0000000..e25a7e5 --- /dev/null +++ b/source/core-developers/multiselect-interceptor.md @@ -0,0 +1,36 @@ +--- +layout: core-developers +title: Multiselect Interceptor +--- + +# Multiselect Interceptor + + + +~~~~~~~ +org.apache.struts2.interceptor.MultiselectInterceptor +~~~~~~~ + is in the + +~~~~~~~ +defaultStack +~~~~~~~ +\. It checks each form parameter submitted to the action and if it finds one with a prefix of + +~~~~~~~ +__multiselect_ +~~~~~~~ + it inserts a value for a parameter whose name is derived from the suffix to + +~~~~~~~ +__multiselect_ +~~~~~~~ + if it does not exist\. The default value inserted is an empty String array\. + +This means that a a field that can have multiple selected values(select, checkboxlist, etc) can be accompanied by a hidden input with the same name but a prefix of + +~~~~~~~ +__multiselect_ +~~~~~~~ + so that if the no value is selected on the form the action will still receive a value(empty collection) rather than the default HTML action of not providing a value for unselected elements, + \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/namespace-annotation.md ---------------------------------------------------------------------- diff --git a/source/core-developers/namespace-annotation.md b/source/core-developers/namespace-annotation.md new file mode 100644 index 0000000..13fddbd --- /dev/null +++ b/source/core-developers/namespace-annotation.md @@ -0,0 +1,30 @@ +--- +layout: core-developers +title: Namespace Annotation +--- + +# Namespace Annotation + +####Namespace Annotation#### + +The + +~~~~~~~ +@Namespace +~~~~~~~ + annotation allows the definition of an Action's namespace in the + +~~~~~~~ +Action +~~~~~~~ + class rather than based on [Zero Configuration](zero-configuration.html)'s conventions\. + +#####Usage##### + +This annotation is placed at the class level\. + +#####Parameters##### + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| value | String | true | The namespace to use for the annotated action class\. | http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/namespace-configuration.md ---------------------------------------------------------------------- diff --git a/source/core-developers/namespace-configuration.md b/source/core-developers/namespace-configuration.md new file mode 100644 index 0000000..efcbf90 --- /dev/null +++ b/source/core-developers/namespace-configuration.md @@ -0,0 +1,142 @@ +--- +layout: core-developers +title: Namespace Configuration +--- + +# Namespace Configuration + +The namespace attribute subdivides action configurations into logical modules, each with its own identifying prefix\. Namespaces avoid conflicts between action names\. Each namespace can have its own "menu" or "help" action, each with its own implementation\. While the prefix appears in the browser URI, the tags are "namespace aware", so the namespace prefix does not need to be embedded in forms and links\. + + + +| Struts 2 Namespaces are the equivalent of Struts Action 1 modules, but more convenient and flexible\. + +| + +#####Default Namespace##### + +The default namespace is + +~~~~~~~ +"" +~~~~~~~ + \- an empty string\. The default namespace is used as a "catch\-all" namespace\. If an action configuration is not found in a specified namespace, the default namespace is also be searched\. The local/global strategy allows an application to have global action configurations outside of the action element "extends" hierarchy\. + +The namespace prefix can be registered with Java declarative security, to ensure only authorized users can access the actions in a given namespace\. + +#####Root Namespace##### + +A root namespace ("/") is also supported\. The root is the namespace when a request directly under the context path is received\. As with other namespaces, it will fall back to the default ("") namespace if a local action is not found\. + +#####Namespace Example##### + + + +~~~~~~~ + +<package name="default"> + <action name="foo" class="mypackage.simpleAction"> + <result name="success" type="dispatcher">greeting.jsp</result> + </action> + + <action name="bar" class="mypackage.simpleAction"> + <result name="success" type="dispatcher">bar1.jsp</result> + </action> +</package> + +<package name="mypackage1" namespace="/"> + <action name="moo" class="mypackage.simpleAction"> + <result name="success" type="dispatcher">moo.jsp</result> + </action> +</package> + +<package name="mypackage2" namespace="/barspace"> + <action name="bar" class="mypackage.simpleAction"> + <result name="success" type="dispatcher">bar2.jsp</result> + </action> +</package> + +~~~~~~~ + +#####How the Code Works##### + +If a request for + +~~~~~~~ +/barspace/bar.action +~~~~~~~ + is made, the + +~~~~~~~ +/barspace +~~~~~~~ + namespace is searched for the + +~~~~~~~ +bar +~~~~~~~ + action\. If found, the + +~~~~~~~ +bar +~~~~~~~ + action is executed, else it will fall back to the default namespace\. In the Namespace Example, the + +~~~~~~~ +bar +~~~~~~~ + action does exist in the + +~~~~~~~ +/barspace +~~~~~~~ + namespace, so the + +~~~~~~~ +bar +~~~~~~~ + action will be executed, and if "success" is returned, the request will be forwarded to + +~~~~~~~ +bar2.jsp +~~~~~~~ +\. + + + +| If a request is made to /barspace/foo\.action, the namespace /barspace will be checked for action foo\. If a local action is not found, the default namespace is checked\. In the Namespace Example, there is no action foo in the namespace /barspace, therefore the default will be checked and /foo\.action will be executed\. + +| + +In the Namespace Example, if a request for + +~~~~~~~ +moo.action +~~~~~~~ + is made, the root namespace ('/') is searched for a + +~~~~~~~ +moo +~~~~~~~ + action; if a root action is not found, the default namespace is checked\. In this case, the + +~~~~~~~ +moo +~~~~~~~ + action does exist and will be executed\. Upon success, the request would be forwarded to + +~~~~~~~ +bar2.jsp +~~~~~~~ +\. + + + +| If a request is made for /foo\.action, the root / namespace will be checked\. If foo is found, the root action will be selected\. Otherwise, the framework will check the default namespace\. In the Namespace Example, the foo action does not exist in the root namespace, so the default namespace is checked, and the default foo action is executed\. + +| + + +Namespace are not hierarchical like a file system path\. There is one namespace level\. For example if the URL /barspace/myspace/bar\.action is requested, the framework will first look for namespace /barspace/myspace\. If the action does not exist at /barspace/myspace, the search will immediately fall back to the default namespace ""\. The framework will not parse the namespace into a series of "folders"\. In the Namespace Example, the bar action in the default namespace would be selected\. + +| \ No newline at end of file http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/no-op-interceptor.md ---------------------------------------------------------------------- diff --git a/source/core-developers/no-op-interceptor.md b/source/core-developers/no-op-interceptor.md new file mode 100644 index 0000000..6fd62c6 --- /dev/null +++ b/source/core-developers/no-op-interceptor.md @@ -0,0 +1,18 @@ +--- +layout: core-developers +title: NoOp Interceptor +--- + +# NoOp Interceptor + + + +~~~~~~~ +org.apache.struts2.interceptor.NoOpInterceptor +~~~~~~~ + is in the + +~~~~~~~ +emptyStack +~~~~~~~ + and it performs no computation, it is there to allow create an empty stack that can be used with actions that do not required receiving request parameters or are fully stateless, i\.e\. when producing a JSON response on public endpoints\. http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/nutshell.md ---------------------------------------------------------------------- diff --git a/source/core-developers/nutshell.md b/source/core-developers/nutshell.md new file mode 100644 index 0000000..d780136 --- /dev/null +++ b/source/core-developers/nutshell.md @@ -0,0 +1,150 @@ +--- +layout: core-developers +title: Nutshell +--- + +# Nutshell + + The framework documentation is written for active web developers and assumes a working knowledge about how Java web applications are built\. For more about the underlying nuts and bolts, see the [Key Technologies Primer](http://struts\.apache\.org/primer\.html)^[http://struts\.apache\.org/primer\.html]\. + +> + +####Apache Struts 2 Architecture in a Nutshell#### + + + +1. The web browser requests a resource (/mypage.action, /reports/myreport.pdf, et cetera)\ +2. The Filter Dispatcher looks at the request and determines the appropriate Action\ +3. The Interceptors automatically apply common functionality to the request, like workflow, validation, and file upload handling\ +4. The Action method executes, usually storing and/or retrieving information from a database\ +5. The Result renders the output to the browser, be it HTML, images, PDF, or something else\ + +| +|------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + +####Struts Tags in a nutshell#### + +The Struts Tags help you create rich web applications with a minimum of coding\. Often, much of the coding effort in a web application goes into the pages\. The Struts Tags reduce effort by reducing code\. + + +~~~~~~~ + +<% User user = ... %> +<form action="Profile_update.action" method="post"> + <table> + <tr> + <td align="right"><label>First name:</label></td> + <td><input type="text" name="user.firstname" value="<%=user.getFirstname() %> /></td> + </tr> + <tr> + <td><input type="radio" name="user.gender" value="0" id="user.gender0" + <% if (user.getGender()==0) { %> checked="checked" %> } %> /> + <label for="user.gender0">Female</label> + </tr> + </table> +</form> +... + +~~~~~~~ + +Looking over the markup, it's easy to see why Java web development without the aid from a modern framework is hard\! So far, we've only coded two controls, and there are six more to go\! Let's rewrite and finish the form using Struts Tags\. + +|\ +\ + +|\ +\<s:actionerror/\>\ +\<s:form action="Profile\_update" validate="true"\>\ + \<s:textfield label="Username" name="username"/\>\ + \<s:password label="Password" name="password"/\>\ + \<s:password label="(Repeat) Password" name="password2"/\>\ + \<s:textfield label="Full Name" name="fullName"/\>\ + \<s:textfield label="From Address" name="fromAddress"/\>\ + \<s:textfield label="Reply To Address" name="replyToAddress"/\>\ + \<s:submit value="Save" name="Save"/\>\ + \<s:submit action="Register\_cancel" value="Cancel" name="Cancel" onclick="form\.onsubmit=null"/\>\ +\</s:form\>\ + The Struts Tags also support validation and localization as first\-class features\. So not only is there less code, but there is _more_ utility\. \ +In about the same amount of code as two conventional controls, the Struts Tags can create an entire data\-input form with eight controls\. Not only is there less code, but the code is easier to read and maintain\. | +|--------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ----------------------------------------------------------------------------------| + +####Struts Configuration in a Nutshell#### + +A web application uses a deployment descriptor to initialize resources like filters and listeners\. The web deployment descriptor is formatted as a XML document and named + +~~~~~~~ +web.xml +~~~~~~~ +\. Struts can either initialize its resources by scanning your classes using Java packages declared in this + +~~~~~~~ +web.xml +~~~~~~~ + file, or you can have full control over the configuration via a configuration file, named + +~~~~~~~ +struts.xml +~~~~~~~ +\. These resources include action mappings, to direct input to server\-side Action classes, and result types, to select output pages\. + +Here's a typical configuration ( + +~~~~~~~ +struts.xml +~~~~~~~ +) for a login workflow: + + +~~~~~~~ + +<struts> + <package name="default" extends="struts-default"> + <action name="Logon" class="mailreader2.Logon"> + <result name="input">/pages/Logon.jsp</result> + <result name="cancel" type="redirectAction">Welcome</result> + <result type="redirectAction">MainMenu</result> + <result name="expired" type="chain">ChangePassword</result> + </action> + + <action name="Logoff" class="mailreader2.Logoff"> + <result type="redirectAction">Welcome</result> + </action> + </package> +</struts> + +~~~~~~~ + +(light\-on) The framework provides general\-purpose defaults, so we can start using Struts right away, "out of the box"\. Any factory defaults can be overridden in an application's configuration, as needed\. + +####Struts MVC in a Nutshell#### + +Struts is a [Model View Controller](http://struts\.apache\.org/primer\.html\#mvc)^[http://struts\.apache\.org/primer\.html\#mvc] framework\. Struts provides Controller and View components, and integrates with other technologies to provide the Model\. The framework's Controller acts as a bridge between the application's Model and the web View\. + +To make it easier to present dynamic data, the framework includes a library of markup tags\. The tags interact with the framework's validation and internationalization features, to ensure that input is correct and output is localized\. The tag library can be used with JSP, FreeMarker, or Velocity\. Of course, other tag libraries, JSTL, and AJAX can also be used, with or without the Struts tags\. JavaServer Faces components are also supported\. + +When a request is received, the Controller invokes an Action class\. The Action class examines or updates the application's state by consulting the Model (or, preferably, an interface representing the Model)\. To transfer data between the Model and the View, properties can be placed on the Action class, or on a plain old JavaBean\. + +Most often, the Model is represented as a graph of JavaBean objects\. The Model should do the "heavy lifting", and the Action will act as a "traffic cop" or adapter\. The framework provides sophisticated, automatic type conversion to simplify transfering data between rich domain objects and text\-only HTTP requests\. + +Struts is extensible\. _Very_ extensible\. Every class deployed by the framework is based on an interface\. We provide all the base classes an application may ever need, but if we missed something, it's easy to add your own\. We provide the general\-purpose framework, but you can still write _your_ application _your_ way\. + +####Is Struts the best choice for every project?#### + +Apache Struts 2 helps you create an extensible development environment for enterprise\-grade applications, based on industry standards and proven design patterns\. If you need to write a very simple application, with a handful of pages, then you might consider a "Model 1" solution that uses only server pages\. + +But, if you are writing a more complicated application, with dozens of pages, that need to be maintained over time, then Struts can help\. For more about whether Model 1 or MVC/Model 2 is right for you, see [Understanding JavaServer Pages Model 2 architecture](http://www\.javaworld\.com/javaworld/jw\-12\-1999/jw\-12\-ssj\-jspmvc\.html)^[http://www\.javaworld\.com/javaworld/jw\-12\-1999/jw\-12\-ssj\-jspmvc\.html]\. + +####Platform Requirements#### + +Struts 2 requires + ++ Servlet API 2\.4 + ++ JSP API 2\.0 + ++ Java 5 + +For a full list of requirements, including dependencies used by optional plugins, see [Project Dependencies](http://struts\.apache\.org/2\.x/struts2\-core/dependencies\.html)^[http://struts\.apache\.org/2\.x/struts2\-core/dependencies\.html] + + (ok) An alternate set of JARs for Java 4 are also available\. See the "J4" distribution\. + http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/object-factory.md ---------------------------------------------------------------------- diff --git a/source/core-developers/object-factory.md b/source/core-developers/object-factory.md new file mode 100644 index 0000000..21c2175 --- /dev/null +++ b/source/core-developers/object-factory.md @@ -0,0 +1,105 @@ +--- +layout: core-developers +title: ObjectFactory +--- + +# ObjectFactory + +All objects created by the framework are instantiated by the ObjectFactory\. The ObjectFactory provides the means of integrating the framework with IoC containers like Spring, Pico, Plexus, and so forth\. + +####Customize#### + +#####Extend ObjectFactory##### + + +Customized ObjectFactory must extend ObjectFactory or any of its descendants and have a default, no\-argument constructor\. + +| + +To register a customized ObjectFactory, add or edit an entry in + +~~~~~~~ +struts.properties +~~~~~~~ + + + +~~~~~~~ + struts.objectFactory=foo.bar.MyCustomObjectFactory + +~~~~~~~ + +where foo\.bar\.MyCustomObjectFactory is the custom object factory\. + + +~~~~~~~ +public class MyObjectFactory extends ObjectFactory { + ..... +} + +~~~~~~~ + +#####Define dedicated factory##### + +If you want to just extend one part of ObjectFactory, ie\. to change how [Result Types](result-types.html) are build, you can implement + +~~~~~~~ +ResultFactory +~~~~~~~ + interface and register it with dedicated name, see _Extension Points_ for more details\. Original ObjectFactory will use these dedicated factories to do the work\. It's already done this way \- the original functionality of ObjectFactory was extracted to separated classes which implements the interfaces below\. Check the source of ObjectFactory to see more details\. All these factories are available as from version 2\.3\.16\. + +List of Factory interfaces: + ++ + +~~~~~~~ +ResultFactory +~~~~~~~ + \- dedicated interfaces used by to create [Result Types](result-types.html) + + + + +~~~~~~~ +StrutsResultFactory +~~~~~~~ + it's internal implementation which checks if Result implements + +~~~~~~~ +ParamNameAwareResult +~~~~~~~ + interface to restrict names of parameters set on the instance of Result, see [Result Types](result-types.html) for more info\. + ++ + +~~~~~~~ +ActionFactory +~~~~~~~ + \- dedicated interface used by to actions + ++ + +~~~~~~~ +InterceptorFactory +~~~~~~~ + \- dedicated interface used by to create interceptors + ++ + +~~~~~~~ +ValidatorFactory +~~~~~~~ + \- dedicated interface used by to create validators + ++ + +~~~~~~~ +ConverterFactory +~~~~~~~ + \- dedicated interface used by to create instances of _TypeConverter_ + ++ + +~~~~~~~ +UnknownHandlerFactory +~~~~~~~ + \- dedicated interfaces used by  to create instances of [Unknown Handlers](unknown-handlers.html) (as from version 2\.3\.18) http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/package-configuration.md ---------------------------------------------------------------------- diff --git a/source/core-developers/package-configuration.md b/source/core-developers/package-configuration.md new file mode 100644 index 0000000..d1ec9ed --- /dev/null +++ b/source/core-developers/package-configuration.md @@ -0,0 +1,98 @@ +--- +layout: core-developers +title: Package Configuration +--- + +# Package Configuration + +Packages are a way to group actions, results, result types, interceptors, and interceptor\-stacks into a logical configuration unit\. Conceptually, packages are similiar to objects in that they can be extended and have individual parts that can be overridden by "sub" packages\. + +#####Packages##### + +The package element has one required attribute, + +~~~~~~~ +name +~~~~~~~ +, which acts as the key for later reference to the package\. The + +~~~~~~~ +extends +~~~~~~~ + attribute is optional and allows one package to inherit the configuration of one or more previous packages \- including all interceptor, interceptor\-stack, and action configurations\. + + (\!) Note that the configuration file is processed sequentially down the document, so the package referenced by an "extends" should be defined _above_ the package which extends it\. + +The optional + +~~~~~~~ +abstract +~~~~~~~ + attribute creates a base package that can omit the action configuration\. + +| Attribute | Required | Description | +|-----------|----------|-------------| +| name |**yes**| key to for other packages to reference | +| extends | no | inherits package behavior of the package it extends | +| namespace | no | see [Namespace Configuration](#PAGE_14276)| +| abstract | no | declares package to be abstract (no action configurations required in package) | + +__Simple usage__ + +**Package Example (struts\.xml)** + + +~~~~~~~ + +<struts> + <package name="employee" extends="struts-default" namespace="/employee"> + <default-interceptor-ref name="crudStack"/> + + <action name="list" method="list" + class="org.apache.struts2.showcase.action.EmployeeAction" > + <result>/empmanager/listEmployees.jsp</result> + <interceptor-ref name="basicStack"/> + </action> + <action name="edit-*" class="org.apache.struts2.showcase.action.EmployeeAction"> + <param name="empId">{1}</param> + <result>/empmanager/editEmployee.jsp</result> + <interceptor-ref name="crudStack"> + <param name="validation.excludeMethods">execute</param> + </interceptor-ref> + </action> + <action name="save" method="save" + class="org.apache.struts2.showcase.action.EmployeeAction" > + <result name="input">/empmanager/editEmployee.jsp</result> + <result type="redirect">edit-${currentEmployee.empId}.action</result> + </action> + <action name="delete" method="delete" + class="org.apache.struts2.showcase.action.EmployeeAction" > + <result name="error">/empmanager/editEmployee.jsp</result> + <result type="redirect">edit-${currentEmployee.empId}.action</result> + </action> + </package> +</struts> + +~~~~~~~ + +__Inherit from more than one package__ + +**Multi package Example (struts\.xml)** + + +~~~~~~~ + +<struts> + <package name="employee" extends="struts-default, json-default" namespace="/employee"> + + <action name="list" method="list" class="org.apache.struts2.showcase.action.EmployeeAction" > + <result>/empmanager/listEmployees.jsp</result> + <result type="json"> + <param name="root">employees</param> + </result> + </action> + + </package> +</struts> + +~~~~~~~ \ No newline at end of file http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/parameter-filter-interceptor.md ---------------------------------------------------------------------- diff --git a/source/core-developers/parameter-filter-interceptor.md b/source/core-developers/parameter-filter-interceptor.md new file mode 100644 index 0000000..be7d0c5 --- /dev/null +++ b/source/core-developers/parameter-filter-interceptor.md @@ -0,0 +1,43 @@ +--- +layout: core-developers +title: Parameter Filter Interceptor +--- + +# Parameter Filter Interceptor + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.interceptor.ParameterFilterInterceptor} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.interceptor.ParameterFilterInterceptor} +~~~~~~~ + +#####Example##### + + + +~~~~~~~ + +<interceptors> + ... + <interceptor name="parameterFilter" class="com.opensymphony.xwork2.interceptor.ParameterFilterInterceptor"/> + ... +</interceptors> + +<action ....> + ... + <interceptor-ref name="parameterFilter"> + <param name="blocked">person,person.address.createDate,personDao</param> + </interceptor-ref> + ... +</action> + +~~~~~~~ + http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/parameters-interceptor.md ---------------------------------------------------------------------- diff --git a/source/core-developers/parameters-interceptor.md b/source/core-developers/parameters-interceptor.md new file mode 100644 index 0000000..7f50afa --- /dev/null +++ b/source/core-developers/parameters-interceptor.md @@ -0,0 +1,228 @@ +--- +layout: core-developers +title: Parameters Interceptor +--- + +# Parameters Interceptor + +This interceptor sets all parameters on the value stack\. + +This interceptor gets all parameters from \{@link ActionContext\#getParameters()\} and sets them on the value stack by calling + +~~~~~~~ +ValueStack#setValue(String, Object) +~~~~~~~ +, typically resulting in the values submitted in a form request being applied to an action in the value stack\. Note that the parameter map must contain a String key and often containers a String\[\] for the value\. + +The interceptor takes one parameter named 'ordered'\. When set to true action properties are guaranteed to be set top\-down which means that top action's properties are set first\. Then it's subcomponents properties are set\. The reason for this order is to enable a 'factory' pattern\. For example, let's assume that one has an action that contains a property named + +~~~~~~~ +modelClass +~~~~~~~ + that allows to choose what is the underlying implementation of model\. By assuring that + +~~~~~~~ +modelClass +~~~~~~~ + property is set before any model properties are set, it's possible to choose model implementation during + +~~~~~~~ +action.setModelClass() +~~~~~~~ + call\. Similarly it's possible to use + +~~~~~~~ +action.setPrimaryKey() +~~~~~~~ +property set call to actually load the model class from persistent storage\. Without any assumption on parameter order you have to use patterns like _Preparable Interface_ \. + +Because parameter names are effectively OGNL statements, it is important that security be taken in to account\. This interceptor will not apply any values in the parameters map if the expression contains an assignment (=), multiple expressions (,), or references any objects in the context (\#)\. This is all done in the + +~~~~~~~ +#acceptableName(String) +~~~~~~~ + method\. In addition to this method, if the action being invoked implements the + +~~~~~~~ +ParameterNameAware +~~~~~~~ + interface, the action will be consulted to determine if the parameter should be set\. +In addition to these restrictions, a flag ( + +~~~~~~~ +ReflectionContextState#DENY_METHOD_EXECUTION +~~~~~~~ + ) is set such that no methods are allowed to be invoked\. That means that any expression such as + +~~~~~~~ +person.doSomething() +~~~~~~~ + or + +~~~~~~~ +person.getName() +~~~~~~~ + will be explicitly forbidden\. This is needed to make sure that your application is not exposed to attacks by malicious users\. + +While this interceptor is being invoked, a flag ( + +~~~~~~~ +ReflectionContextState#CREATE_NULL_OBJECTS +~~~~~~~ + ) is turned on to ensure that any null reference is automatically created \- if possible\. See the type conversion documentation and the + +~~~~~~~ +InstantiatingNullHandler +~~~~~~~ + javadocs for more information\. + +Finally, a third flag ( + +~~~~~~~ +XWorkConverter#REPORT_CONVERSION_ERRORS +~~~~~~~ + ) is set that indicates any errors when converting the the values to their final data type (String\[\] \-> int) an unrecoverable error occurred\. With this flag set, the type conversion errors will be reported in the action context\. See the type conversion documentation and the + +~~~~~~~ +XWorkConverter +~~~~~~~ + javadocs for more information\. + +If you are looking for detailed logging information about your parameters, turn on + +~~~~~~~ +DEBUG +~~~~~~~ + level logging for this interceptor\. A detailed log of all the parameter keys and values will be reported\. + + + +Since XWork 2\.0\.2, this interceptor extends MethodFilterInterceptor, therefore being able to deal with excludeMethods / includeMethods parameters\. See [Default Workflow Interceptor](default-workflow-interceptor.html) for documentation and examples on how to use this feature\. + +| + +For more information on ways to restrict the parameter names allowed, see the + +~~~~~~~ +ParameterNameAware +~~~~~~~ + javadocs\. + +#####Parameters##### + ++ + +~~~~~~~ +ordered +~~~~~~~ + \- set to true if you want the top\-down property setter behaviour + ++ + +~~~~~~~ +acceptParamNames +~~~~~~~ + \- a comma delimited list of regular expressions to describe a whitelist of accepted parameter names\. Don't change the default unless you know what you are doing in terms of security implications + ++ + +~~~~~~~ +excludeParams +~~~~~~~ + \- a comma delimited list of regular expressions to describe a blacklist of not allowed parameter names + ++ + +~~~~~~~ +paramNameMaxLength +~~~~~~~ + \- the maximum length of parameter names; parameters with longer names will be ignored; the default is 100 characters + +#####Excluding parameters##### + +This interceptor can be forced to ignore parameters, by setting its _excludeParams_ attribute\. This attribute accepts a comma separated list of regular expressions\. When any of these expressions match the name of a parameter, such parameter will be ignored by the interceptor\. Interceptor stacks defined by Struts already exclude some parameters: + +**Default List of Parameters Excluded** + + +~~~~~~~ +dojo\..*,^struts\..*,^session\..*,^request\..*,^application\..*,^servlet(Request|Response)\..*,parameters\...* + +~~~~~~~ + +Below is an example of adding a parameter named submit to the list of parameters that should be excluded\. + +**Setup Interceptor Stack To Exclude submit Parameter** + + +~~~~~~~ +<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> +</interceptors> + +<default-interceptor-ref name="appDefault" /> + +~~~~~~~ + +#####Extending the Interceptor##### + +The best way to add behavior to this interceptor is to utilize the + +~~~~~~~ +ParameterNameAware +~~~~~~~ + interface in your actions\. However, if you wish to apply a global rule that isn't implemented in your action, then you could extend this interceptor and override the + +~~~~~~~ +#acceptableName(String) +~~~~~~~ + method\. + + +> + +> + +> Using ParameterNameAware could be dangerous as ParameterNameAware\#acceptableParameterName(String) takes precedence over ParametersInterceptor which means if ParametersInterceptor excluded given parameter name you can accept it with ParameterNameAware\#acceptableParameterName(String)\. + +> + +> + +> The best idea is to define very tight restrictions with ParametersInterceptor and relax them per action with ParameterNameAware\#acceptableParameterName(String) + +> + +#####Warning on missing parameters##### + +When there is no setter for given parameter name, a warning message like below will be logged in devMode: + + +~~~~~~~ +SEVERE: Developer Notification (set struts.devMode to false to disable this message): +Unexpected Exception caught setting 'search' on 'class demo.ItemSearchAction: Error setting expression 'search' with value ['search', ] +Error setting expression 'search' with value ['search', ] - [unknown location] + at com.opensymphony.xwork2.ognl.OgnlValueStack.handleRuntimeException(OgnlValueStack.java:201) + at com.opensymphony.xwork2.ognl.OgnlValueStack.setValue(OgnlValueStack.java:178) + at com.opensymphony.xwork2.ognl.OgnlValueStack.setParameter(OgnlValueStack.java:152) + +~~~~~~~ + +Thus is expected behaviour to allow developer to spot missing setter or typo in either parameter name or setter\. + +#####Examples##### + + + +~~~~~~~ +<action name="someAction" class="com.examples.SomeAction"> + <interceptor-ref name="params"/> + <result name="success">good_result.ftl</result> +</action> +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/parent-package-annotation.md ---------------------------------------------------------------------- diff --git a/source/core-developers/parent-package-annotation.md b/source/core-developers/parent-package-annotation.md new file mode 100644 index 0000000..fd4a8c8 --- /dev/null +++ b/source/core-developers/parent-package-annotation.md @@ -0,0 +1,28 @@ +--- +layout: core-developers +title: ParentPackage Annotation +--- + +# ParentPackage Annotation + +The + +~~~~~~~ +@ParentPackage +~~~~~~~ + annotation allows the definition of + +~~~~~~~ +Action +~~~~~~~ +'s package for an action found via [Zero Configuration](zero-configuration.html)\. + +#####Usage##### + +This annotation is placed at the class level\. + +#####Parameters##### + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| value | String | true | Names the package the action will inherit\. | http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/performance-tuning.md ---------------------------------------------------------------------- diff --git a/source/core-developers/performance-tuning.md b/source/core-developers/performance-tuning.md new file mode 100644 index 0000000..42de03c --- /dev/null +++ b/source/core-developers/performance-tuning.md @@ -0,0 +1,73 @@ +--- +layout: core-developers +title: Performance Tuning +--- + +# Performance Tuning + +####Performance tuning#### + +The following are some tips and tricks to squeeze the most performance out of Struts 2\. + + + +| For Struts 2 versions before 2\.3: the OGNL version 3\.0\.3 library is a drop\-in replacement for older OGNL jars, and provides **much** better performance\. See the following Jira issue for more information: [https://issues\.apache\.org/jira/browse/WW\-3580](https://issues\.apache\.org/jira/browse/WW\-3580) + +| + +#####Turn off logging and devMode\.##### + +[devMode](development-mode.html) allows reloading of configuration and validation related files, but because they happen on each request, this setting will totally kill your performance\. + When using logging, make sure to turn off logging (esp\. Freemarker generates a LOT of logging), and check if a level is enabled before printing it, or you will get the cost of the String parsing/concatination anyways\. + +#####Use the Java Templates##### + +If you use the simple theme, and do not overwrite any of the FreeMarker templates, consider using the _java templates_ , which provide a drop in replacement for most tags, and are a lot faster than the regular tags\. + +#####Do not use interceptors you do not need\.##### + +If you do not require a full stack of interceptors for an Action, then try using a different one (basicStack), or remove interceptors you do not need\. Remove the I18nInterceptor interceptor if you don't need it, as it can cause a session to be created\. + +#####Use the correct HTTP headers (Cache\-Control & Expires)\.##### + +When returning HTML views, make sure to add the correct headers so browsers know how to cache them\. + +#####Copy the static content from the Struts 2 jar when using the Ajax theme (Dojo) or the Calendar tag\.##### + +Struts 2 uses some external javascript libraries and cascading stylesheets for certain themes and tags\. These by default are located inside the Struts 2 jar, and a special filter returns them when requesting a special path (/struts)\. Although Struts 2 can handle these requests, an application/servlet container is not optimized for these kind of requests\. Consider moving these \.js and \.css files to a seperated server (Lighttpd, Apache HTTPD, \.\.)\. + +#####Create a freemarker\.properties file in your WEB\-INF/classes directory\.##### + +Create the freemarker\.properties file and add the following setting (or whatever value you deem fitting): + + +~~~~~~~ +template_update_delay=60000 + +~~~~~~~ + +This value determines how often Freemarker checks if it needs to reloads the templates from disk\. The default value is 500 ms\. Since there is no reason to check if a template needs reloading, it is best to set this to a very large value\. Note that this value is in seconds and freemarker will convert this value to milliseconds\. + +You can also use _struts\.freemarker\.templatesCache\.updateDelay_ constant to achieve the same effect\. + +See also: [Freemarker configuration properties](http://freemarker\.sourceforge\.net/docs/api/freemarker/template/Configuration\.html\#setSetting(java\.lang\.String,%20java\.lang\.String))^[http://freemarker\.sourceforge\.net/docs/api/freemarker/template/Configuration\.html\#setSetting(java\.lang\.String,%20java\.lang\.String)] + +#####Enable Freemarker template caching##### + +As of Struts 2\.0\.10, setting the property _struts\.freemarker\.templatesCache_ to true will enable the Struts internal caching of Freemarker templates\. This property is set to false by default\. + +In Struts versions prior to 2\.0\.10, you had to copy the /template directory from the Struts 2 jar in your WEB\_APP root to utilize Freemarker's built in chaching mechanism in order to achieve similar results\. + +The built in Freemarker caching mechanism fails to properly cache templates when they are retrieved from the classpath\. Copying them to the WEB\_APP root allows Freemarker to cache them correctly\. Freemarker looks at the last modified time of the template to determine if it needs to reload the templates\. Resources retrieved from the classpath have no last modified time, so Freemarker will reload them on every request\. + +#####When overriding a theme, copy all necessary templates to the theme directory\.##### + +There's a performance cost when a template cannot be found in the current directory\. The reason for this is that Struts 2 must check for a template in the current theme first before falling back to the parent theme\. In the future, this penalty could be eliminated by implementing a missing template cache in Struts 2\. + +#####Do not create sessions unless you need them\.##### + +Struts 2 does not create sessions unless asked to (for example, by having the createSession interceptor in your interceptor stack)\. Note that when you use SiteMesh however, a session will **always** be created (See [http://forums\.opensymphony\.com/thread\.jspa?messageID=5688](http://forums\.opensymphony\.com/thread\.jspa?messageID=5688) for details)\. The I18nInterceptor interceptor can create sessions, so make sure you remove it, if you don't need it\. + +#####When using Freemarker, try to use the Freemarker equivalent rather than using the JSP tags\.##### + +Freemarker has support for iterating lists, displaying properties, including other templates, macro's, and so on\. There is a small performance cost when using the S2 tags instead of the Freemarker equivalent (eg\. \<s:property value="foo"/\> should be replaced by \$\{foo\})\. http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/plaintext-result.md ---------------------------------------------------------------------- diff --git a/source/core-developers/plaintext-result.md b/source/core-developers/plaintext-result.md new file mode 100644 index 0000000..74777fe --- /dev/null +++ b/source/core-developers/plaintext-result.md @@ -0,0 +1,28 @@ +--- +layout: core-developers +title: PlainText Result +--- + +# PlainText Result + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=org.apache.struts2.dispatcher.PlainTextResult} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=params|javadoc=true|url=org.apache.struts2.dispatcher.PlainTextResult} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.dispatcher.PlainTextResult} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/postback-result.md ---------------------------------------------------------------------- diff --git a/source/core-developers/postback-result.md b/source/core-developers/postback-result.md new file mode 100644 index 0000000..baae824 --- /dev/null +++ b/source/core-developers/postback-result.md @@ -0,0 +1,30 @@ +--- +layout: core-developers +title: Postback Result +--- + +# Postback Result + +####Description#### + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=org.apache.struts2.dispatcher.PostbackResult} +~~~~~~~ + +####Parameters#### + + + +~~~~~~~ +{snippet:id=params|javadoc=true|url=org.apache.struts2.dispatcher.PostbackResult} +~~~~~~~ + +####Examples#### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.dispatcher.PostbackResult} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/pre-result-listener.md ---------------------------------------------------------------------- diff --git a/source/core-developers/pre-result-listener.md b/source/core-developers/pre-result-listener.md new file mode 100644 index 0000000..44d106c --- /dev/null +++ b/source/core-developers/pre-result-listener.md @@ -0,0 +1,55 @@ +--- +layout: core-developers +title: PreResultListener +--- + +# PreResultListener + +A PreResultListener can affect an action invocation between the interceptor/action phase and the result phase\. Typical uses include switching to a different Result or somehow modifying the Result or Action objects before the Result executes\. + +####Examples#### + +A PreResultListener can be added by an Action or an Interceptor\. + +#####By an Action##### + + + +~~~~~~~ + + public class MyAction extends ActionSupport { + ... + public String execute() throws Exception { + ActionInvocation invocation = ActionContext.getContext().getActionInvocation(); + invocation.addPreResultListener(new PreResultListener() { + public void beforeResult(ActionInvocation invocation, + String resultCode) { + // perform operation necessary before Result execution + } + }); + } + ... + } + +~~~~~~~ + +#####By an Interceptor##### + + + +~~~~~~~ + + public class MyInterceptor extends AbstractInterceptor { + ... + public String intercept(ActionInvocation invocation) throws Exception { + invocation.addPreResultListener(new PreResultListener() { + public void beforeResult(ActionInvocation invocation, + String resultCode) { + // perform operation necessary before Result execution + } + }); + } + ... + } + +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/prepare-interceptor.md ---------------------------------------------------------------------- diff --git a/source/core-developers/prepare-interceptor.md b/source/core-developers/prepare-interceptor.md new file mode 100644 index 0000000..8114096 --- /dev/null +++ b/source/core-developers/prepare-interceptor.md @@ -0,0 +1,41 @@ +--- +layout: core-developers +title: Prepare Interceptor +--- + +# Prepare Interceptor + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.interceptor.PrepareInterceptor} +~~~~~~~ + + +~~~~~~~ +{snippet:id=javadocPrepareInterceptor|javadoc=true|url=com.opensymphony.xwork2.interceptor.PrefixMethodInvocationUtil} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.interceptor.PrepareInterceptor} +~~~~~~~ + +#####Extending the Interceptor##### + + + +~~~~~~~ +{snippet:id=extending|javadoc=true|url=com.opensymphony.xwork2.interceptor.PrepareInterceptor} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=com.opensymphony.xwork2.interceptor.PrepareInterceptor} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/pure-java-script-client-side-validation.md ---------------------------------------------------------------------- diff --git a/source/core-developers/pure-java-script-client-side-validation.md b/source/core-developers/pure-java-script-client-side-validation.md new file mode 100644 index 0000000..6bb74b9 --- /dev/null +++ b/source/core-developers/pure-java-script-client-side-validation.md @@ -0,0 +1,49 @@ +--- +layout: core-developers +title: Pure JavaScript Client Side Validation +--- + +# Pure JavaScript Client Side Validation#### {#PAGE_14262} + +Pure JavaScript client side validation is the simplest but least feature\-rich type of [Client Side Validation](client-side-validation.html). +This type of validation uses 100% client\-side JavaScript code to try to validate the values entered by the user. +Because the validation logic is actually repeated in the JavaScript code, it is important to understand that +some values will be considered acceptable by the JavaScript code but will be marked as unacceptable by the server\-side [Validation](validation.html). + + +~~~~~~~ +{snippet:id=supported-validators|url=struts2/core/src/main/resources/template/xhtml/form-close-validate.ftl} +~~~~~~~ + + +> + +> + +> JavaScript client validation is not available for visitor validations\. + +> + +__Error reporting__ + +Because client side validation does not talk to the server, the theme (_xhtml theme_ or _css\_xhtml theme_ ) is responsible for properly manipulating the HTML DOM to display the error message inline\. The JavaScript that is responsible for doing this logic is + +~~~~~~~ +validation.js +~~~~~~~ + and can be found in each theme\. + + + +| Errors are reported using the default validation message, not the internationalized version that the server\-side might be aware of\. This is a known issue\. You may want to try the [AJAX Client Side Validation](ajax-client-side-validation.html) for messages that are fully internationalized\. + +| + +__Additional Validator Support__ + +If you wish to add additional validator support beyond those listed, you may override the _xhtml theme_ teamplte + +~~~~~~~ +form-close-validate.ftl +~~~~~~~ +\. This file contains the JavaScript that tries to validate each user\-entered value from within the browswer\. The _css\_xhtml theme_ extends the _xhtml theme_ and therefore doesn't have it's own form\-close\-validate\.ftl template\. http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/redirect-action-result.md ---------------------------------------------------------------------- diff --git a/source/core-developers/redirect-action-result.md b/source/core-developers/redirect-action-result.md new file mode 100644 index 0000000..ed7a123 --- /dev/null +++ b/source/core-developers/redirect-action-result.md @@ -0,0 +1,57 @@ +--- +layout: core-developers +title: Redirect Action Result +--- + +# Redirect Action Result + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=org.apache.struts2.result.ServletActionRedirectResult} +~~~~~~~ + + +See [ActionMapper](action-mapper.html) for more details + +| + +####Parameters#### + + + +~~~~~~~ +{snippet:id=params|javadoc=true|url=org.apache.struts2.result.ServletActionRedirectResult} +~~~~~~~ + +####Examples#### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.result.ServletActionRedirectResult} +~~~~~~~ + + + +~~~~~~~ +<!-- + Example of "anchor" param usage in conjunction with "redirectAction" result-type. + + Generated URL: /displayReport.action#SUMMARY +--> + +<action name="displayReport"> + <result>/jsp/displayReport.jsp</result> +</action> + +<action name="financeReport" class="com.mycompany.reports.FinanceReportAction"> + <result name="input">/jsp/index.jsp</result> + <result name="success" type="redirectAction"> + <param name="actionName">displayReport</param> + <param name="parse">false</param> + <param name="anchor">SUMMARY</param> + </result> +</action> + +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/redirect-result.md ---------------------------------------------------------------------- diff --git a/source/core-developers/redirect-result.md b/source/core-developers/redirect-result.md new file mode 100644 index 0000000..82d3d59 --- /dev/null +++ b/source/core-developers/redirect-result.md @@ -0,0 +1,51 @@ +--- +layout: core-developers +title: Redirect Result +--- + +# Redirect Result + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=org.apache.struts2.result.ServletRedirectResult} +~~~~~~~ + +####Parameters#### + + + +~~~~~~~ +{snippet:id=params|javadoc=true|url=org.apache.struts2.result.ServletRedirectResult} +~~~~~~~ + +####Examples#### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.result.ServletRedirectResult} +~~~~~~~ + + + +~~~~~~~ +<package name="passingRequestParameters" extends="struts-default" namespace="/passingRequestParameters"> + <-- Pass parameters (reportType, width and height) --> + <!-- + The redirect url generated will be - the namespace of current acction will be appended as location doesn't start with "/": + /passingRequestParameters/generateReport.jsp?reportType=pie&width=100&height=100#summary + --> + <action name="gatherReportInfo" class="..."> + <result name="showReportResult" type="redirect"> + <param name="location">generateReport.jsp</param> + <param name="reportType">pie</param> + <param name="width">100</param> + <param name="height">100</param> + <param name="parse">false</param> + <param name="anchor">summary</param> + </result> + </action> +</package> + +~~~~~~~ \ No newline at end of file http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/regex-field-validator-annotation.md ---------------------------------------------------------------------- diff --git a/source/core-developers/regex-field-validator-annotation.md b/source/core-developers/regex-field-validator-annotation.md new file mode 100644 index 0000000..8b16b3c --- /dev/null +++ b/source/core-developers/regex-field-validator-annotation.md @@ -0,0 +1,36 @@ +--- +layout: core-developers +title: RegexFieldValidator Annotation +--- + +# RegexFieldValidator Annotation + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.RegexFieldValidator} +~~~~~~~ + +#####Usage##### + + + +~~~~~~~ +{snippet:id=usage|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.RegexFieldValidator} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.RegexFieldValidator} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|javadoc=true|lang=java|url=com.opensymphony.xwork2.validator.annotations.RegexFieldValidator} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/regex-validator.md ---------------------------------------------------------------------- diff --git a/source/core-developers/regex-validator.md b/source/core-developers/regex-validator.md new file mode 100644 index 0000000..17018a7 --- /dev/null +++ b/source/core-developers/regex-validator.md @@ -0,0 +1,35 @@ +--- +layout: core-developers +title: regex validator +--- + +# regex validator + +####Description#### + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RegexFieldValidator} +~~~~~~~ + +####Parameters#### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RegexFieldValidator} +~~~~~~~ + +**(\!) Warning** + + +> \{snippet:id=parameters\-warning|javadoc=true|url=com\.opensymphony\.xwork2\.validator\.validators\.RegexFieldValidator\} + +####Examples#### + + + +~~~~~~~ +{snippet:id=example|javadoc=true|lang=xml|url=com.opensymphony.xwork2.validator.validators.RegexFieldValidator} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/reloading-configuration.md ---------------------------------------------------------------------- diff --git a/source/core-developers/reloading-configuration.md b/source/core-developers/reloading-configuration.md new file mode 100644 index 0000000..55f91b7 --- /dev/null +++ b/source/core-developers/reloading-configuration.md @@ -0,0 +1,19 @@ +--- +layout: core-developers +title: Reloading configuration +--- + +# Reloading configuration + +Struts allows for dynamic reloading of xml configuration file (ie, reloading actions\.xml)\. + +This allows you to reconfigure your action mapping during development\. There may be a slight performance penalty, so this is not recommended for production use\. + +In order to enable this feature, add the following to your struts\.properties file: + + +~~~~~~~ + +struts.configuration.xml.reload=true + +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/required-field-validator-annotation.md ---------------------------------------------------------------------- diff --git a/source/core-developers/required-field-validator-annotation.md b/source/core-developers/required-field-validator-annotation.md new file mode 100644 index 0000000..fc1886c --- /dev/null +++ b/source/core-developers/required-field-validator-annotation.md @@ -0,0 +1,35 @@ +--- +layout: core-developers +title: RequiredFieldValidator Annotation +--- + +# RequiredFieldValidator Annotation + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.RequiredFieldValidator} +~~~~~~~ + +#####Usage##### + + + +~~~~~~~ +{snippet:id=usage|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.RequiredFieldValidator} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.RequiredFieldValidator} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|javadoc=true|lang=java|url=com.opensymphony.xwork2.validator.annotations.RequiredFieldValidator} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/required-string-validator-annotation.md ---------------------------------------------------------------------- diff --git a/source/core-developers/required-string-validator-annotation.md b/source/core-developers/required-string-validator-annotation.md new file mode 100644 index 0000000..d7554a7 --- /dev/null +++ b/source/core-developers/required-string-validator-annotation.md @@ -0,0 +1,36 @@ +--- +layout: core-developers +title: RequiredStringValidator Annotation +--- + +# RequiredStringValidator Annotation + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.RequiredStringValidator} +~~~~~~~ + +#####Usage##### + + + +~~~~~~~ +{snippet:id=usage|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.RequiredStringValidator} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.RequiredStringValidator} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|javadoc=true|lang=java|url=com.opensymphony.xwork2.validator.annotations.RequiredStringValidator} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/required-validator.md ---------------------------------------------------------------------- diff --git a/source/core-developers/required-validator.md b/source/core-developers/required-validator.md new file mode 100644 index 0000000..ede31e0 --- /dev/null +++ b/source/core-developers/required-validator.md @@ -0,0 +1,30 @@ +--- +layout: core-developers +title: required validator +--- + +# required validator + +####Description#### + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RequiredFieldValidator} +~~~~~~~ + +####Parameters#### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RequiredFieldValidator} +~~~~~~~ + +####Examples#### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RequiredFieldValidator} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/requiredstring-validator.md ---------------------------------------------------------------------- diff --git a/source/core-developers/requiredstring-validator.md b/source/core-developers/requiredstring-validator.md new file mode 100644 index 0000000..bb6c7d8 --- /dev/null +++ b/source/core-developers/requiredstring-validator.md @@ -0,0 +1,30 @@ +--- +layout: core-developers +title: requiredstring validator +--- + +# requiredstring validator + +####Description#### + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RequiredStringValidator} +~~~~~~~ + +####Parameters#### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RequiredStringValidator} +~~~~~~~ + +####Examples#### + + + +~~~~~~~ +{snippet:id=examples|lang=xml|javadoc=true|url=com.opensymphony.xwork2.validator.validators.RequiredStringValidator} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/restful-action-mapper.md ---------------------------------------------------------------------- diff --git a/source/core-developers/restful-action-mapper.md b/source/core-developers/restful-action-mapper.md new file mode 100644 index 0000000..67147ca --- /dev/null +++ b/source/core-developers/restful-action-mapper.md @@ -0,0 +1,184 @@ +--- +layout: core-developers +title: RestfulActionMapper +--- + +# RestfulActionMapper + + +A custom action mapper using the following format: + + +~~~~~~~ +http://HOST/ACTION_NAME/PARAM_NAME1/PARAM_VALUE1/PARAM_NAME2/PARAM_VALUE2 +~~~~~~~ + +You can have as many parameters you'd like to use\. Alternatively the URL can be shortened to the following: + + +~~~~~~~ +http://HOST/ACTION_NAME/PARAM_VALUE1/PARAM_NAME2/PARAM_VALUE2 +~~~~~~~ + +This is the same as: + + +~~~~~~~ +http://HOST/ACTION_NAME/ACTION_NAME + "Id"/PARAM_VALUE1/PARAM_NAME2/PARAM_VALUE2 +~~~~~~~ + +Suppose for example we would like to display some articles by id at using the following URL sheme: + + +~~~~~~~ +http://HOST/article/Id +~~~~~~~ + +Your action just needs a setArticleId() method, and requests such as /article/1, /article/2, etc will all map to that URL pattern\. + +#####Restful2ActionMapper##### + +Improved restful action mapper that adds several ReST\-style improvements to action mapping, but supports fully\-customized URL's via XML\. The two primary REST enhancements are: + ++ If the method is not specified (via '\!' or 'method:' prefix), the method is "guessed" at using ReST\-style conventions that examine the URL and the HTTP method\. + ++ Parameters are extracted from the action name, if parameter name/value pairs are specified using PARAM\_NAME/PARAM\_VALUE syntax\. + +These two improvements allow a GET request for 'category/action/movie/Thrillers' to be mapped to the action name 'movie' with an id of 'Thrillers' with an extra parameter named 'category' with a value of 'action'\. A single action mapping can then handle all CRUD operations using wildcards, e\.g\. + + +~~~~~~~ + +<action name="movie/*" className="app.MovieAction"> + <param name="id">{1}</param> + ... +</action> + +~~~~~~~ + +This mapper supports the following parameters: + ++ _struts\.mapper\.idParameterName_ \- if set, this value will be the name of the parameter under which the id is stored\. The id will then be removed from the action name\. This allows restful actions to not require wildcards\. + +The following URL's will invoke its methods: + +|Request |method called| +|---------------------------|-------------| +| GET: /movie/ |method="index" | +| GET: /movie/Thrillers | method="view", id="Thrillers" | +| GET: /movie/Thrillers\!edit | method="edit", id="Thrillers" | +| GET: /movie/new | method="editNew" | +| POST: /movie/ | method="create" | +| PUT: /movie/Thrillers | method="update", id="Thrillers" | +| DELETE: /movie/Thrillers | method="remove", id="Thrillers" | + +To simulate the HTTP methods PUT and DELETE, since they aren't supported by HTML, the HTTP parameter "\_\_http\_method" will be used\. + +The syntax and design for this feature was inspired by the REST support in Ruby on Rails\. See [Simple RESTful support](http://ryandaigle\.com/articles/2006/08/01/whats\-new\-in\-edge\-rails\-simply\-restful\-support\-and\-how\-to\-use\-it)^[http://ryandaigle\.com/articles/2006/08/01/whats\-new\-in\-edge\-rails\-simply\-restful\-support\-and\-how\-to\-use\-it] + +__Example__ + +To use the Restful2ActionMapper in an existing struts application we have to change the strus\.mapper\.class constant and let it point to the Restful2ActionMapper + + +~~~~~~~ + +<constant name="struts.mapper.class" value="org.apache.struts2.dispatcher.mapper.Restful2ActionMapper" /> + +~~~~~~~ + +The problem with the above approach is that we may break existing actions because the Restful2ActionMapper tries to guess the method name using conventions that aren't applicable to normal action classes\. + +To overcome the above problem, we have to use a different action mapper depending on the url we want to process\. REST actions will be processed by the Restful2ActionMapper and non\-REST actions by the DefaultActionMapper + +To achieve that we have to rely on namespaces and the PrefixBasedActionMapper that can choose which action mapper to use for a particular url based on a prefix (the action namespace)\. + +To put everything together, we create a package for our rest actions + + +~~~~~~~ + +<package name="rest" namespace="/rest" extends="struts-default"> + ....interceptor config + <action name="movie/*" class="app.MovieAction"> + <param name="id">{1}</param> + ....results + </action> + .... +</package> + +~~~~~~~ + +All other actions remain in their existing packages and namespaces we use the PrefixBasedActionMapper telling it to use the Restful2ActionMapper for actions in the /rest namespace and the DefaultActionMapper for all other actions + + +~~~~~~~ + +<constant name="struts.mapper.class" value="org.apache.struts2.dispatcher.mapper.PrefixBasedActionMapper" /> +<constant name="struts.mapper.prefixMapping" value="/rest:restful2,:struts" /> + +~~~~~~~ + +For the Restful2ActionMapper to work we also have to set + + +~~~~~~~ + +<constant name="struts.enable.SlashesInActionNames" value="true" /> +<constant name="struts.mapper.alwaysSelectFullNamespace" value="false" /> + +~~~~~~~ + +__Unit testing__ + +Below you will find a simple unit test to test how to test actions when + +~~~~~~~ +Restful2ActionMapper +~~~~~~~ + is used\. + + +~~~~~~~ + +public class MovieActionTest extends StrutsJUnit4TestCase<MovieActionTest>{ + + @Before + public void setUp() throws Exception { + //assumes Basic authentication + super.setUp(); + String credentials = "username:password"; + request.addHeader("authorization", "BASIC " + Base64.encodeBase64String(credentials.getBytes())); + } + + @Test + public void testIndex() throws Exception { + request.setMethod("get"); //Http method should be set + + ActionProxy proxy = getActionProxy("/rest/movie/"); + + proxy.setExecuteResult(false); + String result = proxy.execute(); + + //assertions ... + } + + @Test + public void testView() throws Exception { + request.setMethod("get"); //Http method should be set + + ActionProxy proxy = getActionProxy("/rest/movie/1"); + MovieAction movieAction = MovieAction.class.cast(proxy.getAction()); + + proxy.setExecuteResult(false); + + String result = proxy.execute(); + //assertions ... + assertEquals("1", movieAction.getId()); + } +} + +~~~~~~~ + +Thanks to Antonios Gkogkakis for the examples\! + http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/result-annotation.md ---------------------------------------------------------------------- diff --git a/source/core-developers/result-annotation.md b/source/core-developers/result-annotation.md new file mode 100644 index 0000000..15d49ae --- /dev/null +++ b/source/core-developers/result-annotation.md @@ -0,0 +1,197 @@ +--- +layout: core-developers +title: Result Annotation +--- + +# Result Annotation + +The + +~~~~~~~ +@Result +~~~~~~~ + annotation allows the definition of + +~~~~~~~ +Action +~~~~~~~ + results in the + +~~~~~~~ +Action +~~~~~~~ + class rather than an XML file\. + + + +| The @Result annotation lives at the Action_class_ level and not the method level\. This matches what is found in an XML\-based Action configuration\. **Do not be tempted to annotate your Action's methods; it will not work\.** + +| + +In order for + +~~~~~~~ +@Result +~~~~~~~ + and + +~~~~~~~ +@Results +~~~~~~~ + annotations to be configured correctly you must set the + +~~~~~~~ +actionPackages +~~~~~~~ + filter + +~~~~~~~ +init-param +~~~~~~~ + to a comma\-separated list of packages containing the annotated + +~~~~~~~ +Action +~~~~~~~ + classes\. See [Zero Configuration](zero-configuration.html) for further information; there are + +~~~~~~~ +Action +~~~~~~~ + class naming conventions if you don't implement the + +~~~~~~~ +Action +~~~~~~~ + interface and other tidbits there\. + +#####@Result Annotation Parameters##### + + + +~~~~~~~ +{float:right|width=300px} + {info} + See org.apache.struts2.config.Result annotation JavaDocs. + {info} +{float} +~~~~~~~ + ++ name \- Result name; default + +~~~~~~~ +Action.SUCCESS +~~~~~~~ + ++ value \- Value of result (result destination) + ++ type \- Type of result; default + +~~~~~~~ +NullResult +~~~~~~~ +\. For example: + + + + + +~~~~~~~ +NullResult.class +~~~~~~~ + + + + +~~~~~~~ +FreemarkerResult.class +~~~~~~~ + + + + +~~~~~~~ +PlainTextResult.class +~~~~~~~ + + + + +~~~~~~~ +VelocityResult.class +~~~~~~~ + + + + +~~~~~~~ +ServletDispatcherResult.class +~~~~~~~ + + + + +~~~~~~~ +ServletRedirectResult.class +~~~~~~~ + + + + +~~~~~~~ +ServletActionRedirectResult.class +~~~~~~~ + \- equivalent to the + +~~~~~~~ +redirectAction +~~~~~~~ + type in XML config + + + + +~~~~~~~ +TilesResult.class +~~~~~~~ + + + \.\. (for more result, please consult the API docs, and look for implementations of the XWork + +~~~~~~~ +Result +~~~~~~~ + interface) + ++ params \- An Array of the parameters in the form \{key1, value1, key2, value2\} + +#####@Result â Defining a Single Result##### + +Map the "success" result (explicitly named) to a Tile definition named "/home\.page"\. + +**Defining a Single Result** + + +~~~~~~~ + +@Result(name="success", value="/home.page", type=TilesResult.class) +public class HomeAction extends ActionSupport { + // ... +} + +~~~~~~~ + +#####@Results â Defining Multiple Results##### + +Defines a set of results for an + +~~~~~~~ +Action +~~~~~~~ +\. + +**Defining Multiple Results** + + +~~~~~~~ + +@Results({ + @Result(name="success", value="/home.page", type=TilesResult.class), + @Result(name="homeError", value="/homeError.page", type=TilesResult.class) +}) +public class HomeAction extends ActionSupport { + // .... +} + +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/result-configuration.md ---------------------------------------------------------------------- diff --git a/source/core-developers/result-configuration.md b/source/core-developers/result-configuration.md new file mode 100644 index 0000000..64b14bf --- /dev/null +++ b/source/core-developers/result-configuration.md @@ -0,0 +1,272 @@ +--- +layout: core-developers +title: Result Configuration +--- + +# Result Configuration + + +When an _action_ class method completes, it returns a String\. The value of the String is used to select a result element\. An action mapping will often have a set of results representing different possible outcomes\. A standard set of result tokens are defined by the + +~~~~~~~ +ActionSupport +~~~~~~~ + base class\. + +**Predefined result names** + + +~~~~~~~ +String SUCCESS = "success"; +String NONE = "none"; +String ERROR = "error"; +String INPUT = "input"; +String LOGIN = "login"; + +~~~~~~~ + +Of course, applications can define other result tokens to match specific cases\. + +(information) Returning + +~~~~~~~ +ActionSupport.NONE +~~~~~~~ + (or + +~~~~~~~ +null +~~~~~~~ +) from an _action_ class method causes the results processing to be skipped\. This is useful if the action fully handles the result processing such as writing directly to the HttpServletResponse OutputStream\. + +#####Result Elements##### + +The result element has two jobs\. First, it provides a logical name\. An + +~~~~~~~ +Action +~~~~~~~ + can pass back a token like "success" or "error" without knowing any other implementation details\. Second, the result element provides a result type\. Most results simply forward to a server page or template, but other [Result Types](result-types.html) can be used to do more interesting things\. + +__Intelligent Defaults__ + +Each package may set a default result type to be used if none is specified in a result element\. If one package extends another, the "child" package can set its own default result, or inherit one from the parent\. + +**Setting a default Result Type** + + +~~~~~~~ +<result-types> + <result-type name="dispatcher" default="true" + class="org.apache.struts2.dispatcher.ServletDispatcherResult" /> +</result-types> +~~~~~~~ + +If a + +~~~~~~~ +type +~~~~~~~ + attribute is not specified, the framework will use the default + +~~~~~~~ +dispatcher +~~~~~~~ + type, which forwards to another web resource\. If the resource is a JavaServer Page, then the container will render it, using its JSP engine\. + +Likewise if the + +~~~~~~~ +name +~~~~~~~ + attribute is not specified, the framework will give it the name "success"\. + +Using these intelligent defaults, the most often used result types also become the simplest\. + +**Result element without defaults** + + +~~~~~~~ +<result name="success" type="dispatcher"> + <param name="location">/ThankYou.jsp</param> +</result> + +~~~~~~~ + +**A Result element using some defaults** + + +~~~~~~~ +<result> + <param name="location">/ThankYou.jsp</param> +</result> + +~~~~~~~ + +The + +~~~~~~~ +param +~~~~~~~ + tag sets a property on the Result object\. The most commonly\-set property is + +~~~~~~~ +location +~~~~~~~ +, which usually specifies the path to a web resources\. The + +~~~~~~~ +param +~~~~~~~ + attribute is another intelligent default\. + +**Result element using more defaults** + + +~~~~~~~ +<result>/ThankYou.jsp</result> + +~~~~~~~ + +Mixing results with intelligent defaults with other results makes it easier to see the "critical path"\. + +**Multiple Results** + + +~~~~~~~ +<action name="Hello"> + <result>/hello/Result.jsp</result> + <result name="error">/hello/Error.jsp</result> + <result name="input">/hello/Input.jsp</result> +</action> + +~~~~~~~ + +A special 'other' result can be configured by adding a result with name="\*"\. This result will only be selected if no result is found with a matching name\. + +**'\*' Other Result** + + +~~~~~~~ +<action name="Hello"> + <result>/hello/Result.jsp</result> + <result name="error">/hello/Error.jsp</result> + <result name="input">/hello/Input.jsp</result> + <result name="*">/hello/Other.jsp</result> +</action> + +~~~~~~~ + +(information) The name="\*" is **not** a wildcard pattern, it is a special name that is only selected if an exact match is not found\. + + (\!) In most cases if an action returns an unrecognized result name this would be a programming error and should be fixed\. + +__Multiple names__ + +It is possible to define multiple names for the same result: + + +~~~~~~~ +<action name="save"> + <result>success.jsp</result> + <result name="error, input">input-form.jsp</result> +</action> +~~~~~~~ + +Such functionality was added in Struts 2\.5 + +#####Global Results##### + +Most often, results are nested with the action element\. But some results apply to multiple actions\. In a secure application, a client might try to access a page without being authorized, and many actions may need access to a "logon" result\. + +If actions need to share results, a set of global results can be defined for each package\. The framework will first look for a local result nested in the action\. If a local match is not found, then the global results are checked\. + +**Defining global results** + + +~~~~~~~ +<global-results> + <result name="error">/Error.jsp</result> + <result name="invalid.token">/Error.jsp</result> + <result name="login" type="redirectAction">Logon!input</result> +</global-results> + +~~~~~~~ + +(light\-on) For more about results, see [Result Types](result-types.html). + +#####Dynamic Results##### + +A result may not be known until execution time\. Consider the implementation of a state\-machine\-based execution flow; the next state might depend on any combination of form input elements, session attributes, user roles, moon phase, etc\. In other words, determining the next action, input page, etc\. may not be known at configuration time\. + +Result values may be retrieved from its corresponding Action implementation by using EL expressions that access the Action's properties, just like the Struts 2 tag libraries\. So given the following Action fragment: + +**FragmentAction implementation** + + +~~~~~~~ +private String nextAction; + +public String getNextAction() { + return nextAction; +} + +~~~~~~~ + +you might define a result like this: + +**FragmentAction configuration** + + +~~~~~~~ +<action name="fragment" class="FragmentAction"> + <result name="next" type="redirectAction">${nextAction}</result> +</action> + +~~~~~~~ + +If a + +~~~~~~~ +FragmentAction +~~~~~~~ + method returns "next" the actual _value_ of that result will be whatever is in + +~~~~~~~ +FragmentAction +~~~~~~~ +'s + +~~~~~~~ +nextAction +~~~~~~~ + property\. So + +~~~~~~~ +nextAction +~~~~~~~ + may be computed based on whatever state information necessary then passed at runtime to "next"'s + +~~~~~~~ +redirectAction +~~~~~~~ +\. + +See _Parameters in configuration results_ for an expanded discussion\. + + + +#####Returning Result Objects##### + +Instead of configuring results and returning the name, it is possible to return a result object: + + +~~~~~~~ +public Result runAction() { + ServletDispatcherResult result = new ServletDispatcherResult(); + result.setLocation("input-form.jsp"); + return result; +} +~~~~~~~ + + http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/result-types.md ---------------------------------------------------------------------- diff --git a/source/core-developers/result-types.md b/source/core-developers/result-types.md new file mode 100644 index 0000000..08880ff --- /dev/null +++ b/source/core-developers/result-types.md @@ -0,0 +1,111 @@ +--- +layout: core-developers +title: Result Types +--- + +# Result Types + +Most use cases can be divided into two phases\. First, we need to change or query the application's state, and then we need to present an updated view of the application\. The Action class manages the application's state, and the Result Type manages the view\. + +####Predefined Result Types#### + +The framework provides several implementations of the + +~~~~~~~ +com.opensymphony.xwork2.Result +~~~~~~~ + interface, ready to use in your own applications\. + +|[Chain Result](chain-result.html)|Used for [Action Chaining](action-chaining.html)| +|---------------------------|---------------------------------------| +|[Dispatcher Result](dispatcher-reult.html)|Used for web resource integration, including _JSP_ integration| +|[FreeMarker Result](freemarker-result.html)|Used for _FreeMarker_ integration| +|[HttpHeader Result](httpheader-result.html)|Used to control special HTTP behaviors| +|[Redirect Result](redirect-result.html)|Used to redirect to another URL (web resource)| +|[Redirect Action Result](redirect-action-result.html)|Used to redirect to another action mapping| +|[Stream Result](stream-result.html)|Used to stream an InputStream back to the browser (usually for file downloads)| +|[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 2 Result_ |Used to provide Tiles 2 integration| +|_Tiles 3 Result_ |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_ |Used to serialize actions into JSON| + +#####Optional##### + +|_JasperReports Plugin_ |Used for _JasperReports Tutorial_ integration|Optional, third\-party plugin| +|-----------------------|----------------------------------------------|-----------------------------| + +Additional Result Types can be created and plugged into an application by implementing the + +~~~~~~~ +com.opensymphony.xwork2.Result +~~~~~~~ + interface\. Custom Result Types might include generating an email or JMS message, generating images, and so forth\. + +####Default Parameters#### + +To minimize configuration, Results can be configured with a single value, which will be converted into a parameter, and each Result can specify which parameter this value should be set as\. For example, here is a result defined in XML that uses a default parameter: + + +~~~~~~~ +<result type="freemarker">foo.fm</result> + +~~~~~~~ + +That is the equivalent to this: + + +~~~~~~~ +<result type="freemarker"> + <param name="location">foo.vm</param> +</result> + +~~~~~~~ + +Since probably 95% of your actions won't need results that contain multiple parameters, this little shortcut saves you a significant amount of configuration\. It also follows that if you have specified the default parameter, you don't need to set the same parameter as a specifically\-named parameter\. + +####Registering Result Types#### + +All Result Types are plugged in via the [Result Configuration](result-configuration.html). + +#####Extending##### + +You can always extend defined result types and implement whatever logic you need\. To simplify process of that, you can define your custom + +~~~~~~~ +ResultFactory +~~~~~~~ + and use it with connection with custom interface which your Result implements\. Check [Define dedicated factory](object-factory.html) to see how to do it\. + +Struts 2 provides one such extension for you: + +~~~~~~~ +ParamNameAwareResult +~~~~~~~ + interface when used with + +~~~~~~~ +StrutsResultBuilder +~~~~~~~ + can limit parameters assigned to the result\. So you can simple extend existing result with such a functionality as below: + + +~~~~~~~ +public class MyResult extends ServletDispatcherResult implements ParamNameAwareResult { + + public boolean acceptableParamName(String name, String value) { + return "accept".equals(name); + } + +} + +~~~~~~~ + +and then register it and use instead of default + +~~~~~~~ +dispatcher +~~~~~~~ + result\. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/roles-interceptor.md ---------------------------------------------------------------------- diff --git a/source/core-developers/roles-interceptor.md b/source/core-developers/roles-interceptor.md new file mode 100644 index 0000000..cc9b5d8 --- /dev/null +++ b/source/core-developers/roles-interceptor.md @@ -0,0 +1,28 @@ +--- +layout: core-developers +title: Roles Interceptor +--- + +# Roles Interceptor + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=org.apache.struts2.interceptor.RolesInterceptor} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=org.apache.struts2.interceptor.RolesInterceptor} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.interceptor.RolesInterceptor} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/scope-interceptor.md ---------------------------------------------------------------------- diff --git a/source/core-developers/scope-interceptor.md b/source/core-developers/scope-interceptor.md new file mode 100644 index 0000000..d9f3494 --- /dev/null +++ b/source/core-developers/scope-interceptor.md @@ -0,0 +1,65 @@ +--- +layout: core-developers +title: Scope Interceptor +--- + +# Scope Interceptor + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=org.apache.struts2.interceptor.ScopeInterceptor} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=org.apache.struts2.interceptor.ScopeInterceptor} +~~~~~~~ + +#####Extending the Interceptor##### + + + +~~~~~~~ +{snippet:id=extending|javadoc=true|url=org.apache.struts2.interceptor.ScopeInterceptor} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.interceptor.ScopeInterceptor} +~~~~~~~ + +__Some more examples__ + +The scope interceptor can be used to pass arbitrary objects from one action ActionA to another other ActionB, provided you have a getter in ActionA and and a similar setter in actionB\. Also, you should use a key parameter to make sure you tell ASF/WW which action gets which objects\. This allows you to mix several actions with several scopes, without running the risk of getting wrong objects\. + + +~~~~~~~ + <action name="scopea" class="com.mevipro.test.action.ScopeActionA"> + <result name="success" type="dispatcher">/jsp/test.jsp</result> + <interceptor-ref name="basicStack"/> + <interceptor-ref name="scope"> + <param name="key">funky</param> + <param name="session">person</param> + <param name="autoCreateSession">true</param> + </interceptor-ref> + </action> + <action name="scopeb" class="com.mevipro.test.action.ScopeActionB"> + <result name="success" type="dispatcher">/jsp/test.jsp</result> + <interceptor-ref name="scope"> + <param name="key">funky</param> + <param name="session">person</param> + <param name="autoCreateSession">true</param> + </interceptor-ref> + <interceptor-ref name="basicStack"/> + </action> + +~~~~~~~ + +Don't forget: you'll need at least a getPerson() getter in ScopeActionA and a setPerson(Person person) setter in ScopeActionB, ánd you need to make sure you specify the key (you don't need this if you only use one action, as in the example above)\. Without the key, the scope interceptor will store your variables, but won't set them on the other action\. http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/scoped-model-driven-interceptor.md ---------------------------------------------------------------------- diff --git a/source/core-developers/scoped-model-driven-interceptor.md b/source/core-developers/scoped-model-driven-interceptor.md new file mode 100644 index 0000000..a3e9bc9 --- /dev/null +++ b/source/core-developers/scoped-model-driven-interceptor.md @@ -0,0 +1,36 @@ +--- +layout: core-developers +title: Scoped Model Driven Interceptor +--- + +# Scoped Model Driven Interceptor + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.interceptor.ScopedModelDrivenInterceptor} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.interceptor.ScopedModelDrivenInterceptor} +~~~~~~~ + +#####Extending the Interceptor##### + + + +~~~~~~~ +{snippet:id=extending|javadoc=true|url=com.opensymphony.xwork2.interceptor.ScopedModelDrivenInterceptor} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=com.opensymphony.xwork2.interceptor.ScopedModelDrivenInterceptor} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/servlet-config-interceptor.md ---------------------------------------------------------------------- diff --git a/source/core-developers/servlet-config-interceptor.md b/source/core-developers/servlet-config-interceptor.md new file mode 100644 index 0000000..d8f28b6 --- /dev/null +++ b/source/core-developers/servlet-config-interceptor.md @@ -0,0 +1,36 @@ +--- +layout: core-developers +title: Servlet Config Interceptor +--- + +# Servlet Config Interceptor + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=org.apache.struts2.interceptor.ServletConfigInterceptor} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=org.apache.struts2.interceptor.ServletConfigInterceptor} +~~~~~~~ + +#####Extending the Interceptor##### + + + +~~~~~~~ +{snippet:id=extending|javadoc=true|url=org.apache.struts2.interceptor.ServletConfigInterceptor} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.interceptor.ServletConfigInterceptor} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/short-validator.md ---------------------------------------------------------------------- diff --git a/source/core-developers/short-validator.md b/source/core-developers/short-validator.md new file mode 100644 index 0000000..5825307 --- /dev/null +++ b/source/core-developers/short-validator.md @@ -0,0 +1,35 @@ +--- +layout: core-developers +title: short validator +--- + +# short validator + +####Description#### + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator.validators.ShortRangeFieldValidator} +~~~~~~~ + +####Parameters#### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.validators.ShortRangeFieldValidator} +~~~~~~~ + +**(\!) Warning** + + +> \{snippet:id=parameters\-warning|javadoc=true|url=com\.opensymphony\.xwork2\.validator\.validators\.ShortRangeFieldValidator\} + +####Examples#### + + + +~~~~~~~ +{snippet:id=example|javadoc=true|lang=xml|url=com.opensymphony.xwork2.validator.validators.ShortRangeFieldValidator} +~~~~~~~
