[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Shane Bryzak
Shane_Bryzak at symantec.com
Sat Feb 10 08:07:29 EST 2007
User: sbryzak2
Date: 07/02/10 08:07:29
Modified: doc/reference/en/modules configuration.xml
Log:
documented filter changes
Revision Changes Path
1.35 +514 -325 jboss-seam/doc/reference/en/modules/configuration.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: configuration.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/configuration.xml,v
retrieving revision 1.34
retrieving revision 1.35
diff -u -b -r1.34 -r1.35
--- configuration.xml 4 Feb 2007 17:42:27 -0000 1.34
+++ configuration.xml 10 Feb 2007 13:07:29 -0000 1.35
@@ -25,7 +25,7 @@
<programlisting><![CDATA[<listener>
<listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
-</listener>]]></programlisting>
+ </listener>]]></programlisting>
<para>
This listener is responsible for bootstrapping Seam, and for destroying
@@ -40,7 +40,7 @@
<programlisting><![CDATA[<lifecycle>
<phase-listener>org.jboss.seam.jsf.SeamPhaseListener</phase-listener>
-</lifecycle>]]></programlisting>
+ </lifecycle>]]></programlisting>
<para>
The actual listener class here varies depending upon how you want to
@@ -54,7 +54,7 @@
<programlisting><![CDATA[<application>
<el-resolver>org.jboss.seam.jsf.SeamELResolver</el-resolver>
-</application>]]></programlisting>
+ </application>]]></programlisting>
<para>
(This line should not strictly speaking be necessary, but it works
@@ -68,10 +68,255 @@
state saving. You'll need this in <literal>web.xml</literal>:
</para>
-<programlisting><![CDATA[<context-param>
+ <programlisting><![CDATA[<context-param>
<param-name>javax.faces.STATE_SAVING_METHOD</param-name>
<param-value>client</param-value>
-</context-param>]]></programlisting>
+ </context-param>]]></programlisting>
+
+ </sect2>
+
+ <sect2>
+ <title>Seam servlet filter</title>
+
+ <para>
+ Seam also comes with a master servlet filter that enables a number of
+ built-in Seam filters. Configuring the master filter requires the following
+ entry in <literal>web.xml</literal>:
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <filter>
+ <filter-name>Seam Filter</filter-name>
+ <filter-class>org.jboss.seam.web.SeamFilter</filter-class>
+ </filter>
+
+ <filter-mapping>
+ <filter-name>Seam Filter</filter-name>
+ <url-pattern>/*</url-pattern>
+ </filter-mapping>
+ ]]>
+ </programlisting>
+
+ <para>
+ Adding the master filter enables each of the following built-in filters.
+ </para>
+
+ <sect3>
+ <title>Seam exception handling filter</title>
+ <para>
+ This filter provides the exception mapping functionality in
+ <literal>pages.xml</literal> (almost all applications will need this).
+ It also takes care of rolling back uncommitted transactions when uncaught
+ exceptions occur. (According to the Java EE specification, the web container
+ should do this automatically, but we've found that this behavior cannot be
+ relied upon in all application servers. And it is certainly not required of
+ plain servlet engines like Tomcat.)
+ </para>
+
+ <para>
+ By default, the exception handling filter will process all requests,
+ however this behavior may be adjusted by adding a
+ <literal><web:exception-filter></literal> entry to
+ <literal>components.xml</literal>, as shown in this example:
+ </para>
+
+ <programlisting>
+ <![CDATA[
+<components xmlns="http://jboss.com/products/seam/components"
+ xmlns:core="http://jboss.com/products/seam/core"
+ xmlns:web="http://jboss.com/products/seam/web"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation=
+ "http://jboss.com/products/seam/core http://jboss.com/products/seam/core-1.1.xsd
+ http://jboss.com/products/seam/components http://jboss.com/products/seam/components-1.1.xsd
+ http://jboss.com/products/seam/web http://jboss.com/products/seam/web-1.1.xsd">
+
+ <web:exception-filter url-pattern="*.seam"/>
+
+</components>
+ ]]>
+ </programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>url-pattern</literal> — Used to specify which requests
+ are filtered, the default is all requests.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>disabled</literal> — Used to disable this filter.
+ Default is <literal>false</literal> (enabled).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3>
+ <title>Conversation propagation with redirects</title>
+ <para>
+ This filter enables post-then-redirect in JSF, and allows Seam to
+ propagate the conversation context across browser redirects. It
+ intercepts any browser redirects and adds a request parameter that
+ specifies the Seam conversation ID.
+ </para>
+
+ <para>
+ The redirect filter will also process all requests by default, but this
+ behavior can also be adjusted in <literal>components.xml</literal>:
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <web:redirect-filter url-pattern="*.seam"/>
+ ]]>
+ </programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>url-pattern</literal> — Used to specify which requests
+ are filtered, the default is all requests.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>disabled</literal> — Used to disable this filter.
+ Default is <literal>false</literal> (enabled).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3>
+ <title>Multipart form requests</title>
+ <para>
+ This feature is necessary when using the Seam file upload JSF control. It
+ detects multipart form requests and processes them according to the
+ multipart/form-data specification (rfc-2388). To override the default
+ settings, add the following entry to <literal>components.xml</literal>:
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <web:multipart-filter create-temp-files="true" max-request-size="1000000" url-pattern="*.seam"/>
+ ]]>
+ </programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>create-temp-files</literal> — If set to
+ <literal>true</literal>, uploaded files are written to a temporary
+ file (instead of held in memory). This may be an important
+ consideration if large file uploads are expected. The default
+ setting is <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>max-request-size</literal> — If the size of a file upload
+ request (determined by reading the <literal>Content-Length</literal>
+ header in the request) exceeds this value, the request will be
+ aborted. The default setting is 0 (no size limit).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>url-pattern</literal> — Used to specify which requests
+ are filtered, the default is all requests.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>disabled</literal> — Used to disable this filter.
+ Default is <literal>false</literal> (enabled).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3>
+ <title>Character encoding</title>
+ <para>
+ Sets the character encoding of submitted data.
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <web:character-encoding-filter encoding="UTF-16" override-client="true" url-pattern="*.seam"/>
+ ]]>
+ </programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>encoding</literal> — The encoding to use.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>override-client</literal> — If this is set to
+ <literal>true</literal>, the request encoding will be set to
+ whatever is specified by <literal>encoding</literal> no matter
+ whether the request already specifies an encoding or not. If
+ set to <literal>false</literal>, the request encoding will only
+ be set if the request doesn't already specify an encoding. The
+ default setting is <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>url-pattern</literal> — Used to specify which requests
+ are filtered, the default is all requests.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>disabled</literal> — Used to disable this filter.
+ Default is <literal>false</literal> (enabled).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3>
+ <title>Context filter</title>
+ <para>
+ This filter allows custom servlets to interact with the Seam context, by
+ setting up the Seam context before the request, and tearing it down after.
+ </para>
+
+ <para>
+ Contrary to the other filters, this filter is disabled by default and
+ requires an entry in <literal>components.xml</literal> to enable it:
+ </para>
+
+ <programlisting>
+ <![CDATA[
+ <web:context-filter url-pattern="/custom/*"/>
+ ]]>
+ </programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>url-pattern</literal> — Used to specify which requests
+ are filtered, the default is all requests. If the url-pattern
+ is specified for the context filter, then the filter will be
+ enabled (unless explicitly disabled).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>disabled</literal> — Used to disable this filter.
+ Default is <literal>true</literal> (disabled).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
</sect2>
@@ -130,62 +375,6 @@
</sect2>
<sect2>
- <title>Enabling Seam exception handling</title>
-
- <para>
- If you want to use Seam's exception mapping functionality
- in <literal>pages.xml</literal> (almost all applications
- will need this), you need to add a servlet filter to
- <literal>web.xml</literal>:
- </para>
-
- <programlisting><![CDATA[<filter>
- <filter-name>Seam Exception Filter</filter-name>
- <filter-class>org.jboss.seam.servlet.SeamExceptionFilter</filter-class>
-</filter>
-
-<filter-mapping>
- <filter-name>Seam Exception Filter</filter-name>
- <url-pattern>*.seam</url-pattern>
-</filter-mapping>]]></programlisting>
-
- <para>
- This servlet filter also takes care of rolling back uncommitted transactions
- when uncaught exceptions occur. (According to the Java EE specification, the
- web container should do this automatically, but we've found that this behavior
- cannot be relied upon in all application servers. And it is certainly not
- required of plain servlet engines like Tomcat.)
- </para>
-
- </sect2>
-
- <sect2>
- <title>Enabling conversation propagation with redirects</title>
-
- <para>
- If you want to use post-then-redirect in JSF, and you want Seam to
- propagate the conversation context across the browser redirects,
- you need to register a servlet filter:
- </para>
-
- <programlisting><![CDATA[<filter>
- <filter-name>Seam Redirect Filter</filter-name>
- <filter-class>org.jboss.seam.servlet.SeamRedirectFilter</filter-class>
-</filter>
-
-<filter-mapping>
- <filter-name>Seam Redirect Filter</filter-name>
- <url-pattern>*.jsf</url-pattern>
-</filter-mapping>]]></programlisting>
-
- <para>
- This filter intercepts any browser redirects and adds a request
- parameter that specifies the Seam conversation id.
- </para>
-
- </sect2>
-
- <sect2>
<title>Using facelets</title>
<para>
More information about the jboss-cvs-commits
mailing list