public class URI extends Object implements Serializable
A class to represent a Uniform Resource Identifier (URI). This class is designed to handle the parsing of URIs and provide access to the various components (scheme, host, port, userinfo, path, query string and fragment) that may constitute a URI.
Parsing of a URI specification is done according to the URI syntax described in RFC 2396, and amended by RFC 2732.
Every absolute URI consists of a scheme, followed by a colon (':'), followed by a scheme-specific part. For URIs that follow the "generic URI" syntax, the scheme-specific part begins with two slashes ("//") and may be followed by an authority segment (comprised of user information, host, and port), path segment, query segment and fragment. Note that RFC 2396 no longer specifies the use of the parameters segment and excludes the "user:password" syntax as part of the authority segment. If "user:password" appears in a URI, the entire user/password string is stored as userinfo.
For URIs that do not follow the "generic URI" syntax (e.g. mailto), the entire scheme-specific part is treated as the "path" portion of the URI.
Note that, unlike the java.net.URL class, this class does not provide any built-in network access functionality nor does it provide any scheme-specific functionality (for example, it does not know a default port for a specific scheme). Rather, it only knows the grammar and basic set of operations that can be applied to a URI.
Modifier and Type | Class and Description |
---|---|
static class |
URI.MalformedURIException
MalformedURIExceptions are thrown in the process of building a URI
or setting fields on a URI when an operation would result in an
invalid URI specification.
|
Constructor and Description |
---|
URI()
Construct a new and uninitialized URI.
|
URI(String p_uriSpec)
Construct a new URI from a URI specification string.
|
URI(String p_uriSpec,
boolean allowNonAbsoluteURI)
Construct a new URI from a URI specification string.
|
URI(String p_scheme,
String p_schemeSpecificPart)
Construct a new URI that does not follow the generic URI syntax.
|
URI(String p_scheme,
String p_userinfo,
String p_host,
int p_port,
String p_path,
String p_queryString,
String p_fragment)
Construct a new URI that follows the generic URI syntax from its
component parts.
|
URI(String p_scheme,
String p_host,
String p_path,
String p_queryString,
String p_fragment)
Construct a new URI that follows the generic URI syntax from its
component parts.
|
URI(URI p_other)
Construct a new URI from another URI.
|
URI(URI p_base,
String p_uriSpec)
Construct a new URI from a base URI and a URI specification string.
|
URI(URI p_base,
String p_uriSpec,
boolean allowNonAbsoluteURI)
Construct a new URI from a base URI and a URI specification string.
|
Modifier and Type | Method and Description |
---|---|
void |
absolutize(URI p_base)
Absolutize URI with given base URI.
|
void |
appendPath(String p_addToPath)
Append to the end of the path of this URI.
|
boolean |
equals(Object p_test)
Determines if the passed-in Object is equivalent to this URI.
|
String |
getFragment()
Get the fragment for this URI.
|
String |
getHost()
Get the host for this URI.
|
String |
getPath()
Get the path for this URI.
|
String |
getPath(boolean p_includeQueryString,
boolean p_includeFragment)
Get the path for this URI (optionally with the query string and
fragment).
|
int |
getPort()
Get the port for this URI.
|
String |
getQueryString()
Get the query string for this URI.
|
String |
getRegBasedAuthority()
Get the registry based authority for this URI.
|
String |
getScheme()
Get the scheme for this URI.
|
String |
getSchemeSpecificPart()
Get the scheme-specific part for this URI (everything following the
scheme and the first colon).
|
String |
getUserinfo()
Get the userinfo for this URI.
|
int |
hashCode()
Returns a hash-code value for this URI.
|
boolean |
isAbsoluteURI()
Returns whether this URI represents an absolute URI.
|
static boolean |
isConformantSchemeName(String p_scheme)
Determine whether a scheme conforms to the rules for a scheme name.
|
boolean |
isGenericURI()
Get the indicator as to whether this URI uses the "generic URI"
syntax.
|
static boolean |
isWellFormedAddress(String address)
Determine whether a string is syntactically capable of representing
a valid IPv4 address, IPv6 reference or the domain name of a network host.
|
static boolean |
isWellFormedIPv4Address(String address)
Determines whether a string is an IPv4 address as defined by
RFC 2373, and under the further constraint that it must be a 32-bit
address.
|
static boolean |
isWellFormedIPv6Reference(String address)
Determines whether a string is an IPv6 reference as defined
by RFC 2732, where IPv6address is defined in RFC 2373.
|
void |
setFragment(String p_fragment)
Set the fragment for this URI.
|
void |
setHost(String p_host)
Set the host for this URI.
|
void |
setPath(String p_path)
Set the path for this URI.
|
void |
setPort(int p_port)
Set the port for this URI. -1 is used to indicate that the port is
not specified, otherwise valid port numbers are between 0 and 65535.
|
void |
setQueryString(String p_queryString)
Set the query string for this URI.
|
void |
setRegBasedAuthority(String authority)
Sets the registry based authority for this URI.
|
void |
setScheme(String p_scheme)
Set the scheme for this URI.
|
void |
setUserinfo(String p_userinfo)
Set the userinfo for this URI.
|
String |
toString()
Get the URI as a string specification.
|
public URI()
public URI(URI p_other)
p_other
- the URI to copy (cannot be null)public URI(String p_uriSpec) throws URI.MalformedURIException
p_uriSpec
- the URI specification string (cannot be null or
empty)URI.MalformedURIException
- if p_uriSpec violates any syntax
rulespublic URI(String p_uriSpec, boolean allowNonAbsoluteURI) throws URI.MalformedURIException
p_uriSpec
- the URI specification string (cannot be null or
empty)allowNonAbsoluteURI
- true to permit non-absolute URIs,
false otherwise.URI.MalformedURIException
- if p_uriSpec violates any syntax
rulespublic URI(URI p_base, String p_uriSpec) throws URI.MalformedURIException
p_base
- the base URI (cannot be null if p_uriSpec is null or
empty)p_uriSpec
- the URI specification string (cannot be null or
empty if p_base is null)URI.MalformedURIException
- if p_uriSpec violates any syntax
rulespublic URI(URI p_base, String p_uriSpec, boolean allowNonAbsoluteURI) throws URI.MalformedURIException
p_base
- the base URI (cannot be null if p_uriSpec is null or
empty)p_uriSpec
- the URI specification string (cannot be null or
empty if p_base is null)allowNonAbsoluteURI
- true to permit non-absolute URIs,
false otherwise.URI.MalformedURIException
- if p_uriSpec violates any syntax
rulespublic URI(String p_scheme, String p_schemeSpecificPart) throws URI.MalformedURIException
p_scheme
- the URI scheme (cannot be null or empty)p_schemeSpecificPart
- the scheme-specific part (cannot be
null or empty)URI.MalformedURIException
- if p_scheme violates any
syntax rulespublic URI(String p_scheme, String p_host, String p_path, String p_queryString, String p_fragment) throws URI.MalformedURIException
p_scheme
- the URI scheme (cannot be null or empty)p_host
- the hostname, IPv4 address or IPv6 reference for the URIp_path
- the URI path - if the path contains '?' or '#',
then the query string and/or fragment will be
set from the path; however, if the query and
fragment are specified both in the path and as
separate parameters, an exception is thrownp_queryString
- the URI query string (cannot be specified
if path is null)p_fragment
- the URI fragment (cannot be specified if path
is null)URI.MalformedURIException
- if any of the parameters violates
syntax rules or semantic rulespublic URI(String p_scheme, String p_userinfo, String p_host, int p_port, String p_path, String p_queryString, String p_fragment) throws URI.MalformedURIException
p_scheme
- the URI scheme (cannot be null or empty)p_userinfo
- the URI userinfo (cannot be specified if host
is null)p_host
- the hostname, IPv4 address or IPv6 reference for the URIp_port
- the URI port (may be -1 for "unspecified"; cannot
be specified if host is null)p_path
- the URI path - if the path contains '?' or '#',
then the query string and/or fragment will be
set from the path; however, if the query and
fragment are specified both in the path and as
separate parameters, an exception is thrownp_queryString
- the URI query string (cannot be specified
if path is null)p_fragment
- the URI fragment (cannot be specified if path
is null)URI.MalformedURIException
- if any of the parameters violates
syntax rules or semantic rulespublic void absolutize(URI p_base)
p_base
- base URI for absolutizationpublic String getScheme()
public String getSchemeSpecificPart()
public String getUserinfo()
public String getHost()
public int getPort()
public String getRegBasedAuthority()
public String getPath(boolean p_includeQueryString, boolean p_includeFragment)
p_includeQueryString
- if true (and query string is not null),
then a "?" followed by the query string
will be appendedp_includeFragment
- if true (and fragment is not null),
then a "#" followed by the fragment
will be appendedpublic String getPath()
public String getQueryString()
public String getFragment()
public void setScheme(String p_scheme) throws URI.MalformedURIException
p_scheme
- the scheme for this URI (cannot be null)URI.MalformedURIException
- if p_scheme is not a conformant
scheme namepublic void setUserinfo(String p_userinfo) throws URI.MalformedURIException
p_userinfo
- the userinfo for this URIURI.MalformedURIException
- if p_userinfo contains invalid
characterspublic void setHost(String p_host) throws URI.MalformedURIException
Set the host for this URI. If null is passed in, the userinfo field is also set to null and the port is set to -1.
Note: This method overwrites registry based authority if it previously existed in this URI.
p_host
- the host for this URIURI.MalformedURIException
- if p_host is not a valid IP
address or DNS hostname.public void setPort(int p_port) throws URI.MalformedURIException
p_port
- the port number for this URIURI.MalformedURIException
- if p_port is not -1 and not a
valid port numberpublic void setRegBasedAuthority(String authority) throws URI.MalformedURIException
Sets the registry based authority for this URI.
Note: This method overwrites server based authority if it previously existed in this URI.
authority
- the registry based authority for this URIURI.MalformedURIException
- it authority is not a
well formed registry based authoritypublic void setPath(String p_path) throws URI.MalformedURIException
p_path
- the path for this URI (may be null)URI.MalformedURIException
- if p_path contains invalid
characterspublic void appendPath(String p_addToPath) throws URI.MalformedURIException
p_addToPath
- the new segment to be added to the current pathURI.MalformedURIException
- if p_addToPath contains syntax
errorspublic void setQueryString(String p_queryString) throws URI.MalformedURIException
p_queryString
- the query string for this URIURI.MalformedURIException
- if p_queryString is not null and this
URI does not conform to the generic
URI syntax or if the path is nullpublic void setFragment(String p_fragment) throws URI.MalformedURIException
p_fragment
- the fragment for this URIURI.MalformedURIException
- if p_fragment is not null and this
URI does not conform to the generic
URI syntax or if the path is nullpublic boolean equals(Object p_test)
public int hashCode()
Object.hashCode
method. public String toString()
public boolean isGenericURI()
public boolean isAbsoluteURI()
public static boolean isConformantSchemeName(String p_scheme)
public static boolean isWellFormedAddress(String address)
public static boolean isWellFormedIPv4Address(String address)
Determines whether a string is an IPv4 address as defined by RFC 2373, and under the further constraint that it must be a 32-bit address. Though not expressed in the grammar, in order to satisfy the 32-bit address constraint, each segment of the address cannot be greater than 255 (8 bits of information).
IPv4address = 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT
public static boolean isWellFormedIPv6Reference(String address)
Determines whether a string is an IPv6 reference as defined by RFC 2732, where IPv6address is defined in RFC 2373. The IPv6 address is parsed according to Section 2.2 of RFC 2373, with the additional constraint that the address be composed of 128 bits of information.
IPv6reference = "[" IPv6address "]"
Note: The BNF expressed in RFC 2373 Appendix B does not accurately describe section 2.2, and was in fact removed from RFC 3513, the successor of RFC 2373.
Copyright © The Apache Software Foundation. All Rights Reserved.