com.arsdigita.web
Class URL

java.lang.Object
  extended bycom.arsdigita.web.URL

public class URL
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/web/URL.java#33 $
Author:
Justin Ross <jross@redhat.com>
See Also:
ParameterMap, DispatcherServlet, LoginSignal, ReturnSignal, WebConfig, Application

Field Summary
static String JSP_DIR
          The standard location for JSP files.
static String SERVLET_DIR
          The standard location for servlets.
static String STATIC_DIR
          The standard location for static files.
static String versionId
           
static String XSL_DIR
          The standard location for XSL files.
 
Constructor Summary
URL(javax.servlet.http.HttpServletRequest sreq)
          Produce a URL representation of the given request.
URL(String scheme, String serverName, int serverPort, String contextPath, String servletPath, String pathInfo, ParameterMap params)
          Assembles a fully qualified URL from its fundamental pieces.
 
Method Summary
static URL excursion(javax.servlet.http.HttpServletRequest sreq, String path)
           
static URL excursion(javax.servlet.http.HttpServletRequest sreq, String path, ParameterMap params)
           
 String getContextPath()
          Returns the context path of the URL.
static String getDispatcherPath()
           
 String getDispatcherPrefix()
          Experimental
 String getParameter(String name)
          Returns the value of one query parameter.
 Map getParameterMap()
          Returns an immutable map of the query parameters.
 String[] getParameterValues(String name)
          Returns the values for a parameter.
 String getPathInfo()
          Returns the servlet-local path data of the URL.
 String getQueryString()
          Returns the query string of the URL.
 String getRequestURI()
          Returns the "file" part of the URL, in contrast to the server part.
 String getScheme()
          Returns the scheme (sometimes called the protocol) of the URL.
 String getServerName()
          Returns the domain name part of the URL.
 int getServerPort()
          Returns the port number of the URL.
 String getServerURI()
          Returns the server half of the URL, as opposed to the "file" half.
 String getServletPath()
          Returns the servlet path of the URL.
 String getURL()
          Returns a String representation of the URL, fully qualified.
static URL here(javax.servlet.http.HttpServletRequest sreq, String pathInfo)
           
static URL here(javax.servlet.http.HttpServletRequest sreq, String pathInfo, ParameterMap params)
           
static URL request(javax.servlet.http.HttpServletRequest sreq, ParameterMap params)
          Creates a URL using the elements of the user's original request but with the given set of parameters instead of the original ones.
static URL root()
          Creates a URL to the site's root path.
static URL there(Application app, String pathInfo, ParameterMap params)
          Create a URL with local parameters to pathInfo under the specified application.
static URL there(javax.servlet.http.HttpServletRequest sreq, Application app, String pathInfo)
          Creates a URL with no local parameters to pathInfo under the specified application.
static URL there(javax.servlet.http.HttpServletRequest sreq, Application app, String pathInfo, ParameterMap params)
          Creates a URL to pathInfo under the specified application and using the given parameters.
static URL there(javax.servlet.http.HttpServletRequest sreq, String path)
          Creates a URL with no local parameters to path under the CCM main dispatcher.
static URL there(javax.servlet.http.HttpServletRequest sreq, String path, ParameterMap params)
          Creates a URL to path under the CCM main dispatcher and with the given parameters.
static URL there(String path, ParameterMap params)
          Creates a URL with local parameters.
 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.
 
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

JSP_DIR

public static final String JSP_DIR
The standard location for JSP files.

See Also:
Constant Field Values

STATIC_DIR

public static final String STATIC_DIR
The standard location for static files.

See Also:
Constant Field Values

XSL_DIR

public static final String XSL_DIR
The standard location for XSL files.

See Also:
Constant Field Values

SERVLET_DIR

public static final String SERVLET_DIR
The standard location for servlets.

See Also:
Constant Field Values
Constructor Detail

URL

public URL(String scheme,
           String serverName,
           int serverPort,
           String contextPath,
           String servletPath,
           String pathInfo,
           ParameterMap params)

Assembles a fully qualified URL from its fundamental pieces. The contract of URL dictates that once params is passed in to this constructor, no parameters should be added or removed. This is to make URL in practice a read-only object.

Parameters:
scheme - "http", for example; see ServletRequest.getScheme()
serverName - a valid domain name, for example "ccm.redhat.com"; see ServletRequest.getServerName()
serverPort - 8080, for instance; see ServletRequest.getServerPort()
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 - a ParameterMap representing a set of query parameters

URL

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

Produce a URL representation of the given request.

Parameters:
sreq - an HttpServletRequest from which to copy
Method Detail

toDebugString

public final String toDebugString()

Produces a short description of a URL suitable for debugging.

Returns:
a debugging representation of this URL

getURL

public final String getURL()
Returns a String representation of the URL, fully qualified. The port is omitted if it is the standard HTTP port, 80.

Returns:
a String URL, with all of its parts

getScheme

public final String getScheme()

Returns the scheme (sometimes called the protocol) of the URL. Examples are "http" and "https".

Returns:
a String representing the URL's scheme
See Also:
ServletRequest.getScheme()

getServerName

public final String getServerName()

Returns the domain name part of the URL. For instance, "ccm.redhat.com".

Returns:
a String representing the URL's server name
See Also:
ServletRequest.getServerName()

getServerPort

public final int getServerPort()

Returns the port number of the URL. 8080, for example.

Returns:
an int for the URL's port number
See Also:
ServletRequest.getServerPort()

getServerURI

public final String getServerURI()

Returns the server half of the URL, as opposed to the "file" half. For example, "http://ccm.redhat.com:8080". Note that there is no trailing slash; any characters following the server port are considered part of the request URI.

This method has no equivalent in the Servlet API, but it is similar in spirit to HttpServletRequest.getRequestURI().

It is defined to return

getScheme() + "://" + getServerName() + ":" + getServerPort()
or, if the server port is 80,
getScheme() + "://" + getServerName()

Returns:
a String comprised of the scheme, server name, and server port plus connecting bits
See Also:
getRequestURI()

getContextPath

public final String getContextPath()

Returns the context path of the URL. 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 web app context
See Also:
HttpServletRequest.getContextPath()

getDispatcherPrefix

public final String getDispatcherPrefix()

Experimental

Returns the dispatcher prefix of this request as set by the InternalPrefixerServlet


getServletPath

public final String getServletPath()

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

Returns:
a String path to a servlet
See Also:
HttpServletRequest.getServletPath()

getPathInfo

public final String getPathInfo()

Returns the servlet-local path data of the URL. 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
See Also:
HttpServletRequest.getPathInfo()

getRequestURI

public final String getRequestURI()

Returns the "file" part of the URL, in contrast to the server part. The value cannot be null and always starts with a "/". For example, "/ccm/forum/thread.jsp".

This method is defined to return the equivalent of getContextPath() + getServletPath() + getPathInfo().

Returns:
a String comprised of the context path, servlet path, and path info
See Also:
HttpServletRequest.getRequestURI()

getQueryString

public final String getQueryString()

Returns the query string of the URL. If the URL was constructed with a null ParameterMap, this method returns null. If the URL was constructed with an empty ParameterMap, this method returns the empty string. Example values are null, "", and "ticket-id=56&user-id=24".

Returns:
a String representing the query parameters of the URL
See Also:
HttpServletRequest.getQueryString()

getParameter

public final String getParameter(String name)

Returns the value of one query parameter. If the URL was constructed with a null ParameterMap, this method returns null. If the parameter requested has multiple values, this method will only return the first; use getParameterValues(String) to get all of the values.

Parameters:
name - the name of the parameter to fetch
Returns:
the String value of the parameter
See Also:
ServletRequest.getParameter(String)

getParameterValues

public final String[] getParameterValues(String name)

Returns the values for a parameter. If the URL was constructed with a null ParameterMap, this method returns null.

Parameters:
name - the name of the parameter to get
Returns:
a String[] of values for the parameter
See Also:
ServletRequest.getParameterValues(String)

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 ParameterMap, this method returns null.

Returns:
a Map of the URL's query parameters
See Also:
ServletRequest.getParameterMap()

root

public static final URL root()

Creates a URL to the site's root path. For example, http://somewhere.net/.

Returns:
a URL to your server's root path

request

public static final URL request(javax.servlet.http.HttpServletRequest sreq,
                                ParameterMap params)

Creates a URL using the elements of the user's original request but with the given set of parameters instead of the original ones.

Parameters:
sreq - the servlet request
params - a ParameterMap of params to replace those of the request
Returns:
a URL representing the original request except for its parameters

there

public static final URL there(javax.servlet.http.HttpServletRequest sreq,
                              String path,
                              ParameterMap params)

Creates a URL to path under the CCM main dispatcher and with the given parameters. A null ParameterMap indicates that the URL has no query string at all. If the parameter map is not null, its parameter listeners are run and may further edit the parameter map.

Parameters:
sreq - the servlet request
path - a String path to which to dispatch
params - a ParameterMap of parameters to use; this value may be null
Returns:
a URL with a path to dispatch to
See Also:
DispatcherServlet

there

public static final URL there(javax.servlet.http.HttpServletRequest sreq,
                              String path)

Creates a URL with no local parameters to path under the CCM main dispatcher. This method implicitly creates an empty parameter map (not a null one); this empty map may be altered by parameter listeners, for instance to include global parameters.

Parameters:
sreq - the servlet request
path - a String path to dispatch to
Returns:
a URL to a path under the dispatcher and with an empty parameter map

there

public static final URL there(javax.servlet.http.HttpServletRequest sreq,
                              Application app,
                              String pathInfo,
                              ParameterMap params)

Creates a URL to pathInfo under the specified application and using the given parameters. The parmeter map argument may be null, indicating that the URL has no query string.

Parameters:
sreq - the servlet request
app - the Application to dispatch to
pathInfo - a String of extra path info for the application
params - a ParameterMap of parameters to use
Returns:
a URL to an application with a particular pathInfo

there

public static final URL there(javax.servlet.http.HttpServletRequest sreq,
                              Application app,
                              String pathInfo)

Creates a URL with no local parameters to pathInfo under the specified application.

Parameters:
sreq - the servlet request
app - the Application to dispatch to
pathInfo - a String of extra path info for the application
Returns:
a URL to an application with a particular pathInfo

there

public static final URL there(String path,
                              ParameterMap params)

Creates a URL with local parameters.

This function should not be used unless you really don't have an HttpServletRequest object as it will ignore any Host header given by the client.


there

public static final URL there(Application app,
                              String pathInfo,
                              ParameterMap params)

Create a URL with local parameters to pathInfo under the specified application.

This function should not be used unless you really don't have an HttpServletRequest object as it will ignore any Host header given by the client.


here

public static final URL here(javax.servlet.http.HttpServletRequest sreq,
                             String pathInfo,
                             ParameterMap params)

here

public static final URL here(javax.servlet.http.HttpServletRequest sreq,
                             String pathInfo)

excursion

public static final URL excursion(javax.servlet.http.HttpServletRequest sreq,
                                  String path,
                                  ParameterMap params)

excursion

public static final URL excursion(javax.servlet.http.HttpServletRequest sreq,
                                  String path)

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

getDispatcherPath

public static final String getDispatcherPath()


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