Module com.gluonhq.connect
Package com.gluonhq.connect.provider

Class RestClient

  • public class RestClient
extends Object

    The RestClient assists in using the DataProvider with HTTP URLs as the data source. For instance, to read an object from a sample URL that responds with json, you can use the following code:

         RestClient restClient = RestClient.create()
             .host("http://myhost.com")
             .path("restservice/2/sample/19")
             .method("GET");
     GluonObservableObject<Sample> sample = DataProvider.retrieveObject(restClient.createObjectDataReader(Sample.class));

    • Method Detail

      • create

        public static RestClient create()
        Create a RestClient builder for constructing a RestDataSource or one of the classes that are used in the methods of the DataProvider.
        Returns:
        a RestClient that can be used together with the DataProvider

      • host

        public RestClient host​(String host)
        Sets the complete host address of the URL for the HTTP connection. The host consists of the scheme, the remote host name and the port. If no port is specified, the default scheme port will be used.
        Parameters:
        host - the complete host address of the URL
        Returns:
        A reference to this rest client.
        See Also:
        RestDataSource.setHost(String)

      • path

        public RestClient path​(String path)
        Sets the entire path of the URL for the HTTP connection. A forward slash will automatically be added in front of the provided path if it is missing.
        Parameters:
        path - the entire path of the URL
        Returns:
        A reference to this rest client.
        See Also:
        RestDataSource.setPath(String)

      • method

        public RestClient method​(String method)
        Sets the request method to use for the HTTP connection.
        Parameters:
        method - the request method for the HTTP connection
        Returns:
        A reference to this rest client.
        See Also:
        RestDataSource.setMethod(String)

      • readTimeout

        public RestClient readTimeout​(int readTimeout)
        Sets the read timeout for the HTTP connection, in milliseconds. A timeout of zero is interpreted as an infinite timeout.
        Parameters:
        readTimeout - an int that specifies the timeout value to be used in milliseconds
        Returns:
        A reference to this rest client.
        See Also:
        RestDataSource.setReadTimeout(int)

      • connectTimeout

        public RestClient connectTimeout​(int connectTimeout)
        Sets the connect timeout for the HTTP connection, in milliseconds. A timeout of zero is interpreted as an infinite timeout.
        Parameters:
        connectTimeout - an int that specifies the timeout value to be used in milliseconds
        Returns:
        A reference to this rest client.
        See Also:
        RestDataSource.setConnectTimeout(int)

      • dataString

        public RestClient dataString​(String dataString)
        Sets the entity to use for the HTTP connection. The dataString will be written to the OutputStream of the HTTP connection. Please note, when specifying both a data string and form parameters, the data string will be appended with an ampersand, followed by the encoded list of form parameters.
        Parameters:
        dataString - the entity for the HTTP connection
        Returns:
        A reference to this rest client.
        See Also:
        RestDataSource.setDataString(String)

      • consumerKey

        public RestClient consumerKey​(String consumerKey)
        Sets the consumer key to use for creating the OAuth 1.0 signature that is sent along with the request, by setting the Authorization request header. Setting the consumer secret is mandatory when setting the consumer key.
        Parameters:
        consumerKey - the consumer key used for calculating the OAuth 1.0 signature
        Returns:
        A reference to this rest client.
        See Also:
        RestDataSource.setConsumerKey(String)

      • consumerSecret

        public RestClient consumerSecret​(String consumerSecret)
        Sets the consumer secret to use for creating the OAuth 1.0 signature that is sent along with the request, by setting the Authorization request header. Setting the consumer secret has no effect when the consumer key is not set.
        Parameters:
        consumerSecret - the consumer secret used for calculating the OAuth 1.0 signature
        Returns:
        A reference to this rest client.
        See Also:
        RestDataSource.setConsumerSecret(String)

      • contentType

        public RestClient contentType​(String contentType)
        Sets the Content-Type request header for the HTTP connection. The request header will only be set when either a data string or form parameters were set. In case the content type header was not set, it will by default be set to application/x-www-form-urlencoded.
        Parameters:
        contentType - the Content-Type request header for the HTTP connection
        Returns:
        A reference to this rest client.
        See Also:
        RestDataSource.setContentType(String)

      • header

        public RestClient header​(String field,
                         String value)
        Adds a single HTTP header to the request. NOTE: Headers set using this method will be included in addition to those set via other methods (e.g. by contentType(String)), so to avoid complications you should only set headers here if you haven't set them via any other methods
        Parameters:
        field - The name of the HTTP header field (e.g. "Accept")
        value - The header value to send with the request
        Returns:
        A reference to this rest client.

      • multipartField

        public RestClient multipartField​(String field,
                                 String value)

        Adds a form field to an HTTP Multipart Form-Data request. The content type of the form field will be text/plain.

        Note: the content type needs to be set explicitly to multipart/form-data for the multipart form to be written to the request.

        Parameters:
        field - the name of the form field
        value - the value of the form field
        Returns:
        A reference to this rest client.

      • multipartField

        public RestClient multipartField​(String field,
                                 byte[] value)

        Adds a binary field to an HTTP Multipart Form-Data request. The content type of the binary field will be application/octet-stream.

        Note: the content type needs to be set explicitly to multipart/form-data for the multipart form to be written to the request.

        Parameters:
        field - the name of the form part
        value - the bytes of the form part
        Returns:
        A reference to this rest client.

      • createRestDataSource

        public RestDataSource createRestDataSource()
        Build a RestDataSource that can be used as an InputDataSource to read from or an OutputDataSource to write to the HTTP connection that is created with the parameters specified by this rest client builder.
        Returns:
        A RestDataSource that works with an HTTP connection, created with parameters that are set on this rest client.

      • createObjectDataReader

        public <T> ObjectDataReader<T> createObjectDataReader​(Class<T> targetClass)
        Creates an instance of ObjectDataReader that can be passed directly in the DataProvider.retrieveObject(ObjectDataReader) method. The object data reader will read the data from the HTTP connection provided by the RestDataSource.

        The object data reader will try to detect the converter to use based on the Content-Type response header that is returned from the HTTP connection. The specified targetClass will be passed in to the detected converter where needed. A custom converter can be specified with createObjectDataReader(InputStreamInputConverter) when no suitable converter could be detected.

        Type Parameters:
        T - the type of the object to read
        Parameters:
        targetClass - the class definition of the object to read
        Returns:
        an ObjectDataReader instance that constructs an object from an HTTP connection with an automatically detected converter

      • createObjectDataReader

        public <T> ObjectDataReader<T> createObjectDataReader​(InputStreamInputConverter<T> converter)
        Creates an instance of ObjectDataReader that can be passed directly in the DataProvider.retrieveObject(ObjectDataReader) method. The object data reader will read the data from the HTTP connection provided by the RestDataSource and convert it into an object by using the specified converter.
        Type Parameters:
        T - the type of the object to read
        Parameters:
        converter - the converter to use to convert the data read from the HTTP connection into an object
        Returns:
        an ObjectDataReader instance that constructs an object from an HTTP connection with the specified converter

      • createObjectDataWriter

        public <T> ObjectDataWriter<T> createObjectDataWriter​(Class<T> targetClass)
        Creates an instance of ObjectDataWriter that can be passed directly in the DataProvider.storeObject(Object, ObjectDataWriter) method. The object data writer will try to detect the output converter to use based on the Content-Type request header that was set. The specified targetClass will be passed in to the detected converter where needed. A custom output converter can be specified with createObjectDataWriter(OutputStreamOutputConverter, InputStreamInputConverter) when no suitable converter could be detected. If an output converter could be found, the writer will convert an object by using the detected converter and writes the converted data to the OutputStream of the HTTP connection that is provided by the RestDataSource.

        The ObjectDataWriter also returns an optional object. In case of the RestClient, the returned object will be read from the response of the HTTP request. The object data reader will try to detect the input converter to use based on the Content-Type response header that is returned from the HTTP connection. The specified targetClass will be passed in to the detected input converter as well where needed. The reader will then use the input converter to convert the read bytes from the response of the HTTP request into an object.

        Type Parameters:
        T - the type of the object to write
        Parameters:
        targetClass - the class definition of the object to write
        Returns:
        an ObjectDataWriter instance that writes an object into an HTTP connection with an automatically detected output converter and that constructs an object from that HTTP connection with an automatically detected input converter

      • createObjectDataWriter

        public <T> ObjectDataWriter<T> createObjectDataWriter​(OutputStreamOutputConverter<T> outputConverter,
                                                      InputStreamInputConverter<T> inputConverter)
        Creates an instance of ObjectDataWriter that can be passed directly in the DataProvider.storeObject(Object, ObjectDataWriter) method. The object data writer will convert an object by using the specified output converter and writes the converted data to the OutputStream of the HTTP connection that is provided by the RestDataSource.

        The ObjectDataWriter also returns an optional object. In case of the RestClient, the returned object will be read from the response of the HTTP request. The object data reader will use the specified input converter to convert the read bytes from the response of the HTTP request into an object.

        Type Parameters:
        T - the type of the object to write
        Parameters:
        outputConverter - the output converter to use to convert the object into data to write to the HTTP connection
        inputConverter - the input converter to use to convert the data read from the HTTP connection into an object
        Returns:
        an ObjectDataWriter instance that writes an object into an HTTP connection with the specified outputConverter and that constructs an object from the HTTP connection response with the specified inputConverter

      • createObjectDataRemover

        public <T> ObjectDataRemover<T> createObjectDataRemover​(Class<T> targetClass)
        Creates an instance of ObjectDataRemover that can be passed directly in the DataProvider.removeObject(GluonObservableObject, ObjectDataRemover) method. See the documentation for the createObjectDataWriter(Class) method, as the writer works exactly the same as the remover.
        Type Parameters:
        T - the type of the object to remove
        Parameters:
        targetClass - the class definition of the object to remove
        Returns:
        an ObjectDataRemover instance that writes an object into an HTTP connection with the specified outputConverter and that constructs an object from the HTTP connection response with the specified inputConverter

      • createListDataReader

        public <E> ListDataReader<E> createListDataReader​(Class<E> targetClass)
        Creates an instance of ListDataReader that can be passed directly in the DataProvider.retrieveList(ListDataReader) method. The list data reader will read the data from the HTTP connection provided by the RestDataSource.

        The list data reader will try to detect the converter to use based on the Content-Type response header that is returned from the HTTP connection. The specified targetClass will be passed in to the detected converter where needed. A custom converter can be specified with createListDataReader(InputStreamIterableInputConverter) when no suitable converter could be detected.

        Type Parameters:
        E - the type of the objects contained in the list to read
        Parameters:
        targetClass - the class definition of the objects contained in the list
        Returns:
        a ListDataReader instance that constructs a list of objects from the HTTP connection with an automatically detected converter

      • createListDataReader

        public <E> ListDataReader<E> createListDataReader​(InputStreamIterableInputConverter<E> converter)
        Creates an instance of ListDataReader that can be passed directly in the DataProvider.retrieveList(ListDataReader) method. The list data reader will read the data from the HTTP connection provided by the RestDataSource and converts it into a list of objects by using the specified converter.
        Type Parameters:
        E - the type of the objects contained in the list to read
        Parameters:
        converter - the converter to use to convert the data read from the HTTP connection into a list of objects
        Returns:
        a ListDataReader instance that constructs a list of objects from the HTTP connection with the specified converter