com.arsdigita.util.servlet
Class HttpResourceLocator

java.lang.Object
  extended bycom.arsdigita.util.servlet.HttpResourceLocator

public class HttpResourceLocator
extends Object

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

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


Copyright (c) 2004 Red Hat, Inc. Corporation. All Rights Reserved. Generated at July 20 2004:2337 UTC