Repository: struts-site Updated Branches: refs/heads/master 67669c5f2 -> 3e113c51f
Cleans up pages Project: http://git-wip-us.apache.org/repos/asf/struts-site/repo Commit: http://git-wip-us.apache.org/repos/asf/struts-site/commit/3e113c51 Tree: http://git-wip-us.apache.org/repos/asf/struts-site/tree/3e113c51 Diff: http://git-wip-us.apache.org/repos/asf/struts-site/diff/3e113c51 Branch: refs/heads/master Commit: 3e113c51fae4c1ec056e102d39ebd61730bc0b6d Parents: 67669c5 Author: Lukasz Lenart <lukaszlen...@apache.org> Authored: Wed Aug 23 13:16:49 2017 +0200 Committer: Lukasz Lenart <lukaszlen...@apache.org> Committed: Wed Aug 23 13:16:49 2017 +0200 ---------------------------------------------------------------------- source/core-developers/configuration-files.md | 58 +++---- source/core-developers/default-properties.md | 20 +++ source/core-developers/struts-properties.md | 37 ----- source/core-developers/struts-xml.md | 31 +--- source/core-developers/web-xml.md | 182 +++++++-------------- 5 files changed, 108 insertions(+), 220 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/struts-site/blob/3e113c51/source/core-developers/configuration-files.md ---------------------------------------------------------------------- diff --git a/source/core-developers/configuration-files.md b/source/core-developers/configuration-files.md index b2efcab..df655a0 100644 --- a/source/core-developers/configuration-files.md +++ b/source/core-developers/configuration-files.md @@ -5,49 +5,37 @@ title: Configuration Files # Configuration Files -From a Struts developer point of view, the one required configuration file used by the framework is +From a Struts developer point of view, the one required configuration file used by the framework is `web.xml`. +From here, you have full control over how Struts configures both itself and your application. By default, Struts will +load a set of internal configuration files to configure itself, then another set to configure your application, however +it is possible to build an entire Struts application without writing a single configuration file other than `web.xml`. -~~~~~~~ -web.xml -~~~~~~~ -\. From here, you have full control over how Struts configures both itself and your application\. By default, Struts will load a set of internal configuration files to configure itself, then another set to configure your application, however it is possible to build an entire Struts application without writing a single configuration file other than - -~~~~~~~ -web.xml -~~~~~~~ -\. - -The table lists the files that you can use to configure the framework for your application\. Some configuration files can be reloaded dynamically\. Dynamic reloading makes interactive development possible\. See [Reloading configuration](reloading-configuration.html) for more\. +The table lists the files that you can use to configure the framework for your application. Some configuration files +can be reloaded dynamically. Dynamic reloading makes interactive development possible. +See [Reloading configuration](reloading-configuration.html) for more. | File | Optional | Location (relative to webapp) | Purpose | |------|----------|-------------------------------|---------| -|[web.xml](web-xml.html)| no | /WEB\-INF/ | Web deployment descriptor to include all necessary framework components | -|[struts.xml](struts-xml.html)| yes | /WEB\-INF/classes/ | Main configuration, contains result/view types, action mappings, interceptors, and so forth \ +|[web.xml](web-xml.html)| no | /WEB-INF/ | Web deployment descriptor to include all necessary framework components | +|[struts.xml](struts-xml.html)| yes | /WEB-INF/classes/ | Main configuration, contains result/view types, action mappings, interceptors, and so forth \ | -|[struts.properties](struts-properties.html)| yes | /WEB\-INF/classes/ | Framework properties | -|[struts\-default\.xml](struts-default-xml.html)| yes | /WEB\-INF/lib/struts2\-core\.jar | Default configuration provided by Struts | -|[struts\-default\.vm](struts-default-vm.html)| yes | /WEB\-INF/classes/ | Default macros referenced by velocity\.properties| -| struts\-plugin\.xml | yes | At the root of a plugin JAR| Optional configuration files for _Plugins_ in the same format as struts\.xml\. | -|[velocity\.properties](velocity-properties.html)| yes | /WEB\-INF/classes/ | Override the default _Velocity_ configuration | - -####Static Content#### +|[struts.properties](struts-properties.html)| yes | /WEB-INF/classes/ | Framework properties | +|[struts-default.xml](struts-default-xml.html)| yes | /WEB-INF/lib/struts2-core.jar | Default configuration provided by Struts | +|[struts-default.vm](struts-default-vm.html)| yes | /WEB-INF/classes/ | Default macros referenced by velocity.properties| +| struts-plugin.xml | yes | At the root of a plugin JAR| Optional configuration files for [Plugins](../plugins-developer-guide/) in the same format as struts.xml. | +|[velocity.properties](velocity-properties.html)| yes | /WEB-INF/classes/ | Override the default _Velocity_ configuration | -Common static content that is needed by the framework (JavaScript and CSS files, etc\.) is served automatically by the FilterDispatcher filter\. Any request starting with " +## Static Content -~~~~~~~ -/struts/ -~~~~~~~ -" denotes that static content is required, and then mapping the value after " - -~~~~~~~ -/struts/ -~~~~~~~ -" to common packages in the framework and, optionally in the application's class path\. +Common static content that is needed by the framework (JavaScript and CSS files, etc.) is served automatically by +the FilterDispatcher filter. Any request starting with `/struts/` denotes that static content is required, and then +mapping the value after `/struts/` to common packages in the framework and, optionally in the application's class path. By default, the following packages are searched: -+ org\.apache\.struts2\.static - -+ template +- `org.apache.struts2.static` +- `template` -Additional packages can be specified by providing a comma separated list to the configuration parameter named "packages" (configured in web\.xml for the FilterDispatcher filter)\. When specifying additional static content, you should be careful not to expose sensitive configuration information (such as the password to a database)\. +Additional packages can be specified by providing a comma separated list to the configuration parameter named "packages" +(configured in `web.xml` for the FilterDispatcher filter). When specifying additional static content, you should +be careful not to expose sensitive configuration information (such as the password to a database). http://git-wip-us.apache.org/repos/asf/struts-site/blob/3e113c51/source/core-developers/default-properties.md ---------------------------------------------------------------------- diff --git a/source/core-developers/default-properties.md b/source/core-developers/default-properties.md new file mode 100644 index 0000000..65329be --- /dev/null +++ b/source/core-developers/default-properties.md @@ -0,0 +1,20 @@ +--- +layout: core-developers +title: default.properties +--- + +# default.properties + +> All properties can also be set using [Constant Configuration](constant-configuration.html) 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 `default.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 `default.properties` (inside `struts2-core.jar`). + +**default.properties** + +{% highlight txt %} +{% remote_file_content https://raw.githubusercontent.com/apache/struts/master/core/src/main/resources/org/apache/struts2/default.properties %} +{% endhighlight %} http://git-wip-us.apache.org/repos/asf/struts-site/blob/3e113c51/source/core-developers/struts-properties.md ---------------------------------------------------------------------- diff --git a/source/core-developers/struts-properties.md b/source/core-developers/struts-properties.md deleted file mode 100644 index b0bc6df..0000000 --- a/source/core-developers/struts-properties.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -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/3e113c51/source/core-developers/struts-xml.md ---------------------------------------------------------------------- diff --git a/source/core-developers/struts-xml.md b/source/core-developers/struts-xml.md index de06daa..96c827c 100644 --- a/source/core-developers/struts-xml.md +++ b/source/core-developers/struts-xml.md @@ -5,26 +5,11 @@ 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\. +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/3e113c51/source/core-developers/web-xml.md ---------------------------------------------------------------------- diff --git a/source/core-developers/web-xml.md b/source/core-developers/web-xml.md index ab0df71..dc8bf3d 100644 --- a/source/core-developers/web-xml.md +++ b/source/core-developers/web-xml.md @@ -5,32 +5,19 @@ 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. -The +## Simple Example -~~~~~~~ -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 +Configuring `web.xml` for the framework is a matter of adding a filter and filter-mapping. -~~~~~~~ -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\. +**Filter Example (web.xml)** -####Simple Example#### - -Configuring - -~~~~~~~ -web.xml -~~~~~~~ - for the framework is a matter of adding a filter and filter\-mapping\. - -**Filter Example (web\.xml)** - - -~~~~~~~ +```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"; @@ -49,15 +36,14 @@ web.xml <!-- ... --> </web-app> +``` -~~~~~~~ - -#####Changed filter package in Struts \>= 2\.5##### +## 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: +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: - -~~~~~~~ +```xml <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"; @@ -67,87 +53,54 @@ As from Struts 2\.5 all filters were moved to top package, if you are using olde <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 +## 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 -~~~~~~~ +```xml ... <filter> <filter-name>struts2</filter-name> <filter-class>org.apache.struts2.dispatcher.FilterDispatcher</filter-class> ... +``` -~~~~~~~ +See [SiteMesh Plugin](../plugins/sitemesh-plugin.html) for an example on when to use seperate Filters for prepare +and execution phase - See _SiteMesh Plugin_ for an example on when to use seperate Filters for prepare and execution phase +## Exclude specific URLs -#####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. - In the example above we've mapped the Struts 2 dispatcher to +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. -~~~~~~~ -/* -~~~~~~~ -, 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\. +Since Struts 2.1.7, you are able to provide a comma separated 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: -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 - - - - -~~~~~~~ +```xml <struts> - <constant name="struts.action.excludePattern" value=".*unfiltered.*,.*\\.nofilter"/> + <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 +## Taglib Example -~~~~~~~ -struts-core.jar -~~~~~~~ +Typically, configuring a taglib is neither required nor recommended. The taglib is included in `struts-core.jar`, and +the container will discover it automatically. +> 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`. -~~~~~~~ -META-INF -~~~~~~~ - folder, and add a - -~~~~~~~ -taglib -~~~~~~~ - element to the - -~~~~~~~ -web.xml -~~~~~~~ -\. - - -~~~~~~~ +```xml <!-- ... --> </welcome-file-list> @@ -156,17 +109,16 @@ web.xml <taglib-location>/WEB-INF/struts-tags.tld</taglib-location> </taglib> </web-app> +``` -~~~~~~~ +## Custom FileManager and FileManagerFactory implementations -####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. -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: -To register your own FileManger you can do it with \<init\-param/\> as below: - - -~~~~~~~ +```xml <filter> <filter-name>struts2</filter-name> <filter-class>org.apache.struts2.dispatcher.filter.StrutsPrepareAndExecuteFilter</filter-class> @@ -175,47 +127,29 @@ To register your own FileManger you can do it with \<init\-param/\> as below: <param-value>com.company.MyFileManager</param-value> </init-param> </filter> +``` -~~~~~~~ - -You can as well register your own FileManagerFactory with \<init\-param/\>, see example: - +You can as well register your own FileManagerFactory with `<init-param/>`, see example: -~~~~~~~ +```xml <filter> <filter-name>struts2</filter-name> - <filter-class>org.apache.struts2.dispatcher.ng.filter.StrutsPrepareAndExecuteFilter</filter-class> + <filter-class>org.apache.struts2.dispatcher.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 +Take a look on default implementations - `DefaultFileManager.java` and `DefaultFileManagerFactory.java` to understand how and why. -~~~~~~~ -ConfigurationProvider -~~~~~~~ - to programmatically configure your application\. To do this use +## Custom configuration provider -~~~~~~~ -configProviders -~~~~~~~ - (it can be a comma\-separated list of class names) +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: -~~~~~~~ -<init-param/> -~~~~~~~ - as below: - - -~~~~~~~ +```xml <filter> <filter-name>struts2</filter-name> <filter-class>org.apache.struts2.dispatcher.filter.StrutsPrepareAndExecuteFilter</filter-class> @@ -224,8 +158,6 @@ configProviders <param-value>com.company.MyConfigurationProvider</param-value> </init-param> </filter> -~~~~~~~ +``` See [Configuration Provider & Configuration](configuration-provider-and-configuration.html) for more details. - -Â
