Package manifold.json.rt.api

Class Requester<T>

  • Type Parameters:
    T - The type corresponding with the HTTP requests made from this class. For instance, this type is returned from GET calls and is also the type of the payload sent for POST, PUT, and PATCH calls. Since DELETE calls do not necessarily send or receive this type, it is not part of the signatures of those methods.
    public class Requester<T>
extends Object
    This class defines methods to simplify making HTTP requests involved with basic REST API calls supporting GET, POST, PUT, PATCH, and DELETE and handles responses in JSON & JSON Schema, YAML, XML, CSV, or plain text. An instance of this class may be used for multiple get/post/etc. requests.

    Normally you use this class via the JSON API request(url) method to manage simple HTTP request API calls: 

    
 User user = User.request("http://example.com/users").getOne("/$id");

 // or

 Requester<User> req = User.request("http://example.com/users")
   .withBearerAuthorization("xxx...x"); // eg., using OAuth token
 User user = req.getOne("/$id");
 user.setName("Scott");
 req.putOne("/$id", user);

    • Constructor Detail

      • Requester

        public Requester​(String urlBase)
        Get an instance of Requester from a JSON API type eg., User.request(). Requester is a builder type: you can configure the requests you'll make using withXxx() calls to specify an authorization token, response format, custom headers, etc. Then you can make one or more requests with a single instance: 
        
 Requester<User> req = User.request("http://example.com/users")
   .withBearerAuthorization("xxx...x"); // eg., using OAuth token
 User user = req.getOne("/$id");
 user.setName("Scott");
 req.putOne("/$id", user);
        Parameters:
        urlBase - A URL providing HTTP services for T, such as "http://example.com/users"

      • Requester

        public Requester​(Endpoint endpoint)

    • Method Detail

      • getEndpoint

        public Endpoint getEndpoint()

      • getTimeout

        public int getTimeout()

      • withResponseFormat

        public Requester<T> withResponseFormat​(Requester.Format format)
        Set the default format expected in the response. The response will be parsed according to this setting.
        Parameters:
        format - Json, Yaml, Xml, Csv, or Plain text. Default is Json.

      • withHeader

        public Requester<T> withHeader​(String name,
                               String value)
        Set an HTTP request header name : value pair See

        • withParam

          public Requester<T> withParam​(String name,
                              String value)
          Add a name=value parameter to the request URL.

        • withBasicAuthorization

          public Requester<T> withBasicAuthorization​(String username,
                                           String password)
          Set the Basic Authorization header using the provided username and password

        • withBearerAuthorization

          public Requester<T> withBearerAuthorization​(String accessToken)
          Set the Bearer Authorization header using the provided accessToken. For instance, if using OAuth, accessToken is the token response from: 
          
 curl -d "grant_type=password&client_id=[...]&client_secret=[...]&username=[...]&password=[...]"
   https://[domain]/[oauth-service]

        • withTimeout

          public Requester<T> withTimeout​(int timeout)
          The connection timeout setting in milliseconds. If the timeout expires before the connection can be established, a {@link java.net.SocketTimeoutException) is thrown. A value of zero is interpreted as an infinite timeout, this is the default setting.

        • withRawResponseHandler

          public Requester<T> withRawResponseHandler​(Function<T,​Object> handler)
          Parameters:
          handler - An optional handler for processing the raw response as an arbitrary Bindings instance. The handler may return a custom bindings object which overrides the default, type-safe result instance. In any case, the handler can process the response in any way. Note, modifications made to the response persist and, therefore, affect default internal data and error processing.

        • getRawResponseHandler

          public Function<T,​Object> getRawResponseHandler()
          Returns:
          The raw response handler or null if one is not assigned.

        • getOne

          public T getOne()
          Use HTTP GET for a single T JSON API object specified in the urlSuffix, such as "/108".
          Returns:
          A single T JSON API object specified in the urlSuffix

          Same as calling: getOne(String, Object, Format) with getOne("", null, _format)

        • getOne

          public T getOne​(String urlSuffix)
          Use HTTP GET for a single T JSON API object specified in the urlSuffix, such as "/108".
          Parameters:
          urlSuffix - A suffix identifying the T JSON API object to getOne
          Returns:
          A single T JSON API object specified in the urlSuffix

          Same as calling: getOne(String, Object, Format) with getOne(urlSuffix, null, _format)

        • getOne

          public T getOne​(String urlSuffix,
                Object arguments,
                Requester.Format format)
          Make an HTTP GET request to urlBase + urlSuffix. arguments, if non-null, is sent in the URL as JSON encoded URL arguments.
          Parameters:
          arguments - A JSON value object, sent in the URL as JSON encoded arguments, nullable
          urlSuffix - A suffix, such as "/108", nullable
          format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain
          Returns:
          A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)

        • getMany

          public IJsonList<T> getMany()
          Uses HTTP GET for the complete list of T JSON API objects as a IJsonList<T>.
          Returns:
          The complete list of T JSON API objects as a IJsonList<T>

          Same as calling: getMany(String, Object, Format) with getMany("", null, _format)

        • getMany

          public IJsonList<T> getMany​(String urlSuffix,
                            Object arguments,
                            Requester.Format format)
          Make an HTTP GET request to urlBase + urlSuffix. arguments, if non-null, is sent in the URL as JSON encoded URL arguments.
          Parameters:
          arguments - A JSON value object, sent in the URL as JSON encoded arguments, nullable
          urlSuffix - A suffix, such as "/108", nullable
          format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain
          Returns:
          A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)

        • postOne

          public <R> R postOne​(String urlSuffix,
                     T payload,
                     Requester.Format format)
          Make an HTTP POST request to urlBase + urlSuffix. The payload, if non-null, is sent as JSON encoded text in the request's message body.
          Type Parameters:
          R - The expected type of the response
          Parameters:
          payload - A JSON value object, sent as JSON encoded text in the request's message body
          urlSuffix - A suffix, such as "/108", nullable
          format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain
          Returns:
          A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)

        • postMany

          public <R> R postMany​(String urlSuffix,
                      List<T> payload,
                      Requester.Format format)
          Make an HTTP POST request to urlBase + urlSuffix. The payload, if non-null, is sent as JSON encoded text in the request's message body.
          Type Parameters:
          R - The expected type of the response
          Parameters:
          payload - A JSON value object, sent as JSON encoded text in the request's message body
          urlSuffix - A suffix, such as "/108", nullable
          format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain
          Returns:
          A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)

        • putOne

          public <R> R putOne​(String urlSuffix,
                    T payload,
                    Requester.Format format)
          Make an HTTP PUT request to urlBase + urlSuffix. The payload, if non-null, is sent as JSON encoded text in the request's message body.
          Type Parameters:
          R - The expected type of the response
          Parameters:
          payload - A JSON value object, sent as JSON encoded text in the request's message body
          urlSuffix - A suffix, such as "/108", nullable
          format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain
          Returns:
          A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)

        • putMany

          public <R> R putMany​(String urlSuffix,
                     List<T> payload,
                     Requester.Format format)
          Make an HTTP PUT request to urlBase + urlSuffix. The payload, if non-null, is sent as JSON encoded text in the request's message body.
          Type Parameters:
          R - The expected type of the response
          Parameters:
          payload - A JSON value object, sent as JSON encoded text in the request's message body
          urlSuffix - A suffix, such as "/108", nullable
          format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain
          Returns:
          A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)

        • patchOne

          public <R> R patchOne​(String urlSuffix,
                      T payload,
                      Requester.Format format)
          Make an HTTP PATCH request to urlBase + urlSuffix. The payload, if non-null, is sent as JSON encoded text in the request's message body.
          Type Parameters:
          R - The expected type of the response
          Parameters:
          payload - A JSON value object, sent as JSON encoded text in the request's message body
          urlSuffix - A suffix, such as "/108", nullable
          format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain
          Returns:
          A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)

        • patchMany

          public <R> R patchMany​(String urlSuffix,
                       List<T> payload,
                       Requester.Format format)
          Make an HTTP PATCH request to urlBase + urlSuffix. The payload, if non-null, is sent as JSON encoded text in the request's message body.
          Type Parameters:
          R - The expected type of the response
          Parameters:
          payload - A JSON value object, sent as JSON encoded text in the request's message body
          urlSuffix - A suffix, such as "/108", nullable
          format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain
          Returns:
          A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)

        • delete

          public <R> R delete​(String urlSuffix,
                    Object arguments,
                    Requester.Format format)
          Make an HTTP DELETE request to urlBase + urlSuffix. The payload, if non-null, is sent in the URL as JSON encoded URL arguments.
          Type Parameters:
          R - The expected type of the response
          Parameters:
          arguments - A JSON value object, sent in the URL as JSON encoded arguments, nullable
          urlSuffix - A suffix, such as "/108", nullable
          format - The expected format of the response. One of: Json, Yaml, Xml, Csv, or Plain
          Returns:
          A JSON value parsed from the format specified encoded response (primitive/boxed type, String, List of JSON values, or Bindings of String/JSON value)