Package groovyx.net.http
Class URIBuilder
java.lang.Object
groovyx.net.http.URIBuilder
- All Implemented Interfaces:
Cloneable
This class implements a mutable URI. All
set
, add
and remove
methods affect this class' internal URI
representation. All mutator methods support chaining, e.g.
new URIBuilder("http://www.google.com/") .setScheme( "https" ) .setPort( 443 ) .setPath( "some/path" ) .toString();A slightly more 'Groovy' version would be:
new URIBuilder('http://www.google.com/').with { scheme = 'https' port = 443 path = 'some/path' query = [p1:1, p2:'two'] return it }.toString()
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionaddQueryParam
(String param, Object value) This will append a query parameter to the existing query string.protected URIBuilder
addQueryParam
(org.apache.http.NameValuePair nvp) protected URIBuilder
addQueryParams
(List<org.apache.http.NameValuePair> nvp) addQueryParams
(Map<?, ?> params) Add these parameters to the URIBuilder's existing query string.Implementation of Groovy'sas
operator, to allow type conversion.protected URIBuilder
clone()
Create a copy of this URIBuilder instance.static URI
convertToURI
(Object uri) Utility method to convert a number of type to a URI instance.boolean
Determine if this URIBuilder is equal to another URIBuilder instance.getHost()
SeeURI.getHost()
getPath()
Note that this property is not necessarily reflexive with thesetPath(String)
method!URIBuilder.setPath()
will resolve a relative path, whereas this method will always return the full, absolute path.int
getPort()
SeeURI.getPort()
getQuery()
Get the query string as a map for convenience.protected List
<org.apache.http.NameValuePair> Get the scheme for this URI.boolean
hasQueryParam
(String name) Indicates if the given parameter is already part of this URI's query string.removeQueryParam
(String param) Remove the given query parameter from this URI's query string.setFragment
(String fragment) The document fragment, without a preceeding '#'.Set the host portion of this URI.Set the path component of this URI.setPort
(int port) Set the port for this URI, or-1
to unset the port.Set the query portion of the URI.protected URIBuilder
setQueryNVP
(List<org.apache.http.NameValuePair> nvp) setRawQuery
(String query) Set the raw, already-escaped query string.Set the URI scheme, AKA the 'protocol.' e.g.setUserInfo
(String userInfo) Set the userInfo portion of the URI, ornull
if the URI should have no user information.toString()
Print this builder's URI representation.toURI()
Convenience method to convert this object to a URI instance.toURL()
Convenience method to convert this object to a URL instance.protected URI
update
(String scheme, String userInfo, String host, int port, String path, String query, String fragment)
-
Field Details
-
base
-
ENC
- See Also:
-
-
Constructor Details
-
URIBuilder
- Throws:
URISyntaxException
-
URIBuilder
- Throws:
URISyntaxException
-
URIBuilder
- Parameters:
uri
-- Throws:
IllegalArgumentException
- if uri is null
-
-
Method Details
-
convertToURI
Utility method to convert a number of type to a URI instance.- Parameters:
uri
- aURI
,URL
or any object that produces a valid URI string from itstoString()
result.- Returns:
- a valid URI parsed from the given object
- Throws:
URISyntaxException
-
update
protected URI update(String scheme, String userInfo, String host, int port, String path, String query, String fragment) throws URISyntaxException - Throws:
URISyntaxException
-
setScheme
Set the URI scheme, AKA the 'protocol.' e.g.setScheme('https')
- Throws:
URISyntaxException
- if the given scheme contains illegal characters.
-
getScheme
Get the scheme for this URI. SeeURI.getScheme()
- Returns:
- the scheme portion of the URI
-
setPort
Set the port for this URI, or-1
to unset the port.- Parameters:
port
-- Returns:
- this URIBuilder instance
- Throws:
URISyntaxException
-
getPort
public int getPort()SeeURI.getPort()
- Returns:
- the port portion of this URI (-1 if a port is not specified.)
-
setHost
Set the host portion of this URI.- Parameters:
host
-- Returns:
- this URIBuilder instance
- Throws:
URISyntaxException
- if the host parameter contains illegal characters.
-
getHost
SeeURI.getHost()
- Returns:
- the host portion of the URI
-
setPath
Set the path component of this URI. The value may be absolute or relative to the current path. e.g.def uri = new URIBuilder( 'http://localhost/p1/p2?a=1' ) uri.path = '/p3/p2' assert uri.toString() == 'http://localhost/p3/p2?a=1' uri.path = 'p2a' assert uri.toString() == 'http://localhost/p3/p2a?a=1' uri.path = '../p4' assert uri.toString() == 'http://localhost/p4?a=1invalid input: '&b'=2invalid input: '&c'=3#frag'
- Parameters:
path
- the path portion of this URI, relative to the current URI.- Returns:
- this URIBuilder instance, for method chaining.
- Throws:
URISyntaxException
- if the given path contains characters that cannot be converted to a valid URI
-
getPath
Note that this property is not necessarily reflexive with thesetPath(String)
method!URIBuilder.setPath()
will resolve a relative path, whereas this method will always return the full, absolute path. SeeURI.getPath()
- Returns:
- the full path portion of the URI.
-
setQueryNVP
- Throws:
URISyntaxException
-
setQuery
Set the query portion of the URI. For query parameters with multiple values, put the values in a list like so:uri.query = [ p1:'val1', p2:['val2', 'val3'] ] // will produce a query string of ?p1=val1invalid input: '&p2'=val2invalid input: '&p2'=val3
- Parameters:
params
- a Map of parameters that will be transformed into the query string- Returns:
- this URIBuilder instance, for method chaining.
- Throws:
URISyntaxException
-
setRawQuery
Set the raw, already-escaped query string. No additional escaping will be done on the string.- Parameters:
query
-- Returns:
- Throws:
URISyntaxException
-
getQuery
Get the query string as a map for convenience. If any parameter contains multiple values (e.g.p1=oneinvalid input: '&p1'=two
) both values will be inserted into a list for that paramter key ([p1 : ['one','two']]
). Note that this is not a "live" map. Therefore, you cannot calluri.query.a = 'BCD'
You will not modify the query string but instead the generated map of parameters. Instead, you need to useremoveQueryParam(String)
first, thenaddQueryParam(String, Object)
, or callsetQuery(Map)
which will set the entire query string.- Returns:
- a map of String name/value pairs representing the URI's query string.
-
getQueryNVP
-
hasQueryParam
Indicates if the given parameter is already part of this URI's query string.- Parameters:
name
- the query parameter name- Returns:
- true if the given parameter name is found in the query string of the URI.
-
removeQueryParam
Remove the given query parameter from this URI's query string.- Parameters:
param
- the query name to remove- Returns:
- this URIBuilder instance, for method chaining.
- Throws:
URISyntaxException
-
addQueryParam
- Throws:
URISyntaxException
-
addQueryParam
This will append a query parameter to the existing query string. If the given parameter is already part of the query string, it will be appended to. To replace the existing value of a certain parameter, either callremoveQueryParam(String)
first, or usegetQuery()
, modify the value in the map, then callsetQuery(Map)
.- Parameters:
param
- query parameter namevalue
- query parameter value (will be converted to a string if not null. Ifvalue
is null, it will be set as the empty string.- Returns:
- this URIBuilder instance, for method chaining.
- Throws:
URISyntaxException
- if the query parameter values cannot be converted to a valid URI.- See Also:
-
addQueryParams
protected URIBuilder addQueryParams(List<org.apache.http.NameValuePair> nvp) throws URISyntaxException - Throws:
URISyntaxException
-
addQueryParams
Add these parameters to the URIBuilder's existing query string. Parameters may be passed either as a single map argument, or as a list of named arguments. e.g.uriBuilder.addQueryParams( [one:1,two:2] ) uriBuilder.addQueryParams( three : 3 )
If any of the parameters already exist in the URI query, these values will not replace them. Multiple values for the same query parameter may be added by putting them in a list. SeesetQuery(Map)
.- Parameters:
params
- parameters to add to the existing URI query (if any).- Returns:
- this URIBuilder instance, for method chaining.
- Throws:
URISyntaxException
-
setFragment
The document fragment, without a preceeding '#'. Usenull
to use no document fragment.- Parameters:
fragment
-- Returns:
- this URIBuilder instance, for method chaining.
- Throws:
URISyntaxException
- if the given value contains illegal characters.
-
getFragment
- Returns:
- the URI document fragment
-
setUserInfo
Set the userInfo portion of the URI, ornull
if the URI should have no user information.- Parameters:
userInfo
-- Returns:
- this URIBuilder instance
- Throws:
URISyntaxException
- if the given value contains illegal characters.
-
getUserInfo
- Returns:
- the user info portion of the URI, or
null
if it is not specified.
-
toString
Print this builder's URI representation. -
toURL
Convenience method to convert this object to a URL instance.- Returns:
- this builder as a URL
- Throws:
MalformedURLException
- if the underlying URI does not represent a valid URL.
-
toURI
Convenience method to convert this object to a URI instance.- Returns:
- this builder's underlying URI representation
-
asType
Implementation of Groovy'sas
operator, to allow type conversion.- Parameters:
type
-URL
,URL
, orString
.- Returns:
- a representation of this URIBuilder instance in the given type
- Throws:
MalformedURLException
- iftype
is URL and this URIBuilder instance does not represent a valid URL.
-
clone
Create a copy of this URIBuilder instance. -
equals
Determine if this URIBuilder is equal to another URIBuilder instance.
-