Class URIBuilder

  • All Implemented Interfaces:
    java.lang.Cloneable

    public class URIBuilder
    extends java.lang.Object
    implements java.lang.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 
      Modifier and Type Field Description
      protected java.net.URI base  
      private java.lang.String ENC  
    • 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's as 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()
      See URI.getFragment()
      java.lang.String getHost()
      See URI.getHost()
      java.lang.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()
      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()
      See URI.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, or null 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)  
      • Methods inherited from class java.lang.Object

        finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • base

        protected java.net.URI base
    • 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 - 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:
        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. See URI.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()
        See URI.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()
        See URI.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 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​(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 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 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 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:
        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. See setQuery(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 '#'. Use null 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()
        See URI.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, or null 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()
        See URI.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 class java.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'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:
        java.net.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 java.lang.Object
      • equals

        public boolean equals​(java.lang.Object obj)
        Determine if this URIBuilder is equal to another URIBuilder instance.
        Overrides:
        equals in class java.lang.Object
        Returns:
        if obj is a URIBuilder instance whose underlying URI implementation is equal to this one's.
        See Also:
        URI.equals(Object)