Implementing clients using 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 stand-alone 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 used in the JAX-RS server side services are provided with the client.

Avoid trouble Avoid trouble: You can add custom entity providers to the client configuration if the entity providers do not require injection of @javax.ws.rs.core.Context objects.gotcha
To use the Apache Wink REST client that is provided with IBM® JAX-RS, you must add the following JAR files to the client classpath:
  • ibm-jaxrs-wink.jar
  • slf4j-api.jar
  • slf4j-jdk14.jar
  • jsr311-api.jar
  • commons-lang.jar
If the Apache HttpClient Version 4.0 is used as the underlying transport, the following additional JAR files are required on the client classpath:
  • jcl-over-slf4j.jar
  • http-core.jar
  • httpclient.jar
  • commons-codec.jar

See the Apache Wink API documentation for more information about the client classes and methods.

Procedure

  1. Create a org.apache.wink.client.ClientConfig object and call methods on the object to set the configuration of the client.
    public class MyClientApplication {
        public static void main(String args[]) {
             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 a org.apache.wink.client.ApacheHttpClientConfig object instead. You must also include the Apache HTTP client libraries in the classpath.
    public class MyClientApplication {
        public static void main(String args[]) {
             org.apache.wink.client.ClientConfig clientConfig = new org.apache.wink.client.ApacheHttpClientConfig();
            
        }
    }
  2. (optional) If you use a custom entity provider, add the entity provider using the client configuration.
    public class MyClientApplication {
        public static void main(String args[]) {
             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);
        }
    }
  3. Create a org.apache.wink.client.RestClient object with the client configuration.
    public class MyClientApplication {
        public static void main(String args[]) {
             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);
    
        }
    }
  4. Create a org.apache.wink.client.Resource object with a URI from the REST client.
    public class MyClientApplication {
        public static void main(String args[]) {
             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”);
        }
    }
  5. 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 */*.
    public class MyClientApplication {
        public static void main(String args[]) {
             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.
  6. Process the response by using the status code, response headers, or the response message body.
    public class MyClientApplication {
        public static void main(String args[]) {
             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.
  7. (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 stand-alone JAX-RS client using the Apache Wink REST client that can issue requests to a JAX-RS application.




In this information ...


IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic Task topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Sep 6, 2012 5:50:55 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=v610webmob&product=was-nd-mp&topic=twbs_jaxrs_xmlcontent_jaxb
File name: twbs_jaxrs_impl_client_winkrestclient.html