http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/static-content.md ---------------------------------------------------------------------- diff --git a/source/core-developers/static-content.md b/source/core-developers/static-content.md new file mode 100644 index 0000000..4d1ad28 --- /dev/null +++ b/source/core-developers/static-content.md @@ -0,0 +1,93 @@ +--- +layout: core-developers +title: Static Content +--- + +# Static Content + +Struts can serve static content like css and javascript files\. This feature is enabled by default, but can be disabled by setting: + + +~~~~~~~ + +<constant name="struts.serve.static" value="false" /> + +~~~~~~~ + + +> + +> + +> If you disable this feature, but use the xhtml, or css\_xhtml theme, make sure that the javascript and css files shipped inside the core jar are extracted to your web application directory\. + +> + +#####Custom Static Content Loaders##### + +Static content is served by an implementation of + +~~~~~~~ +org.apache.struts2.dispatcher.StaticContentLoader +~~~~~~~ +\. To write your own + +~~~~~~~ +StaticContentLoader +~~~~~~~ +, implement + +~~~~~~~ +StaticContentLoader +~~~~~~~ + and define a bean for the class: + + +~~~~~~~ + +<bean type="org.apache.struts2.dispatcher.StaticContentLoader" class="MyStaticContentLoader" name="myLoader" /> +<constant name="struts.staticContentLoader" value="myLoader" /> + +~~~~~~~ + +#####Default Content Loader##### + +Struts provides a default implementation of + +~~~~~~~ +StaticContentLoader +~~~~~~~ + which is + +~~~~~~~ +org.apache.struts2.dispatcher.DefaultStaticContentLoader +~~~~~~~ +\. This loader will handle urls that start with "/static/"\. + +This content loader can serve static content from the classpath, so when writing a plugin, you can put a file inside your plugin's jar like "/static/image/banner\.jpg" and it will be served when the url "/static/image/banner\.jpg" is requested\. + + + +| This loader is not optimized to handle static content, and to improve performance, it is recommended that you extract your static content to the web application directory, and let the container handle them\. + +| + +#####Preventing Struts from Handling a Request##### + +If there is a request that Struts is handling as an action, and you wish to make Struts ignore it, you can do so by specifying a comma separated list of regular expressions like: + + +~~~~~~~ + +<constant name="struts.action.excludePattern" value="/some/conent/.*?" /> + +~~~~~~~ + +These regular expression will be evaluated against the request's URI ( + +~~~~~~~ +HttpServletRequest.getRequestURI() +~~~~~~~ +), and if any of them matches, then Struts will not handle the request\. + +To evaluate each pattern Pattern class from JDK will be used, you can find more about what kind of pattern you can use in the [Pattern class JavaDoc](http://docs\.oracle\.com/javase/1\.5\.0/docs/api/java/util/regex/Pattern\.html)^[http://docs\.oracle\.com/javase/1\.5\.0/docs/api/java/util/regex/Pattern\.html]\.
http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/static-parameters-interceptor.md ---------------------------------------------------------------------- diff --git a/source/core-developers/static-parameters-interceptor.md b/source/core-developers/static-parameters-interceptor.md new file mode 100644 index 0000000..1d33257 --- /dev/null +++ b/source/core-developers/static-parameters-interceptor.md @@ -0,0 +1,36 @@ +--- +layout: core-developers +title: Static Parameters Interceptor +--- + +# Static Parameters Interceptor + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.interceptor.StaticParametersInterceptor} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.interceptor.StaticParametersInterceptor} +~~~~~~~ + +#####Extending the Interceptor##### + + + +~~~~~~~ +{snippet:id=extending|javadoc=true|url=com.opensymphony.xwork2.interceptor.StaticParametersInterceptor} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=com.opensymphony.xwork2.interceptor.StaticParametersInterceptor} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/stream-result.md ---------------------------------------------------------------------- diff --git a/source/core-developers/stream-result.md b/source/core-developers/stream-result.md new file mode 100644 index 0000000..c5abb4b --- /dev/null +++ b/source/core-developers/stream-result.md @@ -0,0 +1,158 @@ +--- +layout: core-developers +title: Stream Result +--- + +# Stream Result + +A custom Result type for sending raw data (via an InputStream) directly to the HttpServletResponse\. Very useful for allowing users to download content\. + + + +| If you are running your app server under HTTPS and having issues with PDF's or other file streams you should take a look at [HTTPS and IE Issues](https-and-ie-issues.html) + +| + +####Parameters#### + ++ **contentType** \- the stream mime\-type as sent to the web browser (default = + +~~~~~~~ +text/plain +~~~~~~~ +)\. + ++ **contentLength** \- the stream length in bytes (the browser displays a progress bar)\. + ++ **contentDisposition** \- the content disposition header value for specifying the file name (default = + +~~~~~~~ +inline +~~~~~~~ +, values are typically _attachment;filename="document\.pdf"_ \. + ++ **inputName **\- the name of the InputStream property from the chained action (default = **inputStream**)\. + ++ **bufferSize **\- the size of the buffer to copy from input to output (default = + +~~~~~~~ +1024 +~~~~~~~ +)\. + ++ **allowCaching** \- if set to 'false' it will set the headers + +~~~~~~~ +Pragma +~~~~~~~ + and + +~~~~~~~ +Cache-Control +~~~~~~~ + to + +~~~~~~~ +no-cahce +~~~~~~~ +, and prevent client from caching the content (default = + +~~~~~~~ +true +~~~~~~~ +)\. + ++ **contentCharSet** \- if set to a string, ';charset=value' will be added to the content\-type header, where value is the string set\. If set to an expression, the result of evaluating the expression will be used\. If not set, then no charset will be set on the header + +These parameters can also be set by exposing a similarly named getter method on your Action\. For example, you can provide + +~~~~~~~ +getContentType() +~~~~~~~ + to override that parameter for the current action\. To do it you you must explicitly define this param as an expression i\.e\. + +**parameter defined as an expression** + + +~~~~~~~ +<param name="contentType">${contentType}</param> +~~~~~~~ + + + +| Please be aware that this was changed since Struts 2\.5\.2, previously each parameter was automagically resolved by looking throughout the ValueStack, now you must explicitly define wich parameter must be evaluated, even inputName\. + +| + +####Examples#### + +#####Annotation based Configuration##### + +To configure Actions and Results with Annotations you need to activate the Struts2 _Convention Plugin_ in your Struts2 application\. + + +~~~~~~~ +package com.mycompany.webapp.actions; + +import java.io.File; +import java.io.FileInputStream; +import java.io.InputStream; + +import org.apache.struts2.convention.annotation.Result; + +import com.opensymphony.xwork2.Action; +import com.opensymphony.xwork2.ActionSupport; + +@Result( + name = "success", + type = "stream", + params = { + "contentType", "${type}", + "inputName", "${stream}", + "bufferSize", "1024", + "contentDisposition", "attachment;filename=\"${filename}\"" + } +) +public class FileDisplay extends ActionSupport { + + private String type = "image/jpeg"; + private String filename; + private InputStream stream; + + public String execute() throws Exception { + + filename = "myimage.jpg"; + File img = new File("/path/to/image/image.jpg"); + stream = new FileInputStream(img); + + return Action.SUCCESS; + } + + private String getType() { + return this.type; + } + + private String getFilename() { + return this.filename; + } + + private String getStream() { + return this.stream; + } +} + +~~~~~~~ + +#####XML based Configuration##### + +**Example configuration** + + +~~~~~~~ +<result name="success" type="stream"> + <param name="contentType">image/jpeg</param> + <param name="inputName">${imageStream}</param> + <param name="contentDisposition">attachment;filename="document.pdf"</param> + <param name="bufferSize">1024</param> +</result> +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/string-length-field-validator-annotation.md ---------------------------------------------------------------------- diff --git a/source/core-developers/string-length-field-validator-annotation.md b/source/core-developers/string-length-field-validator-annotation.md new file mode 100644 index 0000000..29badcc --- /dev/null +++ b/source/core-developers/string-length-field-validator-annotation.md @@ -0,0 +1,36 @@ +--- +layout: core-developers +title: StringLengthFieldValidator Annotation +--- + +# StringLengthFieldValidator Annotation + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.StringLengthFieldValidator} +~~~~~~~ + +#####Usage##### + + + +~~~~~~~ +{snippet:id=usage|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.StringLengthFieldValidator} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.StringLengthFieldValidator} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|javadoc=true|lang=java|url=com.opensymphony.xwork2.validator.annotations.StringLengthFieldValidator} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/stringlength-validator.md ---------------------------------------------------------------------- diff --git a/source/core-developers/stringlength-validator.md b/source/core-developers/stringlength-validator.md new file mode 100644 index 0000000..bcc9088 --- /dev/null +++ b/source/core-developers/stringlength-validator.md @@ -0,0 +1,35 @@ +--- +layout: core-developers +title: stringlength validator +--- + +# stringlength validator + +####Description#### + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator.validators.StringLengthFieldValidator} +~~~~~~~ + +####Parameters#### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.validators.StringLengthFieldValidator} +~~~~~~~ + +**(\!) Warning** + + +> \{snippet:id=parameters\-warning|javadoc=true|url=com\.opensymphony\.xwork2\.validator\.validators\.StringLengthFieldValidator\} + +####Examples#### + + + +~~~~~~~ +{snippet:id=example|javadoc=true|lang=xml|url=com.opensymphony.xwork2.validator.validators.StringLengthFieldValidator} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/struts-default-vm.md ---------------------------------------------------------------------- diff --git a/source/core-developers/struts-default-vm.md b/source/core-developers/struts-default-vm.md new file mode 100644 index 0000000..a4775fa --- /dev/null +++ b/source/core-developers/struts-default-vm.md @@ -0,0 +1,38 @@ +--- +layout: core-developers +title: struts-default.vm +--- + +# struts-default.vm + +If Velocity is being use, the + +~~~~~~~ +struts-default.vm +~~~~~~~ + supplies some VelocityMacros that might be useful\. + +**struts\-default\.vm** + + +~~~~~~~ + +#macro(bean $bean_name $name) + #set ($name = $action.bean($bean_name)) +#end + +#macro(includeservlet $name) + $action.include($name,$req,$res) +#end + +#macro(url $name) + #set ($name = $action.bean("org.apache.struts.util.URLBean")) + $name.setRequest($req) + $name.setResponse($res) +#end + +#macro(property $object $property) +$!{ognl.findValue($property, $object)} +#end + +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/struts-default-xml.md ---------------------------------------------------------------------- diff --git a/source/core-developers/struts-default-xml.md b/source/core-developers/struts-default-xml.md new file mode 100644 index 0000000..9b65c14 --- /dev/null +++ b/source/core-developers/struts-default-xml.md @@ -0,0 +1,38 @@ +--- +layout: core-developers +title: struts-default.xml +--- + +# struts-default.xml + +A base configuration file named + +~~~~~~~ +struts-default.xml +~~~~~~~ + is included in the + +~~~~~~~ +struts2.jar +~~~~~~~ + file\. This file is automatically included into + +~~~~~~~ +struts.xml +~~~~~~~ + file to provide the standard configuration settings without having to copy them\. + + + +| To exclude the struts\-default\.xml or to provide your own version, see the struts\.configuration\.files setting in [struts.properties](struts-properties.html)\. + +| + +The contents of struts\-default\.xml are here: + + +~~~~~~~ +{snippet:id=all|lang=xml|url=struts2/core/src/main/resources/struts-default.xml} +~~~~~~~ + +This file defines all of the default bundled results and interceptors and many interceptor stacks which you can use either as\-is or as a basis for your own application\-specific interceptor stacks\. **Notice the name of the package is "struts\-default"**\. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/struts-properties.md ---------------------------------------------------------------------- diff --git a/source/core-developers/struts-properties.md b/source/core-developers/struts-properties.md new file mode 100644 index 0000000..b0bc6df --- /dev/null +++ b/source/core-developers/struts-properties.md @@ -0,0 +1,37 @@ +--- +layout: core-developers +title: struts.properties +--- + +# struts.properties + + (ok) All properties can also be set using [Constant Configuration](#PAGE_29602) in an XML configuration file\. + +The framework uses a number of properties that can be changed to fit your needs\. To change any of these properties, specify the property key and value in an + +~~~~~~~ +struts.properties +~~~~~~~ + file\. The properties file can be locate anywhere on the classpath, but it is typically found under + +~~~~~~~ +/WEB-INF/classes +~~~~~~~ + +The list of properties can be found in + +~~~~~~~ +struts-default.properties +~~~~~~~ + (inside + +~~~~~~~ +struts2.jar +~~~~~~~ +)\. + +**struts\-default\.properties** + + +> \{snippet:lang=none|id=complete\_file|url=struts2/core/src/main/resources/org/apache/struts2/default\.properties\} + http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/struts-xml.md ---------------------------------------------------------------------- diff --git a/source/core-developers/struts-xml.md b/source/core-developers/struts-xml.md new file mode 100644 index 0000000..de06daa --- /dev/null +++ b/source/core-developers/struts-xml.md @@ -0,0 +1,30 @@ +--- +layout: core-developers +title: struts.xml +--- + +# struts.xml + +The core configuration file for the framework is the default ( + +~~~~~~~ +struts.xml +~~~~~~~ +) file and should reside on the classpath of the webapp (generally + +~~~~~~~ +/WEB-INF/classes +~~~~~~~ +)\. + ++ The default file may include other configuration files as needed\. + ++ A + +~~~~~~~ +struts-plugin.xml +~~~~~~~ + file can be placed in a JAR and automatically plugged into an application, so that modules can be self\-contained and automatically configured\. + + + + In the case of Freemarker and Velocity modules, the templates can also be loaded from the classpath, so the entire module can be plugged in as a single JAR\. http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/sunone-7-0.md ---------------------------------------------------------------------- diff --git a/source/core-developers/sunone-7-0.md b/source/core-developers/sunone-7-0.md new file mode 100644 index 0000000..c855143 --- /dev/null +++ b/source/core-developers/sunone-7-0.md @@ -0,0 +1,53 @@ +--- +layout: core-developers +title: SunOne 7.0 +--- + +# SunOne 7.0 + +To use SunOne wkith the framework, you will need to grant the appropriate permissions\. You can simply grant all permissions, or just the specific permissions the framework needs\. + +#####Granting All Permissions##### + + + +~~~~~~~ + +grant { + permission java.security.AllPermission; +}; + +~~~~~~~ + +#####Granting Specific Permissions##### + ++ Grant Write Permissions to + +~~~~~~~ +java.util.PropertyPermission +~~~~~~~ + ++ Add + +~~~~~~~ +java.lang.reflect.ReflectPermission +~~~~~~~ + "suppressAccessChecks" + ++ Grant all permissions to + +~~~~~~~ +OgnlInvokePermission +~~~~~~~ + + + +~~~~~~~ + +grant { + permission java.util.PropertyPermission "*", "read, write"; + permission java.lang.reflect.ReflectPermission "suppressAccessChecks"; + permission ognl.OgnlInvokePermission "*"; +}; + +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/timer-interceptor.md ---------------------------------------------------------------------- diff --git a/source/core-developers/timer-interceptor.md b/source/core-developers/timer-interceptor.md new file mode 100644 index 0000000..a7e059d --- /dev/null +++ b/source/core-developers/timer-interceptor.md @@ -0,0 +1,36 @@ +--- +layout: core-developers +title: Timer Interceptor +--- + +# Timer Interceptor + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.interceptor.TimerInterceptor} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.interceptor.TimerInterceptor} +~~~~~~~ + +#####Extending the Interceptor##### + + + +~~~~~~~ +{snippet:id=extending|javadoc=true|url=com.opensymphony.xwork2.interceptor.TimerInterceptor} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=com.opensymphony.xwork2.interceptor.TimerInterceptor} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/token-interceptor.md ---------------------------------------------------------------------- diff --git a/source/core-developers/token-interceptor.md b/source/core-developers/token-interceptor.md new file mode 100644 index 0000000..6dab330 --- /dev/null +++ b/source/core-developers/token-interceptor.md @@ -0,0 +1,37 @@ +--- +layout: core-developers +title: Token Interceptor +--- + +# Token Interceptor + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=org.apache.struts2.interceptor.TokenInterceptor} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=org.apache.struts2.interceptor.TokenInterceptor} +~~~~~~~ + +#####Extending the Interceptor##### + + + +~~~~~~~ +{snippet:id=extending|javadoc=true|url=org.apache.struts2.interceptor.TokenInterceptor} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.interceptor.TokenInterceptor} +~~~~~~~ + http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/token-session-interceptor.md ---------------------------------------------------------------------- diff --git a/source/core-developers/token-session-interceptor.md b/source/core-developers/token-session-interceptor.md new file mode 100644 index 0000000..7b1bf2b --- /dev/null +++ b/source/core-developers/token-session-interceptor.md @@ -0,0 +1,36 @@ +--- +layout: core-developers +title: Token Session Interceptor +--- + +# Token Session Interceptor + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=org.apache.struts2.interceptor.TokenSessionStoreInterceptor} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=org.apache.struts2.interceptor.TokenSessionStoreInterceptor} +~~~~~~~ + +#####Extending the Interceptor##### + + + +~~~~~~~ +{snippet:id=extending|javadoc=true|url=org.apache.struts2.interceptor.TokenSessionStoreInterceptor} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.interceptor.TokenSessionStoreInterceptor} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/type-conversion-annotation.md ---------------------------------------------------------------------- diff --git a/source/core-developers/type-conversion-annotation.md b/source/core-developers/type-conversion-annotation.md new file mode 100644 index 0000000..e14dc6b --- /dev/null +++ b/source/core-developers/type-conversion-annotation.md @@ -0,0 +1,36 @@ +--- +layout: core-developers +title: TypeConversion Annotation +--- + +# TypeConversion Annotation + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.conversion.annotations.TypeConversion} +~~~~~~~ + +#####Usage##### + + + +~~~~~~~ +{snippet:id=usage|javadoc=true|url=com.opensymphony.xwork2.conversion.annotations.TypeConversion} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.conversion.annotations.TypeConversion} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|javadoc=true|lang=java|url=com.opensymphony.xwork2.conversion.annotations.TypeConversion} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/type-conversion.md ---------------------------------------------------------------------- diff --git a/source/core-developers/type-conversion.md b/source/core-developers/type-conversion.md new file mode 100644 index 0000000..6fbe165 --- /dev/null +++ b/source/core-developers/type-conversion.md @@ -0,0 +1,533 @@ +--- +layout: core-developers +title: Type Conversion +--- + +# Type Conversion + +Routine type conversion in the framework is transparent\. Generally, all you need to do is ensure that HTML inputs have names that can be used in _OGNL_ expressions\. (HTML inputs are form elements and other GET/POST parameters\.) + +####Built in Type Conversion Support#### + +Type Conversion is implemented by XWork\. + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.conversion.impl.XWorkBasicConverter} +~~~~~~~ + ++ Enumerations + ++ BigDecimal and BigInteger + +####Relationship to Parameter Names#### + +There is no need to capture form values using intermediate Strings and primitives\. Instead, the framework can read from and write to properties of objects addressed via OGNL expressions and perform the appropriate type conversion for you\. + +Here are some tips for leveraging the framework's type conversion capabilities: + ++ Use OGNL expressions \- the framework will automatically take care of creating the actual objects for you\. + ++ Use JavaBeans\! The framework can only create objects that obey the JavaBean specification, provide no\-arg constructions and include getters and setters where appropriate\. + ++ Remember that _person\.name_ will call **getPerson()\.setName()**\. If the framework creates the Person object for you, it remember that a + +~~~~~~~ +setPerson +~~~~~~~ + method must also exist\. + ++ The framework will not instantiate an object if an instance already exists\. The PrepareInterceptor or action's constructor can be used to create target objects before type conversion\. + ++ For lists and maps, use index notation, such as _people\[0\]\.name_ or _friends\['patrick'\]\.name_ \. Often these HTML form elements are being rendered inside a loop\. For _JSP Tags_ , use the iterator tag's status attribute\. For _FreeMarker Tags_ , use the special property \$\{foo\_index\}\[\]\. + ++ For multiple select boxes, it isn't possible to use index notation to name each individual item\. Instead, name your element _people\.name_ and the framework will understand that it should create a new Person object for each selected item and set its name accordingly\. + +####Creating a Type Converter#### + +Create a type converter by extending StrutsTypeConverter\. The Converter's role is to convert a String to an Object and an Object to a String\. + + +~~~~~~~ + + public class MyConverter extends StrutsTypeConverter { + public Object convertFromString(Map context, String[] values, Class toClass) { + ..... + } + + public String convertToString(Map context, Object o) { + ..... + } + } + +~~~~~~~ + + + +| To allow Struts to recognize that a conversion error has occurred, the converter class needs to throw XWorkException or preferably TypeConversionException\. + +| + +####Applying a Type Converter to an Action#### + +Create a file called 'ActionClassName\-conversion\.properties' in the same location of the classpath as the Action class itself resides\. + +Eg\. if the action class name is MyAction, the action\-level conversion properties file should be named 'MyAction\-conversion\.properties'\. If the action's package is com\.myapp\.actions the conversion file should also be in the classpath at /com/myapp/actions/\. + +Within the conversion file, name the action's property and the Converter to apply to it: + + +~~~~~~~ + +# syntax: <propertyName> = <converterClassName> +point = com.acme.PointConverter +person.phoneNumber = com.acme.PhoneNumberConverter + +~~~~~~~ + +Type conversion can also be specified via [Annotations](#PAGE_14017) within the action\. + +####Applying a Type Converter to a bean or model#### + +When getting or setting the property of a bean, the framework will look for "classname\-conversion\.properties" in the same location of the **classpath** as the target bean\. This is the same mechanism as used for actions\. + +**Example:** A custom converter is required for the Amount property of a Measurement bean\. The Measurement class cannot be modified as its located within one of the application's dependencies\. The action using Measurement implements ModelDriven\<Measurement\> so it cannot apply converters to the properties directly\. +**Solution:** The conversion file needs to be in the same location of the classpath as Measurement\. Create a directory in your source or resources tree matching the package of Measurement and place the converters file there\. + +eg\. for com\.acme\.measurements\.Measurement, create a file in the application source/resources at /com/acme/measurements/Measurement\-conversion\.properties: + + +~~~~~~~ + +# syntax: <propertyName>=<converterClassName> +amount=com.acme.converters.MyCustomBigDecimalConverter + +~~~~~~~ + +####Applying a Type Converter for an application#### + +Application\-wide converters can be specified in a file called xwork\-conversion\.properties located in the root of the classpath\. + + +~~~~~~~ + +# syntax: <type> = <converterClassName> +java.math.BigDecimal = com.acme.MyBigDecimalConverter + +~~~~~~~ + +####A Simple Example#### + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.conversion.impl.XWorkConverter} +~~~~~~~ + +\{snippet:id=i18n\-note|javadoc=true|url=com\.opensymphony\.xwork2\.conversion\.impl\.XWorkConverter\} + +The framework ships with a base helper class that simplifies converting to and from Strings, + +~~~~~~~ +org.apache.struts2.util.StrutsTypeConverter +~~~~~~~ +\. The helper class makes it easy to write type converters that handle converting objects to Strings as well as from Strings\. + +From the JavaDocs: + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=org.apache.struts2.util.StrutsTypeConverter} +~~~~~~~ + +####Advanced Type Conversion#### + +The framework also handles advanced type conversion cases, like null property handling and converting values in Maps and Collections, and type conversion error handling\. + +#####Null Property Handling##### + +Null property handling will automatically create objects where null references are found\. + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.conversion.impl.InstantiatingNullHandler} +~~~~~~~ + + +~~~~~~~ +{snippet:id=example|javadoc=true|url=com.opensymphony.xwork2.conversion.impl.InstantiatingNullHandler} +~~~~~~~ + +#####Collection and Map Support##### + +Collection and Map support provides intelligent null handling and type conversion for Java Collections\. + +The framework supports ways to discover the object type for elements in a collection\. The discover is made via an _ObjectTypeDeterminer_ \. A default implementation is provided with the framework\. The Javadocs explain how Map and Collection support is discovered in the + +~~~~~~~ +DefaultObjectTypeDeterminer +~~~~~~~ +\. + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.conversion.impl.DefaultObjectTypeDeterminer} +~~~~~~~ + +Additionally, you can create your own custom + +~~~~~~~ +ObjectTypeDeterminer +~~~~~~~ + by implementing the + +~~~~~~~ +ObjectTypeDeterminer +~~~~~~~ + interface\. There is also an optional ObjectTypeDeterminer that utilizes Java 5 generics\. See the [Annotations](#PAGE_14017) page for more information\. + +__Indexing a collection by a property of that collection__ + +It is also possible to obtain a unique element of a collection by passing the value of a given property of that element\. By default, the property of the element of the collection is determined in _Class_ \-conversion\.properties using + +~~~~~~~ +KeyProperty_xxx=yyy +~~~~~~~ +, where xxx is the property of the bean _Class_ that returns the collection and yyy is the property of the collection element that we want to index on\. + +For an example, see the following two classes: + +**MyAction\.java** + + +~~~~~~~ + +/** + * @return a Collection of Foo objects + */ +public Collection getFooCollection() +{ + return foo; +} + +~~~~~~~ + +**Foo\.java** + + +~~~~~~~ + +/** + * @return a unique identifier + */ +public Long getId() +{ + return id; +} + +~~~~~~~ + +To enable type conversion, put the instruction + +~~~~~~~ +KeyProperty_fooCollection=id +~~~~~~~ + in the + +~~~~~~~ +MyAction-conversion.properties +~~~~~~~ + file\. This technique allows use of the idiom + +~~~~~~~ +fooCollection(someIdValue) +~~~~~~~ + to obtain the Foo object with value + +~~~~~~~ +someIdValue +~~~~~~~ + in the Set + +~~~~~~~ +fooCollection +~~~~~~~ +\. For example, + +~~~~~~~ +fooCollection(22) +~~~~~~~ + would return the Foo object in the + +~~~~~~~ +fooCollection +~~~~~~~ + Collection whose + +~~~~~~~ +id +~~~~~~~ + property value was 22\. + +This technique is useful, because it ties a collection element directly to its unique identifier\. You are not forced to use an index\. You can edit the elements of a collection associated to a bean without any additional coding\. For example, parameter name + +~~~~~~~ +fooCollection(22).name +~~~~~~~ + and value + +~~~~~~~ +Phil +~~~~~~~ + would set name the Foo Object in the + +~~~~~~~ +fooCollection +~~~~~~~ + Collection whose + +~~~~~~~ +id +~~~~~~~ + property value was 22 to be Phil\. + +The framework automatically converts the type of the parameter sent in to the type of the key property using type conversion\. + +Unlike Map and List element properties, if + +~~~~~~~ +fooCollection(22) +~~~~~~~ + does not exist, it will not be created\. If you would like it created, use the notation + +~~~~~~~ +fooCollection.makeNew[index] +~~~~~~~ + where _index_ is an integer 0, 1, and so on\. Thus, parameter value pairs + +~~~~~~~ +fooCollection.makeNew[0]=Phil +~~~~~~~ + and + +~~~~~~~ +fooCollection.makeNew[1]=John +~~~~~~~ + would add two new Foo Objects to + +~~~~~~~ +fooCollection -- +~~~~~~~ + one with name property value + +~~~~~~~ +Phil +~~~~~~~ + and the other with name property value + +~~~~~~~ +John +~~~~~~~ +\. However, in the case of a Set, the + +~~~~~~~ +equals +~~~~~~~ + and + +~~~~~~~ +hashCode +~~~~~~~ + methods should be defined such that they don't only include the + +~~~~~~~ +id +~~~~~~~ + property\. Otherwise, one element of the null + +~~~~~~~ +id +~~~~~~~ + properties Foos to be removed from the Set\. + +####An advanced example for indexed Lists and Maps#### + +Here is the model bean used within the list\. The KeyProperty for this bean is the + +~~~~~~~ +id +~~~~~~~ + attribute\. + +**MyBean\.java** + + +~~~~~~~ + +public class MyBean implements Serializable { + + private Long id; + private String name; + + public Long getId() { + return id; + } + + public void setId(Long id) { + this.id = id; + } + + public String getName() { + return name; + } + + public void setName(String name) { + this.name = name; + } + + + public String toString() { + return "MyBean{" + + "id=" + id + + ", name='" + name + '\'' + + '}'; + } +} + +~~~~~~~ + +The Action has a + +~~~~~~~ +beanList +~~~~~~~ + attribute initialized with an empty ArrayList\. + +**MyBeanAction\.java** + + +~~~~~~~ + +public class MyBeanAction implements Action { + + private List beanList = new ArrayList(); + private Map beanMap = new HashMap(); + + public List getBeanList() { + return beanList; + } + + public void setBeanList(List beanList) { + this.beanList = beanList; + } + + public Map getBeanMap() { + return beanMap; + } + + public void setBeanMap(Map beanMap) { + this.beanMap = beanMap; + } + + public String execute() throws Exception { + return SUCCESS; + } +} + +~~~~~~~ + +These + +~~~~~~~ +conversion.properties +~~~~~~~ + tell the TypeConverter to use MyBean instances as elements of the List\. + +**MyBeanAction\-conversion\.properties** + + +~~~~~~~ + +KeyProperty_beanList=id +Element_beanList=MyBean +CreateIfNull_beanList=true + +~~~~~~~ + ++ When submitting this via a form, the + +~~~~~~~ +id +~~~~~~~ + value is used as KeyProperty for the MyBean instances in the beanList\. + ++ Notice the () notation\! Do not use \[\] notation, which is for Maps only\! + ++ The value for name will be set to the MyBean instance with this special id\. + ++ The List does not have null values added for unavailable id values\. This approach avoids the risk of OutOfMemoryErrors\! + +**MyBeanAction\.jsp** + + +~~~~~~~ + +<s:iterator value="beanList" id="bean"> + <stextfield name="beanList(%{bean.id}).name" /> +</s:iterator> + +~~~~~~~ + +####Type Conversion Error Handling#### + +Type conversion error handling provides a simple way to distinguish between an input _validation_ problem and an input _type conversion_ problem\. + + +~~~~~~~ +{snippet:id=error-reporting|javadoc=true|url=com.opensymphony.xwork2.conversion.impl.XWorkConverter} +~~~~~~~ + +There are two ways the error reporting can occur: + +1. Globally, using the [Conversion Error Interceptor](conversion-error-interceptor.html) + +2. On a per-field basis, using the [conversion validator](conversion-validator.html) + +By default, the conversion interceptor is included in + +~~~~~~~ + +~~~~~~~ + in the default stack\. To keep conversion errors from reporting globally, change the interceptor stack, and add additional validation rules\. + +####Common Problems#### + +#####Null and Blank Values##### + +Some properties cannot be set to null\. Primitives like boolean and int cannot be null\. If your action needs to or will accept null or blank values, use the object equivalents Boolean and Integer\. Similarly, a blank string "" cannot be set on a primitive\. At the time of writing, a blank string also cannot be set on a BigDecimal or BigInteger\. Use server\-side validation to prevent invalid values from being set on your properties (or handle the conversion errors appropriately)\. + +#####Interfaces##### + +The framework cannot instantiate an object if it can't determine an appropriate implementation\. It recognizes well\-known collection interfaces (List, Set, Map, etc) but cannot instantiate MyCustomInterface when all it sees is the interface\. In this case, instantiate the target implementation first (eg\. in a prepare method) or substitute in an implementation\. + +#####Generics and Erasure##### + +The framework will inspect generics to determine the appropriate type for collections and array elements\. However, in some cases Erasure can result in base types that cannot be converted (typically Object or Enum)\. + +The following is an example of this problem: + + +~~~~~~~ + +public abstract class Measurement<T extends Enum> + public void setUnits(T enumValue) {...} +} + +public class Area extends Measurement<UnitsOfArea> { + @Override + public void setUnits(UnitsOfArea enumValue){...} +} + +~~~~~~~ + +Although to the developer the area\.setUnits(enumValue) method only accepts a UnitsOfArea enumeration, due to erasure the signature of this method is actually setUnits(java\.lang\.Enum)\. The framework does not know that the parameter is a UnitsOfArea and when it attempts to instantiate the Enum an exception is thrown (java\.lang\.IllegalArgumentException: java\.lang\.Enum is not an enum type)\. http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/unknown-handlers.md ---------------------------------------------------------------------- diff --git a/source/core-developers/unknown-handlers.md b/source/core-developers/unknown-handlers.md new file mode 100644 index 0000000..fec6e6c --- /dev/null +++ b/source/core-developers/unknown-handlers.md @@ -0,0 +1,63 @@ +--- +layout: core-developers +title: Unknown Handlers +--- + +# Unknown Handlers + +Unknown Handler stacks are available from Struts 2\.1 on\. + +> + +#####Unkown Handlers##### + +Unknown Handlers are classes that implement the + +~~~~~~~ +com.opensymphony.xwork2.UnknownHandler +~~~~~~~ + interface, and are called by the framework, when an unknown action, result, or method are executed\. To define an unknown handler, create a class implementing the mentioned interface, and add a bean definition to your struts\.xml: + + +~~~~~~~ + +<bean type="com.opensymphony.xwork2.UnknownHandler" name="handler" class="myclasses.SomeUnknownHandler"/> + +~~~~~~~ + +#####Stacking Unknown Handlers##### + +Multiple unknown handlers can be defined, using the _unknown\-handler\-stack_ tag: + + +~~~~~~~ + +<bean type="com.opensymphony.xwork2.UnknownHandler" name="handler1" class="com.opensymphony.xwork2.config.providers.SomeUnknownHandler"/> +<bean type="com.opensymphony.xwork2.UnknownHandler" name="handler2" class="com.opensymphony.xwork2.config.providers.SomeUnknownHandler"/> + +<unknown-handler-stack> + <unknown-handler-ref name="handler1" /> + <unknown-handler-ref name="handler2" /> +</unknown-handler-stack> + +~~~~~~~ + +When multiple unknown handlers are stacked like above, they will be called in the specified order, in the same cases when a single unknown handler would be called (when an unknown action, result, or method are executed), until one of them handles the requested action\. + +#####Uknown Handlers Manager##### + +The default class that handles unknown handler stacks is + +~~~~~~~ +com.opensymphony.xwork2.DefaultUnknownHandlerManager +~~~~~~~ +, a custom implementation of this class can be provided by implementing the interface + +~~~~~~~ +com.opensymphony.xwork2.UnknownHandlerManager +~~~~~~~ + and setting the property + +~~~~~~~ +struts.unknownHandlerManager +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/url-validator-annotation.md ---------------------------------------------------------------------- diff --git a/source/core-developers/url-validator-annotation.md b/source/core-developers/url-validator-annotation.md new file mode 100644 index 0000000..cc6dfef --- /dev/null +++ b/source/core-developers/url-validator-annotation.md @@ -0,0 +1,72 @@ +--- +layout: core-developers +title: UrlValidator Annotation +--- + +# UrlValidator Annotation + +This validator checks that a field is a valid URL\. + +Usage + +  The annotation must be applied at method level\. + +Parameters + +| Parameter|Required|Default|Notes| +|----------|--------|-------|-----| +|message|yes| |field error message| +|key|no| |i18n key from language specific properties file| +|messageParams|no| |additional params to be used to customize message \- will be evaluated against the Value Stack| +|fieldName|no| |field name under validation| +|shortCircuit|no|false|if this validator should be used as shortCircuit| +|urlRegex|no| |defines regex to use to validate url| +|urlRegexExpression|no| |defines regex as expression to validate url, expression will be evaluated against current stack to get proper regex| +|type|yes|ValidatorType\.FIELD|Enum value from ValidatorType\. Either FIELD or SIMPLE can be used here| + +Examples + +**UrlValidator usage example** + + +~~~~~~~ +@UrlValidator(message = "Default message", key = "i18n.key", shortCircuit = true) +~~~~~~~ + +**UrlValidator usage example** + + +~~~~~~~ +@UrlValidator(message = "Default message", key = "i18n.key", urlRegexExpression = "${urlRegex}") +~~~~~~~ + + + +| urlRegex neither urlRegexExpression are only used on client side to validate URLs \- this will be changed with next major release\! + +| + + +If no urlRegex neither urlRegexExpression is defined, default regex will be used instead, based on [StackOverflow answer](http://stackoverflow\.com/questions/161738/what\-is\-the\-best\-regular\-expression\-to\-check\-if\-a\-string\-is\-a\-valid\-url)^[http://stackoverflow\.com/questions/161738/what\-is\-the\-best\-regular\-expression\-to\-check\-if\-a\-string\-is\-a\-valid\-url] + +| + +**Default URL regex** + + +~~~~~~~ +return "^(https?|ftp):\/\/" + + "(([a-z0-9$_\\.\\+!\\*\\'\\(\\),;\\?&=-]|%[0-9a-f]{2})+" + + "(:([a-z0-9$_\\.\\+!\\*\\'\\(\\),;\\?&=-]|%[0-9a-f]{2})+)?" + + "@)?(#?" + + ")((([a-z0-9]\\.|[a-z0-9][a-z0-9-]*[a-z0-9]\\.)*" + + "[a-z][a-z0-9-]*[a-z0-9]" + + "|((\\d|[1-9]\\d|1\\d{2}|2[0-4][0-9]|25[0-5])\\.){3}" + + "(\\d|[1-9]\\d|1\\d{2}|2[0-4][0-9]|25[0-5])" + + ")(:\\d+)?" + + ")(((\\/+([a-z0-9$_\\.\\+!\\*\\'\\(\\),;:@&=-]|%[0-9a-f]{2})*)*" + + "(\\?([a-z0-9$_\\.\\+!\\*\\'\\(\\),;:@&=-]|%[0-9a-f]{2})*)" + + "?)?)?" + + "(#([a-z0-9$_\\.\\+!\\*\\'\\(\\),;:@&=-]|%[0-9a-f]{2})*)?" + + "$"; +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/url-validator.md ---------------------------------------------------------------------- diff --git a/source/core-developers/url-validator.md b/source/core-developers/url-validator.md new file mode 100644 index 0000000..335fae7 --- /dev/null +++ b/source/core-developers/url-validator.md @@ -0,0 +1,42 @@ +--- +layout: core-developers +title: url validator +--- + +# url validator + +####Description#### + +URLValidator checks that a given field is a String and a valid URL + +Parameters + ++ fieldName \- The field name this validator is validating\. Required if using Plain\-Validator Syntax otherwise not required + ++ urlRegexExpression \- The regex defined as expression used to validate url\. If not defined 'urlRegex' will be used instead + ++ urlRegex \- The regex used to validate url\. If not defined default regex will be used + +####Examples#### + + + +~~~~~~~ +<validators> + <!-- Plain Validator Syntax --> + <validator type="url"> + <param name="fieldName">myHomePage</param> + <message>Invalid homepage url</message> + </validator> + + <!-- Field Validator Syntax --> + <field name="myHomepage"> + <field-validator type="url"> + <message>Invalid homepage url</message> + </field-validator> + </field> +</validators> + +~~~~~~~ + +See more details in [UrlValidator Annotation](url-validator-annotation.html) http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/using-field-validators.md ---------------------------------------------------------------------- diff --git a/source/core-developers/using-field-validators.md b/source/core-developers/using-field-validators.md new file mode 100644 index 0000000..2cbfc4a --- /dev/null +++ b/source/core-developers/using-field-validators.md @@ -0,0 +1,34 @@ +--- +layout: core-developers +title: Using Field Validators +--- + +# Using Field Validators + +#####Description##### + +The followings show a simple example using Struts' Field Validators + +__Step 1__ + +Create the jsp page + +~~~~~~~ +{snippet:id=fieldValidatorsExample|lang=xml|javadoc=false|url=struts2/apps/showcase/src/main/webapp/WEB-INF/validation/fieldValidatorsExample.jsp} +~~~~~~~ + +__Step 2__ + +Create the action class + +~~~~~~~ +{snippet:id=fieldValidatorsExample|javadoc=false|lang=java|url=struts2/apps/showcase/src/main/java/org/apache/struts2/showcase/validation/FieldValidatorsExampleAction.java} +~~~~~~~ + +__Step 3__ + +Create the validator\.xml\. + +~~~~~~~ +{snippet:id=fieldValidatorsExample|javadoc=false|lang=xml|url=struts2/apps/showcase/src/main/resources/org/apache/struts2/showcase/validation/FieldValidatorsExampleAction-submitFieldValidatorsExamples-validation.xml} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/using-non-field-validators.md ---------------------------------------------------------------------- diff --git a/source/core-developers/using-non-field-validators.md b/source/core-developers/using-non-field-validators.md new file mode 100644 index 0000000..f1ff67c --- /dev/null +++ b/source/core-developers/using-non-field-validators.md @@ -0,0 +1,34 @@ +--- +layout: core-developers +title: Using Non Field Validators +--- + +# Using Non Field Validators + +#####Description##### + +The followings show a simple example using Webwork's Non Field Validators + +__Step 1__ + +Create the jsp page + +~~~~~~~ +{snippet:id=nonFieldValidatorsExample|lang=xml|javadoc=false|url=struts2/apps/showcase/src/main/webapp/WEB-INF/validation/nonFieldValidatorsExample.jsp} +~~~~~~~ + +__Step 2__ + +Create the action class + +~~~~~~~ +{snippet:id=nonFieldValidatorsExample|javadoc=false|lang=java|url=struts2/apps/showcase/src/main/java/org/apache/struts2/showcase/validation/NonFieldValidatorsExampleAction.java} +~~~~~~~ + +__Step 3__ + +Create the validator\.xml\. + +~~~~~~~ +{snippet:id=nonFieldValidatorsExample|javadoc=false|lang=xml|url=struts2/apps/showcase/src/main/resources/org/apache/struts2/showcase/validation/NonFieldValidatorsExampleAction-submitNonFieldValidatorsExamples-validation.xml} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/using-visitor-field-validator.md ---------------------------------------------------------------------- diff --git a/source/core-developers/using-visitor-field-validator.md b/source/core-developers/using-visitor-field-validator.md new file mode 100644 index 0000000..7af261e --- /dev/null +++ b/source/core-developers/using-visitor-field-validator.md @@ -0,0 +1,34 @@ +--- +layout: core-developers +title: Using Visitor Field Validator +--- + +# Using Visitor Field Validator + +#####Description##### + +The followings show a simple example using Webwork's Field Validators + +__Step 1__ + +Create the jsp page\. + +~~~~~~~ +{snippet:id=visitorValidatorsExample|lang=xml|javadoc=false|url=struts2/apps/showcase/src/main/webapp/WEB-INF/validation/visitorValidatorsExample.jsp} +~~~~~~~ + +__Step 2__ + +Create the action class\. + +~~~~~~~ +{snippet:id=visitorValidatorsExample|javadoc=false|lang=java|url=struts2/apps/showcase/src/main/java/org/apache/struts2/showcase/validation/VisitorValidatorsExampleAction.java} +~~~~~~~ + +__Step 3__ + +Create the validator\.xml\. + +~~~~~~~ +{snippet:id=visitorValidatorsExample|javadoc=false|lang=xml|url=struts2/apps/showcase/src/main/resources/org/apache/struts2/showcase/validation/VisitorValidatorsExampleAction-submitVisitorValidatorsExamples-validation.xml} +~~~~~~~ \ No newline at end of file http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/validation-annotation.md ---------------------------------------------------------------------- diff --git a/source/core-developers/validation-annotation.md b/source/core-developers/validation-annotation.md new file mode 100644 index 0000000..d92a26d --- /dev/null +++ b/source/core-developers/validation-annotation.md @@ -0,0 +1,64 @@ +--- +layout: core-developers +title: Validation Annotation +--- + +# Validation Annotation + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.Validation} +~~~~~~~ + +#####Usage##### + + + +~~~~~~~ +{snippet:id=usage|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.Validation} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.Validation} +~~~~~~~ + +#####Examples##### + +**An Annotated Interface** + ++ Mark the interface with @Validation() + ++ Apply standard or custom annoations at method level + + + +~~~~~~~ +{snippet:id=example|javadoc=true|lang=java|url=com.opensymphony.xwork2.validator.annotations.Validation} +~~~~~~~ + +**An Annotated Class** + + +~~~~~~~ +{snippet:id=example2|javadoc=true|lang=java|url=com.opensymphony.xwork2.validator.annotations.Validation} +~~~~~~~ + + +> + +> + +> When multiple methods are used to map different actions on the same class, and one of them is annotated with _@Validations_ , those validators will be triggered for all the actions, unless they are annotated with @SkipValidation or _validateAnnotatedMethodOnly_ is set to _true_ in the "validation" interceptor, like: + +> + > \<interceptor\-ref name="validation"\> + > \<param name="validateAnnotatedMethodOnly"\>true\</param\> + > \<param name="excludeMethods"\>input,back,cancel,browse\</param\> + > \</interceptor\-ref\> + > + \ No newline at end of file http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/validation-interceptor.md ---------------------------------------------------------------------- diff --git a/source/core-developers/validation-interceptor.md b/source/core-developers/validation-interceptor.md new file mode 100644 index 0000000..155abff --- /dev/null +++ b/source/core-developers/validation-interceptor.md @@ -0,0 +1,36 @@ +--- +layout: core-developers +title: Validation Interceptor +--- + +# Validation Interceptor + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.validator.ValidationInterceptor} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.ValidationInterceptor} +~~~~~~~ + +#####Extending the Interceptor##### + + + +~~~~~~~ +{snippet:id=extending|javadoc=true|url=com.opensymphony.xwork2.validator.ValidationInterceptor} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=com.opensymphony.xwork2.validator.ValidationInterceptor} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/validation-parameter-annotation.md ---------------------------------------------------------------------- diff --git a/source/core-developers/validation-parameter-annotation.md b/source/core-developers/validation-parameter-annotation.md new file mode 100644 index 0000000..373279c --- /dev/null +++ b/source/core-developers/validation-parameter-annotation.md @@ -0,0 +1,35 @@ +--- +layout: core-developers +title: ValidationParameter annotation +--- + +# ValidationParameter annotation + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.ValidationParameter} +~~~~~~~ + +__Usage__ + + + +~~~~~~~ +{snippet:id=usage|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.ValidationParameter} +~~~~~~~ + +__Parameters__ + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.ValidationParameter} +~~~~~~~ + +__Examples__ + + + +~~~~~~~ +{snippet:id=example|javadoc=true|lang=java|url=com.opensymphony.xwork2.validator.annotations.ValidationParameter} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/validation.md ---------------------------------------------------------------------- diff --git a/source/core-developers/validation.md b/source/core-developers/validation.md new file mode 100644 index 0000000..29f84de --- /dev/null +++ b/source/core-developers/validation.md @@ -0,0 +1,390 @@ +--- +layout: core-developers +title: Validation +--- + +# Validation + +Struts 2 validation is configured via XML or annotations\. Manual validation in the action is also possible, and may be combined with XML and annotation\-driven validation\. + +Validation also depends on both the + +~~~~~~~ +validation +~~~~~~~ + and + +~~~~~~~ +workflow +~~~~~~~ + interceptors (both are included in the default interceptor stack)\. The + +~~~~~~~ +validation +~~~~~~~ + interceptor does the validation itself and creates a list of field\-specific errors\. The + +~~~~~~~ +workflow +~~~~~~~ + interceptor checks for the presence of validation errors: if any are found, it returns the "input" result (by default), taking the user back to the form which contained the validation errors\. + +If we're using the default settings _and_ our action doesn't have an "input" result defined _and_ there are validation (or, incidentally, type conversion) errors, we'll get an error message back telling us there's no "input" result defined for the action\. + +**CONTENTS** + + +####Using Annotations#### + +[Annotations](validation-annotation.html) can be used as an alternative to XML for validation\. + + + +####Bean Validation#### + +With struts 2\.5 comes the Bean Validation Plugin\. That is an alternative to the classic struts validation described here\. See the _Plugin Page_ for details\. + +####Examples#### + +In all examples given here, the validation message displayed is given in plain English \- to internationalize the message, put the string in a properties file and use a property key instead, specified by the 'key' attribute\. It will be looked up by the framework (see [Localization](localization.html)). + +1. [Basic Validation](basic-validation.html) + +2. [Client-side Validation](client-side-validation.html) + +3. _AJAX Validation_ + +4. [Using Field Validators](using-field-validators.html) + +5. [Using Non Field Validators](using-non-field-validators.html) + +6. [Using Visitor Field Validator](using-visitor-field-validator.html) + +7. _How do we repopulate controls when validation fails_ (FAQ entry) + +####Bundled Validators#### + + +When using a Field Validator, Field Validator Syntax is **ALWAYS** preferable than using the Plain Validator Syntax as it facilitates grouping of field\-validators according to fields\. This is very handy especially if a field needs to have many field\-validators which is almost always the case\. + +| + +1. [conversion validator](conversion-validator.html) + +2. [date validator](date-validator.html) + +3. [double validator](double-validator.html) + +4. [email validator](email-validator.html) + +5. [expression validator](expression-validator.html) + +6. [fieldexpression validator](fieldexpression-validator.html) + +7. [int validator](int-validator.html) + +8. [regex validator](regex-validator.html) + +9. [required validator](required-validator.html) + +10. [requiredstring validator](requiredstring-validator.html) + +11. [short validator](short-validator.html) + +12. [stringlength validator](stringlength-validator.html) + +13. [url validator](url-validator.html) + +14. [visitor validator](visitor-validator.html) + +15. [conditionalvisitor validator](conditionalvisitor-validator.html) + +####Registering Validators#### + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java} +~~~~~~~ +The following list shows the default validators included in the framework and is an example of the syntax used to declare our own validators\. + +~~~~~~~ +{snippet:lang=xml|url=struts2/core/src/main/resources/com/opensymphony/xwork2/validator/validators/default.xml} +~~~~~~~ + + +The validators\.xml used to reference a DTD hosted by Opensymphony, the original location of the XWork project\. Since the the move to Apache Struts, DTDs were changed\. Please ensure in your projects to include the DTD header as described in the examples found here + +| + + +The validators\.xml containing custom validators needs to contain a copy of the default validators\. No DTD was used in validators\.xml\. See: [http://struts\.apache\.org/2\.x/docs/release\-notes\-208\.html\#ReleaseNotes2\.0\.8\-MigrationfrompreviousReleases](http://struts\.apache\.org/2\.x/docs/release\-notes\-208\.html\#ReleaseNotes2\.0\.8\-MigrationfrompreviousReleases) + +| + +####Turning on Validation#### + +The default interceptor stack, "defaultStack", already has validation turned on\. When creating your own interceptor\-stack be sure to include **both** the + +~~~~~~~ +validation +~~~~~~~ + and + +~~~~~~~ +workflow +~~~~~~~ + interceptors\. From + +~~~~~~~ +struts-default.xml +~~~~~~~ +: + + +~~~~~~~ +<interceptor-stack name="defaultStack"> + ... + <interceptor-ref name="validation"> + <param name="excludeMethods">input,back,cancel,browse</param> + </interceptor-ref> + <interceptor-ref name="workflow"> + <param name="excludeMethods">input,back,cancel,browse</param> + </interceptor-ref> +</interceptor-stack> + +~~~~~~~ + +Beginning with version 2\.0\.4 Struts provides an extension to XWork's + +~~~~~~~ +com.opensymphony.xwork2.validator.ValidationInterceptor +~~~~~~~ + interceptor\. + + +~~~~~~~ +<interceptor name="validation" class="org.apache.struts2.interceptor.validation.AnnotationValidationInterceptor"/> + +~~~~~~~ + +This interceptor allows us to turn off validation for a specific method by using the + +~~~~~~~ [email protected] +~~~~~~~ + annotation on the action method\. + +####Validator Scopes#### + + + +~~~~~~~ +{snippet:id=fieldValidators|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java} +~~~~~~~ + + +~~~~~~~ +{snippet:id=nonFieldValidators|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java} +~~~~~~~ + +#####Notes##### + + + +~~~~~~~ +{snippet:id=validatorsNote|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java} +~~~~~~~ + +####Defining Validation Rules#### + + + +~~~~~~~ +{snippet:id=validationRules1|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java} +~~~~~~~ + + +~~~~~~~ +{snippet:id=exValidationRules1|lang=xml|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java} +~~~~~~~ + + +~~~~~~~ +{snippet:id=validationRules2|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java} +~~~~~~~ + + +In this context, "Action Alias" refers to the action name as given in the Struts configuration\. Often, the name attribute matches the method name, but they may also differ\. + +| + +####Localizing and Parameterizing Messages#### + + + +~~~~~~~ +{snippet:id=validationRules3|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java} +~~~~~~~ + + +~~~~~~~ +{snippet:id=exValidationRules3|javadoc=true|lang=xml|url=com.opensymphony.xwork2.validator/ValidatorFactory.java} +~~~~~~~ + + +~~~~~~~ +{snippet:id=validationRules4|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java} +~~~~~~~ + + +~~~~~~~ +{snippet:id=exValidationRules4|javadoc=true|lang=xml|url=com.opensymphony.xwork2.validator/ValidatorFactory.java} +~~~~~~~ + +####Validator Flavor#### + + + +~~~~~~~ +{snippet:id=validatorFlavours|javadoc=true|url=com.opensymphony.xwork2.validator/Validator.java} +~~~~~~~ + +####Non\-Field Validator Vs Field\-Validator validatortypes#### + +There are two ways you can define validators in your \-validation\.xml file: + +1. <validator> + +2. <field-validator> + +Keep the following in mind when using either syntax: + +Non\-Field\-Validator: The \<validator\> element allows you to declare both types of validators (either a plain Validator a field\-specific FieldValidator)\. + + +~~~~~~~ +<validator type="expression> + <param name="expression">foo gt bar</param> + <message>foo must be great than bar.</message> +</validator> + +~~~~~~~ + + +~~~~~~~ +<validator type="required"> + <param name="fieldName">bar</param> + <message>You must enter a value for bar.</message> +</validator> + +~~~~~~~ + +**field\-validator**: The \<field\-validator\> elements are basically the same as the \<validator\> elements except that they inherit the fieldName attribute from the enclosing \<field\> element\. FieldValidators defined within a \<field\-validator\> element will have their fieldName automatically filled with the value of the parent \<field\> element's fieldName attribute\. The reason for this structure is to conveniently group the validators for a particular field under one element, otherwise the fieldName attribute would have to be repeated, over and over, for each individual \<validator\>\. + + + +| It is always better to defined field\-validator inside a \<field\> tag instead of using a \<validator\> tag and supplying fieldName as its param as the xml code itself is clearer (grouping of field is clearer) + +| + + +Note that you should only use FieldValidators (not plain Validators) within a block\. A plain Validator inside a \<field\> will not be allowed and would generate error when parsing the xml, as it is not allowed in the defined dtd (xwork\-validator\-1\.0\.2\.dtd) + +| + +Declaring a FieldValidator using the \<field\-validator\> syntax: + + +~~~~~~~ +<field name="email_address"> + <field-validator type="required"> + <message>You cannot leave the email address field empty.</message> + </field-validator> + <field-validator type="email"> + <message>The email address you entered is not valid.</message> + </field-validator> +</field> + +~~~~~~~ + +The choice is yours\. It's perfectly legal to only use elements without the elements and set the fieldName attribute for each of them\. The following are effectively equal: + + +~~~~~~~ +<field name="email_address"> + <field-validator type="required"> + <message>You cannot leave the email address field empty.</message> + </field-validator> + <field-validator type="email"> + <message>The email address you entered is not valid.</message> + </field-validator> +</field> + +<validator type="required"> + <param name="fieldName">email_address</param> + <message>You cannot leave the email address field empty.</message> +</validator> +<validator type="email"> + <param name="fieldName">email_address</param> + <message>The email address you entered is not valid.</message> +</validator> + +~~~~~~~ + +####Short\-Circuiting Validator#### + + + +~~~~~~~ +{snippet:id=shortCircuitingValidators1|javadoc=true|url=com.opensymphony.xwork2.validator/Validator.java} +~~~~~~~ + + +~~~~~~~ +{snippet:id=exShortCircuitingValidators|lang=xml|javadoc=true|url=com.opensymphony.xwork2.validator/Validator.java} +~~~~~~~ + + +~~~~~~~ +{snippet:id=shortCircuitingValidators2|javadoc=true|url=com.opensymphony.xwork2.validator/Validator.java} +~~~~~~~ + + +~~~~~~~ +{snippet:id=scAndValidatorFlavours1|1=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator/Validator.java} +~~~~~~~ + + +~~~~~~~ +{snippet:id=exScAndValidatorFlavours|lang=xml|javadoc=true|url=com.opensymphony.xwork2.validator/Validator.java} +~~~~~~~ + + +~~~~~~~ +{snippet:id=scAndValidatorFlavours2|1=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator/Validator.java} +~~~~~~~ + +####How Validators of an Action are Found#### + + + +~~~~~~~ +{snippet:id=howXworkFindsValidatorForAction|javadoc=true|url=com.opensymphony.xwork2.validator/Validator.java} +~~~~~~~ + +####Writing custom validators#### + +If you want to write custom validator use on of these classes as a starting point: + ++ com\.opensymphony\.xwork2\.validator\.validators\.ValidatorSupport + ++ com\.opensymphony\.xwork2\.validator\.validators\.FieldValidatorSupport + ++ com\.opensymphony\.xwork2\.validator\.validators\.RangeValidatorSupport + ++ com\.opensymphony\.xwork2\.validator\.validators\.RepopulateConversionErrorFieldValidatorSupport + +####Resources#### + +[WebWork Validation](http://today\.java\.net/pub/a/today/2006/01/19/webwork\-validation\.html)^[http://today\.java\.net/pub/a/today/2006/01/19/webwork\-validation\.html] http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/validations-annotation.md ---------------------------------------------------------------------- diff --git a/source/core-developers/validations-annotation.md b/source/core-developers/validations-annotation.md new file mode 100644 index 0000000..1adb125 --- /dev/null +++ b/source/core-developers/validations-annotation.md @@ -0,0 +1,94 @@ +--- +layout: core-developers +title: Validations Annotation +--- + +# Validations Annotation + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.Validations} +~~~~~~~ + +#####Usage##### + + + +~~~~~~~ +{snippet:id=usage|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.Validations} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.Validations} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|javadoc=true|lang=java|url=com.opensymphony.xwork2.validator.annotations.Validations} +~~~~~~~ + +#####Different validations per method##### + + +Different validations per method is NOT supported for client\-side validation\! + +| + +To use different validations per method, the validateAnnotatedMethodOnly property must be set on the validation interceptor\. + + +~~~~~~~ + +<interceptor-ref name="validation"> + <param name="validateAnnotatedMethodOnly">true</param> + <param name="excludeMethods">input,back,cancel,browse</param> +</interceptor-ref> + +~~~~~~~ + +Here's a complete example of updating the default stack: + + +~~~~~~~ + + <package name="default" extends="struts-default"> + <interceptors> + <interceptor-stack name="content"> + <interceptor-ref name="exception"/> + <interceptor-ref name="alias"/> + <interceptor-ref name="servletConfig"/> + <interceptor-ref name="prepare"/> + <interceptor-ref name="i18n"/> + <interceptor-ref name="chain"/> + <interceptor-ref name="debugging"/> + <interceptor-ref name="profiling"/> + <interceptor-ref name="scopedModelDriven"/> + <interceptor-ref name="modelDriven"/> + <interceptor-ref name="fileUpload"/> + <interceptor-ref name="checkbox"/> + <interceptor-ref name="staticParams"/> + <interceptor-ref name="params"> + <param name="excludeParams">dojo\..*</param> + </interceptor-ref> + <interceptor-ref name="conversionError"/> + <interceptor-ref name="validation"> + <param name="validateAnnotatedMethodOnly">true</param> + <param name="excludeMethods">input,back,cancel,browse</param> + </interceptor-ref> + <interceptor-ref name="workflow"> + <param name="excludeMethods">input,back,cancel,browse</param> + </interceptor-ref> + </interceptor-stack> + </interceptors> + <default-interceptor-ref name="default"/> + </package> +</struts> + +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/velocity-properties.md ---------------------------------------------------------------------- diff --git a/source/core-developers/velocity-properties.md b/source/core-developers/velocity-properties.md new file mode 100644 index 0000000..a35d9cd --- /dev/null +++ b/source/core-developers/velocity-properties.md @@ -0,0 +1,31 @@ +--- +layout: core-developers +title: velocity.properties +--- + +# velocity.properties + +If a + +~~~~~~~ +velocity.properties +~~~~~~~ + is provided on the classpath (e\.g\., + +~~~~~~~ +/WEB-INF/classes +~~~~~~~ +), it will be loaded by Velocity\. + +**velocity\.properties** + + +~~~~~~~ + +# Velocity Macro libraries. +velocimacro.library = action-default.vm, tigris-macros.vm, myapp.vm + +~~~~~~~ + +(light\-on) See [struts\-default\.vm](struts-default-vm.html) and the _Velocity_ documentation for more information\. + http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/velocity-result.md ---------------------------------------------------------------------- diff --git a/source/core-developers/velocity-result.md b/source/core-developers/velocity-result.md new file mode 100644 index 0000000..794be29 --- /dev/null +++ b/source/core-developers/velocity-result.md @@ -0,0 +1,28 @@ +--- +layout: core-developers +title: Velocity Result +--- + +# Velocity Result + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=org.apache.struts2.dispatcher.VelocityResult} +~~~~~~~ + +####Parameters#### + + + +~~~~~~~ +{snippet:id=params|javadoc=true|url=org.apache.struts2.dispatcher.VelocityResult} +~~~~~~~ + +####Examples#### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=org.apache.struts2.dispatcher.VelocityResult} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/visitor-field-validator-annotation.md ---------------------------------------------------------------------- diff --git a/source/core-developers/visitor-field-validator-annotation.md b/source/core-developers/visitor-field-validator-annotation.md new file mode 100644 index 0000000..635d4b0 --- /dev/null +++ b/source/core-developers/visitor-field-validator-annotation.md @@ -0,0 +1,36 @@ +--- +layout: core-developers +title: VisitorFieldValidator Annotation +--- + +# VisitorFieldValidator Annotation + + + +~~~~~~~ +{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.VisitorFieldValidator} +~~~~~~~ + +#####Usage##### + + + +~~~~~~~ +{snippet:id=usage|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.VisitorFieldValidator} +~~~~~~~ + +#####Parameters##### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.annotations.VisitorFieldValidator} +~~~~~~~ + +#####Examples##### + + + +~~~~~~~ +{snippet:id=example|javadoc=true|lang=java|url=com.opensymphony.xwork2.validator.annotations.VisitorFieldValidator} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/visitor-validator.md ---------------------------------------------------------------------- diff --git a/source/core-developers/visitor-validator.md b/source/core-developers/visitor-validator.md new file mode 100644 index 0000000..55b2324 --- /dev/null +++ b/source/core-developers/visitor-validator.md @@ -0,0 +1,35 @@ +--- +layout: core-developers +title: visitor validator +--- + +# visitor validator + +####Description#### + + + +~~~~~~~ +{snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator.validators.VisitorFieldValidator} +~~~~~~~ + +####Parameters#### + + + +~~~~~~~ +{snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.validator.validators.VisitorFieldValidator} +~~~~~~~ + +####Examples#### + + + +~~~~~~~ +{snippet:id=example|lang=xml|javadoc=true|url=com.opensymphony.xwork2.validator.validators.VisitorFieldValidator} +~~~~~~~ + + +~~~~~~~ +{snippet:id=explanation|javadoc=true|url=com.opensymphony.xwork2.validator.validators.VisitorFieldValidator} +~~~~~~~ http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/web-xml.md ---------------------------------------------------------------------- diff --git a/source/core-developers/web-xml.md b/source/core-developers/web-xml.md new file mode 100644 index 0000000..ab0df71 --- /dev/null +++ b/source/core-developers/web-xml.md @@ -0,0 +1,231 @@ +--- +layout: core-developers +title: web.xml +--- + +# web.xml + + +The + +~~~~~~~ +web.xml +~~~~~~~ + web application descriptor file represents the core of the Java web application, so it is appropriate that it is also part of the core of the Struts framework\. In the + +~~~~~~~ +web.xml +~~~~~~~ + file, Struts defines its FilterDispatcher, the Servlet Filter class that initializes the Struts framework and handles all requests\. This filter can contain initialization parameters that affect what, if any, additional configuration files are loaded and how the framework should behave\. + +####Simple Example#### + +Configuring + +~~~~~~~ +web.xml +~~~~~~~ + for the framework is a matter of adding a filter and filter\-mapping\. + +**Filter Example (web\.xml)** + + +~~~~~~~ +<web-app id="MyStrutsApp" version="2.4" + xmlns="http://java.sun.com/xml/ns/j2ee"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd";> + + <filter> + <filter-name>struts2</filter-name> + <filter-class>org.apache.struts2.dispatcher.filter.StrutsPrepareAndExecuteFilter</filter-class> + </filter> + + <filter-mapping> + <filter-name>struts2</filter-name> + <url-pattern>/*</url-pattern> + </filter-mapping> + + <!-- ... --> + +</web-app> + +~~~~~~~ + +#####Changed filter package in Struts \>= 2\.5##### + +As from Struts 2\.5 all filters were moved to top package, if you are using older version you must use the old package, see example: + + +~~~~~~~ +<web-app id="WebApp_9" version="2.4" + xmlns="http://java.sun.com/xml/ns/j2ee"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd";> + + <filter> + <filter-name>struts2</filter-name> + <filter-class>org.apache.struts2.dispatcher.ng.filter.StrutsPrepareAndExecuteFilter</filter-class> + ... +~~~~~~~ + +#####Changed Filter Structure in Struts \>= 2\.1\.3##### + + To split up the the dispatcher phases, FilterDispatcher is deprecated since Struts 2\.1\.3\. If working with older versions, you need to use + + +~~~~~~~ + ... + <filter> + <filter-name>struts2</filter-name> + <filter-class>org.apache.struts2.dispatcher.FilterDispatcher</filter-class> + ... + +~~~~~~~ + + See _SiteMesh Plugin_ for an example on when to use seperate Filters for prepare and execution phase + +#####Exclude specific URLs##### + + In the example above we've mapped the Struts 2 dispatcher to + +~~~~~~~ +/* +~~~~~~~ +, so Struts 2 has a crack at all incoming requests\. This is because Struts 2 serves static content from its jar files, including Dojo JavaScript files (if using S2\.0, or the Dojo plugin in S2\.1\+) and FreeMarker templates for the Struts 2 tags that produce HTML\. + +If we change the filter mapping to something else, for example + +~~~~~~~ +/*.html +~~~~~~~ +, we must take this in to account and extract the content that would normally be served from the Struts 2 jar files, or some other solution\. + +Since Struts 2\.1\.7, you are able to provide a comma seperated list of patterns for which when matching against the + request URL the Filter will just pass by\. This is done via the configuration option struts\.action\.excludePattern, for example in your struts\.xml + + + + +~~~~~~~ +<struts> + <constant name="struts.action.excludePattern" value=".*unfiltered.*,.*\\.nofilter"/> + ... + +</struts> +~~~~~~~ + +####Taglib Example#### + +Typically, configuring a taglib is neither required nor recommended\. The taglib is included in + +~~~~~~~ +struts-core.jar +~~~~~~~ +, and the container will discover it automatically\. + + (ok) If, for some reason, a taglib configuration is needed within web\.xml, extract the TLD file from the + +~~~~~~~ +struts-core.jar +~~~~~~~ + + +~~~~~~~ +META-INF +~~~~~~~ + folder, and add a + +~~~~~~~ +taglib +~~~~~~~ + element to the + +~~~~~~~ +web.xml +~~~~~~~ +\. + + +~~~~~~~ + <!-- ... --> + </welcome-file-list> + + <taglib> + <taglib-uri>/s</taglib-uri> + <taglib-location>/WEB-INF/struts-tags.tld</taglib-location> + </taglib> +</web-app> + +~~~~~~~ + +####Custom FileManager and FileManagerFactory implementations#### + +If there is a need to support an App Server's specific file system (eg\. VFS in JBoss), you can implement your own version of FileManager\. But it must be registered at "the beginning" to support bootstrap of the whole framework\. + +To register your own FileManger you can do it with \<init\-param/\> as below: + + +~~~~~~~ +<filter> + <filter-name>struts2</filter-name> + <filter-class>org.apache.struts2.dispatcher.filter.StrutsPrepareAndExecuteFilter</filter-class> + <init-param> + <param-name>struts.fileManager</param-name> + <param-value>com.company.MyFileManager</param-value> + </init-param> +</filter> + +~~~~~~~ + +You can as well register your own FileManagerFactory with \<init\-param/\>, see example: + + +~~~~~~~ +<filter> + <filter-name>struts2</filter-name> + <filter-class>org.apache.struts2.dispatcher.ng.filter.StrutsPrepareAndExecuteFilter</filter-class> + <init-param> + <param-name>struts.fileManagerFactory</param-name> + <param-value>com.company.MyFileManagerFactory</param-value> + </init-param> +</filter> + +~~~~~~~ + +Take a look on default implementations \- DefaultFileManager\.java and DefaultFileManagerFactory\.java to understand how and why\. + +####Custom configuration provider#### + +It is possible to use your custom + +~~~~~~~ +ConfigurationProvider +~~~~~~~ + to programmatically configure your application\. To do this use + +~~~~~~~ +configProviders +~~~~~~~ + (it can be a comma\-separated list of class names) + +~~~~~~~ +<init-param/> +~~~~~~~ + as below: + + +~~~~~~~ +<filter> + <filter-name>struts2</filter-name> + <filter-class>org.apache.struts2.dispatcher.filter.StrutsPrepareAndExecuteFilter</filter-class> + <init-param> + <param-name>configProviders</param-name> + <param-value>com.company.MyConfigurationProvider</param-value> + </init-param> +</filter> +~~~~~~~ + +See [Configuration Provider & Configuration](configuration-provider-and-configuration.html) for more details. + + http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/weblogic-6-1.md ---------------------------------------------------------------------- diff --git a/source/core-developers/weblogic-6-1.md b/source/core-developers/weblogic-6-1.md new file mode 100644 index 0000000..f2d7081 --- /dev/null +++ b/source/core-developers/weblogic-6-1.md @@ -0,0 +1,118 @@ +--- +layout: core-developers +title: WebLogic 6.1 +--- + +# WebLogic 6.1 + +####Running on Weblogic Server 6\.1#### + +This document describes why the framework doesn't work "as\-is" on Weblogic Server 6\.1 and shows how to build an additional JAR that will fix the problems\. + +(information) The service pack SP4 of Weblogic Server 6\.1 was used to test these notes\. + +The first part of this document describes the technical problems and the theoretical solution\. + +#####Why It Doesn't Just Work##### + +Weblogic 6\.1 was published just prior to the finalization of the Servlet 2\.3 specification\. The incompatibility is that servlet filters and listeners in Weblogic 6\.1 do not work with the 2\.3 spec primarily because the servlet context is not retrieved in the same way\. This causes virtually all filter initialization operations to fail with an AbstractMethodError exception\. + +#####How the Framework is Modified##### + +In Servlet 2\.3, the servlet context is available from the session object; this is not true for Weblogic Server 6\.1\. Hence, filters and listeners must be modified to retrieve the servlet context from a different source; this is accomplished by retrieving the servlet context from the FilterConfig passed to the servlet filters during initialzation\. + +However, the framework code cannot be modifed to do this, because this will break the Servlet 2\.3 specification\. The goal is to leave the "original" framework unmodified so that it is still Servlet 2\.3 compatible, and then to add an additional JAR that "breaks" the frame to work on Weblogic Server 6\.1\. + +The framework has already been modified slightly to make the above effort possible: + +1. **RequestLifecycleFilter** is modified to retrieve its servlet context from the method + +~~~~~~~ +getServletContext +~~~~~~~ +. This method, + +~~~~~~~ +getServletContext +~~~~~~~ +, is then implemented to return the servlet context from where it is available in Servlet 2.3: the session object. The logical operation is unchanged, but now subclasses can override + +~~~~~~~ +getServletContext +~~~~~~~ + to retrieve the servlet context from a different location as we'll see below. + +1. **SessionLifecycleListener** is modified in the same way as RequestLifecycleFilter. The method, + +~~~~~~~ +getServletContext +~~~~~~~ +, is implemented to return the servlet context, in this case also from the session object. Again, subclasses can override the + +~~~~~~~ +getServletContext +~~~~~~~ + method to restore the servlet context from a different source. Again, this class's functionality is unchanged. + +Now, in a separate project, the following classes are added and compiled into a separate JAR: + +__RequestLifecycleFilterCompatWeblogic61__ + +This subclass of RequestLifecycleFilter simply overrides getServletContext() to retrieve the servlet context from the filter config, creates a singleton class, SessionContextSingleton, and assigns the servlet context to the singleton so that the listeners will have the ability to retrieve it\. + +__SessionLifecycleListenerCompatWeblogic61__ + +This subclass of SessionLifecycleListener simply overrides getServletContext() to retrieve the servlet context from the singleton created above\. + +__FilterDispatcherCompatWeblogic61__ + +Although the superclass of this class, FilterDispatcher, is commented out, this subclass retrieves the servlet context in the same way as RequestLifecycleFilterCompatWeblogic61 in case it is ever resurrected\. At this time, this class is unnecessary\. + +__ServletContextSingleton__ + +A singleton class whose sole purpose is to hold the servlet context so that listener classes have access to it\. + +#####Setting Up to Run on Weblogic 6\.1##### + +__Building your own project__ + +In the \{\{web\.xml\} file, make the following class name substitutions: + +| Old Class Name | New Class Name | +|----------------|----------------| +| RequestLifecycleFilter | RequestLifecycleFilterCompatWeblogic61 | +| SessionLifecycleListener | SessionLifecycleListenerCompatWeblogic61 | +| FilterDispatcher | FilterDispatcherCompatWeblogic61 | + +#####FAQ##### + +__I still get the AbstractMethodError Exception when Weblogic Server starts up\. What am I doing wrong?__ + +1. Check to see if a + +~~~~~~~ +action2-example.war +~~~~~~~ + is still lingering in your + +~~~~~~~ +mydomain/applications +~~~~~~~ + folder and delete it if it is there. + +2. See next FAQ question. + +__The server behavior seems like it is from a previous source code base; I can't debug it\. What's the clue?__ + +Sometimes BEA Weblogic Server doesn't "rebuild" its temporary files\. Do the following to force the temporary files to rebuild: + +1. Stop the server. + +2. Delete the .wlnotdelete folder in + +~~~~~~~ +mydomain/applications +~~~~~~~ +. + +3. Restart the server. http://git-wip-us.apache.org/repos/asf/struts-site/blob/f903a0f7/source/core-developers/weblogic.md ---------------------------------------------------------------------- diff --git a/source/core-developers/weblogic.md b/source/core-developers/weblogic.md new file mode 100644 index 0000000..f84d389 --- /dev/null +++ b/source/core-developers/weblogic.md @@ -0,0 +1,121 @@ +--- +layout: core-developers +title: WebLogic +--- + +# WebLogic + + +When deploying to WebLogic, some developers report problems with the framework locating resources, especially with Velocity\. For more about WebLogic and Velocity, see the [Velocity website](http://wiki\.apache\.org/jakarta\-velocity/VelocityAndWeblogic)^[http://wiki\.apache\.org/jakarta\-velocity/VelocityAndWeblogic]\. + +| + +To deploy to WebLogic, the common approach is to create and deploy an unexpanded WAR to the WebLogic deployment directory\. With WL 8\.x, the deployment directory is typically at \<bea\_home\>/user\_projects/domains/mydomain/\. + +> + +#####Adding an struts\-velocity\.properties Configuration File##### + ++ In the + +~~~~~~~ +struts.properties +~~~~~~~ + file (usually kept in the + +~~~~~~~ +WEB-INF/classes +~~~~~~~ + directory), add an entry that specifies a Velocity configuation file\. + + + + + +**struts\.properties** + + +~~~~~~~ + +struts.velocity.configfile = struts-velocity.properties + +~~~~~~~ + ++ Create the corresponding Velocity properties file ("struts\-velocity\.properties"), preferably in the same location as the + +~~~~~~~ +struts.properties +~~~~~~~ + file\. + ++ Copy into the Velocity properties file the contents of the + +~~~~~~~ +velocity.properties +~~~~~~~ + file that is the the SAF + +~~~~~~~ +velocity-dep.jar +~~~~~~~ +\. + ++ In your new + +~~~~~~~ +struts-velocity.properties +~~~~~~~ + file, find he section titled " + +~~~~~~~ +T E M P L A T E L O A D E R S +~~~~~~~ +", and change this section as so: + + + +~~~~~~~ + +=========================================== +resource.loader = class + +file.resource.loader.description = Velocity File Resource Loader +file.resource.loader.class = org.apache.velocity.runtime.resource.loader.FileResourceLoader +file.resource.loader.path = . +file.resource.loader.cache = false +file.resource.loader.modificationCheckInterval = 2 + +class.resource.loader.class = org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader +class.resource.loader.cache = true +=========================================== + +~~~~~~~ + ++ Redeploy a fresh WAR to WebLogic\. + +#####NPE when using Struts 2 Jasper Reports plugin##### + +When using mentioned plugin in Weblogic 11g you can get NullPointerException within Struts 2\. To solve the problem you must enable the "Archived Real Path" global property in Weblogic admin console \> configuration \> Web Applications\. It's because JasperReportsResult determines the report directory base on servletContext\.getRealPath(finalLocation)\. + +#####Convention based application doesn't work##### + +When you deployed an application that base on the Convention Plugin and you get an error messages that says: + + +~~~~~~~ + +There is no Action mapped for namespace / and action name xxxxxx + +~~~~~~~ + +create struts\.properties file in WEB\-INF/classes folder (in the expanded application's folder or in the source code) with below statements: + + +~~~~~~~ + +#struts convention property modifications for Weblogic +struts.convention.action.includeJars=.*?/yourwebapp.*?jar(!/)? +struts.convention.action.fileProtocols=jar,zip + +~~~~~~~ + +Thanks to Amit who the first published solution on his [blog](http://tech\-architecture\.blogspot\.com/2009/02/getting\-struts\-21\-to\-work\-in\-weblogic\.html)^[http://tech\-architecture\.blogspot\.com/2009/02/getting\-struts\-21\-to\-work\-in\-weblogic\.html]
