org.apache.beehive.netui.core.urls
Class URLRewriterService

Object
  extended by URLRewriterService

public class URLRewriterService
extends Object

Methods for registering URL rewriters, adding URL rewriters to the chain, and for rewriting URLs using registered rewriters.

Note that when a URLRewriter is registered with this service it is added to a chain (a List) of rewriters. When rewriting occurs, we loop through each rewriter in the list. The only exception to this is when a rewriter that does not allow other rewriters to be used is registered. This then becomes the exclusive rewriter to use and no other rewriters can be registered.

The final step of the full rewriting process should be to run the rewritten URI through the templated URL formatting process. See getTemplatedURL(javax.servlet.ServletContext, javax.servlet.ServletRequest, org.apache.beehive.netui.core.urls.MutableURI, java.lang.String, org.apache.beehive.netui.core.urls.URIContext)

Also note that this API allows a client to register their own templated URI formatter so they can manage their own templates and formatting.


Constructor Summary
URLRewriterService()
           
 
Method Summary
static boolean allowParamsOnFormAction(ServletContext servletContext, ServletRequest request)
          Tell whether rewritten form actions should be allowed to have query parameters.
static void dumpURLRewriters(ServletRequest request, PrintStream output)
          Print out information about the chain of URLRewriters in this request.
static AjaxUrlInfo getAjaxUrl(ServletContext servletContext, ServletRequest request, Object nameable)
          This method will return two bits of information that are used by components that want run through the AJAX facilities.
static String getNamePrefix(ServletContext servletContext, ServletRequest request, String name)
          Get the prefix to use when rewriting a query parameter name.
static String getTemplatedURL(ServletContext servletContext, ServletRequest request, MutableURI uri, String key, URIContext uriContext)
          Format the given URI using a URL template, if defined in the URL template config file, WEB-INF/url-template-config.xml.
static List getURLRewriters(ServletRequest request)
          Get the unmodifiable list of URLRewriter objects in the request that will be used if rewriteURL(javax.servlet.ServletContext, javax.servlet.ServletRequest, javax.servlet.ServletResponse, org.apache.beehive.netui.core.urls.MutableURI, org.apache.beehive.netui.core.urls.URLType, boolean) is called.
static void registerTemplatedURLFormatter(ServletRequest request, TemplatedURLFormatter formatter)
          Register a TemplatedURLFormatter in the request.
static boolean registerURLRewriter(int index, ServletRequest request, URLRewriter rewriter)
          Register a URLRewriter (add to a list) in the request.
static boolean registerURLRewriter(ServletRequest request, URLRewriter rewriter)
          Register a URLRewriter (add to a list) in the request.
static void rewriteURL(ServletContext servletContext, ServletRequest request, ServletResponse response, MutableURI url, URLType type, boolean needsToBeSecure)
          Rewrite the given URL, looping through the list of registered URLRewriters.
static void unregisterAllURLRewriters(ServletRequest request)
          Unregister the URLRewriter (remove from the list) from the request.
static void unregisterTemplatedURLFormatter(ServletRequest request)
          Unregister the TemplatedURLFormatter from the request.
static void unregisterURLRewriter(ServletRequest request, URLRewriter rewriter)
          Unregister the URLRewriter (remove from the list) from the request.
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

URLRewriterService

public URLRewriterService()
Method Detail

getNamePrefix

public static String getNamePrefix(ServletContext servletContext,
                                   ServletRequest request,
                                   String name)
Get the prefix to use when rewriting a query parameter name. Loops through the list of registered URLRewriters to build up a the prefix.

Parameters:
servletContext - the current ServletContext.
request - the current ServletRequest.
name - the name of the query parameter.
Returns:
a prefix to use to rewrite a query parameter name.

getAjaxUrl

public static AjaxUrlInfo getAjaxUrl(ServletContext servletContext,
                                     ServletRequest request,
                                     Object nameable)
This method will return two bits of information that are used by components that want run through the AJAX facilities. The AjaxUrlInfo class is returned and specifies this information. Unlike the other URLRewriter method, this is a true Chain of Responsibility (CoR) implementation. The first URLRewriter to return the AjaxUrlInfo object wins and that is returned from this call. The reason for this is that the implementation of the Ajax Context is also a true CoR implementation. These must match.

Parameters:
servletContext - the current ServletContext.
request - the current ServletRequest.
nameable - this object that is the target of the Ajax request. Typically it is an INameable.

rewriteURL

public static void rewriteURL(ServletContext servletContext,
                              ServletRequest request,
                              ServletResponse response,
                              MutableURI url,
                              URLType type,
                              boolean needsToBeSecure)
Rewrite the given URL, looping through the list of registered URLRewriters.

Once the MutableURI has been rewritten, and if it is an instance of FreezableMutableURI, then this method will set the URI to a frozen state. I.e. immutable. If a user then tries to use a setter method on the rewritten URI, the FreezableMutableURI will throw an IllegalStateException.

Note that after the rewritting the caller should run the rewritten URI through the templated URI formatting process as the last step in rewriting. See getTemplatedURL(javax.servlet.ServletContext, javax.servlet.ServletRequest, org.apache.beehive.netui.core.urls.MutableURI, java.lang.String, org.apache.beehive.netui.core.urls.URIContext)

Parameters:
servletContext - the current ServletContext.
request - the current ServletRequest.
response - the current ServletResponse.
url - the URL to be rewritten.
type - the type of URL to be rewritten. This is one of the following values:
  • action: a standard (non-resource) URL
  • resource: a resource (e.g., image) URL
needsToBeSecure - a flag indicating whether the URL should be secure (SSL required) or not
See Also:
registerURLRewriter(javax.servlet.ServletRequest, org.apache.beehive.netui.core.urls.URLRewriter)

getURLRewriters

public static List getURLRewriters(ServletRequest request)
Get the unmodifiable list of URLRewriter objects in the request that will be used if rewriteURL(javax.servlet.ServletContext, javax.servlet.ServletRequest, javax.servlet.ServletResponse, org.apache.beehive.netui.core.urls.MutableURI, org.apache.beehive.netui.core.urls.URLType, boolean) is called.

Parameters:
request - the current ServletRequest.
Returns:
an unmodifiable list of the URLRewriters that have been registered.

registerURLRewriter

public static boolean registerURLRewriter(ServletRequest request,
                                          URLRewriter rewriter)
Register a URLRewriter (add to a list) in the request. It will be added to the end of a list of URLRewriter objects and will be used if rewriteURL(javax.servlet.ServletContext, javax.servlet.ServletRequest, javax.servlet.ServletResponse, org.apache.beehive.netui.core.urls.MutableURI, org.apache.beehive.netui.core.urls.URLType, boolean) is called.

Parameters:
request - the current ServletRequest.
rewriter - the URLRewriter to register.
Returns:
false if a URLRewriter has been registered that does not allow other rewriters. Otherwise, true if the URLRewriter was added to the chain or already exists in the chain.

registerURLRewriter

public static boolean registerURLRewriter(int index,
                                          ServletRequest request,
                                          URLRewriter rewriter)
Register a URLRewriter (add to a list) in the request. It will be added at the specified position in this list of URLRewriter objects and will be used if rewriteURL(javax.servlet.ServletContext, javax.servlet.ServletRequest, javax.servlet.ServletResponse, org.apache.beehive.netui.core.urls.MutableURI, org.apache.beehive.netui.core.urls.URLType, boolean) is called.

Parameters:
index - the place to insert the URLRewriter
request - the current ServletRequest.
rewriter - the URLRewriter to register.
Returns:
false if a URLRewriter has been registered that does not allow other rewriters. Otherwise, true if the URLRewriter was added to the chain or already exists in the chain.

unregisterURLRewriter

public static void unregisterURLRewriter(ServletRequest request,
                                         URLRewriter rewriter)
Unregister the URLRewriter (remove from the list) from the request.

Parameters:
request - the current ServletRequest.
rewriter - the URLRewriter to unregister
See Also:
registerURLRewriter(javax.servlet.ServletRequest, org.apache.beehive.netui.core.urls.URLRewriter)

unregisterAllURLRewriters

public static void unregisterAllURLRewriters(ServletRequest request)
Unregister the URLRewriter (remove from the list) from the request.

Parameters:
request - the current ServletRequest.

allowParamsOnFormAction

public static boolean allowParamsOnFormAction(ServletContext servletContext,
                                              ServletRequest request)
Tell whether rewritten form actions should be allowed to have query parameters. If this returns false, then a form-tag implementation should render query parameters into hidden fields on the form instead of allowing them to remain in the URL.


dumpURLRewriters

public static void dumpURLRewriters(ServletRequest request,
                                    PrintStream output)
Print out information about the chain of URLRewriters in this request.

Parameters:
request - the current HttpServletRequest.
output - a PrintStream to output chain of URLRewriters in this request. If null, System.err is used.

getTemplatedURL

public static String getTemplatedURL(ServletContext servletContext,
                                     ServletRequest request,
                                     MutableURI uri,
                                     String key,
                                     URIContext uriContext)
Format the given URI using a URL template, if defined in the URL template config file, WEB-INF/url-template-config.xml. The URIContext encapsulates some additional data needed to write out the string form. E.g. It defines if the "&" entity or the '&' character should be used to separate quary parameters.

First try to use ther per-request registered TemplatedURLFormatter. If one is not registered, try to use the per-webapp default TemplatedURLFormatter, defined in beehive-netui-config.xml (with a class name) and set as an attribute of the ServletContext. Otherwise, with no formatter, just return MutableURI.getURIString(URIContext).

Parameters:
servletContext - the current ServletContext.
request - the current ServletRequest.
uri - the MutableURI to be formatted into a String.
key - the URL template type to use for formatting the URI
uriContext - data required to write out the string form.
Returns:
the URL as a String

registerTemplatedURLFormatter

public static void registerTemplatedURLFormatter(ServletRequest request,
                                                 TemplatedURLFormatter formatter)
Register a TemplatedURLFormatter in the request.

The TemplatedURLFormatter should be used as a final step in the rewriting process to format the rewritten URL as defined by a template in the WEB-INF/url-template-config.xml. There can only be one TemplatedURLFormatter, not a chain as with the URLRewriters.

Parameters:
request - the current ServletRequest.
formatter - the TemplatedURLFormatter to register.

unregisterTemplatedURLFormatter

public static void unregisterTemplatedURLFormatter(ServletRequest request)
Unregister the TemplatedURLFormatter from the request.

Parameters:
request - the current ServletRequest.