Class RESTClient


  • public class RESTClient
    extends HTTPBuilder
    Extension to HTTPBuilder that basically attempts to provide a slightly more REST-ful face on top of HTTPBuilder. The differences between this class and HTTPBuilder are such:
    • Access to response headers. All "request" methods on this class by default return an instance of HttpResponseDecorator, which allows for simple evaluation of the response.
    • No streaming responses. Responses are expected to either not carry data (in the case of HEAD or DELETE) or be parse-able into some sort of object. That object is accessible via HttpResponseDecorator.getData().

    By default, all request method methods will return a HttpResponseDecorator instance, which provides convenient access to response headers and the parsed response body. The response body is parsed based on content-type, identical to how HTTPBuilder's default response handler functions.

    Failed requests (i.e. responses which return a status code > 399) will by default throw a HttpResponseException. This exception may be used to retrieve additional information regarding the response as well.

    Since:
    0.5
    • Constructor Detail

      • RESTClient

        public RESTClient()
        Constructor.
        See Also:
        HTTPBuilder()
      • RESTClient

        public RESTClient​(java.lang.Object defaultURI)
                   throws java.net.URISyntaxException
        Parameters:
        defaultURI - default request URI (String, URI, URL or URIBuilder)
        Throws:
        java.net.URISyntaxException
      • RESTClient

        public RESTClient​(java.lang.Object defaultURI,
                          java.lang.Object defaultContentType)
                   throws java.net.URISyntaxException
        Parameters:
        defaultURI - default request URI (String, URI, URL or URIBuilder)
        defaultContentType - default content-type (String or ContentType)
        Throws:
        java.net.URISyntaxException
    • Method Detail

      • put

        public java.lang.Object put​(java.util.Map<java.lang.String,​?> args)
                             throws java.net.URISyntaxException,
                                    org.apache.http.client.ClientProtocolException,
                                    java.io.IOException

        Convenience method to perform a PUT request.

        The request body (specified by a body named parameter) will be encoded based on the requestContentType named parameter, or if none is given, the default content-type for this instance.

        Parameters:
        args - named parameters - see HTTPBuilder.RequestConfigDelegate.setPropertiesFromMap(Map)
        Returns:
        a HttpResponseDecorator, unless the default success handler is overridden.
        Throws:
        org.apache.http.client.ClientProtocolException
        java.io.IOException
        java.net.URISyntaxException
      • patch

        public java.lang.Object patch​(java.util.Map<java.lang.String,​?> args)
                               throws java.net.URISyntaxException,
                                      org.apache.http.client.ClientProtocolException,
                                      java.io.IOException

        Convenience method to perform a PATCH request.

        The request body (specified by a body named parameter) will be encoded based on the requestContentType named parameter, or if none is given, the default content-type for this instance.

        Parameters:
        args - named parameters - see HTTPBuilder.RequestConfigDelegate.setPropertiesFromMap(Map)
        Returns:
        a HttpResponseDecorator, unless the default success handler is overridden.
        Throws:
        org.apache.http.client.ClientProtocolException
        java.io.IOException
        java.net.URISyntaxException
      • head

        public java.lang.Object head​(java.util.Map<java.lang.String,​?> args)
                              throws java.net.URISyntaxException,
                                     org.apache.http.client.ClientProtocolException,
                                     java.io.IOException

        Perform a HEAD request, often used to check preconditions before sending a large PUT or POST request.

        Parameters:
        args - named parameters - see HTTPBuilder.RequestConfigDelegate.setPropertiesFromMap(Map)
        Returns:
        a HttpResponseDecorator, unless the default success handler is overridden.
        Throws:
        org.apache.http.client.ClientProtocolException
        java.io.IOException
        java.net.URISyntaxException
      • delete

        public java.lang.Object delete​(java.util.Map<java.lang.String,​?> args)
                                throws java.net.URISyntaxException,
                                       org.apache.http.client.ClientProtocolException,
                                       java.io.IOException

        Perform a DELETE request. This method does not accept a body argument.

        Parameters:
        args - named parameters - see HTTPBuilder.RequestConfigDelegate.setPropertiesFromMap(Map)
        Returns:
        a HttpResponseDecorator, unless the default success handler is overridden.
        Throws:
        org.apache.http.client.ClientProtocolException
        java.io.IOException
        java.net.URISyntaxException
      • options

        public java.lang.Object options​(java.util.Map<java.lang.String,​?> args)
                                 throws org.apache.http.client.ClientProtocolException,
                                        java.io.IOException,
                                        java.net.URISyntaxException

        Perform an OPTIONS request.

        Parameters:
        args - named parameters - see HTTPBuilder.RequestConfigDelegate.setPropertiesFromMap(Map)
        Returns:
        a HttpResponseDecorator, unless the default success handler is overridden.
        Throws:
        org.apache.http.client.ClientProtocolException
        java.io.IOException
        java.net.URISyntaxException
      • defaultFailureHandler

        protected void defaultFailureHandler​(HttpResponseDecorator resp,
                                             java.lang.Object data)
                                      throws HttpResponseException
        Throws an exception for non-successful HTTP response codes. The exception instance will have a reference to the response object, in order to inspect status code and headers within the catch block.
        Parameters:
        resp - response object
        data - parsed response data
        Throws:
        HttpResponseException - exception which can access the response object.