groovyx.net.http
Class URIBuilder

java.lang.Object  extended by 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'] }.toString() 

Author:
Tom Nichols


Field Summary
protected  URIbase
           
 
Constructor Summary
URIBuilder(String url)
           
URIBuilder(URI uri)
           
URIBuilder(URL url)
           
 
Method Summary
protected  URIBuilderaddQueryParam(org.apache.http.NameValuePair nvp)
           
 URIBuilderaddQueryParam(String param, Object value)
          This will append a query parameter to the existing query string.
protected  URIBuilderaddQueryParams(List<org.apache.http.NameValuePair> nvp)
           
 URIBuilderaddQueryParams(Map<?,?> params)
          Add these parameters to the URIBuilder's existing query string.
 ObjectasType(Class<?> type)
          Implementation of Groovy's as operator, to allow type conversion.
protected  URIBuilderclone()
          Create a copy of this URIBuilder instance.
static URIconvertToURI(Object uri)
          Utility method to convert a number of type to a URI instance.
 booleanequals(Object obj)
          Determine if this URIBuilder is equal to another URIBuilder instance.
 StringgetFragment()
          See URI.getFragment()
 StringgetHost()
          See URI.getHost()
 StringgetPath()
          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.
 intgetPort()
          See URI.getPort()
 Map<String,Object>getQuery()
          Get the query string as a map for convenience.
protected  List<org.apache.http.NameValuePair>getQueryNVP()
           
 StringgetScheme()
          Get the scheme for this URI.
 StringgetUserInfo()
          See URI.getUserInfo()
 booleanhasQueryParam(String name)
          Indicates if the given parameter is already part of this URI's query string.
 URIBuilderremoveQueryParam(String param)
          Remove the given query parameter from this URI's query string.
 URIBuildersetFragment(String fragment)
          The document fragment, without a preceeding '#'.
 URIBuildersetHost(String host)
          Set the host portion of this URI.
 URIBuildersetPath(String path)
          Set the path component of this URI.
 URIBuildersetPort(int port)
          Set the port for this URI, or -1 to unset the port.
 URIBuildersetQuery(Map<?,?> params)
          Set the query portion of the URI.
protected  URIBuildersetQueryNVP(List<org.apache.http.NameValuePair> nvp)
           
 URIBuildersetRawQuery(String query)
          Set the raw, already-escaped query string.
 URIBuildersetScheme(String scheme)
          Set the URI scheme, AKA the 'protocol.' e.g.
 URIBuildersetUserInfo(String userInfo)
          Set the userInfo portion of the URI, or null if the URI should have no user information.
 StringtoString()
          Print this builder's URI representation.
 URItoURI()
          Convenience method to convert this object to a URI instance.
 URLtoURL()
          Convenience method to convert this object to a URL instance.
protected  URIupdate(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<org.apache.http.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<org.apache.http.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(org.apache.http.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<org.apache.http.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)


Copyright © 2008-2012. All Rights Reserved.


NOTHING
NOTHING
Add the Maven Dependecy to your project: maven dependecy for com.amazonaws : aws-java-sdk : 1.3.14