Package com.ellucian.ethos.integration.client

Class EthosClient

  • Direct Known Subclasses:
    EthosConfigurationClient, EthosErrorsClient, EthosMessagesClient, EthosProxyClient
    public class EthosClient
extends Object
    Base HTTP client to interact with Ellucian Ethos API. This class is mostly used internally by the SDK to support making generic GET, POST, PUT, and DELETE requests to the Ethos Integration API via HTTP(S). It lightly wraps the the Apache HttpClient library for simplicity.

    This class requires an Ethos Integration API key that is used to call the /auth endpoint. If the API key is valid, the auth endpoint will return a signed JWT (access token) that will be used to make all other calls to Ethos Integration.

    Access Tokens have an expiration, and by default, this client will automatically get a new access token before the current one expires. This will prevent getting 401 Unauthorized responses from Ethos Integration for trying to use an expired token. This setting can be overridden by calling setAutoRefresh with a false boolean value.

    Another default authentication behavior of this client is that it will request a token that expires in 60 minutes. The default duration for an access token from Ethos Integration is 5 minutes, but the /auth endpoint allows an expirationMinutes query parameter to change that behavior. The /auth endpoint accepts an expirationMinutes value as an integer between 1 and 120. This setting can be overridden by calling this client's setExpirationMinutes method.

    This class has a region property. The region is associated with an AWS region, and this determines how the URL's will be built when making requests to ensure the request is being routed to the correct Ethos Integration deployment. The region is one of the SupportedRegions enumeration values. By default, it is set to US, but it can be overridden by calling the setRegion method.

    Since:
    0.0.1

    • Field Detail

      • token

        protected AccessToken token
        The AccessToken used to authenticate each request.

      • httpProtocolClientBuilder

        protected HttpProtocolClientBuilder httpProtocolClientBuilder
        The Http client builder which builds an HttpClient used for making secure calls to the Ethos Integration API.

      • ethosResponseBuilder

        protected EthosResponseBuilder ethosResponseBuilder
        Used to build an EthosResponse from the given HttpResponse in the responseHandler of each call made.

      • responseHandler

        protected org.apache.http.client.ResponseHandler<EthosResponse> responseHandler
        The responseHandler used for each request made. Either supplies an EthosResponse, or throws an HttpResponseException if the HttpStatus code is not a successful code.

    • Constructor Detail

      • EthosClient

        public EthosClient​(String apiKey,
                   Integer connectionTimeout,
                   Integer connectionRequestTimeout,
                   Integer socketTimeout)
        Instantiates this client using the given API key and timeout values.
        Parameters:
        apiKey - A valid API key from Ethos Integration. This is required to be a valid 36 character GUID string. If it is null, empty, or not in a valid GUID format, then an IllegalArgumentException will be thrown.
        connectionTimeout - The timeout in seconds for a connection to be established, or null to use the HttpProtocolClientBuilder.DEFAULT_CONNECTION_TIMEOUT value.
        connectionRequestTimeout - The timeout in seconds when requesting a connection from the Apache connection manager, or null to use the HttpProtocolClientBuilder.DEFAULT_CONNECTION_REQUEST_TIMEOUT value.
        socketTimeout - The timeout in seconds when waiting for data between consecutive data packets, or null to use the HttpProtocolClientBuilder.DEFAULT_SOCKET_TIMEOUT value.

    • Method Detail

      • getAccessToken

        public AccessToken getAccessToken()
                           throws IOException
        Gets an access token. If this client does not currently have an access token, it will make a call to the Ethos Integration /auth endpoint to get one. Additionally, if autoRefresh is set to true, this will check to see if the current token is expired and, if so, get a new one.
        Returns:
        an access token
        Throws:
        IOException - If it fails to get an access token

      • get

        public EthosResponse get​(String url,
                         Map<String,​String> headers)
                  throws IOException
        Make an HTTP GET request with the given headers. This will return the response as an EthosResponse, so any other desired response format will need to convert the EthosResponse in the subclass extending this. Also note that HTTP status codes that throw errors will come back as an exception via the responseHandler.
        Parameters:
        url - The URL to GET.
        headers - The headers to send to the request.
        Returns:
        The response as an EthosResponse containing headers, response body (content), and HTTP status code.
        Throws:
        IllegalArgumentException - If the url is null or blank.
        IOException - If there is an error connecting or if there is an HTTP error code.

      • get

        public EthosResponse get​(String url)
                  throws IOException
        Convenience method to make an HTTP call without headers.
        Parameters:
        url - The URL to GET.
        Returns:
        The response as an EthosResponse containing response headers, response body (content), and the HTTP status code.
        Throws:
        IOException - If there is an error connecting or if there is an HTTP error code.

      • head

        public EthosResponse head​(String url)
                   throws IOException
        Make an HTTP HEAD request against the given URL. This will return an EthosResponse object containing the response headers. Note that the HTTP status codes that throw errors will come back as an exception via the responseHandler.
        Parameters:
        url - The request URL.
        Returns:
        The response as an EthosResponse containing headers and HTTP status code.
        Throws:
        IllegalArgumentException - If the url is null or blank.
        IOException - If there is an error connecting or if there is an HTTP error code.

      • post

        public EthosResponse post​(String url,
                          Map<String,​String> headers,
                          String body)
                   throws IOException
        Makes an HTTP POST request with the given headers and body to the specified URL.
        Parameters:
        url - The URL to call.
        headers - The headers to send in the request.
        body - The contents to send in the body of the request.
        Returns:
        The response as an EthosResponse containing headers, response body (content), and HTTP status code.
        Throws:
        IllegalArgumentException - If the url or body is null or blank.
        IOException - If there is an error connecting or if there is an HTTP error code.

      • put

        public EthosResponse put​(String url,
                         Map<String,​String> headers,
                         String body)
                  throws IOException
        Makes an HTTP PUT request with the given headers and body to the specified URL.
        Parameters:
        url - The URL to call.
        headers - The headers to send in the request.
        body - The contents to send in the body of the request.
        Returns:
        The response as an EthosResponse containing headers, response body (content), and HTTP status code.
        Throws:
        IllegalArgumentException - If the url or body is null or blank.
        IOException - If there is an error connecting or if there is an HTTP error code.

      • delete

        public void delete​(String url,
                   Map<String,​String> headers)
            throws IOException
        Makes an HTTP DELETE request with the given headers.
        Parameters:
        url - The URL to call.
        headers - The headers to send in the request.
        Throws:
        IOException - If there is an error connecting or if there is an HTTP error code.

      • submitRequest

        protected EthosResponse submitRequest​(org.apache.http.client.methods.HttpRequestBase httpRequestBase,
                                      Map<String,​String> headers)
                               throws IOException
        Intended to be used internally by the SDK.

        Submits all HTTP requests.

        Parameters:
        httpRequestBase - The base HTTP request to submit, could be a GET, PUT, POST, or DELETE, etc. request.
        headers - The request headers map. If null, a new map is built to contain the auth token header.
        Returns:
        An EthosResponse built from the response handler.
        Throws:
        IOException - If there is an error connecting or if there is an HTTP error code.

      • getHttpClient

        protected org.apache.http.client.HttpClient getHttpClient()
        Returns the HttpClient built by the httpProtocolClientBuilder. Used primarily by this class.
        Returns:
        the HttpClient used to make Http calls.

      • getAutoRefresh

        public boolean getAutoRefresh()
        Gets the automatic refresh behavior for access tokens.
        Returns:
        the auto refresh status of the token.

      • setAutoRefresh

        public void setAutoRefresh​(boolean autoRefresh)
        Sets the automatic refresh behavior for access tokens.
        Parameters:
        autoRefresh - true if this provider should automatically get a new token before the current one expires, or false if it should let the token expire.

      • getExpirationMinutes

        public int getExpirationMinutes()
        Gets the number of minutes that a new access token will be valid.
        Returns:
        the number of minutes a token is valid before it expires

      • setExpirationMinutes

        public void setExpirationMinutes​(int expirationMinutes)
        Sets the number of minutes that a new access token will be valid.
        Parameters:
        expirationMinutes - The number of minutes before a token should expire. This is required to be an integer between 1 and 120, otherwise an IllegalArgumentException will be thrown.

      • getRegion

        public SupportedRegions getRegion()
        Gets the region to get the data from. This must be one of the supported regions, which can be found in the SupportedRegions enumeration. This is ultimately used to retrieve data from the proper place.
        Returns:
        The region to get data from.

      • setRegion

        public void setRegion​(SupportedRegions region)
        Sets the region to get the data from. This must be one of the supported regions, which can be found in the SupportedRegions enumeration. This is ultimately used to retrieve data from the proper place.
        Parameters:
        region - the region where data will be retrieved from for this session's duration.