com.holonplatform.http.rest

## Interface RestClient

- All Known Subinterfaces:
    SpringRestClient

      public interface RestClient

  HTTP REST client to build and execute client requests in order to consume responses returned.
  Since:
    5.0.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `RestClient.Invocation` Invocation operations
    `static interface` | `RestClient.Invoker` Invoker to perform a client request in order to consume a response using a `RestClient.RequestDefinition`.
    `static interface` | `RestClient.RequestDefinition` Request message definition and response invocation.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `RestClient` | `clearDefaultHeaders()` Removes all default headers
    `static RestClient` | `create()` Create a new `RestClient` instance using default `ClassLoader` and default implementation, if available.
    `static RestClient` | `create(ClassLoader classLoader)` Create a new `RestClient` instance using given `classLoder` and default implementation, if available.
    `static RestClient` | `create(String fullyQualifiedClassName)` Create a new `RestClient` instance using default `ClassLoader` and the implementation whith given fully qualified class name.
    `static RestClient` | `create(String fullyQualifiedClassName, ClassLoader classLoader)` Create a new `RestClient` instance using given `classLoder` and the implementation whith given fully qualified class name.
    `RestClient` | `defaultTarget(URI baseUri)` Set the default target request base URI, which will be used as target URI for every request configured using `request()`, if not overridden using `RestClient.RequestDefinition.target(URI)`.
    `static RestClient` | `forTarget(String baseUri)` Create a new `RestClient` instance using default `ClassLoader` and default implementation, setting given `baseUri` as default `RestClient` target, which will be used as base URI for every request configured using `request()`, if not overridden using `RestClient.RequestDefinition.target(URI)`.
    `static RestClient` | `forTarget(URI baseUri)` Create a new `RestClient` instance using default `ClassLoader` and default implementation, setting given `baseUri` as default `RestClient` target, which will be used as base URI for every request configured using `request()`, if not overridden using `RestClient.RequestDefinition.target(URI)`.
    `Optional<URI>` | `getDefaultTarget()` Get the default target request base URI, which will be used as target URI for every request configured using `request()`, if not overridden using `RestClient.RequestDefinition.target(URI)`.
    `RestClient` | `removeDefaultHeader(String name)` Removes the default header with given `name`, if present
    `RestClient.RequestDefinition` | `request()` Create a new request definition, to be used to configure request and invoke response.
    `RestClient` | `withDefaultHeader(String name, String value)` Add a default request header which will be automatically added to every invocation request message, if an header with the same name is not already present.

- - ### Method Detail

    - #### defaultTarget

          RestClient defaultTarget(URI baseUri)

      Set the default target request base URI, which will be used as target URI for every request configured using `request()`, if not overridden using `RestClient.RequestDefinition.target(URI)`.

      URI template parameters are not supported for the base target URI.

      Parameters:
        `baseUri` - Default target request base URI
      Returns:
        The updated RestClient

    - #### getDefaultTarget

          Optional<URI> getDefaultTarget()

      Get the default target request base URI, which will be used as target URI for every request configured using `request()`, if not overridden using `RestClient.RequestDefinition.target(URI)`.
      Returns:
        Default target request base URI, if setted

    - #### withDefaultHeader

          RestClient withDefaultHeader(String name,
                                       String value)

      Add a default request header which will be automatically added to every invocation request message, if an header with the same name is not already present.
      Parameters:
        `name` - Header name (not null)
        `value` - Header value
      Returns:
        The updated RestClient

    - #### removeDefaultHeader

          RestClient removeDefaultHeader(String name)

      Removes the default header with given `name`, if present
      Parameters:
        `name` - Header name to remove (not null)
      Returns:
        The updated RestClient

    - #### clearDefaultHeaders

          RestClient clearDefaultHeaders()

      Removes all default headers
      Returns:
        The updated RestClient

    - #### request

          RestClient.RequestDefinition request()

      Create a new request definition, to be used to configure request and invoke response.

      If a default target request URI is configured using `defaultTarget(URI)`, this will be used as request base URI. The target URI can be overridden using `RestClient.RequestDefinition.target(URI)`.

      Returns:
        Request definition builder

    - #### forTarget

          static RestClient forTarget(String baseUri)

      Create a new `RestClient` instance using default `ClassLoader` and default implementation, setting given `baseUri` as default `RestClient` target, which will be used as base URI for every request configured using `request()`, if not overridden using `RestClient.RequestDefinition.target(URI)`.
      Parameters:
        `baseUri` - The base target URI of the returned `RestClient`
      Returns:
        A new `RestClient` instance

    - #### forTarget

          static RestClient forTarget(URI baseUri)

      Create a new `RestClient` instance using default `ClassLoader` and default implementation, setting given `baseUri` as default `RestClient` target, which will be used as base URI for every request configured using `request()`, if not overridden using `RestClient.RequestDefinition.target(URI)`.
      Parameters:
        `baseUri` - The base target URI of the returned `RestClient`
      Returns:
        A new `RestClient` instance

    - #### create

          static RestClient create()

      Create a new `RestClient` instance using default `ClassLoader` and default implementation, if available. If more than one `RestClient` implementation is found using given ClassLoader, the one returned by the `RestClientFactory` with the higher priority is returned.
      Returns:
        A new `RestClient` instance
      Throws:
        `RestClientCreationException` - If a `RestClient` implementation is not available or a instance creation error occurred

    - #### create

          static RestClient create(ClassLoader classLoader)

      Create a new `RestClient` instance using given `classLoder` and default implementation, if available. If more than one `RestClient` implementation is found using given ClassLoader, the one returned by the `RestClientFactory` with the higher priority is returned.
      Parameters:
        `classLoader` - The `ClassLoader` to use
      Returns:
        A new `RestClient` instance
      Throws:
        `RestClientCreationException` - If a `RestClient` implementation is not available or a instance creation error occurred

    - #### create

          static RestClient create(String fullyQualifiedClassName)

      Create a new `RestClient` instance using default `ClassLoader` and the implementation whith given fully qualified class name.
      Parameters:
        `fullyQualifiedClassName` - The `RestClient` implementation fully qualified class name to obtain
      Returns:
        A new `RestClient` instance
      Throws:
        `RestClientCreationException` - If the implementation which corresponds to given fully qualified class name is not available or a instance creation error occurred

    - #### create

          static RestClient create(String fullyQualifiedClassName,
                                   ClassLoader classLoader)

      Create a new `RestClient` instance using given `classLoder` and the implementation whith given fully qualified class name.
      Parameters:
        `fullyQualifiedClassName` - The `RestClient` implementation fully qualified class name to obtain
        `classLoader` - The `ClassLoader` to use
      Returns:
        A new `RestClient` instance
      Throws:
        `RestClientCreationException` - If the implementation which corresponds to given fully qualified class name is not available or a instance creation error occurred

Copyright © 2017 The Holon Platform. All rights reserved.