Implement clients that use the Apache Wink REST client

Implement clients that use the Apache Wink REST client

Use the Apache Wink REST client to send requests and process responses from RESTful services. Use the client API in Java programs to communicate with web services.

By default, the Apache Wink client uses the java.net.HttpURLConnection class from the Java runtime environment for issuing requests and processing responses. The Apache Wink client can also use Apache HttpClient 4.0 as the underlying client transport.

We can also use JAX-RS entity providers to help serialize request entities or deserialize response entities. The standard JAX-RS providers used in the JAX-RS server-side services are provided with the client.

We can configure the Apache Wink REST client programmatically or by setting JVM properties.

To implement an Apache Wink REST client, first create an org.apache.wink.client.ClientConfig object that is then used to construct an org.apache.wink.client.RestClient. We can change the configuration settings for the RestClient object programmatically, or we can use JVM properties to modify the default ClientConfig object values.

To configure the configuration settings for the RestClient object programmatically, start the public methods of the ClientConfig object.
After a ClientConfig object is used to construct a RestClient object, the ClientConfig object can no longer be modified. Attempting to do so results in an org.apache.wink.client.ClientConfigException error message.
Alternatively, we can configure the configuration settings for the RestClient object using JVM properties to modify the default ClientConfig object values. Use the following JVM properties to modify the default ClientConfig object values:

wink.client.readTimeout

This property specifies how long the RestClient object waits (in milliseconds) for a response to requests before timing out. A value of 0 means that the client waits for an unlimited amount of time and will not timeout.

The default is 60,000 milliseconds.

wink.client.connectTimeout

This property specifies how long the RestClient object waits (in milliseconds) before it times out while attempting to connect to the target resource. A value of 0 means that the client waits for an unlimited amount of time and will not timeout.

The default is 60,000 milliseconds.

We can programmatically alter any values for the RestClient object specified using JVM properties. The programmatic values take precedence over any JVM property values.

Tasks
Create an org.apache.wink.client.ClientConfig object.
The following code snippet illustrates how to create an org.apache.wink.client.ClientConfig object:
org.apache.wink.client.ClientConfig clientConfig = new org.apache.wink.client.ClientConfig();
.
If we use an Apache HTTP client as the underlying transport, create and use an org.apache.wink.client.ApacheHttpClientConfig object instead. The following code snippet illustrates how to create an org.apache.wink.client.ApacheHttpClientConfig object:
org.apache.wink.client.ClientConfig clientConfig = new org.apache.wink.client.ApacheHttpClientConfig();
(optional) Modify the default ClientConfig object values to use for the RestClient object.
We can optionally modify the default configuration settings for the RestClient object programmatically. To specify the configuration settings for the RestClient object programmatically, start the public methods of the ClientConfig object; for example:
clientConfig.connectTimeout(30000);
clientConfig.readTimeout(30000);
If we are using the Thin Client for JAX-RS in a stand-alone unmanaged client runtime environment, we can optionally modify the configuration settings for the RestClient object using JVM properties. Set the custom JVM properties on the JVM under which the thin client is running.
If we are not using the Thin Client for JAX-RS as a stand-alone client runtime environment, but we are using the RestClient object in an application intended for installation on the application server, we can optionally modify the configuration settings for the RestClient object using JVM properties. Set the custom JVM properties using the administrative console for our REST client code running within an application installed on the application server. See the Java virtual machine custom properties information for details on using the administrative console to set these custom JVM properties.
(optional) If we use a custom entity provider, add the entity provider using the client configuration.
org.apache.wink.client.ClientConfig clientConfig = new org.apache.wink.client.ClientConfig();

javax.ws.rs.core.Application app = new javax.ws.rs.core.Application() {
       public Set<Class<?>> getClasses() {
           Set<Class<?>> classes = new HashSet<Class<?>>();
           classes.add(MyCustomEntityProvider.class);
           return classes;
       }
};
clientConfig.applications(app);
Create a org.apache.wink.client.RestClient object with the client configuration.
org.apache.wink.client.ClientConfig clientConfig = new org.apache.wink.client.ClientConfig();

javax.ws.rs.core.Application app = new javax.ws.rs.core.Application() {
       public Set<Class<?>> getClasses() {
           Set<Class<?>> classes = new HashSet<Class<?>>();
           classes.add(MyCustomEntityProvider.class);
           return classes;
       }
};
clientConfig.applications(app);

org.apache.wink.client.RestClient client = new org.apache.wink.client.RestClient(clientConfig);
Create a org.apache.wink.client.Resource object with a URI from the REST client.
org.apache.wink.client.ClientConfig clientConfig = new org.apache.wink.client.ClientConfig();

javax.ws.rs.core.Application app = new javax.ws.rs.core.Application() {
       public Set<Class<?>> getClasses() {
           Set<Class<?>> classes = new HashSet<Class<?>>();
           classes.add(MyCustomEntityProvider.class);
           return classes;
       }
};
clientConfig.applications(app);

org.apache.wink.client.RestClient client = new org.apache.wink.client.RestClient(clientConfig);

org.apache.wink.client.Resource resource = client.resource("http://www.example.com/rest/api/book/123");
We can add request headers to the pending request by calling methods on the Resource object.
We can call a Java method such as post() with the request content as a parameter to send the request. In the following example, an HTTP POST request is made with a Content-Type header value of text/plain and an Accept header value of */*.
org.apache.wink.client.ClientConfig clientConfig = new org.apache.wink.client.ClientConfig();

javax.ws.rs.core.Application app = new javax.ws.rs.core.Application() {
       public Set<Class<?>> getClasses() {
           Set<Class<?>> classes = new HashSet<Class<?>>();
           classes.add(MyCustomEntityProvider.class);
           return classes;
       }
};
clientConfig.applications(app);

org.apache.wink.client.RestClient client = new org.apache.wink.client.RestClient(clientConfig);

org.apache.wink.client.Resource resource = client.resource("http://www.example.com/rest/api/book/123");

ClientResponse response = resource.contentType("text/plain").accept("*/*").post("The request body as a string");
Instead of calling resource.post("The request body as a string") with a String object, we can use any other object that has a class with a valid javax.ws.rs.ext.MessageBodyWriter object such as a JAXB annotated class, a byte[], or a custom class that has a custom entity provider.
Process the response using the status code, response headers, or the response message body.
org.apache.wink.client.ClientConfig clientConfig = new org.apache.wink.client.ClientConfig();

javax.ws.rs.core.Application app = new javax.ws.rs.core.Application() {
       public Set<Class<?>> getClasses() {
           Set<Class<?>> classes = new HashSet<Class<?>>();
           classes.add(MyCustomEntityProvider.class);
           return classes;
       }
};
clientConfig.applications(app);

org.apache.wink.client.RestClient client = new org.apache.wink.client.RestClient(clientConfig);

org.apache.wink.client.Resource resource = client.resource("http://www.example.com/rest/api/book/123");

ClientResponse response = resource.contentType("text/plain").accept("*/*").post("The request body as a string");
    
System.out.println("The response code is: " + response.getStatusCode());
System.out.println("The response message body is: " + response.getEntity(String.class));
Instead of calling the response.getEntity(String.class) object with String.class file, we can use any other class that has a valid javax.ws.rs.ext.MessageBodyReader object, such as a JAXB annotated class, a byte[], or a custom class that has a custom entity provider.
(optional) Configure the client to transmit basic authentication security tokens. To configure basic authentication for the client, we can choose to manage the appropriate HTTP headers ourself, or we can use the provided BasicAuthSecurityHandler handler class. The BasicAuthSecurityHandler class simplifies the enablement of basic authentication in the Wink client application. To learn more about using the security client handler to perform basic HTTP authentication, see the securing JAX-RS applications within the web container information.
We have implemented a JAX-RS client using the Apache Wink REST client that can issue requests to a JAX-RS application.

Use the Apache Wink REST client inside server applications to issue requests
Implement a client using the unmanaged RESTful web services JAX-RS 1.1 client
Secure JAX-RS applications within the web container
Java virtual machine custom properties