com.arsdigita.util.servlet
Class HttpResourceLocator

java.lang.Object
  com.arsdigita.util.servlet.HttpResourceLocator

public class HttpResourceLocator

extends Object

URL models a future request according to the servlet worldview. Its principal uses are two:

• To expose all the parts of a URL. To a servlet's way of thinking, these are the scheme, server name, server port, context path, servlet path, path info, and parameters.
• To generate URLs in a consistent and complete way in one place.

Each URL has the following accessors, here set next to an example URL instance, http://example.com:8080/ccmapp/forum/index.jsp?cat=2&cat=5:

Atomic parts:

               getScheme() -> "http"
           getServerName() -> "example.com"
           getServerPort() -> 8080
          getContextPath() -> "/ccmapp"
          getServletPath() -> "/forum"
             getPathInfo() -> "/index.jsp"
       getParameter("cat") -> "2"
 getParameterValues("cat") -> {"2", "5"}
 

Composite parts:

                toString() -> "/ccmapp/forum/index.jsp?cat=2&cat=5"
                  getURL() -> "http://example.com:8080/ccmapp/forum/index.jsp?cat=2&cat=5
            getServerURI() -> "http://example.com:8080"   // No trailing "/"
           getRequestURI() -> "/ccmapp/forum/index.jsp"
          getQueryString() -> "cat=2&cat=5"               // No leading "?"
         getParameterMap() -> {cat={"2", "5"}}
 

The toString() method returns a URL suitable for use in hyperlinks; since in the common case, the scheme, server name, and port are best left off, toString() omits them. The getURL() method returns a String URL which is fully qualified. Both getURL() and getServerURI() omit the port from their return values if the server port is the default, port 80.

Creating URLs will usually be done via one of the static create methods:

URL.root() creates a URL pointing at the server's root path, "/".

URL.request(req, params) creates a URL reflecting the request the client made but using the passed-in parameters instead.

URL.there(req, path, params) and its variants produce URLs that go through the CCM main dispatcher. The variant URL.there(req, app, pathInfo, params) dispatches to pathInfo under the specified application. The variant URL.here(req, pathInfo, params) dispatches to pathInfo under the current application.

URL.excursion(req, path, params) produces URLs that go through the dispatcher to a destination but also encode and store the origin. This is used by LoginSignal and ReturnSignal to implement UI excursions.

All static create methods taking an HttpServletRequest (1) preserve the request's scheme, server name, and port and (2) run parameter listeners if the URL's parameter map is not null.

Those methods not taking an HttpServletRequest use the scheme, server name, and port defined in WebConfig.

All static create methods taking a ParameterMap take null to mean no query string at all. URLs defined this way will have no query string and no "?".

Those methods not taking a ParameterMap argument implicitly create an empty parameter map. Note that this is different from creating a URL with a null parameter map, which produces a URL with no query string.

Version:

$Id: //core-platform/dev/src/com/arsdigita/util/servlet/HttpResourceLocator.java#7 $

Author:

Justin Ross <jross@redhat.com>

Field Summary

static String

versionId

Constructor Summary

HttpResourceLocator(HttpHost host, javax.servlet.http.HttpServletRequest sreq, HttpParameterMap params)
Produces a URL from host, sreq, and params.

HttpResourceLocator(HttpHost host, String contextPath, String servletPath, String pathInfo, HttpParameterMap params)
Assembles a fully qualified URL from its fundamental pieces.

HttpResourceLocator(javax.servlet.http.HttpServletRequest sreq)
Produces a URL representation of sreq.

Method Summary

String	getContextPath() Returns the context path of the resource.
HttpHost	getHost() Returns the virtual host of the resource location.
Map	getParameterMap() Returns an immutable map of the query parameters.
String	getPathInfo() Returns the servlet-local path data of the resource location.
String	getServletPath() Returns the servlet path of the resource.
String	toDebugString() Produces a short description of a URL suitable for debugging.
String	toString() Returns a String representation of the URL suitable for use as a hyperlink.
URL	toURL() Returns a URL to the resource, fully qualified.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

versionId

public static final String versionId

See Also:

Constant Field Values

Constructor Detail

HttpResourceLocator

public HttpResourceLocator(HttpHost host,
                           String contextPath,
                           String servletPath,
                           String pathInfo,
                           HttpParameterMap params)

Assembles a fully qualified URL from its fundamental pieces. The contract of URL dictates that once host and params are passed in to this constructor, they should not be changed. This is to make HttpResourceLocator in practice a read-only object.

Parameters:

host - A HttpHost object representing the requested host

contextPath - The path to your web app; empty string indicates the default context; any other values for contextPath must start with "/" but not end in "/"; contextPath cannot be null; see HttpServletRequest.getContextPath()

servletPath - The path to your servlet; empty string and values starting with "/" are valid, but null is not; see HttpServletRequest.getServletPath()

pathInfo - The path data remaining after the servlet path but before the query string; pathInfo may be null; see HttpServletRequest.getPathInfo()

params - An HttpParameterMap representing a set of query parameters

HttpResourceLocator

public HttpResourceLocator(HttpHost host,
                           javax.servlet.http.HttpServletRequest sreq,
                           HttpParameterMap params)

Produces a URL from host, sreq, and params. The servlet request is mined for its context path, servlet path, and path info.

Parameters:

host - The HttpHost being addressed; it cannot be null

sreq - An HttpServletRequest from which to copy; it cannot be null

params - A HttpParameterMap of query parameters; it can be null

HttpResourceLocator

public HttpResourceLocator(javax.servlet.http.HttpServletRequest sreq)

Produces a URL representation of sreq.

Parameters:

sreq - An HttpServletRequest from which to copy; it cannot be null

Method Detail

toDebugString

public final String toDebugString()

Produces a short description of a URL suitable for debugging.

Returns:

a debugging representation of this URL

toURL

public final URL toURL()

Returns a URL to the resource, fully qualified.

Returns:

A URL for accessing this resource

getHost

public final HttpHost getHost()

Returns the virtual host of the resource location.

Returns:

a HttpHost representing the resource's host name and port number

See Also:

ServletRequest.getServerName(), ServletRequest.getServerPort()

getContextPath

public final String getContextPath()

Returns the context path of the resource. The value cannot be null, and values starting with "/" do not end in "/"; empty string is a valid return value that stands for the default web app. Example values are "" and "/ccm-app".

Returns:

A String path to a webapp context; it cannot be null

See Also:

HttpServletRequest.getContextPath()

getServletPath

public final String getServletPath()

Returns the servlet path of the resource. The value cannot be null.

Returns:

a String path to a servlet; it cannot be null

See Also:

HttpServletRequest.getServletPath()

getPathInfo

public final String getPathInfo()

Returns the servlet-local path data of the resource location. The value may be null. If it is not null, the value begins with a "/". Examples are null, "/", and "/remove.jsp".

Returns:

A String of path data addressed to a servlet; it can be null

See Also:

HttpServletRequest.getPathInfo()

getParameterMap

public final Map getParameterMap()

Returns an immutable map of the query parameters. The map's keys are Strings and the map's values are String[]s. If the URL was constructed with a null HttpParameterMap, this method returns null.

Returns:

a Map of the URL's query parameters

See Also:

ServletRequest.getParameterMap()

toString

public final String toString()

Returns a String representation of the URL suitable for use as a hyperlink. The scheme, server name, and port are omitted.

Returns:

a String URL