|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.arsdigita.web.URL
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.
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 |
public static final String versionId
public static final String JSP_DIR
public static final String STATIC_DIR
public static final String XSL_DIR
public static final String SERVLET_DIR
Constructor Detail |
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.
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 parameterspublic URL(javax.servlet.http.HttpServletRequest sreq)
Produce a URL representation of the given request.
sreq
- an HttpServletRequest
from which to copyMethod Detail |
public final String toDebugString()
Produces a short description of a URL suitable for debugging.
public final String getURL()
String
representation of the URL, fully
qualified. The port is omitted if it is the standard HTTP
port, 80.
String
URL, with all of its partspublic final String getScheme()
Returns the scheme (sometimes called the protocol) of the
URL. Examples are "http"
and
"https"
.
String
representing the URL's schemeServletRequest.getScheme()
public final String getServerName()
Returns the domain name part of the URL. For instance,
"ccm.redhat.com"
.
String
representing the URL's server
nameServletRequest.getServerName()
public final int getServerPort()
Returns the port number of the URL. 8080
, for
example.
int
for the URL's port numberServletRequest.getServerPort()
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()
String
comprised of the scheme, server
name, and server port plus connecting bitsgetRequestURI()
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"
.
String
path to a web app contextHttpServletRequest.getContextPath()
public final String getDispatcherPrefix()
Experimental
Returns the dispatcher prefix of this request as set by the InternalPrefixerServlet
public final String getServletPath()
Returns the servlet path of the URL. The value cannot be null.
String
path to a servletHttpServletRequest.getServletPath()
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"
.
String
of path data addressed to a
servletHttpServletRequest.getPathInfo()
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()
.
String
comprised of the context path,
servlet path, and path infoHttpServletRequest.getRequestURI()
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"
.
String
representing the query parameters
of the URLHttpServletRequest.getQueryString()
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.
name
- the name of the parameter to fetch
String
value of the parameterServletRequest.getParameter(String)
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.
name
- the name of the parameter to get
String[]
of values for the parameterServletRequest.getParameterValues(String)
public final Map getParameterMap()
Returns an immutable map of the query parameters. The map's
keys are String
s and the map's values are
String[]
s. If the URL was constructed with a null
ParameterMap
, this method returns null.
Map
of the URL's query parametersServletRequest.getParameterMap()
public static final URL root()
Creates a URL to the site's root path. For example,
http://somewhere.net/
.
URL
to your server's root pathpublic 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.
sreq
- the servlet requestparams
- a ParameterMap
of params to replace
those of the request
URL
representing the original request
except for its parameterspublic 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.
sreq
- the servlet requestpath
- a String
path to which to dispatchparams
- a ParameterMap
of parameters to use;
this value may be null
URL
with a path to dispatch toDispatcherServlet
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.
sreq
- the servlet requestpath
- a String
path to dispatch to
URL
to a path under the dispatcher and
with an empty parameter mappublic 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.
sreq
- the servlet requestapp
- the Application
to dispatch topathInfo
- a String
of extra path info for
the applicationparams
- a ParameterMap
of parameters to use
URL
to an application with a particular
pathInfo
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.
sreq
- the servlet requestapp
- the Application
to dispatch topathInfo
- a String
of extra path info for
the application
URL
to an application with a particular
pathInfo
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.
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.
public static final URL here(javax.servlet.http.HttpServletRequest sreq, String pathInfo, ParameterMap params)
public static final URL here(javax.servlet.http.HttpServletRequest sreq, String pathInfo)
public static final URL excursion(javax.servlet.http.HttpServletRequest sreq, String path, ParameterMap params)
public static final URL excursion(javax.servlet.http.HttpServletRequest sreq, String path)
public final String toString()
String
representation of the URL
suitable for use as a hyperlink. The scheme, server name, and
port are omitted.
String
URLpublic static final String getDispatcherPath()
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |