Package groovyx.net.http
Class URIBuilder
- java.lang.Object
-
- groovyx.net.http.URIBuilder
-
- All Implemented Interfaces:
java.lang.Cloneable
public class URIBuilder extends java.lang.Object implements java.lang.Cloneable
This class implements a mutable URI. Allset
,add
andremove
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()
-
-
Constructor Summary
Constructors Constructor Description URIBuilder(java.lang.String url)
URIBuilder(java.net.URI uri)
URIBuilder(java.net.URL url)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description URIBuilder
addQueryParam(java.lang.String param, java.lang.Object value)
This will append a query parameter to the existing query string.protected URIBuilder
addQueryParam(org.apache.http.NameValuePair nvp)
protected URIBuilder
addQueryParams(java.util.List<org.apache.http.NameValuePair> nvp)
URIBuilder
addQueryParams(java.util.Map<?,?> params)
Add these parameters to the URIBuilder's existing query string.java.lang.Object
asType(java.lang.Class<?> type)
Implementation of Groovy'sas
operator, to allow type conversion.protected URIBuilder
clone()
Create a copy of this URIBuilder instance.static java.net.URI
convertToURI(java.lang.Object uri)
Utility method to convert a number of type to a URI instance.boolean
equals(java.lang.Object obj)
Determine if this URIBuilder is equal to another URIBuilder instance.java.lang.String
getFragment()
SeeURI.getFragment()
java.lang.String
getHost()
SeeURI.getHost()
java.lang.String
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()
java.util.Map<java.lang.String,java.lang.Object>
getQuery()
Get the query string as a map for convenience.protected java.util.List<org.apache.http.NameValuePair>
getQueryNVP()
java.lang.String
getScheme()
Get the scheme for this URI.java.lang.String
getUserInfo()
SeeURI.getUserInfo()
boolean
hasQueryParam(java.lang.String name)
Indicates if the given parameter is already part of this URI's query string.URIBuilder
removeQueryParam(java.lang.String param)
Remove the given query parameter from this URI's query string.URIBuilder
setFragment(java.lang.String fragment)
The document fragment, without a preceeding '#'.URIBuilder
setHost(java.lang.String host)
Set the host portion of this URI.URIBuilder
setPath(java.lang.String path)
Set the path component of this URI.URIBuilder
setPort(int port)
Set the port for this URI, or-1
to unset the port.URIBuilder
setQuery(java.util.Map<?,?> params)
Set the query portion of the URI.protected URIBuilder
setQueryNVP(java.util.List<org.apache.http.NameValuePair> nvp)
URIBuilder
setRawQuery(java.lang.String query)
Set the raw, already-escaped query string.URIBuilder
setScheme(java.lang.String scheme)
Set the URI scheme, AKA the 'protocol.' e.g.URIBuilder
setUserInfo(java.lang.String userInfo)
Set the userInfo portion of the URI, ornull
if the URI should have no user information.java.lang.String
toString()
Print this builder's URI representation.java.net.URI
toURI()
Convenience method to convert this object to a URI instance.java.net.URL
toURL()
Convenience method to convert this object to a URL instance.protected java.net.URI
update(java.lang.String scheme, java.lang.String userInfo, java.lang.String host, int port, java.lang.String path, java.lang.String query, java.lang.String fragment)
-
-
-
Field Detail
-
base
protected java.net.URI base
-
ENC
private final java.lang.String ENC
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
URIBuilder
public URIBuilder(java.lang.String url) throws java.net.URISyntaxException
- Throws:
java.net.URISyntaxException
-
URIBuilder
public URIBuilder(java.net.URL url) throws java.net.URISyntaxException
- Throws:
java.net.URISyntaxException
-
URIBuilder
public URIBuilder(java.net.URI uri) throws java.lang.IllegalArgumentException
- Parameters:
uri
-- Throws:
java.lang.IllegalArgumentException
- if uri is null
-
-
Method Detail
-
convertToURI
public static java.net.URI convertToURI(java.lang.Object uri) throws java.net.URISyntaxException
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:
java.net.URISyntaxException
-
update
protected java.net.URI update(java.lang.String scheme, java.lang.String userInfo, java.lang.String host, int port, java.lang.String path, java.lang.String query, java.lang.String fragment) throws java.net.URISyntaxException
- Throws:
java.net.URISyntaxException
-
setScheme
public URIBuilder setScheme(java.lang.String scheme) throws java.net.URISyntaxException
Set the URI scheme, AKA the 'protocol.' e.g.setScheme('https')
- Throws:
java.net.URISyntaxException
- if the given scheme contains illegal characters.
-
getScheme
public java.lang.String getScheme()
Get the scheme for this URI. SeeURI.getScheme()
- Returns:
- the scheme portion of the URI
-
setPort
public URIBuilder setPort(int port) throws java.net.URISyntaxException
Set the port for this URI, or-1
to unset the port.- Parameters:
port
-- Returns:
- this URIBuilder instance
- Throws:
java.net.URISyntaxException
-
getPort
public int getPort()
SeeURI.getPort()
- Returns:
- the port portion of this URI (-1 if a port is not specified.)
-
setHost
public URIBuilder setHost(java.lang.String host) throws java.net.URISyntaxException
Set the host portion of this URI.- Parameters:
host
-- Returns:
- this URIBuilder instance
- Throws:
java.net.URISyntaxException
- if the host parameter contains illegal characters.
-
getHost
public java.lang.String getHost()
SeeURI.getHost()
- Returns:
- the host portion of the URI
-
setPath
public URIBuilder setPath(java.lang.String path) throws java.net.URISyntaxException
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=1&b=2&c=3#frag'
- Parameters:
path
- the path portion of this URI, relative to the current URI.- Returns:
- this URIBuilder instance, for method chaining.
- Throws:
java.net.URISyntaxException
- if the given path contains characters that cannot be converted to a valid URI
-
getPath
public java.lang.String 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
protected URIBuilder setQueryNVP(java.util.List<org.apache.http.NameValuePair> nvp) throws java.net.URISyntaxException
- Throws:
java.net.URISyntaxException
-
setQuery
public URIBuilder setQuery(java.util.Map<?,?> params) throws java.net.URISyntaxException
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=val1&p2=val2&p2=val3
- Parameters:
params
- a Map of parameters that will be transformed into the query string- Returns:
- this URIBuilder instance, for method chaining.
- Throws:
java.net.URISyntaxException
-
setRawQuery
public URIBuilder setRawQuery(java.lang.String query) throws java.net.URISyntaxException
Set the raw, already-escaped query string. No additional escaping will be done on the string.- Parameters:
query
-- Returns:
- Throws:
java.net.URISyntaxException
-
getQuery
public java.util.Map<java.lang.String,java.lang.Object> getQuery()
Get the query string as a map for convenience. If any parameter contains multiple values (e.g.p1=one&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
protected java.util.List<org.apache.http.NameValuePair> getQueryNVP()
-
hasQueryParam
public boolean hasQueryParam(java.lang.String name)
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
public URIBuilder removeQueryParam(java.lang.String param) throws java.net.URISyntaxException
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:
java.net.URISyntaxException
-
addQueryParam
protected URIBuilder addQueryParam(org.apache.http.NameValuePair nvp) throws java.net.URISyntaxException
- Throws:
java.net.URISyntaxException
-
addQueryParam
public URIBuilder addQueryParam(java.lang.String param, java.lang.Object value) throws java.net.URISyntaxException
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:
java.net.URISyntaxException
- if the query parameter values cannot be converted to a valid URI.- See Also:
setQuery(Map)
-
addQueryParams
protected URIBuilder addQueryParams(java.util.List<org.apache.http.NameValuePair> nvp) throws java.net.URISyntaxException
- Throws:
java.net.URISyntaxException
-
addQueryParams
public URIBuilder addQueryParams(java.util.Map<?,?> params) throws java.net.URISyntaxException
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:
java.net.URISyntaxException
-
setFragment
public URIBuilder setFragment(java.lang.String fragment) throws java.net.URISyntaxException
The document fragment, without a preceeding '#'. Usenull
to use no document fragment.- Parameters:
fragment
-- Returns:
- this URIBuilder instance, for method chaining.
- Throws:
java.net.URISyntaxException
- if the given value contains illegal characters.
-
getFragment
public java.lang.String getFragment()
SeeURI.getFragment()
- Returns:
- the URI document fragment
-
setUserInfo
public URIBuilder setUserInfo(java.lang.String userInfo) throws java.net.URISyntaxException
Set the userInfo portion of the URI, ornull
if the URI should have no user information.- Parameters:
userInfo
-- Returns:
- this URIBuilder instance
- Throws:
java.net.URISyntaxException
- if the given value contains illegal characters.
-
getUserInfo
public java.lang.String getUserInfo()
SeeURI.getUserInfo()
- Returns:
- the user info portion of the URI, or
null
if it is not specified.
-
toString
public java.lang.String toString()
Print this builder's URI representation.- Overrides:
toString
in classjava.lang.Object
-
toURL
public java.net.URL toURL() throws java.net.MalformedURLException
Convenience method to convert this object to a URL instance.- Returns:
- this builder as a URL
- Throws:
java.net.MalformedURLException
- if the underlying URI does not represent a valid URL.
-
toURI
public java.net.URI toURI()
Convenience method to convert this object to a URI instance.- Returns:
- this builder's underlying URI representation
-
asType
public java.lang.Object asType(java.lang.Class<?> type) throws java.net.MalformedURLException
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:
java.net.MalformedURLException
- iftype
is URL and this URIBuilder instance does not represent a valid URL.
-
clone
protected URIBuilder clone()
Create a copy of this URIBuilder instance.- Overrides:
clone
in classjava.lang.Object
-
equals
public boolean equals(java.lang.Object obj)
Determine if this URIBuilder is equal to another URIBuilder instance.- Overrides:
equals
in classjava.lang.Object
- Returns:
- if
obj
is a URIBuilder instance whose underlying URI implementation is equal to this one's. - See Also:
URI.equals(Object)
-
-