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()
 
  • Field Details

  • Constructor Details

  • Method Details

    • 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()
      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()
      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=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

      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=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

      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=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 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:
    • 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()
      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()
      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: