Package de.aristaflow.ilm.ws.rest.base.service

Class AbstractRestStub.Request

  • Enclosing class:
    AbstractRestStub
    public class AbstractRestStub.Request
extends Object
    A Request represents a request sent to the REST callback and also provides the return value sent via callback response.

    • Field Detail

      • path

        protected final String path
        The context path of the request, that is, the operation which to call.

      • method

        protected final String method
        The HTTP method of the request.

      • headerParams

        protected final Map<String,​List<String>> headerParams
        The headers to be set in the request before sending it.

      • queryParams

        protected final Map<String,​String> queryParams
        The query parameters to be set in the request before sending it.

      • body

        protected String body
        The message body of the request. This may be null.

      • excpRespStatus

        protected final Map<javax.ws.rs.core.Response.StatusType,​Pair<Boolean,​Class<? extends IlmException>>> excpRespStatus
        The expected exceptional responses for specific status types. This maps from status types to the corresponding exception class and whether the response may also be plain text instead of the exception provided as JSON object.

      • excpRespFamily

        protected final Map<javax.ws.rs.core.Response.Status.Family,​Pair<Boolean,​Class<? extends IlmException>>> excpRespFamily
        The expected exceptional responses for specific status families. This maps from status families to the corresponding exception class and whether the response may also be plain text instead of the exception provided as JSON object.

    • Constructor Detail

      • Request

        protected Request​(String path,
                  String method)
        Creates a new request for calling a callback method via REST.
        Parameters:
        path - The context path of the request, that is, the operation which to call.
        method - The HTTP method of the request.

    • Method Detail

      • addHeaderParam

        public AbstractRestStub.Request addHeaderParam​(String name,
                                               String value)
        Add the designated key and value as header to this request.
        Parameters:
        name - The header name.
        value - The header value.
        Returns:
        This request.

      • addQueryParam

        public AbstractRestStub.Request addQueryParam​(String name,
                                              String value)
        Add the designated key and value as query parameter to (the URL of) this request. Both will be escaped for HTML 4.0.
        Parameters:
        name - The query parameter name.
        value - The query parameter value.
        Returns:
        This request.

      • setBody

        public AbstractRestStub.Request setBody​(String value)
        Sets the body of this request to the designated string. This has to be formatted appropriately, e. g. a JSON string.
        Parameters:
        value - The value to be set as body of this request.
        Returns:
        This request.

      • addExceptionalResponse

        public AbstractRestStub.Request addExceptionalResponse​(javax.ws.rs.core.Response.StatusType status,
                                                       boolean allowPlainText,
                                                       Class<? extends IlmException> excpClass)
        Adds the designated response status and the class as expected exception. In case the designated response status is received, the designated exception type will be parsed from the response body.
        Parameters:
        status - The response status which represents the designated exception.
        allowPlainText - Whether a plain text response is allowed (instead of an exception provided as JSON object).
        excpClass - The exception which is expected in case of the designated response status.
        Returns:
        This request.

      • addExceptionalResponse

        public AbstractRestStub.Request addExceptionalResponse​(javax.ws.rs.core.Response.Status.Family family,
                                                       boolean allowPlainText,
                                                       Class<? extends IlmException> excpClass)
        Adds the designated response status and the class as expected exception. In case the designated response status is received, the designated exception type will be parsed from the response body.
        Parameters:
        family - The response status family which represents the the designated exception.
        allowPlainText - Whether a plain text response is allowed (instead of an exception provided as JSON object).
        excpClass - The exception which is expected in case of the designated response status family.
        Returns:
        This request.

      • getVoidResponse

        public void getVoidResponse()
                     throws IlmException,
                            InternalServiceException
        Just waits for the void response, i. e. Response.Status.NO_CONTENT. If the response has a different status or is an exception, an appropriate exception will be thrown.
        Throws:
        IlmException - If the response contains an expected or unexpected response status and the body is an exception conforming to the API, the corresponding IlmException will be parsed from the response body and thrown.
        InternalServiceException - If there are problems creating the request or retrieving the response, an InternalServiceException wrapping an IOException will be thrown; if parsing the response body fails, an InternalServiceException wrapping a WebApplicationException will be thrown.
        See Also:
        getResponse(StatusType, boolean, String, Function)

      • getStringResponse

        public String getStringResponse​(javax.ws.rs.core.Response.StatusType expStatus)
                         throws IlmException,
                                InternalServiceException
        Gets the string response for this request. This expects either a plain string or a simple JSON string in the response body.
        Parameters:
        expStatus - The response status which is expected in case of a string response.
        Returns:
        The string value from the response of this request.
        Throws:
        IlmException - If the response contains an expected or unexpected response status and the body is an exception conforming to the API, the corresponding IlmException will be parsed from the response body and thrown.
        InternalServiceException - If there are problems creating the request or retrieving the response, an InternalServiceException wrapping an IOException will be thrown; if parsing the response body fails, an InternalServiceException wrapping a WebApplicationException will be thrown.
        See Also:
        getResponse(StatusType, boolean, Class)

      • getResponse

        public <T> T getResponse​(javax.ws.rs.core.Response.StatusType expStatus,
                         Class<T> expType)
                  throws IlmException,
                         InternalServiceException
        Gets the response (body) for this request. That is, the request is sent and the corresponding response is handled by interpreting the response code and parsing the response body.
        Use getResponse(StatusType, TypeReference) if you expect a generic type and need the inner type to be handled properly.
        Parameters:
        expStatus - The response status which is expected in case of the response of the designated type.
        expType - The expected type in case of the designated response status. Use null for no expected response body.
        Returns:
        The value of the designated expected type retrieved from the response of this request.
        Throws:
        IlmException - If the response contains an expected or unexpected response status and the body is an exception conforming to the API, the corresponding IlmException will be parsed from the response body and thrown.
        InternalServiceException - If there are problems creating the request or retrieving the response, an InternalServiceException wrapping an IOException will be thrown; if parsing the response body fails, an InternalServiceException wrapping a WebApplicationException will be thrown.
        See Also:
        getResponse(StatusType, boolean, Class)

      • getResponse

        public <T> T getResponse​(javax.ws.rs.core.Response.StatusType expStatus,
                         com.fasterxml.jackson.core.type.TypeReference<T> expType)
                  throws IlmException,
                         InternalServiceException
        Gets the response (body) for this request. That is, the request is sent and the corresponding response is handled by interpreting the response code and parsing the response body.

        Unlike getResponse(StatusType, Class) this handles generic types with inner types properly. For instance new TypeReference<List<Integer>>() { } leads to <List<Integer>> while using List.class will let Jackson guess the inner type according to the received JSON.

        Type Parameters:
        T - The type of the expected response.
        Parameters:
        expStatus - The response status which is expected in case of the response of the designated type.
        expType - The expected type (may be a generic type) in case of the designated response status. Use null for no expected response body.
        Returns:
        The value of the designated expected type retrieved from the response of this request.
        Throws:
        IlmException - If the response contains an expected or unexpected response status and the body is an exception conforming to the API, the corresponding IlmException will be parsed from the response body and thrown.
        InternalServiceException - If there are problems creating the request or retrieving the response, an InternalServiceException wrapping an IOException will be thrown; if parsing the response body fails, an InternalServiceException wrapping a WebApplicationException will be thrown.

      • getResponse

        protected <T> T getResponse​(javax.ws.rs.core.Response.StatusType expStatus,
                            boolean allowPlainText,
                            Class<T> expType)
                     throws IlmException,
                            InternalServiceException
        Gets the response (body) for this request. That is, the request is sent and the corresponding response is handled by interpreting the response code and parsing the response body.
        Parameters:
        expStatus - The response status which is expected in case of the response of the designated type.
        allowPlainText - Whether a plain text response is allowed (instead of a JSON object). This is only useful when expecting String as type.
        expType - The expected type in case of the designated response status. Use null for no expected response body.
        Returns:
        The value of the designated expected type retrieved from the response of this request.
        Throws:
        IlmException - If the response contains an expected or unexpected response status and the body is an exception conforming to the API, the corresponding IlmException will be parsed from the response body and thrown.
        InternalServiceException - If there are problems creating the request or retrieving the response, an InternalServiceException wrapping an IOException will be thrown; if parsing the response body fails, an InternalServiceException wrapping a WebApplicationException will be thrown.

      • getResponse

        protected <T> T getResponse​(javax.ws.rs.core.Response.StatusType expStatus,
                            boolean allowPlainText,
                            String expTypeName,
                            Function<InputStream,​Pair<T,​IOException>> readValue)
                     throws IlmException,
                            InternalServiceException
        Gets the response (body) for this request. That is, the request is sent and the corresponding response is handled by interpreting the response code and parsing the response body.
        Type Parameters:
        T - The type of the expected response.
        Parameters:
        expStatus - The response status which is expected in case of the response of the designated type.
        allowPlainText - Whether a plain text response is allowed (instead of a JSON object). This is only useful when expecting String as type.
        expTypeName - The name of the expected type in case of the designated response status. Use null for no expected response body.
        readValue - A function to read the typed response from the body. This will only be used if the expected type is not null and the received body is JSON. It may return an IOException which will then be actually thrown.
        Returns:
        The value of the designated expected type retrieved from the response of this request.
        Throws:
        IlmException - If the response contains an expected or unexpected response status and the body is an exception conforming to the API, the corresponding IlmException will be parsed from the response body and thrown.
        InternalServiceException - If there are problems creating the request or retrieving the response, an InternalServiceException wrapping an IOException will be thrown; if parsing the response body fails, an InternalServiceException wrapping a WebApplicationException will be thrown.

      • getResponseMediaType

        protected Pair<javax.ws.rs.core.MediaType,​Charset> getResponseMediaType​(HttpURLConnection conn)
        Gets the media type for the response of the designated connection including the corresponding encoding. This will try to retrieve the encoding from the content type and afterwards from the content encoding. If none is found, UTF-8 will be returned.
        Parameters:
        conn - The connection for which to get the encoding for the response.
        Returns:
        The media type and the character set used for the response of the designated connection.

      • readString

        protected String readString​(InputStream is,
                            Charset charset)
                     throws IOException
        Reads a string from the designated input stream using the designated character set. Each read line will be terminated by a line feed (\n).
        Parameters:
        is - The input stream from which to read the string.
        charset - The character set used to read from the stream.
        Returns:
        The string read from the designated input stream.
        Throws:
        IOException - If there are problems reading from the stream, an IOException will be thrown.

      • readExceptionalBody

        protected IlmException readExceptionalBody​(URL url,
                                           int respCode,
                                           boolean excpCode,
                                           String respMsg,
                                           InputStream respBody,
                                           Charset charset,
                                           String expType)
        Tries to read an exception body from the response of the designated URL having the designated (exceptional) response code and message. This either returns the read IlmException or it throws an InternalServiceException wrapping a WebApplicationException.
        Parameters:
        url - The URL from which the response has been returned.
        respCode - The response code.
        excpCode - Whether the response code is an exceptional response code.
        respMsg - The response message.
        respBody - The response body as marked input stream.
        charset - The character set to use for
        expType - The string representation of the expected type which could not be read from the response body so far. This may be null if no expected response body.
        Returns:
        The IlmException that has been read from the designated response body. If this could not be read, an InternalServiceException wrapping a WebApplicationException will be thrown.