groovyx.net.http

Class URIBuilder

java.lang.Object

groovyx.net.http.URIBuilder

All Implemented Interfaces:

Cloneable

public class URIBuilder
extends Object
implements 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()
 

Author:

Tom Nichols

Field Summary

Fields

Modifier and Type	Field and Description
protected URI	base

Constructor Summary

Constructors

Constructor and Description
URIBuilder(String url)
URIBuilder(URI uri)
URIBuilder(URL url)

Method Summary

Methods

Modifier and Type	Method and Description
protected URIBuilder	addQueryParam(NameValuePair nvp)
URIBuilder	addQueryParam(String param, Object value) This will append a query parameter to the existing query string.
protected URIBuilder	addQueryParams(List<NameValuePair> nvp)
URIBuilder	addQueryParams(Map<?,?> params) Add these parameters to the URIBuilder's existing query string.
Object	asType(Class<?> type) Implementation of Groovy's as 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	equals(Object obj) Determine if this URIBuilder is equal to another URIBuilder instance.
String	getFragment() See URI.getFragment()
String	getHost() See URI.getHost()
String	getPath() Note that this property is not necessarily reflexive with the setPath(String) method! URIBuilder.setPath() will resolve a relative path, whereas this method will always return the full, absolute path.
int	getPort() See URI.getPort()
Map<String,Object>	getQuery() Get the query string as a map for convenience.
protected List<NameValuePair>	getQueryNVP()
String	getScheme() Get the scheme for this URI.
String	getUserInfo() See URI.getUserInfo()
boolean	hasQueryParam(String name) Indicates if the given parameter is already part of this URI's query string.
URIBuilder	removeQueryParam(String param) Remove the given query parameter from this URI's query string.
URIBuilder	setFragment(String fragment) The document fragment, without a preceeding '#'.
URIBuilder	setHost(String host) Set the host portion of this URI.
URIBuilder	setPath(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(Map<?,?> params) Set the query portion of the URI.
protected URIBuilder	setQueryNVP(List<NameValuePair> nvp)
URIBuilder	setRawQuery(String query) Set the raw, already-escaped query string.
URIBuilder	setScheme(String scheme) Set the URI scheme, AKA the 'protocol.' e.g.
URIBuilder	setUserInfo(String userInfo) Set the userInfo portion of the URI, or null if the URI should have no user information.
String	toString() Print this builder's URI representation.
URI	toURI() Convenience method to convert this object to a URI instance.
URL	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)

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

base

protected URI base

Constructor Detail

URIBuilder

public URIBuilder(String url)
           throws URISyntaxException

Throws:

URISyntaxException

URIBuilder

public URIBuilder(URL url)
           throws URISyntaxException

Throws:

URISyntaxException

URIBuilder

public URIBuilder(URI uri)
           throws IllegalArgumentException

Parameters:

uri -

Throws:

IllegalArgumentException - if uri is null

Method Detail

convertToURI

public static URI convertToURI(Object uri)
                        throws URISyntaxException

Utility method to convert a number of type to a URI instance.

Parameters:

uri - a URI, URL or any object that produces a valid URI string from its toString() 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

public URIBuilder setScheme(String scheme)
                     throws URISyntaxException

Set the URI scheme, AKA the 'protocol.' e.g. setScheme('https')

Throws:

URISyntaxException - if the given scheme contains illegal characters.

getScheme

public String getScheme()

Get the scheme for this URI. See URI.getScheme()

Returns:

the scheme portion of the URI

setPort

public URIBuilder setPort(int port)
                   throws URISyntaxException

Set the port for this URI, or -1 to unset the port.

Parameters:

port -

Returns:

this URIBuilder instance

Throws:

URISyntaxException

getPort

public int getPort()

See URI.getPort()

Returns:

the port portion of this URI (-1 if a port is not specified.)

setHost

public URIBuilder setHost(String host)
                   throws URISyntaxException

Set the host portion of this URI.

Parameters:

host -

Returns:

this URIBuilder instance

Throws:

URISyntaxException - if the host parameter contains illegal characters.

getHost

public String getHost()

See URI.getHost()

Returns:

the host portion of the URI

setPath

public URIBuilder setPath(String path)
                   throws 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:

URISyntaxException - if the given path contains characters that cannot be converted to a valid URI

getPath

public String getPath()

Note that this property is not necessarily reflexive with the setPath(String) method! URIBuilder.setPath() will resolve a relative path, whereas this method will always return the full, absolute path. See URI.getPath()

Returns:

the full path portion of the URI.

setQueryNVP

protected URIBuilder setQueryNVP(List<NameValuePair> nvp)
                          throws URISyntaxException

Throws:

URISyntaxException

setQuery

public URIBuilder setQuery(Map<?,?> params)
                    throws 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:

URISyntaxException

setRawQuery

public URIBuilder setRawQuery(String query)
                       throws URISyntaxException

Set the raw, already-escaped query string. No additional escaping will be done on the string.

Parameters:

query -

Returns:

Throws:

URISyntaxException

getQuery

public Map<String,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 call

 uri.query.a = 'BCD'

You will not modify the query string but instead the generated map of parameters. Instead, you need to use removeQueryParam(String) first, then addQueryParam(String, Object), or call setQuery(Map) which will set the entire query string.

Returns:

a map of String name/value pairs representing the URI's query string.

getQueryNVP

protected List<NameValuePair> getQueryNVP()

hasQueryParam

public boolean hasQueryParam(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(String param)
                            throws 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:

URISyntaxException

addQueryParam

protected URIBuilder addQueryParam(NameValuePair nvp)
                            throws URISyntaxException

Throws:

URISyntaxException

addQueryParam

public URIBuilder addQueryParam(String param,
                       Object value)
                         throws 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 call removeQueryParam(String) first, or use getQuery(), modify the value in the map, then call setQuery(Map).

Parameters:

param - query parameter name

value - query parameter value (will be converted to a string if not null. If value 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:

setQuery(Map)

addQueryParams

protected URIBuilder addQueryParams(List<NameValuePair> nvp)
                             throws URISyntaxException

Throws:

URISyntaxException

addQueryParams

public URIBuilder addQueryParams(Map<?,?> params)
                          throws 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. See setQuery(Map).

Parameters:

params - parameters to add to the existing URI query (if any).

Returns:

this URIBuilder instance, for method chaining.

Throws:

URISyntaxException

setFragment

public URIBuilder setFragment(String fragment)
                       throws URISyntaxException

The document fragment, without a preceeding '#'. Use null to use no document fragment.

Parameters:

fragment -

Returns:

this URIBuilder instance, for method chaining.

Throws:

URISyntaxException - if the given value contains illegal characters.

getFragment

public String getFragment()

See URI.getFragment()

Returns:

the URI document fragment

setUserInfo

public URIBuilder setUserInfo(String userInfo)
                       throws URISyntaxException

Set the userInfo portion of the URI, or null if the URI should have no user information.

Parameters:

userInfo -

Returns:

this URIBuilder instance

Throws:

URISyntaxException - if the given value contains illegal characters.

getUserInfo

public String getUserInfo()

See URI.getUserInfo()

Returns:

the user info portion of the URI, or null if it is not specified.

toString

public String toString()

Print this builder's URI representation.

Overrides:

toString in class Object

toURL

public URL toURL()
          throws MalformedURLException

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

public URI toURI()

Convenience method to convert this object to a URI instance.

Returns:

this builder's underlying URI representation

asType

public Object asType(Class<?> type)
              throws MalformedURLException

Implementation of Groovy's as operator, to allow type conversion.

Parameters:

type - URL, URL, or String.

Returns:

a representation of this URIBuilder instance in the given type

Throws:

MalformedURLException - if type 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 class Object

equals

public boolean equals(Object obj)

Determine if this URIBuilder is equal to another URIBuilder instance.

Overrides:

equals in class Object

Returns:

if obj is a URIBuilder instance whose underlying URI implementation is equal to this one's.

See Also:

URI.equals(Object)