@NotThreadSafe public final class UriBuilder extends Object
This class complements the immutable URI
class by enabling its
clients to compose a URI from its components which can get read or written
as independent properties.
Each URI is composed of the five components scheme
,
authority
, path
,
query
and fragment
.
When done with setting the properties for the URI components, the resulting
URI can be composed by calling any of the methods getUri()
,
toUri()
, getString()
or toString()
.
This class quotes illegal characters wherever required for the respective URI component. As a deviation from RFC 2396, non-US-ASCII characters get preserved when encoding.
Note that using this class is superior to the five argument URI constructor
new
because the URI constructor does not quote all paths correctly.
For example, URI(scheme, authority, path, query, fragment)
new URI(null, null, "foo:bar", null, null)
does not
quote the colon before parsing so the resulting URI will have a scheme
component foo
and a path component bar
instead of just a
path component foo:bar
.
URI
u
it is generally true that
new UriBuilder(u).toUri().equals(u);
and
new UriBuilder().uri(u).toUri().equals(u);
and
new UriBuilder()
.scheme(u.getScheme())
.authority(u.getAuthority())
.path(u.isOpaque() ? u.getSchemeSpecificPart() : u.getPath())
.query(u.getQuery())
.fragment(u.getFragment())
.toUri()
.equals(u);
These identity productions apply for the method toUri()
as well as
the method getUri()
.UriEncoder
Constructor and Description |
---|
UriBuilder()
Constructs a new URI builder.
|
UriBuilder(boolean raw)
Constructs a new URI builder.
|
UriBuilder(URI uri)
Constructs a new URI builder.
|
UriBuilder(URI uri,
boolean raw)
Constructs a new URI builder.
|
Modifier and Type | Method and Description |
---|---|
UriBuilder |
authority(String authority)
Sets the URI authority component.
|
UriBuilder |
clear()
Clears the state of this URI builder.
|
UriBuilder |
fragment(String fragment)
Sets the URI fragment component.
|
String |
getAuthority()
Returns the URI authority component.
|
String |
getFragment()
Returns the URI fragment component.
|
String |
getPath()
Returns the URI path component.
|
String |
getQuery()
Returns the URI query component.
|
String |
getScheme()
Returns the URI scheme component.
|
String |
getString()
|
URI |
getUri()
|
UriBuilder |
path(String path)
Sets the URI path component.
|
UriBuilder |
pathQuery(String pathQuery)
Sets the URI path an query components by splitting the given string at
the first occurence of the query separator
'?' . |
UriBuilder |
query(String query)
Sets the URI query component.
|
UriBuilder |
scheme(String scheme)
Sets the URI scheme component.
|
void |
setAuthority(String authority)
Sets the URI authority component.
|
void |
setFragment(String fragment)
Sets the URI fragment component.
|
void |
setPath(String path)
Sets the URI path component.
|
void |
setPathQuery(String pathQuery)
Sets the URI path an query components by splitting the given string at
the first occurence of the query separator
'?' . |
void |
setQuery(String query)
Sets the URI query component.
|
void |
setScheme(String scheme)
Sets the URI scheme component.
|
void |
setString(String uri)
Initializes all URI components from the given URI string.
|
void |
setUri(URI uri)
Initializes all URI components from the given URI.
|
UriBuilder |
string(String uri)
Initializes all URI components from the given URI string.
|
String |
toString()
|
URI |
toUri()
|
UriBuilder |
uri(URI uri)
Initializes all URI components from the given URI.
|
static void |
validateScheme(String scheme)
Checks the given string to conform to the syntax constraints for URI
schemes in
RFC 2396
|
public UriBuilder()
UriBuilder(false)
.public UriBuilder(boolean raw)
raw
- If true
, then the '%'
character doesn't get
quoted.public UriBuilder(URI uri)
UriBuilder(uri, false)
.uri
- the uri for initializing the initial state.public UriBuilder(URI uri, boolean raw)
uri
- the uri for initializing the initial state.raw
- If true
, then the '%'
character doesn't get
quoted.public UriBuilder authority(@CheckForNull String authority)
authority
- the URI authority component.this
public UriBuilder clear()
null
.this
public UriBuilder fragment(@CheckForNull String fragment)
fragment
- the URI fragment component.this
@CheckForNull public String getAuthority()
initialized
from an
opaque
URI, then this property is null
.@CheckForNull public String getFragment()
@CheckForNull public String getPath()
initialized
from an
opaque
URI, then this property contains the
scheme specific part of the URI.@CheckForNull public String getQuery()
initialized
from an
opaque
URI, then this property is null
.@CheckForNull public String getScheme()
public String getString() throws URISyntaxException
URISyntaxException
- if composing a valid URI is not possible due
to an invalid scheme.toString()
public URI getUri() throws URISyntaxException
URISyntaxException
- if composing a valid URI is not possible.toUri()
public UriBuilder path(@CheckForNull String path)
path
- the URI path component.this
public UriBuilder pathQuery(@CheckForNull String pathQuery)
'?'
.pathQuery
- the combined URI path and query components.this
public UriBuilder query(@CheckForNull String query)
query
- the URI query component.this
public UriBuilder scheme(@CheckForNull String scheme)
scheme
- the URI scheme component.this
public void setAuthority(@CheckForNull String authority)
authority
- the URI authority component.public void setFragment(@CheckForNull String fragment)
fragment
- the URI fragment component.public void setPath(@CheckForNull String path)
path
- the URI path component.public void setPathQuery(@CheckForNull String pathQuery)
'?'
.pathQuery
- the combined URI path and query components.public void setQuery(@CheckForNull String query)
query
- the URI query component.public void setScheme(@CheckForNull String scheme)
scheme
- the URI scheme component.public void setString(String uri)
uri
- the URI string.IllegalArgumentException
- if uri
does not conform to the
syntax constraints of the URI
class.public void setUri(URI uri)
uri
- the URI.public UriBuilder string(String uri)
uri
- the URI string.this
IllegalArgumentException
- if uri
does not conform to the
syntax constraints of the URI
class.public String toString()
toString
in class Object
IllegalStateException
- if composing a valid URI is not possible.getString()
public URI toUri()
IllegalStateException
- if composing a valid URI is not possible.getUri()
public UriBuilder uri(URI uri)
uri
- the URI.this
public static void validateScheme(String scheme) throws URISyntaxException
scheme
- the string to validate.URISyntaxException
- if scheme
does not conform to the
syntax constraints for URI schemes in
RFC 2396.Copyright © 2005–2018 Schlichtherle IT Services. All rights reserved.