http://git-wip-us.apache.org/repos/asf/struts-site/blob/f694fc8f/content/core-developers/logging.html ---------------------------------------------------------------------- diff --git a/content/core-developers/logging.html b/content/core-developers/logging.html index d06ffdf..dcc17c0 100644 --- a/content/core-developers/logging.html +++ b/content/core-developers/logging.html @@ -127,117 +127,115 @@ <a class="edit-on-gh" href="https://github.com/apache/struts-site/edit/master/source/core-developers/logging.md"; title="Edit this page on GitHub">Edit on GitHub</a> <h1 id="logging">Logging</h1> -<p>#####Logging support#####</p> +<h2 id="logging-support">Logging support</h2> + +<blockquote> + <p>As from Struts 2.5 version, the logging layer is deprecated and Struts uses Log4j2 +The logging layer will be dropped with the next major release.</p> +</blockquote> <p>XWork provides its own layer to support logging - it allows to use many different implementations.</p> <p>Currently XWork provides support for the following libraries (in that order base on classpath discovery):</p> <ul> - <li> - <p>Commons Logging</p> - </li> - <li> - <p><a href="http://www\.slf4j\.org/";>SLF4J</a>^[http://www.slf4j.org/]</p> - </li> - <li> - <p><a href="http://logging\.apache\.org/log4j/2\.x/";>Log4j2</a>^[http://logging.apache.org/log4j/2.x/]</p> - </li> - <li> - <p>JDK Logger</p> - </li> + <li>Commons Logging</li> + <li><a href="http://www.slf4j.org/";>SLF4J</a></li> + <li><a href="http://logging.apache.org/log4j/2.x/";>Log4j2</a></li> + <li>JDK Logger</li> </ul> -<p><strong>Usage</strong></p> +<h2 id="usage">Usage</h2> -<p>To use given type of library add it as a Maven dependency or drop into WEB-INF/lib folder. XWork LoggerFactory class will use given logging provider if available.</p> +<p>To use given type of library add it as a Maven dependency or drop into WEB-INF/lib folder. XWork LoggerFactory class will +use given logging provider if available.</p> <p>To add logging to your application simply declare a Logger as follow:</p> -<div class="highlighter-rouge"><pre class="highlight"><code>import com.opensymphony.xwork2.util.logging.Logger; -import com.opensymphony.xwork2.util.logging.LoggerFactory; - -public class MyAction { +<div class="highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">com.opensymphony.xwork2.util.logging.Logger</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">com.opensymphony.xwork2.util.logging.LoggerFactory</span><span class="o">;</span> - private static final Logger LOG = LoggerFactory.getLogger(MyAction.class); +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyAction</span> <span class="o">{</span> - private String userName; + <span class="kd">private</span> <span class="kd">static</span> <span class="kd">final</span> <span class="n">Logger</span> <span class="n">LOG</span> <span class="o">=</span> <span class="n">LoggerFactory</span><span class="o">.</span><span class="na">getLogger</span><span class="o">(</span><span class="n">MyAction</span><span class="o">.</span><span class="na">class</span><span class="o">);</span> - public String execute() { - LOG.debug("MyAction executed with UserName [#0]", userName); - return "success"; - } + <span class="kd">private</span> <span class="n">String</span> <span class="n">userName</span><span class="o">;</span> - // getter / setter + <span class="kd">public</span> <span class="n">String</span> <span class="n">execute</span><span class="o">()</span> <span class="o">{</span> + <span class="n">LOG</span><span class="o">.</span><span class="na">debug</span><span class="o">(</span><span class="s">"MyAction executed with UserName [#0]"</span><span class="o">,</span> <span class="n">userName</span><span class="o">);</span> + <span class="k">return</span> <span class="s">"success"</span><span class="o">;</span> + <span class="o">}</span> -} + <span class="c1">// getter / setter</span> +<span class="o">}</span> </code></pre> </div> -<p><strong>Implementing my own factory</strong></p> +<h2 id="implementing-my-own-factory">Implementing my own factory</h2> -<p>You plug in your own logging solution, simple extend LoggerFactory class and provide a delegate which implements Logger interface, like below:</p> +<p>You plug in your own logging solution, simple extend LoggerFactory class and provide a delegate which implements Logger +interface, like below:</p> <p><strong>JdkLoggerFactory which adds support for JDK logging</strong></p> -<div class="highlighter-rouge"><pre class="highlight"><code>import com.opensymphony.xwork2.util.logging.Logger; -import com.opensymphony.xwork2.util.logging.LoggerFactory; +<div class="highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">com.opensymphony.xwork2.util.logging.Logger</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">com.opensymphony.xwork2.util.logging.LoggerFactory</span><span class="o">;</span> -/** +<span class="cm">/** * Creates jdk loggers - */ -public class JdkLoggerFactory extends LoggerFactory { + */</span> +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">JdkLoggerFactory</span> <span class="kd">extends</span> <span class="n">LoggerFactory</span> <span class="o">{</span> - @Override - protected Logger getLoggerImpl(Class<?> cls) { - return new JdkLogger(java.util.logging.Logger.getLogger(cls.getName())); - } + <span class="nd">@Override</span> + <span class="kd">protected</span> <span class="n">Logger</span> <span class="n">getLoggerImpl</span><span class="o">(</span><span class="n">Class</span><span class="o"><?></span> <span class="n">cls</span><span class="o">)</span> <span class="o">{</span> + <span class="k">return</span> <span class="k">new</span> <span class="n">JdkLogger</span><span class="o">(</span><span class="n">java</span><span class="o">.</span><span class="na">util</span><span class="o">.</span><span class="na">logging</span><span class="o">.</span><span class="na">Logger</span><span class="o">.</span><span class="na">getLogger</span><span class="o">(</span><span class="n">cls</span><span class="o">.</span><span class="na">getName</span><span class="o">()));</span> + <span class="o">}</span> - @Override - protected Logger getLoggerImpl(String name) { - return new JdkLogger(java.util.logging.Logger.getLogger(name)); - } -} - + <span class="nd">@Override</span> + <span class="kd">protected</span> <span class="n">Logger</span> <span class="n">getLoggerImpl</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">)</span> <span class="o">{</span> + <span class="k">return</span> <span class="k">new</span> <span class="n">JdkLogger</span><span class="o">(</span><span class="n">java</span><span class="o">.</span><span class="na">util</span><span class="o">.</span><span class="na">logging</span><span class="o">.</span><span class="na">Logger</span><span class="o">.</span><span class="na">getLogger</span><span class="o">(</span><span class="n">name</span><span class="o">));</span> + <span class="o">}</span> +<span class="o">}</span> </code></pre> </div> <p><strong>JdkLogger is a wrapper around java.util.logging.Logger and implements Logger interface</strong></p> -<div class="highlighter-rouge"><pre class="highlight"><code>import com.opensymphony.xwork2.util.logging.Logger; -import com.opensymphony.xwork2.util.logging.LoggerUtils; +<div class="highlighter-rouge"><pre class="highlight"><code><span class="o">~~~~~~~</span> +<span class="kn">import</span> <span class="nn">com.opensymphony.xwork2.util.logging.Logger</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">com.opensymphony.xwork2.util.logging.LoggerUtils</span><span class="o">;</span> -import java.util.logging.Level; +<span class="kn">import</span> <span class="nn">java.util.logging.Level</span><span class="o">;</span> -/** +<span class="cm">/** * Delegates to jdk logger. Maps fatal to Level.SEVERE along with error. - */ -public class JdkLogger implements Logger { + */</span> +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">JdkLogger</span> <span class="kd">implements</span> <span class="n">Logger</span> <span class="o">{</span> - private java.util.logging.Logger log; + <span class="kd">private</span> <span class="n">java</span><span class="o">.</span><span class="na">util</span><span class="o">.</span><span class="na">logging</span><span class="o">.</span><span class="na">Logger</span> <span class="n">log</span><span class="o">;</span> - public JdkLogger(java.util.logging.Logger log) { - this.log = log; - } + <span class="kd">public</span> <span class="n">JdkLogger</span><span class="o">(</span><span class="n">java</span><span class="o">.</span><span class="na">util</span><span class="o">.</span><span class="na">logging</span><span class="o">.</span><span class="na">Logger</span> <span class="n">log</span><span class="o">)</span> <span class="o">{</span> + <span class="k">this</span><span class="o">.</span><span class="na">log</span> <span class="o">=</span> <span class="n">log</span><span class="o">;</span> + <span class="o">}</span> - public void error(String msg, String... args) { - log.log(Level.SEVERE, LoggerUtils.format(msg, args)); - } + <span class="kd">public</span> <span class="kt">void</span> <span class="n">error</span><span class="o">(</span><span class="n">String</span> <span class="n">msg</span><span class="o">,</span> <span class="n">String</span><span class="o">...</span> <span class="n">args</span><span class="o">)</span> <span class="o">{</span> + <span class="n">log</span><span class="o">.</span><span class="na">log</span><span class="o">(</span><span class="n">Level</span><span class="o">.</span><span class="na">SEVERE</span><span class="o">,</span> <span class="n">LoggerUtils</span><span class="o">.</span><span class="na">format</span><span class="o">(</span><span class="n">msg</span><span class="o">,</span> <span class="n">args</span><span class="o">));</span> + <span class="o">}</span> - public void error(String msg, Throwable ex, String... args) { - log.log(Level.SEVERE, LoggerUtils.format(msg, args), ex); - } + <span class="kd">public</span> <span class="kt">void</span> <span class="n">error</span><span class="o">(</span><span class="n">String</span> <span class="n">msg</span><span class="o">,</span> <span class="n">Throwable</span> <span class="n">ex</span><span class="o">,</span> <span class="n">String</span><span class="o">...</span> <span class="n">args</span><span class="o">)</span> <span class="o">{</span> + <span class="n">log</span><span class="o">.</span><span class="na">log</span><span class="o">(</span><span class="n">Level</span><span class="o">.</span><span class="na">SEVERE</span><span class="o">,</span> <span class="n">LoggerUtils</span><span class="o">.</span><span class="na">format</span><span class="o">(</span><span class="n">msg</span><span class="o">,</span> <span class="n">args</span><span class="o">),</span> <span class="n">ex</span><span class="o">);</span> + <span class="o">}</span> - ... -} - + <span class="o">...</span> +<span class="o">}</span> </code></pre> </div> -<p>Check <a href="http://struts\.apache\.org/2\.x/xwork\-core/apidocs/com/opensymphony/xwork2/util/logging/package\-summary\.html";>the source code</a>^[http://struts.apache.org/2.x/xwork-core/apidocs/com/opensymphony/xwork2/util/logging/package-summary.html] to see more details.</p> +<p>Check <a href="http://struts.apache.org/struts-core/apidocs/com/opensymphony/xwork2/util/logging/package-summary.html";>the source code</a> +to see more details.</p> -<p><strong>Defining which factory to use</strong></p> +<h2 id="defining-which-factory-to-use">Defining which factory to use</h2> <p>Now you must tell XWork/Struts2 to use your implementation, just define system property like below:</p> @@ -251,16 +249,14 @@ public class JdkLogger implements Logger { </code></pre> </div> -<div class="highlighter-rouge"><pre class="highlight"><code>or -</code></pre> -</div> +<p>or</p> <div class="highlighter-rouge"><pre class="highlight"><code>-Dxwork.loggerFactory=com.opensymphony.xwork2.util.logging.log4j2.Log4j2LoggerFactory </code></pre> </div> -<p>will enable Slf4j or Log4j2 even if there is commons-logging on classpath available (commons-logging is the first LoggerFactory to look for).</p> - +<p>will enable Slf4j or Log4j2 even if there is commons-logging on classpath available (commons-logging is the first +LoggerFactory to look for).</p> </section> </article>
http://git-wip-us.apache.org/repos/asf/struts-site/blob/f694fc8f/content/core-developers/model-driven-interceptor.html ---------------------------------------------------------------------- diff --git a/content/core-developers/model-driven-interceptor.html b/content/core-developers/model-driven-interceptor.html index bbb7a53..8864426 100644 --- a/content/core-developers/model-driven-interceptor.html +++ b/content/core-developers/model-driven-interceptor.html @@ -127,129 +127,52 @@ <a class="edit-on-gh" href="https://github.com/apache/struts-site/edit/master/source/core-developers/model-driven-interceptor.md"; title="Edit this page on GitHub">Edit on GitHub</a> <h1 id="model-driven-interceptor">Model Driven Interceptor</h1> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.interceptor.ModelDrivenInterceptor</span><span class="p">}</span><span class="w"> -</span></code></pre> -</div> - -<table> - <tbody> - <tr> - <td>To create a Model Driven action, implement the ModelDriven interface by adding a model property, or at least the accessor.</td> - </tr> - </tbody> -</table> - -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> - -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> - -<table> - <tbody> - <tr> - <td>public Object getModel() ...</td> - </tr> - </tbody> -</table> - -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> +<p>Watches for <code class="highlighter-rouge">ModelDriven</code> actions and adds the actionâs model on to the value stack.</p> -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> +<blockquote> + <p>The <code class="highlighter-rouge">ModelDrivenInterceptor</code> must come before the both <code class="highlighter-rouge">StaticParametersInterceptor</code> and <code class="highlighter-rouge">ParametersInterceptor</code> +if you want the parameters to be applied to the model.</p> +</blockquote> -<table> - <tbody> - <tr> - <td>In the implementation of getModel, acquire an instance of a business object and return it.</td> - </tr> - </tbody> -</table> +<blockquote> + <p>The <code class="highlighter-rouge">ModelDrivenInterceptor</code> will only push the model into the stack when the model is not null, else it will be ignored.</p> +</blockquote> -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> +<p>To create a Model Driven action, implement the <code class="highlighter-rouge">ModelDriven</code> interface by adding a model property, or at least the accessor.</p> -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> - -<table> - <tbody> - <tr> - <td>On the page, you can address any JavaBean properties on the business object as if they were coded directly on the Action class. (The framework pushes the Model object onto the ValueStack.)</td> - </tr> - </tbody> -</table> +<div class="highlighter-rouge"><pre class="highlight"><code><span class="kd">public</span> <span class="n">Object</span> <span class="nf">getModel</span><span class="p">(</span><span class="o">);</span> +</code></pre> +</div> -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> +<p>In the implementation of <code class="highlighter-rouge">getModel</code>, acquire an instance of a business object and return it.</p> -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> +<p>On the page, you can address any JavaBean properties on the business object as if they were coded directly on the Action +class. The framework pushes the Model object onto the ValueStack.</p> -<table> - <tbody> - <tr> - <td>Many developers use Spring to acquire the business object. With the addition of a setModel method, the business logic can be injected automatically.</td> - </tr> - </tbody> -</table> +<p>Many developers use Spring to acquire the business object. With the addition of a <code class="highlighter-rouge">setModel</code> method, the business logic +can be injected automatically.</p> -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> +<h2 id="parameters">Parameters</h2> -<p>#####Parameters#####</p> +<ul> + <li><code class="highlighter-rouge">refreshModelBeforeResult</code> - set to true if you want the model to be refreshed on the value stack after action +execution and before result execution. The setting is useful if you want to change the model instance during the +action execution phase, like when loading it from the data layer. This will result in <code class="highlighter-rouge">getModel()</code> being called at +least twice.</li> +</ul> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=parameters|javadoc=true|url=com.opensymphony.xwork2.interceptor.ModelDrivenInterceptor</span><span class="p">}</span><span class="w"> -</span></code></pre> -</div> +<h2 id="extending-the-interceptor">Extending the Interceptor</h2> -<p>#####Extending the Interceptor#####</p> - -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=extending|javadoc=true|url=com.opensymphony.xwork2.interceptor.ModelDrivenInterceptor</span><span class="p">}</span><span class="w"> -</span></code></pre> -</div> +<p>There are no known extension points to this interceptor.</p> -<p>#####Examples#####</p> +<h2 id="examples">Examples</h2> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=example|lang=xml|javadoc=true|url=com.opensymphony.xwork2.interceptor.ModelDrivenInterceptor</span><span class="p">}</span><span class="w"> -</span></code></pre> +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><action</span> <span class="na">name=</span><span class="s">"someAction"</span> <span class="na">class=</span><span class="s">"com.examples.SomeAction"</span><span class="nt">></span> + <span class="nt"><interceptor-ref</span> <span class="na">name=</span><span class="s">"modelDriven"</span><span class="nt">/></span> + <span class="nt"><interceptor-ref</span> <span class="na">name=</span><span class="s">"basicStack"</span><span class="nt">/></span> + <span class="nt"><result</span> <span class="na">name=</span><span class="s">"success"</span><span class="nt">></span>good_result.ftl<span class="nt"></result></span> + <span class="nt"></action></span> +</code></pre> </div> </section> http://git-wip-us.apache.org/repos/asf/struts-site/blob/f694fc8f/content/core-developers/parameters-interceptor.html ---------------------------------------------------------------------- diff --git a/content/core-developers/parameters-interceptor.html b/content/core-developers/parameters-interceptor.html index 74bad74..37e8f6e 100644 --- a/content/core-developers/parameters-interceptor.html +++ b/content/core-developers/parameters-interceptor.html @@ -129,156 +129,68 @@ <p>This interceptor sets all parameters on the value stack.</p> -<p>This interceptor gets all parameters from {@link ActionContext#getParameters()} and sets them on the value stack by calling</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>ValueStack#setValue(String, Object) -</code></pre> -</div> -<p>, typically resulting in the values submitted in a form request being applied to an action in the value stack. Note that the parameter map must contain a String key and often containers a String[] for the value.</p> - -<p>The interceptor takes one parameter named âorderedâ. When set to true action properties are guaranteed to be set top-down which means that top actionâs properties are set first. Then itâs subcomponents properties are set. The reason for this order is to enable a âfactoryâ pattern. For example, letâs assume that one has an action that contains a property named</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>modelClass -</code></pre> -</div> -<p> that allows to choose what is the underlying implementation of model. By assuring that</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>modelClass -</code></pre> -</div> -<p> property is set before any model properties are set, itâs possible to choose model implementation during</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>action.setModelClass() -</code></pre> -</div> -<p> call. Similarly itâs possible to use</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>action.setPrimaryKey() -</code></pre> -</div> -<p>property set call to actually load the model class from persistent storage. Without any assumption on parameter order you have to use patterns like <em>Preparable Interface</em> .</p> - -<p>Because parameter names are effectively OGNL statements, it is important that security be taken in to account. This interceptor will not apply any values in the parameters map if the expression contains an assignment (=), multiple expressions (,), or references any objects in the context (#). This is all done in the</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>#acceptableName(String) -</code></pre> -</div> -<p> method. In addition to this method, if the action being invoked implements the </p> - -<div class="highlighter-rouge"><pre class="highlight"><code>ParameterNameAware -</code></pre> -</div> -<p> interface, the action will be consulted to determine if the parameter should be set. -In addition to these restrictions, a flag (</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>ReflectionContextState#DENY_METHOD_EXECUTION -</code></pre> -</div> -<p> ) is set such that no methods are allowed to be invoked. That means that any expression such as</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>person.doSomething() -</code></pre> -</div> -<p> or </p> - -<div class="highlighter-rouge"><pre class="highlight"><code>person.getName() -</code></pre> -</div> -<p> will be explicitly forbidden. This is needed to make sure that your application is not exposed to attacks by malicious users.</p> - -<p>While this interceptor is being invoked, a flag (</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>ReflectionContextState#CREATE_NULL_OBJECTS -</code></pre> -</div> -<p> ) is turned on to ensure that any null reference is automatically created - if possible. See the type conversion documentation and the</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>InstantiatingNullHandler -</code></pre> -</div> -<p> javadocs for more information.</p> - -<p>Finally, a third flag (</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>XWorkConverter#REPORT_CONVERSION_ERRORS -</code></pre> -</div> -<p> ) is set that indicates any errors when converting the the values to their final data type (String[] -> int) an unrecoverable error occurred. With this flag set, the type conversion errors will be reported in the action context. See the type conversion documentation and the</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>XWorkConverter -</code></pre> -</div> -<p> javadocs for more information.</p> - -<p>If you are looking for detailed logging information about your parameters, turn on</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>DEBUG -</code></pre> -</div> -<p> level logging for this interceptor. A detailed log of all the parameter keys and values will be reported.</p> - -<p>Since XWork 2.0.2, this interceptor extends MethodFilterInterceptor, therefore being able to deal with excludeMethods / includeMethods parameters. See <a href="default-workflow-interceptor.html">Default Workflow Interceptor</a> for documentation and examples on how to use this feature.</p> - -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> - -<p>For more information on ways to restrict the parameter names allowed, see the</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>ParameterNameAware -</code></pre> -</div> -<p> javadocs.</p> - -<p>#####Parameters#####</p> - -<ul> - <li></li> -</ul> - -<div class="highlighter-rouge"><pre class="highlight"><code>ordered -</code></pre> -</div> -<p> - set to true if you want the top-down property setter behaviour</p> +<p>This interceptor gets all parameters from <code class="highlighter-rouge">ActionContext#getParameters()</code> and sets them on the value stack by calling +<code class="highlighter-rouge">ValueStack#setValue(String, Object)</code>, typically resulting in the values submitted in a form request being applied +to an action in the value stack. Note that the parameter map must contain a <code class="highlighter-rouge">String</code> key and often containers a <code class="highlighter-rouge">String[]</code> +for the value.</p> + +<p>The interceptor takes one parameter named <code class="highlighter-rouge">ordered</code>. When set to true action properties are guaranteed to be set top-down +which means that top actionâs properties are set first. Then itâs subcomponents properties are set. The reason for this +order is to enable a âfactoryâ pattern. For example, letâs assume that one has an action that contains a property named +<code class="highlighter-rouge">modelClass</code> that allows to choose what is the underlying implementation of model. By assuring that <code class="highlighter-rouge">modelClass</code> +property is set before any model properties are set, itâs possible to choose model implementation during +<code class="highlighter-rouge">action.setModelClass()</code> call. Similarly itâs possible to use <code class="highlighter-rouge">action.setPrimaryKey()</code> property set call to actually +load the model class from persistent storage. Without any assumption on parameter order you have to use patterns +like <a href="prepare-interceptor.html">Preparable Interface</a>.</p> + +<p>Because parameter names are effectively OGNL statements, it is important that security be taken in to account. This +interceptor will not apply any values in the parameters map if the expression contains an assignment (=), multiple +expressions (,), or references any objects in the context (#). This is all done in the <code class="highlighter-rouge">#acceptableName(String)</code> +method. In addition to this method, if the action being invoked implements the <code class="highlighter-rouge">ParameterNameAware</code> interface, the action +will be consulted to determine if the parameter should be set.</p> + +<p>In addition to these restrictions, a flag (<code class="highlighter-rouge">ReflectionContextState#DENY_METHOD_EXECUTION</code>) is set such that no methods +are allowed to be invoked. That means that any expression such as <code class="highlighter-rouge">person.doSomething()</code> or <code class="highlighter-rouge">person.getName()</code> will be +explicitly forbidden. This is needed to make sure that your application is not exposed to attacks by malicious users.</p> + +<p>While this interceptor is being invoked, a flag (<code class="highlighter-rouge">ReflectionContextState#CREATE_NULL_OBJECTS</code>) is turned on to ensure +that any null reference is automatically created - if possible. See the type conversion documentation +and the <code class="highlighter-rouge">InstantiatingNullHandler</code> javadocs for more information.</p> + +<p>Finally, a third flag (<code class="highlighter-rouge">XWorkConverter#REPORT_CONVERSION_ERRORS</code>) is set that indicates any errors when converting +the values to their final data type (<code class="highlighter-rouge">String[] -> int</code>) an unrecoverable error occurred. With this flag set, the type +conversion errors will be reported in the action context. See the type conversion documentation and the <code class="highlighter-rouge">XWorkConverter</code> +javadocs for more information.</p> + +<p>If you are looking for detailed logging information about your parameters, turn on <code class="highlighter-rouge">DEBUG</code> level logging for this +interceptor. A detailed log of all the parameter keys and values will be reported.</p> + +<p>Since XWork 2.0.2, this interceptor extends <code class="highlighter-rouge">MethodFilterInterceptor</code>, therefore being able to deal with +excludeMethods/includeMethods parameters. See <a href="default-workflow-interceptor.html">Default Workflow Interceptor</a> +for documentation and examples on how to use this feature.</p> + +<p>For more information on ways to restrict the parameter names allowed, see the <code class="highlighter-rouge">ParameterNameAware</code> javadocs.</p> + +<h2 id="parameters">Parameters</h2> <ul> - <li></li> + <li><code class="highlighter-rouge">ordered</code> - set to true if you want the top-down property setter behaviour</li> + <li><code class="highlighter-rouge">acceptParamNames</code> - a comma delimited list of regular expressions to describe a whitelist of accepted parameter names. +Donât change the default unless you know what you are doing in terms of security implications</li> + <li><code class="highlighter-rouge">excludeParams</code> - a comma delimited list of regular expressions to describe a blacklist of not allowed parameter names</li> + <li><code class="highlighter-rouge">paramNameMaxLength</code> - the maximum length of parameter names; parameters with longer names will be ignored; +the default is 100 characters</li> </ul> -<div class="highlighter-rouge"><pre class="highlight"><code>acceptParamNames -</code></pre> -</div> -<p> - a comma delimited list of regular expressions to describe a whitelist of accepted parameter names. Donât change the default unless you know what you are doing in terms of security implications</p> +<h2 id="excluding-parameters">Excluding parameters</h2> -<ul> - <li></li> -</ul> - -<div class="highlighter-rouge"><pre class="highlight"><code>excludeParams -</code></pre> -</div> -<p> - a comma delimited list of regular expressions to describe a blacklist of not allowed parameter names</p> - -<ul> - <li></li> -</ul> - -<div class="highlighter-rouge"><pre class="highlight"><code>paramNameMaxLength -</code></pre> -</div> -<p> - the maximum length of parameter names; parameters with longer names will be ignored; the default is 100 characters</p> - -<p>#####Excluding parameters#####</p> - -<p>This interceptor can be forced to ignore parameters, by setting its <em>excludeParams</em> attribute. This attribute accepts a comma separated list of regular expressions. When any of these expressions match the name of a parameter, such parameter will be ignored by the interceptor. Interceptor stacks defined by Struts already exclude some parameters:</p> +<p>This interceptor can be forced to ignore parameters, by setting its <code class="highlighter-rouge">excludeParams</code> attribute. This attribute accepts +a comma separated list of regular expressions. When any of these expressions match the name of a parameter, such parameter +will be ignored by the interceptor. Interceptor stacks defined by Struts already exclude some parameters:</p> <p><strong>Default List of Parameters Excluded</strong></p> -<div class="highlighter-rouge"><pre class="highlight"><code>dojo\..*,^struts\..*,^session\..*,^request\..*,^application\..*,^servlet(Request|Response)\..*,parameters\...* - +<div class="highlighter-rouge"><pre class="highlight"><code>dojo..*,^struts..*,^session..*,^request..*,^application..*,^servlet(Request|Response)..*,parameters...* </code></pre> </div> @@ -286,85 +198,58 @@ In addition to these restrictions, a flag (</p> <p><strong>Setup Interceptor Stack To Exclude submit Parameter</strong></p> -<div class="highlighter-rouge"><pre class="highlight"><code><interceptors> - <interceptor-stack name="appDefault"> - <interceptor-ref name="defaultStack"> - <param name="exception.logEnabled">true</param> - <param name="exception.logLevel">ERROR</param> - <param name="params.excludeParams">dojo\..*,^struts\..*,^session\..*,^request\..*,^application\..*,^servlet(Request|Response)\..*,parameters\...*,submit</param> - </interceptor-ref> - </interceptor-stack> -</interceptors> - -<default-interceptor-ref name="appDefault" /> - +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><interceptors></span> + <span class="nt"><interceptor-stack</span> <span class="na">name=</span><span class="s">"appDefault"</span><span class="nt">></span> + <span class="nt"><interceptor-ref</span> <span class="na">name=</span><span class="s">"defaultStack"</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"exception.logEnabled"</span><span class="nt">></span>true<span class="nt"></param></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"exception.logLevel"</span><span class="nt">></span>ERROR<span class="nt"></param></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"params.excludeParams"</span><span class="nt">></span>dojo..*,^struts..*,^session..*,^request..*,^application..*,^servlet(Request|Response)..*,parameters...*,submit<span class="nt"></param></span> + <span class="nt"></interceptor-ref></span> + <span class="nt"></interceptor-stack></span> +<span class="nt"></interceptors></span> + +<span class="nt"><default-interceptor-ref</span> <span class="na">name=</span><span class="s">"appDefault"</span> <span class="nt">/></span> </code></pre> </div> -<p>#####Extending the Interceptor#####</p> +<h2 id="extending-the-interceptor">Extending the Interceptor</h2> -<p>The best way to add behavior to this interceptor is to utilize the</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>ParameterNameAware -</code></pre> -</div> -<p> interface in your actions. However, if you wish to apply a global rule that isnât implemented in your action, then you could extend this interceptor and override the</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>#acceptableName(String) -</code></pre> -</div> -<p> method.</p> - -<blockquote> - -</blockquote> - -<blockquote> - -</blockquote> +<p>The best way to add behavior to this interceptor is to utilize the <code class="highlighter-rouge">ParameterNameAware</code> interface in your actions. +However, if you wish to apply a global rule that isnât implemented in your action, then you could extend this interceptor +and override the <code class="highlighter-rouge">#acceptableName(String)</code> method.</p> <blockquote> - <p>Using ParameterNameAware could be dangerous as ParameterNameAware#acceptableParameterName(String) takes precedence over ParametersInterceptor which means if ParametersInterceptor excluded given parameter name you can accept it with ParameterNameAware#acceptableParameterName(String).</p> + <p>Using <code class="highlighter-rouge">ParameterNameAware</code> could be dangerous as <code class="highlighter-rouge">ParameterNameAware#acceptableParameterName(String)</code> takes precedence +over <code class="highlighter-rouge">ParametersInterceptor</code> which means if <code class="highlighter-rouge">ParametersInterceptor</code> excluded given parameter name you can accept +it with <code class="highlighter-rouge">ParameterNameAware#acceptableParameterName(String)</code>.</p> </blockquote> <blockquote> - + <p>The best idea is to define very tight restrictions with <code class="highlighter-rouge">ParametersInterceptor</code> and relax them per action +with <code class="highlighter-rouge">ParameterNameAware#acceptableParameterName(String)</code></p> </blockquote> -<blockquote> - -</blockquote> - -<blockquote> - <p>The best idea is to define very tight restrictions with ParametersInterceptor and relax them per action with ParameterNameAware#acceptableParameterName(String)</p> -</blockquote> - -<blockquote> - -</blockquote> - -<p>#####Warning on missing parameters#####</p> +<h2 id="warning-on-missing-parameters">Warning on missing parameters</h2> <p>When there is no setter for given parameter name, a warning message like below will be logged in devMode:</p> <div class="highlighter-rouge"><pre class="highlight"><code>SEVERE: Developer Notification (set struts.devMode to false to disable this message): Unexpected Exception caught setting 'search' on 'class demo.ItemSearchAction: Error setting expression 'search' with value ['search', ] Error setting expression 'search' with value ['search', ] - [unknown location] - at com.opensymphony.xwork2.ognl.OgnlValueStack.handleRuntimeException(OgnlValueStack.java:201) - at com.opensymphony.xwork2.ognl.OgnlValueStack.setValue(OgnlValueStack.java:178) - at com.opensymphony.xwork2.ognl.OgnlValueStack.setParameter(OgnlValueStack.java:152) - + at com.opensymphony.xwork2.ognl.OgnlValueStack.handleRuntimeException(OgnlValueStack.java:201) + at com.opensymphony.xwork2.ognl.OgnlValueStack.setValue(OgnlValueStack.java:178) + at com.opensymphony.xwork2.ognl.OgnlValueStack.setParameter(OgnlValueStack.java:152) </code></pre> </div> <p>Thus is expected behaviour to allow developer to spot missing setter or typo in either parameter name or setter.</p> -<p>#####Examples#####</p> +<p>###Examples</p> -<div class="highlighter-rouge"><pre class="highlight"><code><action name="someAction" class="com.examples.SomeAction"> - <interceptor-ref name="params"/> - <result name="success">good_result.ftl</result> -</action> +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><action</span> <span class="na">name=</span><span class="s">"someAction"</span> <span class="na">class=</span><span class="s">"com.examples.SomeAction"</span><span class="nt">></span> + <span class="nt"><interceptor-ref</span> <span class="na">name=</span><span class="s">"params"</span><span class="nt">/></span> + <span class="nt"><result</span> <span class="na">name=</span><span class="s">"success"</span><span class="nt">></span>good_result.ftl<span class="nt"></result></span> +<span class="nt"></action></span> </code></pre> </div> http://git-wip-us.apache.org/repos/asf/struts-site/blob/f694fc8f/content/core-developers/pre-result-listener.html ---------------------------------------------------------------------- diff --git a/content/core-developers/pre-result-listener.html b/content/core-developers/pre-result-listener.html index 3f382e3..c5768c0 100644 --- a/content/core-developers/pre-result-listener.html +++ b/content/core-developers/pre-result-listener.html @@ -127,48 +127,46 @@ <a class="edit-on-gh" href="https://github.com/apache/struts-site/edit/master/source/core-developers/pre-result-listener.md"; title="Edit this page on GitHub">Edit on GitHub</a> <h1 id="preresultlistener">PreResultListener</h1> -<p>A PreResultListener can affect an action invocation between the interceptor/action phase and the result phase. Typical uses include switching to a different Result or somehow modifying the Result or Action objects before the Result executes.</p> - -<p>####Examples####</p> - -<p>A PreResultListener can be added by an Action or an Interceptor.</p> - -<p>#####By an Action#####</p> - -<div class="highlighter-rouge"><pre class="highlight"><code> - public class MyAction extends ActionSupport { - ... - public String execute() throws Exception { - ActionInvocation invocation = ActionContext.getContext().getActionInvocation(); - invocation.addPreResultListener(new PreResultListener() { - public void beforeResult(ActionInvocation invocation, - String resultCode) { - // perform operation necessary before Result execution - } - }); - } - ... - } - +<p>A <code class="highlighter-rouge">PreResultListener</code> can affect an action invocation between the interceptor/action phase and the result phase. +Typical uses include switching to a different Result or somehow modifying the Result or Action objects before +the Result executes.</p> + +<h2 id="examples">Examples</h2> + +<p>A <code class="highlighter-rouge">PreResultListener</code> can be added by an Action or an Interceptor.</p> + +<h3 id="by-an-action">By an Action</h3> + +<div class="highlighter-rouge"><pre class="highlight"><code> <span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyAction</span> <span class="kd">extends</span> <span class="n">ActionSupport</span> <span class="o">{</span> + <span class="o">...</span> + <span class="kd">public</span> <span class="n">String</span> <span class="n">execute</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span> <span class="o">{</span> + <span class="n">ActionInvocation</span> <span class="n">invocation</span> <span class="o">=</span> <span class="n">ActionContext</span><span class="o">.</span><span class="na">getContext</span><span class="o">().</span><span class="na">getActionInvocation</span><span class="o">();</span> + <span class="n">invocation</span><span class="o">.</span><span class="na">addPreResultListener</span><span class="o">(</span><span class="k">new</span> <span class="n">PreResultListener</span><span class="o">()</span> <span class="o">{</span> + <span class="kd">public</span> <span class="kt">void</span> <span class="n">beforeResult</span><span class="o">(</span><span class="n">ActionInvocation</span> <span class="n">invocation</span><span class="o">,</span> + <span class="n">String</span> <span class="n">resultCode</span><span class="o">)</span> <span class="o">{</span> + <span class="c1">// perform operation necessary before Result execution</span> + <span class="o">}</span> + <span class="o">});</span> + <span class="o">}</span> + <span class="o">...</span> + <span class="o">}</span> </code></pre> </div> -<p>#####By an Interceptor#####</p> - -<div class="highlighter-rouge"><pre class="highlight"><code> - public class MyInterceptor extends AbstractInterceptor { - ... - public String intercept(ActionInvocation invocation) throws Exception { - invocation.addPreResultListener(new PreResultListener() { - public void beforeResult(ActionInvocation invocation, - String resultCode) { - // perform operation necessary before Result execution - } - }); - } - ... - } - +<h3 id="by-an-interceptor">By an Interceptor</h3> + +<div class="highlighter-rouge"><pre class="highlight"><code> <span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyInterceptor</span> <span class="kd">extends</span> <span class="n">AbstractInterceptor</span> <span class="o">{</span> + <span class="o">...</span> + <span class="kd">public</span> <span class="n">String</span> <span class="n">intercept</span><span class="o">(</span><span class="n">ActionInvocation</span> <span class="n">invocation</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">Exception</span> <span class="o">{</span> + <span class="n">invocation</span><span class="o">.</span><span class="na">addPreResultListener</span><span class="o">(</span><span class="k">new</span> <span class="n">PreResultListener</span><span class="o">()</span> <span class="o">{</span> + <span class="kd">public</span> <span class="kt">void</span> <span class="n">beforeResult</span><span class="o">(</span><span class="n">ActionInvocation</span> <span class="n">invocation</span><span class="o">,</span> + <span class="n">String</span> <span class="n">resultCode</span><span class="o">)</span> <span class="o">{</span> + <span class="c1">// perform operation necessary before Result execution</span> + <span class="o">}</span> + <span class="o">});</span> + <span class="o">}</span> + <span class="o">...</span> + <span class="o">}</span> </code></pre> </div> http://git-wip-us.apache.org/repos/asf/struts-site/blob/f694fc8f/content/core-developers/result-types.html ---------------------------------------------------------------------- diff --git a/content/core-developers/result-types.html b/content/core-developers/result-types.html index 44d556d..ccbfea9 100644 --- a/content/core-developers/result-types.html +++ b/content/core-developers/result-types.html @@ -127,25 +127,21 @@ <a class="edit-on-gh" href="https://github.com/apache/struts-site/edit/master/source/core-developers/result-types.md"; title="Edit this page on GitHub">Edit on GitHub</a> <h1 id="result-types">Result Types</h1> -<p>Most use cases can be divided into two phases. First, we need to change or query the applicationâs state, and then we need to present an updated view of the application. The Action class manages the applicationâs state, and the Result Type manages the view.</p> +<p>Most use cases can be divided into two phases. First, we need to change or query the applicationâs state, and then we need +to present an updated view of the application. The Action class manages the applicationâs state, and the Result Type +manages the view.</p> -<p>####Predefined Result Types####</p> +<h2 id="predefined-result-types">Predefined Result Types</h2> -<p>The framework provides several implementations of the</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>com.opensymphony.xwork2.Result -</code></pre> -</div> -<p>interface, ready to use in your own applications.</p> +<p>The framework provides several implementations of the <code class="highlighter-rouge">com.opensymphony.xwork2.Result</code> interface, ready to use in your +own applications.</p> <table> - <thead> + <tbody> <tr> - <th><a href="chain-result.html">Chain Result</a></th> - <th>Used for <a href="action-chaining.html">Action Chaining</a></th> + <td><a href="chain-result.html">Chain Result</a></td> + <td>Used for <a href="action-chaining.html">Action Chaining</a></td> </tr> - </thead> - <tbody> <tr> <td><a href="dispatcher-reult.html">Dispatcher Result</a></td> <td>Used for web resource integration, including <em>JSP</em> integration</td> @@ -183,98 +179,83 @@ <td>Used to display the raw content of a particular page (i.e jsp, HTML)</td> </tr> <tr> - <td><em>Tiles 2 Result</em></td> - <td>Used to provide Tiles 2 integration</td> - </tr> - <tr> - <td><em>Tiles 3 Result</em></td> - <td>Used to provide Tiles 3 integration</td> + <td><a href="tiles-result.html">Tiles Result</a></td> + <td>Used to provide Tiles integration</td> </tr> <tr> <td><a href="postback-result.html">Postback Result</a></td> <td>Used to postback request parameters as a form to the specified destination</td> </tr> <tr> - <td><em>JSON Result</em></td> + <td><a href="json-result.html">JSON Result</a></td> <td>Used to serialize actions into JSON</td> </tr> </tbody> </table> -<p>#####Optional#####</p> - -<p>|<em>JasperReports Plugin</em> |Used for <em>JasperReports Tutorial</em> integration|Optional, third-party plugin| -|ââââââââ|âââââââââââââââ-|ââââââââââ|</p> +<h2 id="optional">Optional</h2> -<p>Additional Result Types can be created and plugged into an application by implementing the</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>com.opensymphony.xwork2.Result -</code></pre> -</div> -<p>interface. Custom Result Types might include generating an email or JMS message, generating images, and so forth.</p> +<table> + <tbody> + <tr> + <td>[JasperReports Plugin]</td> + <td>Used for <em>JasperReports Tutorial</em> integration</td> + <td>Optional, third-party plugin</td> + </tr> + </tbody> +</table> -<p>####Default Parameters####</p> +<p>Additional Result Types can be created and plugged into an application by implementing the <code class="highlighter-rouge">com.opensymphony.xwork2.Result</code> +interface. Custom Result Types might include generating an email or JMS message, generating images, and so forth.</p> -<p>To minimize configuration, Results can be configured with a single value, which will be converted into a parameter, and each Result can specify which parameter this value should be set as. For example, here is a result defined in XML that uses a default parameter:</p> +<h2 id="default-parameters">Default Parameters</h2> -<div class="highlighter-rouge"><pre class="highlight"><code><result type="freemarker">foo.fm</result> +<p>To minimize configuration, Results can be configured with a single value, which will be converted into a parameter, +and each Result can specify which parameter this value should be set as. For example, here is a result defined in XML +that uses a default parameter:</p> +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><result</span> <span class="na">type=</span><span class="s">"freemarker"</span><span class="nt">></span>foo.fm<span class="nt"></result></span> </code></pre> </div> <p>That is the equivalent to this:</p> -<div class="highlighter-rouge"><pre class="highlight"><code><result type="freemarker"> - <param name="location">foo.vm</param> -</result> - +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><result</span> <span class="na">type=</span><span class="s">"freemarker"</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"location"</span><span class="nt">></span>foo.vm<span class="nt"></param></span> +<span class="nt"></result></span> </code></pre> </div> -<p>Since probably 95% of your actions wonât need results that contain multiple parameters, this little shortcut saves you a significant amount of configuration. It also follows that if you have specified the default parameter, you donât need to set the same parameter as a specifically-named parameter.</p> +<p>Since probably 95% of your actions wonât need results that contain multiple parameters, this little shortcut saves you +a significant amount of configuration. It also follows that if you have specified the default parameter, you donât need +to set the same parameter as a specifically-named parameter.</p> -<p>####Registering Result Types####</p> +<h2 id="registering-result-types">Registering Result Types</h2> <p>All Result Types are plugged in via the <a href="result-configuration.html">Result Configuration</a>.</p> -<p>#####Extending#####</p> +<h2 id="extending">Extending</h2> -<p>You can always extend defined result types and implement whatever logic you need. To simplify process of that, you can define your custom</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>ResultFactory -</code></pre> -</div> -<p>and use it with connection with custom interface which your Result implements. Check <a href="object-factory.html">Define dedicated factory</a> to see how to do it.</p> +<p>You can always extend defined result types and implement whatever logic you need. To simplify process of that, you can +define your custom <code class="highlighter-rouge">ResultFactory</code> and use it with connection with custom interface which your Result implements. +Check <a href="object-factory.html">Define dedicated factory</a> to see how to do it.</p> <p>Struts 2 provides one such extension for you:</p> -<div class="highlighter-rouge"><pre class="highlight"><code>ParamNameAwareResult -</code></pre> -</div> -<p>interface when used with</p> +<p><code class="highlighter-rouge">ParamNameAwareResult</code> interface when used with <code class="highlighter-rouge">StrutsResultBuilder</code> can limit parameters assigned to the result. +So you can simple extend existing result with such a functionality as below:</p> -<div class="highlighter-rouge"><pre class="highlight"><code>StrutsResultBuilder -</code></pre> -</div> -<p>can limit parameters assigned to the result. So you can simple extend existing result with such a functionality as below:</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>public class MyResult extends ServletDispatcherResult implements ParamNameAwareResult { - - public boolean acceptableParamName(String name, String value) { - return "accept".equals(name); - } +<div class="highlighter-rouge"><pre class="highlight"><code><span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyResult</span> <span class="kd">extends</span> <span class="n">ServletDispatcherResult</span> <span class="kd">implements</span> <span class="n">ParamNameAwareResult</span> <span class="o">{</span> -} + <span class="kd">public</span> <span class="kt">boolean</span> <span class="n">acceptableParamName</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">,</span> <span class="n">String</span> <span class="n">value</span><span class="o">)</span> <span class="o">{</span> + <span class="k">return</span> <span class="s">"accept"</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span><span class="n">name</span><span class="o">);</span> + <span class="o">}</span> +<span class="o">}</span> </code></pre> </div> -<p>and then register it and use instead of default</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>dispatcher -</code></pre> -</div> -<p>result.</p> +<p>and then register it and use instead of default <code class="highlighter-rouge">dispatcher</code> result.</p> </section> </article> http://git-wip-us.apache.org/repos/asf/struts-site/blob/f694fc8f/content/core-developers/static-content.html ---------------------------------------------------------------------- diff --git a/content/core-developers/static-content.html b/content/core-developers/static-content.html index 759e76a..4638d99 100644 --- a/content/core-developers/static-content.html +++ b/content/core-developers/static-content.html @@ -127,105 +127,56 @@ <a class="edit-on-gh" href="https://github.com/apache/struts-site/edit/master/source/core-developers/static-content.md"; title="Edit this page on GitHub">Edit on GitHub</a> <h1 id="static-content">Static Content</h1> -<p>Struts can serve static content like css and javascript files. This feature is enabled by default, but can be disabled by setting:</p> - -<div class="highlighter-rouge"><pre class="highlight"><code> -<constant name="struts.serve.static" value="false" /> +<p>Struts can serve static content like css and javascript files. This feature is enabled by default, but can be disabled +by setting:</p> +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><constant</span> <span class="na">name=</span><span class="s">"struts.serve.static"</span> <span class="na">value=</span><span class="s">"false"</span> <span class="nt">/></span> </code></pre> </div> <blockquote> - -</blockquote> - -<blockquote> - -</blockquote> - -<blockquote> - <p>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.</p> + <p>If you disable this feature, but use the <code class="highlighter-rouge">xhtml</code>, or <code class="highlighter-rouge">css_xhtml</code> theme, make sure that the javascript and css files +shipped inside the core jar are extracted to your web application directory.</p> </blockquote> -<blockquote> - -</blockquote> - -<p>#####Custom Static Content Loaders#####</p> - -<p>Static content is served by an implementation of</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>org.apache.struts2.dispatcher.StaticContentLoader -</code></pre> -</div> -<p>. To write your own</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>StaticContentLoader -</code></pre> -</div> -<p>, implement</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>StaticContentLoader -</code></pre> -</div> -<p>and define a bean for the class:</p> - -<div class="highlighter-rouge"><pre class="highlight"><code> -<bean type="org.apache.struts2.dispatcher.StaticContentLoader" class="MyStaticContentLoader" name="myLoader" /> -<constant name="struts.staticContentLoader" value="myLoader" /> - -</code></pre> -</div> +<h2 id="custom-static-content-loaders">Custom Static Content Loaders</h2> -<p>#####Default Content Loader#####</p> +<p>Static content is served by an implementation of <code class="highlighter-rouge">org.apache.struts2.dispatcher.StaticContentLoader</code>. To write your own +<code class="highlighter-rouge">StaticContentLoader</code>, implement <code class="highlighter-rouge">StaticContentLoader</code> and define a bean for the class:</p> -<p>Struts provides a default implementation of</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>StaticContentLoader +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><bean</span> <span class="na">type=</span><span class="s">"org.apache.struts2.dispatcher.StaticContentLoader"</span> <span class="na">class=</span><span class="s">"MyStaticContentLoader"</span> <span class="na">name=</span><span class="s">"myLoader"</span> <span class="nt">/></span> +<span class="nt"><constant</span> <span class="na">name=</span><span class="s">"struts.staticContentLoader"</span> <span class="na">value=</span><span class="s">"myLoader"</span> <span class="nt">/></span> </code></pre> </div> -<p>which is</p> -<div class="highlighter-rouge"><pre class="highlight"><code>org.apache.struts2.dispatcher.DefaultStaticContentLoader -</code></pre> -</div> -<p>. This loader will handle urls that start with â/static/â.</p> +<h2 id="default-content-loader">Default Content Loader</h2> -<p>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.</p> +<p>Struts provides a default implementation of <code class="highlighter-rouge">StaticContentLoader</code> which is <code class="highlighter-rouge">org.apache.struts2.dispatcher.DefaultStaticContentLoader</code>. +This loader will handle urls that start with â/static/â.</p> -<table> - <tbody> - <tr> - <td>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.</td> - </tr> - </tbody> -</table> +<p>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.</p> -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> - -<p>#####Preventing Struts from Handling a Request#####</p> +<blockquote> + <p>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.</p> +</blockquote> -<p>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:</p> +<h2 id="preventing-struts-from-handling-a-request">Preventing Struts from Handling a Request</h2> -<div class="highlighter-rouge"><pre class="highlight"><code> -<constant name="struts.action.excludePattern" value="/some/conent/.*?" /> +<p>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:</p> +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><constant</span> <span class="na">name=</span><span class="s">"struts.action.excludePattern"</span> <span class="na">value=</span><span class="s">"/some/conent/.*?"</span> <span class="nt">/></span> </code></pre> </div> -<p>These regular expression will be evaluated against the requestâs URI (</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>HttpServletRequest.getRequestURI() -</code></pre> -</div> -<p>), and if any of them matches, then Struts will not handle the request.</p> +<p>These regular expression will be evaluated against the requestâs URI (<code class="highlighter-rouge">HttpServletRequest.getRequestURI()</code>), and if any +of them matches, then Struts will not handle the request.</p> -<p>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 <a href="http://docs\.oracle\.com/javase/1\.5\.0/docs/api/java/util/regex/Pattern\.html";>Pattern class JavaDoc</a>^[http://docs.oracle.com/javase/1.5.0/docs/api/java/util/regex/Pattern.html].</p> +<p>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 <a href="http://docs.oracle.com/javase/1.5.0/docs/api/java/util/regex/Pattern.html";>Pattern class JavaDoc</a>.</p> </section> </article>
