[jboss-svn-commits] JBL Code SVN: r5301 - in labs/jbossweb/trunk/docbook/usersguide: . en en/modules
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Wed Jul 26 21:32:17 EDT 2006
Author: michael.yuan at jboss.com
Date: 2006-07-26 21:32:14 -0400 (Wed, 26 Jul 2006)
New Revision: 5301
Added:
labs/jbossweb/trunk/docbook/usersguide/en/modules/dotnet.xml
labs/jbossweb/trunk/docbook/usersguide/en/modules/php.xml
labs/jbossweb/trunk/docbook/usersguide/en/modules/rewrite.xml
Modified:
labs/jbossweb/trunk/docbook/usersguide/build.xml
labs/jbossweb/trunk/docbook/usersguide/en/master.xml
labs/jbossweb/trunk/docbook/usersguide/en/modules/about.xml
labs/jbossweb/trunk/docbook/usersguide/en/modules/architecture.xml
labs/jbossweb/trunk/docbook/usersguide/en/modules/connectors.xml
labs/jbossweb/trunk/docbook/usersguide/en/modules/introduction.xml
Log:
add chapters to the user's guide
Modified: labs/jbossweb/trunk/docbook/usersguide/build.xml
===================================================================
--- labs/jbossweb/trunk/docbook/usersguide/build.xml 2006-07-26 21:09:33 UTC (rev 5300)
+++ labs/jbossweb/trunk/docbook/usersguide/build.xml 2006-07-27 01:32:14 UTC (rev 5301)
@@ -1,9 +1,9 @@
<project name="Documentation" default="all.doc" basedir=".">
<!-- Set the following property to generate the doco in the output folder -->
- <!--property name="build.dir" value="${basedir}/../../output/docs/guide"/-->
+ <!--property name="build.dir" value="${basedir}/../../output/docs/usersguide"/-->
- <property name="pdf.name" value="jboss-docbook.pdf" />
+ <property name="pdf.name" value="jbossweb-usersguide.pdf" />
<import file="../../../../docbook-support/support.xml" />
<target name="all.doc" depends="clean">
Modified: labs/jbossweb/trunk/docbook/usersguide/en/master.xml
===================================================================
--- labs/jbossweb/trunk/docbook/usersguide/en/master.xml 2006-07-26 21:09:33 UTC (rev 5300)
+++ labs/jbossweb/trunk/docbook/usersguide/en/master.xml 2006-07-27 01:32:14 UTC (rev 5301)
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
-"../../../../docbook-support/support/docbook-dtd/docbookx.dtd" [
+"../../../../../docbook-support/support/docbook-dtd/docbookx.dtd" [
<!ENTITY about SYSTEM "modules/about.xml">
<!ENTITY introduction SYSTEM "modules/introduction.xml">
<!ENTITY gettingstarted SYSTEM "modules/gettingstarted.xml">
@@ -9,7 +9,6 @@
<!ENTITY rewrite SYSTEM "modules/rewrite.xml">
<!ENTITY php SYSTEM "modules/php.xml">
<!ENTITY dotnet SYSTEM "modules/dotnet.xml">
-<!ENTITY performance SYSTEM "modules/performance.xml">
]>
<book lang="en">
<bookinfo>
@@ -35,7 +34,5 @@
&php;
&dotnet;
-
- &performance;
</book>
Modified: labs/jbossweb/trunk/docbook/usersguide/en/modules/about.xml
===================================================================
--- labs/jbossweb/trunk/docbook/usersguide/en/modules/about.xml 2006-07-26 21:09:33 UTC (rev 5300)
+++ labs/jbossweb/trunk/docbook/usersguide/en/modules/about.xml 2006-07-27 01:32:14 UTC (rev 5301)
@@ -6,6 +6,6 @@
<para>In this guide, we discuss how to install and use the JBoss Web Server. We cover JBoss Web configuration options, performance considerations, as well as how to run non-Java applications on the server.</para>
- <para>This guide is work in progress. Please send your suggestions or comments to the <ulink url="http://www.jboss.com/index.html?module=bb&op=viewforum&f=230">JBoss Web user forum</ulink>.</para>
+ <para>This guide is work in progress. Please send your suggestions or comments to the <ulink url="http://www.jboss.com/index.html?module=bb&op=viewforum&f=230">JBoss Web user forum</ulink>.</para>
</chapter>
Modified: labs/jbossweb/trunk/docbook/usersguide/en/modules/architecture.xml
===================================================================
--- labs/jbossweb/trunk/docbook/usersguide/en/modules/architecture.xml 2006-07-26 21:09:33 UTC (rev 5300)
+++ labs/jbossweb/trunk/docbook/usersguide/en/modules/architecture.xml 2006-07-27 01:32:14 UTC (rev 5301)
@@ -7,7 +7,7 @@
<section>
<title>Core Server Components</title>
- <para>The core functionality of JBoss Web Server is provided by the Apache Tomcat. Apache Tomcat is embedded inside JBoss Application Server using Embedded Engine. This allows the seamless integration with JBoss components by using underlaying Microkernel system.</para>
+ <para>The core functionality of JBoss Web Server is provided by the Apache Tomcat. Apache Tomcat is embedded inside JBoss Application Server using Embedded Engine. This allows the seamless integration with JBoss components by using the underlaying Microkernel system.</para>
<para>Additional modules allows to use the JBoss Web Server as drop-in replacement for standard native web servers, while offering the Reference Implementation for the Java Servlet and JavaServer Pages technologies. The Java Servlet and JavaServer Pages specifications are developed by Sun under the Java Community Process. </para>
Modified: labs/jbossweb/trunk/docbook/usersguide/en/modules/connectors.xml
===================================================================
--- labs/jbossweb/trunk/docbook/usersguide/en/modules/connectors.xml 2006-07-26 21:09:33 UTC (rev 5300)
+++ labs/jbossweb/trunk/docbook/usersguide/en/modules/connectors.xml 2006-07-27 01:32:14 UTC (rev 5301)
@@ -10,10 +10,14 @@
<para>The HTTP connector uses sendfile for hadling large static files (all such files will be sent ansychronously using high performance kernel level calls), and uses a socket poller for keepalive, increasing scalability of the server. Below is an example configuration for the HTTP connector in server.xml.</para>
<programlisting>
-XXXXXX XXXX
+<Connector port="8080"
+ maxThreads="250" strategy="ms" maxHttpHeaderSize="8192"
+ emptySessionPath="true"
+ enableLookups="false" redirectPort="8443" acceptCount="100"
+ connectionTimeout="20000" disableUploadTimeout="true"/>
</programlisting>
- The following attributes are supported in the HTTP connector: </para>
+ <para>The following attributes are supported in the HTTP connector:</para>
<table>
<title>Attributes in the HTTP Connector</title>
<tgroup cols="2" >
<colspec colnum="1" colname="col1" colwidth="1*"/>
<colspec colnum="2" colname="col2" colwidth="1*"/>
@@ -105,7 +109,7 @@
<para>The HTTPS APR connector has the same basic attributes than the HTTP APR connector, but adds OpenSSL specific ones. For instance, here is an example of the HTTPS connector:</para>
<programlisting>
-<<Connector port="443" maxHttpHeaderSize="8192"
maxThreads="50" enableLookups="false"
+<Connector port="443" maxHttpHeaderSize="8192"
maxThreads="50" enableLookups="false"
disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
SSLEngine="on"
SSLCertificateFile="${catalina.base}/conf/localhost.crt"
SSLCertificateKeyFile="${catalina.base}/conf/localhost.key" />
</programlisting>
@@ -156,7 +160,9 @@
<para> The AJP connector uses a socket poller for keepalive, increasing scalability of the server. As AJP is designed around a pool of persistent (or almost persistent) connections, this will reduce significantly the amount of processing threads needed by JBoss Web. Unlike the HTTP connector, the AJP connector cannot use sendfile to optimize static file processing. Below is an example configuration for an AJP connector.</para>
<programlisting>
-XXXXX XXXXXXX
+<Connector port="8009"
+ emptySessionPath="true" enableLookups="false"
+ redirectPort="8443" protocol="AJP/1.3"/>
</programlisting>
<para>The following attributes are supported in the AJP connector. Many of the attributes are very similar to the HTTP connector we have seen above.</para>
@@ -223,9 +229,4 @@
</section>
- <section>
- <title></title>
- <para></para>
- </section>
-
</chapter>
\ No newline at end of file
Added: labs/jbossweb/trunk/docbook/usersguide/en/modules/dotnet.xml
===================================================================
--- labs/jbossweb/trunk/docbook/usersguide/en/modules/dotnet.xml 2006-07-26 21:09:33 UTC (rev 5300)
+++ labs/jbossweb/trunk/docbook/usersguide/en/modules/dotnet.xml 2006-07-27 01:32:14 UTC (rev 5301)
@@ -0,0 +1,7 @@
+<chapter id="dotnet">
+
+ <title>ASP.Net integration</title>
+
+ <para>A key feature of the JBoss Web Server is that it runs ASP.Net applications and allows Java and .Net applications to communicate with each other. We will provide more detailed documentation in this chapter later.</para>
+
+</chapter>
\ No newline at end of file
Modified: labs/jbossweb/trunk/docbook/usersguide/en/modules/introduction.xml
===================================================================
--- labs/jbossweb/trunk/docbook/usersguide/en/modules/introduction.xml 2006-07-26 21:09:33 UTC (rev 5300)
+++ labs/jbossweb/trunk/docbook/usersguide/en/modules/introduction.xml 2006-07-27 01:32:14 UTC (rev 5301)
@@ -15,7 +15,7 @@
</mediaobject>
</figure>
- <para>Aside from performance issues, another shortcoming of Apache Tomcat is that it is a poor integration platform. Tomcat runs only Java applications. If you want to run PHP/CGI scripts side-by-side with your Java applications, you have to front Tomcat with the Apache Web Server or other native web servers. The APR-based hybrid model in JBoss Web supports both in- and out-of-process execution of CGI and PHP scripts. Furthermore, JBoss Web supports ASP.Net applications, and allows Java applications to access running .Net services and objects.</para>
+ <para>Aside from performance issues, another shortcoming of Apache Tomcat is that it is a limited integration platform. Tomcat runs only Java applications. If you want to run PHP/CGI scripts side-by-side with your Java applications, you have to front Tomcat with the Apache Web Server or other native web servers. The APR-based hybrid model in JBoss Web supports both in- and out-of-process execution of CGI and PHP scripts. Furthermore, JBoss Web supports ASP.Net applications, and allows Java applications to access running .Net services and objects.</para>
<note>
<title></title>
Added: labs/jbossweb/trunk/docbook/usersguide/en/modules/php.xml
===================================================================
--- labs/jbossweb/trunk/docbook/usersguide/en/modules/php.xml 2006-07-26 21:09:33 UTC (rev 5300)
+++ labs/jbossweb/trunk/docbook/usersguide/en/modules/php.xml 2006-07-27 01:32:14 UTC (rev 5301)
@@ -0,0 +1,52 @@
+<chapter id="php">
+
+ <title>PHP</title>
+
+ <para>The PHP Module allows JBoss Web Server to run PHP scripts side-by-side with Java applications. It is a servlet that calls a native embedded PHP engine with libraries extentions.</para>
+
+ <section>
+ <title>Installation</title>
+
+ <para>To install the PHP module, you have to download the binary library files for your specific platform from the JBoss Web Server download page. If you do not see a pre-build binary for your platform, you can build it from the source code package by running the buildphp.sh script.</para>
+
+ <para>Extract all the library files from the downloaded tarball (or the build result), and put them in your JBoss Web Server installation directory. The add the following Listener element under the Server element of your conf/server.xml file.</para>
+
+ <programlisting>
+<Listener className="org.apache.catalina.servlets.php.LifecycleListener"/>
+ </programlisting>
+
+ <para>Then, in the conf/web.xml file, add the PHP servlet configuration.</para>
+
+ <programlisting>
+<servlet>
<servlet-name>php</servlet-name>
<servlet-class>org.apache.catalina.servlets.php.Handler</servlet-class>
<init-param>
<param-name>debug</param-name>
<param-value>0</param-value>
</init-param>
<load-on-startup>6</load-on-startup>
</servlet>
<servlet>
<servlet-name>phps</servlet-name>
<servlet-class>org.apache.catalina.servlets.php.Highlight</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>php</servlet-name>
<url-pattern>*.php</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>phps</servlet-name>
<url-pattern>*.phps</url-pattern>
</servlet-mapping>
+ </programlisting>
+
+ <para>Finally, edit the bin/setenv.sh file to add the LD_LIBRARY_PATH variable and modify/add the java.library.path parameter of the JVM:</para>
+
+ <programlisting>
+CATALINA_OPTS="$CATALINA_OPTS -Djava.library.path=$CATALINA_HOME/PHP/lib"
LD_LIBRARY_PATH=$CATALINA_HOME/PHP/lib
export LD_LIBRARY_PATH
+ </programlisting>
+
+ </section>
+
+ <section>
+ <title>Use PHP scripts</title>
+
+ <para>You can now place any PHP scripts in your .war applications side-by-side with your JSP pages. You can access PHP scripts via URLs mapped from your .war application just like you access JSP pages.</para>
+
+ <para>The php-examples.war warfile of the tarball contains some php demo scripts. They are deployed under /php-examples to use them you only need to modify the bin/setenv.sh as described above. You don't have to modify the conf/web.xml nor the conf/server.xml files since the .war application itself configures the PHP servlet and listener. You have to start and restart the servlet container because of the environment modifications. To use the examples, try http://localhost:8080/php-examples/index.php.</para>
+
+ </section>
+
+ <section>
+ <title>PHP extension libraries</title>
+
+ <para>For the moment this feature is only supported on Solaris. Edit the php.ini file and add your library extensions as in the following example:</para>
+
+ <programlisting>
+extension_dir=/home/jfclere/SunOS_i386_tools/PHP/lib/php/extensions/
extension=openssl.so
extension=pdo_pgsql.so
extension=pgsql.so
+ </programlisting>
+
+ </section>
+
+</chapter>
\ No newline at end of file
Added: labs/jbossweb/trunk/docbook/usersguide/en/modules/rewrite.xml
===================================================================
--- labs/jbossweb/trunk/docbook/usersguide/en/modules/rewrite.xml 2006-07-26 21:09:33 UTC (rev 5300)
+++ labs/jbossweb/trunk/docbook/usersguide/en/modules/rewrite.xml 2006-07-27 01:32:14 UTC (rev 5301)
@@ -0,0 +1,164 @@
+<chapter id="rewrite">
+
+ <title>URL Rewriting</title>
+
+ <para>One of the most popular module in the Apache Web Server is the mod_rewrite module, which allows the web master to map any internal URL to arbitrary public URLs. The JBoss Web Server provides a servlet valve that implement the same functionalities as mod_rewrite.</para>
+
+ <para>In order to use the URL rewrite valve, you have to add the following XML element to the JBoss Web's server.xml, or the web application's context.xml configuration file.</para>
+
+ <programlisting>
+<Valve className="org.jboss.web.rewrite.RewriteValve" />
+ </programlisting>
+
+ <para>The valve will then use a rewrite.properties file for the rewrite conditions and rules. The rewrite.properties file location depends on where you put the Valve element in the configuration file:</para>
+
+ <itemizedlist mark="bullet">
+ <listitem><para>If the Valve element is inside an Engine element in server.xml, the rewrite.properties file should be placed in a folder with the same name as the Engine. This folder should be placed either in the classloader, or in the $JBoss/server/default/conf directory (replace default with the configuration you use, if needed).</para></listitem>
+ <listitem><para>If the Valve element is inside a Host element in server.xml, the rewrite.properties file should be placed in a folder named engine_name/host_name, which is placed either in the classloader, or in the conf folder of the current JBoss configuration.</para></listitem>
+ <listitem><para>If the Valve element is inside the context.xml file for a web application, the rewrite.properties file should be placed in the WEB-INF folder of the web application.</para></listitem>
+ </itemizedlist>
+
+ <para>The rewrite.properties file contains a list of directives which closely resemble the directives used by mod_rewrite, in particular the central RewriteRule and RewriteCond directives. For instance, the following rules in the rewrite.properties file make the server serve different files based on the client browser type in the HTTP request's "User-Agent:" header.</para>
+
+ <programlisting>
+RewriteCond %{HTTP_USER_AGENT} ^Mozilla.*
RewriteRule ^/$ /homepage.max.html [L]
RewriteCond %{HTTP_USER_AGENT} ^Lynx.*
RewriteRule ^/$ /homepage.min.html [L]
RewriteRule ^/$ /homepage.std.html [L]
+ </programlisting>
+
+ <para>If you use a browser which identifies itself as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you get the max homepage (which could include frames, or other special features). If you use the Lynx browser (which is terminal-based), then you get the min homepage (which could be a version designed for easy, text-only browsing). If neither of these conditions apply (you use any other browser, or your browser identifies itself as something non-standard), you get the std (standard) homepage.</para>
+
+ <para>In the next two sections, we will discuss the syntax of the RewriteRule and RewriteCond directives.</para>
+
+ <section>
+ <title>RewriteCond</title>
+
+ <para>The RewriteCond directive defines a rule condition. One or more RewriteCond can precede a RewriteRule directive. The following rule is then only used if both the current state of the URI matches its pattern, and if these conditions are met. Its syntax is as follows.</para>
+
+ <programlisting>
+RewriteCond TestString CondPattern
+ </programlisting>
+
+ <para>The TestString typically contains variables in the form of %{NAME_OF_VARIABLE}, where the NAME_OF_VARIABLE refers to a server property or a property related to the current HTTP request. The following </para>
+
+ <table>
+ <title>Server variables for the RewriteCond text string</title>
<tgroup cols="2" >
<colspec colnum="1" colname="col1" colwidth="1*"/>
<colspec colnum="2" colname="col2" colwidth="1*"/>
+
+ <thead>
<row>
<entry>Category</entry>
<entry>Variable Name</entry>
</row>
</thead>
+
<tbody>
<row>
<entry>HTTP headers</entry>
<entry>HTTP_USER_AGENT, HTTP_REFERER, HTTP_COOKIE, HTTP_FORWARDED, HTTP_HOST, HTTP_PROXY_CONNECTION, HTTP_ACCEPT</entry>
+ </row>
+ <row>
<entry>Connection and request</entry>
<entry>REMOTE_ADDR, REMOTE_HOST, REMOTE_PORT, REMOTE_USER, REMOTE_IDENT, REQUEST_METHOD, SCRIPT_FILENAME, REQUEST_PATH, CONTEXT_PATH, SERVLET_PATH, PATH_INFO, QUERY_STRING, AUTH_TYPE</entry>
+ </row>
+ <row>
<entry>Server internals</entry>
<entry>DOCUMENT_ROOT, SERVER_NAME, SERVER_ADDR, SERVER_PORT, SERVER_PROTOCOL, SERVER_SOFTWARE</entry>
+ </row>
+ <row>
<entry>Date and time</entry>
<entry>TIME_YEAR, TIME_MON, TIME_DAY, TIME_HOUR, TIME_MIN, TIME_SEC, TIME_WDAY, TIME</entry>
+ </row>
+ <row>
<entry>Specials</entry>
<entry>THE_REQUEST, REQUEST_URI, REQUEST_FILENAME, HTTPS</entry>
+ </row>
+ <row>
<entry>Dynamic variables</entry>
<entry>ENV:variable, SSL:variable, HTTP:header</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>These variables all correspond to the similarly named HTTP MIME-headers and Servlet API methods. Most are documented elsewhere in the Manual or in the CGI specification. Those that are special to the rewrite valve include those below.</para>
+
+ <itemizedlist mark="bullet">
+ <listitem><para>REQUEST_PATH: Corresponds to the full path that is used for mapping.</para></listitem>
+ <listitem><para>CONTEXT_PATH: Corresponds to the path of the mapped context.</para></listitem>
+ <listitem><para>SERVLET_PATH: Corresponds to the servlet path.</para></listitem>
+ <listitem><para>THE_REQUEST: The full HTTP request line sent by the browser to the server (e.g., "GET /index.html HTTP/1.1"). This does not include any additional headers sent by the browser.</para></listitem>
+ <listitem><para>REQUEST_URI: The resource requested in the HTTP request line. (In the example above, this would be "/index.html".)</para></listitem>
+ <listitem><para>REQUEST_FILENAME: The full local filesystem path to the file or script matching the request.</para></listitem>
+ <listitem><para>HTTPS: Will contain the text "on" if the connection is using SSL/TLS, or "off" otherwise.</para></listitem>
+ <listitem><para>The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same value - the value of the filename field of the internal request_rec structure of the Apache server. The first name is the commonly known CGI variable name while the second is the appropriate counterpart of REQUEST_URI (which contains the value of the uri field of request_rec).</para></listitem>
+ <listitem><para>ENV:variable: the variable can be the name of any Java system property, is also available.</para></listitem>
+ <listitem><para>SSL:variable: the variable is the name of an SSL environment variable. This feature has not been implemented yet.</para></listitem>
+ <listitem><para>HTTP:header: the header can be any HTTP MIME-header name. It can always be used to obtain the value of a header sent in the HTTP request. For instance, the %{HTTP:Proxy-Connection} symbol represents the value of the HTTP header "Proxy-Connection:".</para></listitem>
+ </itemizedlist>
+
+ <para>You can also insert back reference to the Nth matched group (in parentheses) in the current RewriteRule and last matched RewriteCond regular expressions using the $N and %N symbols in the text string.</para>
+
+ <para>In addition, you can put arbitrary dynamic content into the text string via the RewriteMap directive. A RewriteMap directive looks like the following:</para>
+
+ <programlisting>
+RewriteMap name rewriteMapClassName optionalParameters
+ </programlisting>
+
+ <para>The maps are implemented using an interface that users must implement. Its class name is org.jboss.web.rewrite.RewriteMap, and its code is:</para>
+
+ <programlisting>
+package org.jboss.web.rewrite;
public interface RewriteMap {
public String setParameters(String params);
public String lookup(String key);
}
+ </programlisting>
+
+ <para>Then, in the RewriteCond text string, we can use the form ${mapname:key|default}.</para>
+
+ <para>CondPattern is the condition pattern, a regular expression which is applied to the current instance of the TestString. TestString is first evaluated, before being matched against CondPattern. CondPattern is a perl compatible regular expression with the following additions.</para>
+
+ <itemizedlist mark="bullet">
+ <listitem><para>You can prefix the pattern string with a '!' character (exclamation mark) to specify a non-matching pattern.</para></listitem>
+
+ <listitem>
+ <para> There are some special variants of CondPatterns. Instead of real regular expression strings you can also use one of the following:</para>
+ <itemizedlist mark="bullet">
+ <listitem><para>'<CondPattern' (lexicographically precedes) treats the CondPattern as a plain string and compares it lexicographically to TestString. True if TestString lexicographically precedes CondPattern.</para></listitem>
+ <listitem><para>'>CondPattern' (lexicographically follows) treats the CondPattern as a plain string and compares it lexicographically to TestString. True if TestString lexicographically follows CondPattern.</para></listitem>
+ <listitem><para>'=CondPattern' (lexicographically equal) treats the CondPattern as a plain string and compares it lexicographically to TestString. True if TestString is lexicographically equal to CondPattern (the two strings are exactly equal, character for character). If CondPattern is "" (two quotation marks) this compares TestString to the empty string.</para></listitem>
+ <listitem><para>'-d' (is directory) treats the TestString as a pathname and tests whether or not it exists, and is a directory.</para></listitem>
+ <listitem><para>'-f' (is regular file) treats the TestString as a pathname and tests whether or not it exists, and is a regular file.</para></listitem>
+ <listitem><para>'-s' (is regular file, with size) treats the TestString as a pathname and tests whether or not it exists, and is a regular file with size greater than zero.</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>You can also set special flags for CondPattern by appending [flags] as the third argument to the RewriteCond directive, where flags is a comma-separated list of any of the following flags:</para>
+ <itemizedlist mark="bullet">
+ <listitem><para>'nocase|NC' (no case) makes the test case-insensitive - differences between 'A-Z' and 'a-z' are ignored, both in the expanded TestString and the CondPattern. This flag is effective only for comparisons between TestString and CondPattern. It has no effect on filesystem and subrequest checks.</para></listitem>
+ <listitem><para> 'ornext|OR' (or next condition) combines rule conditions with a local OR instead of the implicit AND.</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>An example of the OR flag is as follows. Without this flag you would have to write the condition/rule pair three times.</para>
+
+ <programlisting>
+RewriteCond %{REMOTE_HOST} ^host1.* [OR]
RewriteCond %{REMOTE_HOST} ^host2.* [OR]
RewriteCond %{REMOTE_HOST} ^host3.*
RewriteRule ...some special stuff for any of these hosts...
+ </programlisting>
+
+ </section>
+
+ <section>
+ <title>RewriteRule</title>
+
+ <para>The RewriteRule directive is the real rewriting workhorse. The directive can occur more than once, with each instance defining a single rewrite rule. The order in which these rules are defined is important - this is the order in which they will be applied at run-time. The RewriteRule directive has the following syntax.</para>
+
+ <programlisting>
+RewriteRule Pattern Substitution
</programlisting>
+
+ <para>Pattern is a perl compatible regular expression, which is applied to the current URL, which is the value of the URL when this rule is applied. This may not be the originally requested URL, which may already have matched a previous rule, and have been altered.</para>
+
+ <para>Like the regular expression in RewriteCond, the Pattern string here can also take the '!' prefix to negate a pattern. When using the '!' character to negate a pattern, you cannot include grouped wildcard parts in that pattern. This is because, when the pattern does NOT match (ie, the negation matches), there are no contents for the groups. Thus, if negated patterns are used, you cannot use $N in the substitution string!</para>
+
+ <para>The Substitution of a rewrite rule is the string which is substituted for (or replaces) the original URL which Pattern matched. In addition to plain text, it can include any server variable, back reference to matched parts, and RewriteMap extensions discussed in the previous section.</para>
+
+ <para>As already mentioned, all rewrite rules are applied to the Substitution (in the order in which they are defined in the config file). The URL is completely replaced by the Substitution and the rewriting process continues until all rules have been applied, or it is explicitly terminated by a flag.</para>
<para>There is a special substitution string named '-' which means: NO substitution! This is useful in providing rewriting rules which only match URLs but do not substitute anything for them. It is commonly used in conjunction with the C (chain) flag, in order to apply more than one pattern before substitution occurs.</para>
<para>Additionally you can set special flags for Substitution by appending [flags] as the third argument to the RewriteRule directive. Flags is a comma-separated list of any of the following flags:</para>
+
+ <itemizedlist mark="bullet">
+ <listitem><para>'chain|C' (chained with next rule): This flag chains the current rule with the next rule (which itself can be chained with the following rule, and so on). This has the following effect: if a rule matches, then processing continues as usual - the flag has no effect. If the rule does not match, then all following chained rules are skipped. For instance, it can be used to remove the ".www" part, inside a per-directory rule set, when you let an external redirect happen (where the ".www" part should not occur!).</para></listitem>
+ <listitem><para>'cookie|CO=NAME:VAL:domain[:lifetime[:path]]' (set cookie): This sets a cookie in the client's browser. The cookie's name is specified by NAME and the value is VAL. The domain field is the domain of the cookie, such as '.apache.org', the optional lifetime is the lifetime of the cookie in minutes, and the optional path is the path of the cookie</para></listitem>
+ <listitem><para>'env|E=VAR:VAL' (set environment variable): This forces an environment variable named VAR to be set to the value VAL, where VAL can contain regexp backreferences ($N and %N) which will be expanded. You can use this flag more than once, to set more than one variable. The variables can later be dereferenced in many situations, most commonly from within XSSI (via <!--#echo var="VAR"-->) or CGI ($ENV{'VAR'}). You can also dereference the variable in a later RewriteCond pattern, using %{ENV:VAR}. Use this to strip information from URLs, while maintaining a record of that information.</para></listitem>
+ <listitem><para>'forbidden|F' (force URL to be forbidden): This forces the current URL to be forbidden - it immediately sends back a HTTP response of 403 (FORBIDDEN). Use this flag in conjunction with appropriate RewriteConds to conditionally block some URLs.</para></listitem>
+ <listitem><para>'gone|G' (force URL to be gone): This forces the current URL to be gone - it immediately sends back a HTTP response of 410 (GONE). Use this flag to mark pages which no longer exist as gone.</para></listitem>
+ <listitem><para>'host|H=Host' (apply rewriting to host): Rather that rewrite the URL, the virtual host will be rewritten.</para></listitem>
+ <listitem><para>'last|L' (last rule): Stop the rewriting process here and don't apply any more rewrite rules. This corresponds to the Perl last command or the break command in C. Use this flag to prevent the currently rewritten URL from being rewritten further by following rules. For example, use it to rewrite the root-path URL ('/') to a real one, e.g., '/e/www/'.</para></listitem>
+ <listitem><para>'next|N' (next round): Re-run the rewriting process (starting again with the first rewriting rule). This time, the URL to match is no longer the original URL, but rather the URL returned by the last rewriting rule. This corresponds to the Perl next command or the continue command in C. Use this flag to restart the rewriting process - to immediately go to the top of the loop. Be careful not to create an infinite loop!</para></listitem>
+ <listitem><para>'nocase|NC' (no case): This makes the Pattern case-insensitive, ignoring difference between 'A-Z' and 'a-z' when Pattern is matched against the current URL.</para></listitem>
+ <listitem><para>'noescape|NE' (no URI escaping of output): This flag prevents the rewrite valve from applying the usual URI escaping rules to the result of a rewrite. Ordinarily, special characters (such as '%', '$', ';', and so on) will be escaped into their hexcode equivalents ('%25', '%24', and '%3B', respectively); this flag prevents this from happening. This allows percent symbols to appear in the output, as in RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE] which would turn '/foo/zed' into a safe request for '/bar?arg=P1=zed'.</para></listitem>
+ <listitem><para>'qsappend|QSA' (query string append: This flag forces the rewrite engine to append a query string part of the substitution string to the existing string, instead of replacing it. Use this when you want to add more data to the query string via a rewrite rule.</para></listitem>
+ <listitem><para>'redirect|R [=code]' (force redirect): Prefix Substitution with http://thishost[:thisport]/ (which makes the new URL a URI) to force a external redirection. If no code is given, a HTTP response of 302 (MOVED TEMPORARILY) will be returned. If you want to use other response codes in the range 300-400, simply specify the appropriate number or use one of the following symbolic names: temp (default), permanent, seeother. Use this for rules to canonicalize the URL and return it to the client - to translate ``/~'' into ``/u/'', or to always append a slash to /u/user, etc. Note: When you use this flag, make sure that the substitution field is a valid URL! Otherwise, you will be redirecting to an invalid location. Remember that this flag on its own will only prepend http://thishost[:thisport]/ to the URL, and rewriting will continue. Usually, you will want to stop rewriting at this point, and redirect immediately. To stop rewriting, you should add the 'L' flag!
.</para></listitem>
+ <listitem><para>'skip|S=num' (skip next rule(s)): This flag forces the rewriting engine to skip the next num rules in sequence, if the current rule matches. Use this to make pseudo if-then-else constructs: The last rule of the then-clause becomes skip=N, where N is the number of rules in the else-clause. (This is not the same as the 'chain|C' flag!)</para></listitem>
+ <listitem><para> 'type|T=MIME-type' (force MIME type): Force the MIME-type of the target file to be MIME-type. This can be used to set up the content-type based on some conditions.</para></listitem>
+ </itemizedlist>
+
+ </section>
+
+</chapter>
\ No newline at end of file
More information about the jboss-svn-commits
mailing list