Implement clients using the Apache Wink REST client

Network Deployment (Distributed operating systems), v8.0 > Develop and deploying applications > Develop web services - RESTful services > Develop JAX-RS web applications

Implement clients using the Apache Wink REST client

We can use the Apache Wink REST client to send requests and process responses from RESTful services. We can 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 Java Virtual Machine (JVM) properties.
To implement an Apache Wink REST client, you must first create an org.apache.wink.client.ClientConfig object that is then used to construct an org.apache.wink.client.RestClient. You can change the configuration settings for the RestClient object programmatically, or you can use JVM properties to modify the default ClientConfig object values.
To configure the configuration settings for the RestClient object programmatically, invoke 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, you 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 zero (0) means that the client waits for an unlimited amount of time and will not timeout.
The default value is 60,000 milliseconds.

wink.client.connectTimeout

This property specifies how long the RestClient object waits (in milliseconds) before timing out when attempting to connect to the target resource. A value of zero (0) means that the client waits for an unlimited amount of time and will not timeout.
The default value is 60,000 milliseconds.

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

Procedure
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 you use an Apache HTTP client as the underlying transport, create and use an org.apache.wink.client.ApacheHttpClientConfig object instead. We must also include the Apache HTTP client libraries in the classpath. 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, invoke the public methods of the ClientConfig object; for example:
clientConfig.connectTimeout(30000);
clientConfig.readTimeout(30000);
If you are using the Thin Client for JAX-RS in a stand-alone unmanaged client runtime environment, you 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 you are not using the Thin Client for JAX-RS as a stand-alone client runtime environment, but you are using the RestClient object in an application that is intended for installation on the application server, you can optionally modify the configuration settings for the RestClient object using JVM properties. Set the custom JVM properties using the admin console for your REST client code that is running within an application that is 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 you 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, you 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 by 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, you 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 your client, you can choose to manage the appropriate HTTP headers yourself, or more simply, you 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.
Results

You 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 client
Secure JAX-RS applications within the web container

Related

Java virtual machine custom properties

+
Search Tips | Advanced Search