OCPSoft.com - Simple SolutionsCommunity Documentation
PrettyFaces inbound URL rewriting provides seamless URL rewriting to all Servlets within the Context. This is the capability of intercepting and changing the location of the client's browser URL, modifying or replacing that URL entirely, and displaying a resource.
There are several commonly used rewriting features that PrettyFaces provides for you:
manipulating trailing slashes, upper and lower-casing, custom regex search and replace,
and redirect types such as '301 - Permanent' and '302 - Temporary'.
<rewrite trailingSlash="append" toCase="lowercase" redirect="301"/> <rewrite match="/foo" substitute="/bar" redirect="301"/>
The two rules above will cause ALL inbound and outbound URLs be appended with a trailing slash
(if necessary,) but because of the "match" attribute, only URLs containing '/foo'
will be replaced with '/bar/. Inbound URL-rewriting changes the browser URL
unless the redirect attribute is set to “chain”:
<rewrite toCase="lowercase" redirect="chain" />
Each <rewrite /> rule may specify a match="..."
attribute. This attribute defines which URLs will and will not be transformed by a given
rewrite rule.
<rewrite match="/foo" trailingSlash="append" toCase="lowercase" />
Once a URL has been matched, regex groups may be used to perform value-substitution on the URL; this effectively takes parts of the original URL, and makes them availible in its replacement.
<rewrite match="/foo/(\w+)/" substitute="/bar/$1/" />
This is equivalent to calling the String method url.replaceAll("/foo/(\w+)/", "/bar/$1/");
Note, also, that the same type of substitution is available when issuing an external redirect
from a rewrite-rule:
<rewrite match="/foo/(\w+)/" url="http://example.com/$1/" />
Click here for more detailed information on regular expressions in Java.
The table below outlines each of the individual rewrite-rule options:
| Option | Allowed values | Usage |
|---|---|---|
| inbound | true/false | (Default: true) Enable or disable inbound URL rewriting for this rule. Setting this value to false means that this rule will be ignored on incoming requests. |
| match | a regex | (Optional) Describes, via a regular expression pattern, when this 'rewrite' rule should trigger on an inbound or outbound URL. If empty, this rule will match all URLs. |
| outbound | true/false | (Default: true) Enable or disable outbound URL rewriting for this rule. If enabled, any matching links encoded using HttpServletResponse.encodeURL() will be rewritten according to the rules specified. |
| processor | qualified class name |
(Optional.) Specify a custom processor class to perform more complex, custom URL-rewriting.
This class must implement the interface: 'com.ocpsoft.pretty.faces.rewrite.Processor'
public interface Processor {
String processInbound(HttpServletRequest request, HttpServletResponse response, RewriteRule rule, String url);
String processOutbound(HttpServletRequest request, HttpServletResponse response, RewriteRule rule, String url);
}
|
| redirect | 301, 302, chain | (Default: 301) Specifies which type of redirect should be issued when this rule triggers. If 'chain' is specified, a Servlet forward will be issued to the new URL instead of a redirect. |
| substitute | lifecycle | (Optional.) The regular expression substitution value of the "match" attribute. This effectively enables a "search and replace" functionality. Regular expression back-references to the match="..." attribute are supported in the URL, so using '$' and '/' characters may change the value of the result. See Rewriting URLs that match a specific pattern, for more details. |
| toCase | uppercase, lowercase, ignore | (Default: ignore) Change the entire URL (excluding context-path and query- parameters) to 'UPPERCASE' or 'lowercase'. |
| trailingSlash | append, remove, ignore | (Default: ignore) Control whether trailing slashes on a URL should be appended if missing, or removed if present. |
| url | a well-formed URL | (Optional.) Specify an well-formed URL to replace the current URL. This will overwrite the context-path and query-parameters. This attribute should usually be combined with redirect="301" (default), which is recommended to prevent adverse SEO effects, loss of page- rank.) Note: You must provide a fully qualified URL, including scheme (such as 'http://", 'ftp://', 'mailto:'). Regular expression back-references to the match="..." attribute are supported in the URL, so using '$' and '/' characters may change the value of the result. See Rewriting URLs that match a specific pattern, for more details. |
Rewrite rules must be defined in pretty-config.xml.