Package com.tccc.kos.commons.web.api

Class ApiRequest<T>

java.lang.Object
com.tccc.kos.commons.web.api.ApiRequest<T>
public class ApiRequest<T> extends Object
Data class used by ApiClient to make API calls to local and remote nodes. If the ApiClient doesn't directly support the method and/or options you require, then use this class to build an exact request.

Data Fields

The following fields comprise the ApiRequest: 
 
  private String node;                  // the destination node name; use {@code null} for local
  private RequestMethod method;         // the HTTP method to use (default is GET)
  private String url;                   // the URL to send the request to
  private Map<String, String> headers;  // headers [name/value pairs] (optional)
  private Object body;                  // the body to include in the request (optional)
  private Class<T> responseClass;       // type to convert the response to (optional)
  private int timeout;                  // timeout, in msec (optional); <= 0 means "use default"

Examples

A GET request that returns a string

 
  public class MyClass {

      @Autowired
      private ApiClient apiClient;

      public void someMethod() {
          ApiRequest<String> apiRequest = new ApiRequest();
          apiRequest.setUrl("https://myserver.com/apiv2/path/to/resource?param=value");
          apiRequest.setResponseClass(String.class);
          apiClient.api(apiRequest);
      }
  }

A POST request with body and response objects

 
  public class MyClass {

      @Autowired
      private ApiClient apiClient;

      public void someMethod() {
          ApiRequest<ResponseData> apiRequest = new ApiRequest();
          apiRequest.setNode("Primary")
                    .setMethod(RequestMethod.POST)
                    .setUrl("https://myserver.com/apiv2/path/to/resource?param=value");
                    .addHeader("header1", "value1")
                    .setTrace("XYZ")
                    .setBody(sourceDataObject)
                    .setResonseClass(ResponseData.class)
                    .setTimeout(3000);
          apiClient.api(apiRequest);
      }
  }
Since:
1.0
Version:
2022-09-30
See Also:

  • Constructor Details

    • ApiRequest

      public ApiRequest()
      Constructs a new ApiRequest in which all data fields are null except the request method field, which is initialized to GET.

  • Method Details

    • getNode

      public NodeId getNode()
      Returns the name of the destination node.
      Returns:
      the name of the destination node, or null if none

    • setNode

      public ApiRequest<T> setNode(NodeId node)
      Returns this .
      Parameters:
      node - the id of the destination node
      Returns:
      this

    • setAlias

      public ApiRequest<T> setAlias(String addr)
      Set the router alias of the destination. setNode() calls this with the specified NodeId . Calling this directly will clear the value of node . This can be used with router aliases instead of nodeId's.
      Parameters:
      addr - the websocket router address of the destination

    • getAlias

      public String getAlias()
      Return the currently configured destination alias.

    • getMethod

      public RequestMethod getMethod()
      Returns the HTTP request method.
      Returns:
      the HTTP request method, or null if none

    • setMethod

      public ApiRequest<T> setMethod(RequestMethod method)
      Returns this .
      Parameters:
      method - the HTTP request method
      Returns:
      this

    • getUrl

      public String getUrl()
      Returns the URL.
      Returns:
      the URL, or null if none

    • setUrl

      public ApiRequest<T> setUrl(String url)
      Returns this .
      Parameters:
      url - the URL string to set
      Returns:
      this

    • getBody

      public Object getBody()
      Returns the request body.
      Returns:
      the request body, or null if none

    • setBody

      public ApiRequest<T> setBody(Object body)
      Returns this .
      Parameters:
      body - the request body
      Returns:
      this

    • getResponseClass

      public Class<T> getResponseClass()
      Returns the response body.
      Returns:
      the response body, or null if none

    • setResponseClass

      public ApiRequest<T> setResponseClass(Class<T> responseClass)
      Returns this .
      Parameters:
      responseClass - the response body class
      Returns:
      this

    • getTimeout

      public int getTimeout()
      Returns the timeout value, in msec.
      Returns:
      the timeout value (msec); <= 0 means "use default"

    • setTimeout

      public ApiRequest<T> setTimeout(int timeout)
      Returns this .
      Parameters:
      timeout - the timeout value (msec) to use; <= 0 means "use default"
      Returns:
      this

    • getTrace

      public String getTrace()
      Returns the "trace" header.
      Returns:
      the trace value, or null if it doesn't exist

    • setTrace

      public ApiRequest<T> setTrace(String trace)
      Sets the "trace" header for the message. This causes the router infrastructure code to log data about this message. It does this by adding a header named "trace" whose value is given in the trace parameter.
      Parameters:
      trace - the trace string to put into the log statements

    • setOrdered

      public ApiRequest<T> setOrdered()
      Flags the request as being strictly ordered. It does this by adding a header named "ordered" whose value is true .

    • getHeader

      public String getHeader(String name)
      Returns the header with the specified name.
      Parameters:
      name - the header name
      Returns:
      the value of the header, or null if no header with that name

    • hasHeader

      public boolean hasHeader(String name)
      Determines if the specified header exists.
      Parameters:
      name - the header name
      Returns:
      true if the header exists, otherwise false

    • getHeaders

      public Map<String,String> getHeaders()
      Returns the map of all the headers.
      Returns:
      the map containing the headers; never returns null

    • setHeaders

      public ApiRequest<T> setHeaders(Map<String,String> headers)
      Returns this .
      Parameters:
      headers - map of all name/value headers; can be null
      Returns:
      this

    • addHeader

      public ApiRequest<T> addHeader(String name, Object value)
      Adds the specified header to the message. If the value is null, then the header is removed. The value is converted to its string equivlent using its toString() method.
      Parameters:
      name - the header's name
      value - the header's value
      Returns:
      this

    • addHeaders

      public ApiRequest<T> addHeaders(Map<String,Object> headers)
      Adds all the headers from the specified map. All values are converted to their string equivalent using their toString() method.
      Parameters:
      headers - a map of headers
      Returns:
      this

    • removeHeader

      public String removeHeader(String name)
      Removes the specified header.
      Parameters:
      name - the name of the header to remove
      Returns:
      the previous value associated with name , or null if there was no mapping for name