You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@portals.apache.org by wo...@apache.org on 2014/11/18 00:55:20 UTC
svn commit: r1640257 -
/portals/site/applications/src/site/xdoc/webcontent2/reverse-proxy-module.xml
Author: woonsan
Date: Mon Nov 17 23:55:19 2014
New Revision: 1640257
URL: http://svn.apache.org/r1640257
Log:
APA-67: Adding more info about reverse-proxy module
Modified:
portals/site/applications/src/site/xdoc/webcontent2/reverse-proxy-module.xml
Modified: portals/site/applications/src/site/xdoc/webcontent2/reverse-proxy-module.xml
URL: http://svn.apache.org/viewvc/portals/site/applications/src/site/xdoc/webcontent2/reverse-proxy-module.xml?rev=1640257&r1=1640256&r2=1640257&view=diff
==============================================================================
--- portals/site/applications/src/site/xdoc/webcontent2/reverse-proxy-module.xml (original)
+++ portals/site/applications/src/site/xdoc/webcontent2/reverse-proxy-module.xml Mon Nov 17 23:55:19 2014
@@ -25,7 +25,297 @@
<body>
<section name="Reverse Proxy Module">
- <p>TODO</p>
+ <p>
+ The Reverse Proxy Module provides the features of
+ <a href="http://en.wikipedia.org/wiki/Reverse_proxy">Reverse Proxy</a>,
+ and it consists of HTTP Client builder components, Reverse Proxy Command/Chain components,
+ and Reverse Proxy Servlets and Filters.
+ </p>
+ <p>
+ By using Reverse Proxy Module, you can serve more sophisticated content
+ especially with a custom content rewriter,
+ and you can also allow Cross-Domain Scripting for trusted applications.
+ </p>
+
+ <subsection name="SimpleReverseProxyServlet">
+ <p>
+ A simple Reverse Proxy servlet can be configured in the web.xml like the following example:
+ <source><![CDATA[
+ <!-- Reverse Proxy Servlet -->
+ <servlet>
+ <servlet-name>ReverseProxyServlet</servlet-name>
+ <servlet-class>org.apache.portals.applications.webcontent2.proxy.servlet.SimpleReverseProxyServlet</servlet-class>
+ <init-param>
+ <param-name>mappings</param-name>
+ <param-value>
+ /WEB-INF/rproxy-mappings.yaml
+ </param-value>
+ </init-param>
+ </servlet>
+
+ <!-- Map /rproxyservlet/* path to the Reverse Proxy Servlet -->
+ <servlet-mapping>
+ <servlet-name>ReverseProxyServlet</servlet-name>
+ <url-pattern>/rproxyservlet/*</url-pattern>
+ </servlet-mapping>
+ ]]></source>
+ </p>
+ <p>
+ The servlet (<code>org.apache.portals.applications.webcontent2.proxy.servlet.SimpleReverseProxyServlet</code>)
+ can have the following init parameter(s):
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Default Value</th>
+ <th>Example Value</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>mappings</td>
+ <td></td>
+ <td>
+ /WEB-INF/rproxy-mappings.xml
+ </td>
+ <td>
+ YAML Configuration for path mappings and reverse path mappings.
+ <br/>
+ This parameter value can be any of the following:
+ <ul>
+ <li>File path resource prefixed by 'file:'.</li>
+ <li>Classpath resource prefixed by 'classpath:'.</li>
+ <li>Context relative path resource prefixed by '/'.</li>
+ <li>YAML string</li>
+ </ul>
+ <br/>
+ <strong><em>Note: </em></strong>
+ Variables enclosed by '${' and '}' are expanded by Java System properties.
+ For example, you would get an expanded string, '/home/user1/rproxy-mappings.xml'
+ from '${user.home}/rproxy-mappings.xml' if the user's home directory is '/home/user1'.
+ </td>
+ </tr>
+ </table>
+ </p>
+ <p>
+ The Reverse Proxy mapping configuration in the example above can be like the following:
+ <source><![CDATA[
+--- !simple
+local: /portals/applications/
+remote: http://portals.apache.org/applications/
+contentRewriters:
+ text/html: !!org.apache.portals.applications.webcontent2.proxy.rewriter.DefaultReverseProxyTextLineContentRewriter []
+
+--- !simple
+local: /portals/bridges/
+remote: http://portals.apache.org/bridges/
+contentRewriters:
+ text/html: !!org.apache.portals.applications.webcontent2.proxy.rewriter.DefaultReverseProxyTextLineContentRewriter []
+
+--- !regex
+localPattern: ^/apache/(\w+)/(.*)$
+remoteReplace: http://$1.apache.org/$2
+remotePattern: ^http://(\w+)\.apache\.org/(.*)$
+localReplace: /apache/$1/$2
+contentRewriters:
+ text/html: !!org.apache.portals.applications.webcontent2.proxy.rewriter.DefaultReverseProxyTextLineContentRewriter []
+
+--- !simple
+local: /
+remote: http://apache.org/
+contentRewriters:
+ text/html: !!org.apache.portals.applications.webcontent2.proxy.rewriter.DefaultReverseProxyTextLineContentRewriter []
+ ]]></source>
+ </p>
+ </subsection>
+
+ <subsection name="SimpleReverseProxyFilter">
+ <p>
+ You can use a servlet filter instead with the same Reverse Proxy Maping configuration like the following example:
+ <source><![CDATA[
+ <!-- Reverse Proxy Filter -->
+ <filter>
+ <filter-name>ReverseProxyFilter</filter-name>
+ <filter-class>org.apache.portals.applications.webcontent2.proxy.filter.SimpleReverseProxyFilter</filter-class>
+ <init-param>
+ <param-name>filterPath</param-name>
+ <param-value>/rproxyfilter</param-value>
+ </init-param>
+ <init-param>
+ <param-name>mappings</param-name>
+ <param-value>
+ /WEB-INF/rproxy-mappings.yaml
+ </param-value>
+ </init-param>
+ </filter>
+
+ <!-- Map /rproxyfilter/* path to the Reverse Proxy Filter -->
+ <filter-mapping>
+ <filter-name>ReverseProxyFilter</filter-name>
+ <url-pattern>/rproxyfilter/*</url-pattern>
+ <dispatcher>REQUEST</dispatcher>
+ <dispatcher>INCLUDE</dispatcher>
+ <dispatcher>FORWARD</dispatcher>
+ </filter-mapping>
+ ]]></source>
+ </p>
+ <p>
+ The servlet filter (<code>org.apache.portals.applications.webcontent2.proxy.filter.SimpleReverseProxyFilter</code>)
+ can have the following init parameter(s):
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Default Value</th>
+ <th>Example Value</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>mappings</td>
+ <td></td>
+ <td>
+ /WEB-INF/rproxy-mappings.xml
+ </td>
+ <td>
+ YAML Configuration for path mappings and reverse path mappings.
+ <br/>
+ This parameter value can be any of the following:
+ <ul>
+ <li>File path resource prefixed by 'file:'.</li>
+ <li>Classpath resource prefixed by 'classpath:'.</li>
+ <li>Context relative path resource prefixed by '/'.</li>
+ <li>YAML string</li>
+ </ul>
+ <br/>
+ <strong><em>Note: </em></strong>
+ Variables enclosed by '${' and '}' are expanded by Java System properties.
+ For example, you would get an expanded string, '/home/user1/rproxy-mappings.xml'
+ from '${user.home}/rproxy-mappings.xml' if the user's home directory is '/home/user1'.
+ </td>
+ </tr>
+ </table>
+ </p>
+ </subsection>
+
+ </section>
+
+ <section name="Configuring Reverse Proxy Mappings">
+ <p>
+ In a Reverse Proxy Mappings configuration file, you can list all the (reverse) path mapping configurations
+ in <a href="http://yaml.org/spec/1.1/" target="_blank">YAML</a> documents format.
+ </p>
+ <p>
+ At the moment, two built-in mapping configuration types are supported by default:
+ <ul>
+ <li>Simple mapping</li>
+ <li>Regular Expression based mapping</li>
+ </ul>
+ </p>
+ <p>
+ <strong><em>Note: </em></strong>
+ YAML configurations are internally parsed by using <a href="https://code.google.com/p/snakeyaml/" target="_blank">SnakeYAML</a> library.
+ So, the document type hints and constructor hints are handled by SnakeYAML.
+ </p>
+
+ <subsection name="Simple mapping">
+ <p>
+ Simple mapping allows you to map a local path to a remote URL
+ by replacing the configured local path prefix by the configured remote URL prefix.
+ And a remote URL is mapped to a local path by replacing the configured URL prefix
+ by the configured local path prefix.
+ </p>
+ <p>
+ <strong><em>Note: </em></strong>
+ A simple mapping should start with the line, '--- !simple', to denote a new YAML document with a built-in document type hint ('simple').
+ </p>
+ <p>
+ For example, a simple mapping can be configured like the following:
+ <source><![CDATA[
+--- !simple
+local: /portals/applications/
+remote: http://portals.apache.org/applications/
+ ]]></source>
+ </p>
+ <p>
+ In this simple mapping, for example,
+ if the context path is '/webcontent2' and the request context relative path is '/portals/applications/a/b/c.html'
+ (e.g, 'http://localhost:8080/webcontent2/portals/applications/a/b/c.html'),
+ then the resolved remote URL will be 'http://portals.apache.org/applications/a/b/c.html'.
+ </p>
+ <p>
+ You can also set which content writer components should do rewrite the remote content
+ by setting 'contentRewriters' to a YAML map like the following example:
+ <source><![CDATA[
+--- !simple
+local: /portals/applications/
+remote: http://portals.apache.org/applications/
+contentRewriters:
+ text/html: !!org.apache.portals.applications.webcontent2.proxy.rewriter.DefaultReverseProxyTextLineContentRewriter []
+ ]]></source>
+ </p>
+ <p>
+ With the example configuration above, you will create <code>org.apache.portals.applications.webcontent2.proxy.rewriter.DefaultReverseProxyTextLineContentRewriter</code>
+ instance as content rewriter for 'text/html' content type from the remote content.
+ </p>
+ <p>
+ <strong><em>Note: </em></strong>
+ <code>!!org.apache.portals.applications.webcontent2.proxy.rewriter.DefaultReverseProxyTextLineContentRewriter []</code>
+ is interpreted by SnakeYAML in a special way: SnakeYAML instantiates <code>org.apache.portals.applications.webcontent2.proxy.rewriter.DefaultReverseProxyTextLineContentRewriter</code>
+ class instance with the default constructor (as specified by '[]').
+ Please see <a href="https://code.google.com/p/snakeyaml/" target="_blank">SnakeYAML</a> homepage for details.
+ </p>
+ </subsection>
+
+ <subsection name="Regular Expression based mapping">
+ <p>
+ Regular Expression based mapping allows you to map a local path to a remote URL
+ by matching a local path by the configured local path pattern ('localPattern') and replacing it with the configured 'remoteReplace' string.
+ And a remote URL is mapped to a local path by matching a remote URL by the configured remote URL pattern ('remotePattern') and
+ replacing it with the configured 'localReplace' string.
+ </p>
+ <p>
+ <strong><em>Note: </em></strong>
+ A regular expression based mapping should start with the line, '--- !regex', to denote a new YAML document with a built-in document type hint ('regex').
+ </p>
+ <p>
+ For example, a Regular Expression based mapping can be configured like the following:
+ <source><![CDATA[
+--- !regex
+localPattern: ^/apache/(\w+)/(.*)$
+remoteReplace: http://$1.apache.org/$2
+remotePattern: ^http://(\w+)\.apache\.org/(.*)$
+localReplace: /apache/$1/$2
+ ]]></source>
+ </p>
+ <p>
+ In this Regular Expression based mapping, for example,
+ if the context path is '/webcontent2' and the request context relative path is '/apache/portals/a/b/c.html'
+ (e.g, 'http://localhost:8080/webcontent2/apache/portals/a/b/c.html'),
+ then the resolved remote URL will be 'http://portals.apache.org/a/b/c.html'.
+ </p>
+ <p>
+ You can also set which content writer components should do rewrite the remote content
+ by setting 'contentRewriters' to a YAML map as well like the following example:
+ <source><![CDATA[
+--- !regex
+localPattern: ^/apache/(\w+)/(.*)$
+remoteReplace: http://$1.apache.org/$2
+remotePattern: ^http://(\w+)\.apache\.org/(.*)$
+localReplace: /apache/$1/$2
+contentRewriters:
+ text/html: !!org.apache.portals.applications.webcontent2.proxy.rewriter.DefaultReverseProxyTextLineContentRewriter []
+ ]]></source>
+ </p>
+ <p>
+ With the example configuration above, you will create <code>org.apache.portals.applications.webcontent2.proxy.rewriter.DefaultReverseProxyTextLineContentRewriter</code>
+ instance as content rewriter for 'text/html' content type from the remote content.
+ </p>
+ <p>
+ <strong><em>Note: </em></strong>
+ <code>!!org.apache.portals.applications.webcontent2.proxy.rewriter.DefaultReverseProxyTextLineContentRewriter []</code>
+ is interpreted by SnakeYAML in a special way: SnakeYAML instantiates <code>org.apache.portals.applications.webcontent2.proxy.rewriter.DefaultReverseProxyTextLineContentRewriter</code>
+ class instance with the default constructor (as specified by '[]').
+ Please see <a href="https://code.google.com/p/snakeyaml/" target="_blank">SnakeYAML</a> homepage for details.
+ </p>
+ </subsection>
+
</section>
</body>