Implementing clients that use the Apache Wink REST client

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

About this task

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.

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

You 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, start the public methods of the ClientConfig object.
Note: 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 by 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 value 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 value is 60,000 milliseconds.

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

Procedure

  1. 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();
    
  2. (optional) Modify the default ClientConfig object values that you want to use for the RestClient object.
    • You 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 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 by 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 by using JVM properties. Set the custom JVM properties by using the administrative 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.
  3. (optional) If you use a custom entity provider, add the entity provider by 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);
    
  4. 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);
    
  5. 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(“https://www.example.com/rest/api/book/123”);
    
  6. You can add request headers to the pending request by calling methods on the Resource object.
    You 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(“https://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.
  7. 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(“https://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.
  8. (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 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.