Class 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 Detail

      • base

        protected URI base
    • 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
      • getScheme

        public String getScheme()
        Get the scheme for this URI. See URI.getScheme()
        Returns:
        the scheme portion of the URI
      • getPort

        public int getPort()
        Returns:
        the port portion of this URI (-1 if a port is not specified.)
      • 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.
      • 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
      • 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

        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

        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.
      • 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:
        URI.equals(Object)