• Table of contents
• Programming Guide - Web Services Client (RESTful)
  • Step-By-Step
    • Web Services Client
    • Web Services Client (Asynchronous)
  • Project Dependencies
• API Reference
  • Synchronous Web Service Client
    • Input Parameter
    • Output Parameter
  • Asynschronous Web Service Client
    • Input Parameter
    • Output Parameter

Programming Guide - Web Services Client (RESTful)¶

This guide describes how to develop the client for RESTful-based web services. And, it can be used in Java project and Java Web Application project.

There are 2 types of web services client:

• Synchronous based - the client invoke the request and get the response in the same session
• Asynchronous based - the client invoke the request and get the response via the callback method (2 different sessions)

Refer to the below diagram to have a better understanding how the Web Services works:

Step-By-Step¶

Assume that you have setup the Eclipse environment.

This section contains 2 parts:

• Web Services Client
• Web Services Client (Asynchronous)
  • Callback of Web Services Invocation

Web Services Client¶

1. launch Eclipse
2. you can either:
   • create a new Java Project, or
     • JDK compiler compliance version should set to 5.0 or above
   • create a new Dynamic Web Project, or
     • Dynamic web module version should set to 2.4 or above
     • JDK compiler compliance version should set to 5.0 or above
   • use the existing project
     • JDK compiler compliance version should set to 5.0 or above
3. import all of the dependencies into the project
4. obtain the following information from the web service provider:
   • refer to Input Parameter section
5. use those information to construct the WebServicesRequest<E, T> request object, for example:
   

   WebServicesRequest<MemberInfo, Boolean> request = new WebServicesRequest<MemberInfo, Boolean>(
                       memberInfo, Boolean.class);
   request.setHttpMethod(HttpMethod.POST);
   request.setRequestUrl("http://foo.bar.com/webapp/reg-services/shopper");
   
   

   • E - is the type of the request entity, e.g. MemberInfo
   • T - is the type of the response entity, e.g. Boolean
     • note: if the request entity is empty or not needed, just pass in an empty String object, not null, e.g.:
       

       WebServicesRequest<String, MemberInfo> request = new WebServicesRequest<String, MemberInfo>("", MemberInfo.class);
       
       

6. after constructed request object, pass it on to the WebServicesHelper.invoke method.
   

   WebServicesRequest<MemberInfo, Boolean> request = createRegisterMemberRequest();
   
   Boolean response = WebServicesHelper.invoke(request);
   
   

7. done

Web Services Client (Asynchronous)¶

See also Web Services Client

Web Service Client

1. launch Eclipse
2. you can either:
   • create a new Java Project, or
     • JDK compiler compliance version should set to 5.0 or above
   • create a new Dynamic Web Project, or
     • Dynamic web module version should set to 2.4 or above
     • JDK compiler compliance version should set to 5.0 or above
   • use the existing project
     • JDK compiler compliance version should set to 5.0 or above
3. import all of the dependencies into the project
4. obtain the following information from the web service provider:
   • refer to Input Parameter section
5. use those information to construct the AsyncWebServicesRequest<E, T> request object, for example:
   

   AsyncWebServicesRequest<MemberInfo, Boolean> request = new AsyncWebServicesRequest<MemberInfo, Boolean>(ASYNC_WS_URL,
                       memberInfo, Boolean.class);
   request.setHttpMethod(HttpMethod.POST);
   request.setRequestUrl("http://foo.bar.com/reg-services/shopper");
   request.setCallbackUrl("http://192.168.2.68:8080/dummy-mall/callback.jsp");
   request.setMallIndicator("840");
   request.setTrxType("MEMBER REGISTRATION");
   request.setClientTrxId("REG-123");
   
   

   • E - is the type of the request entity, e.g. MemberInfo
   • T - is the type of the response entity, e.g. Boolean
     • note: if the request entity is empty or not needed, just pass in an empty String object, not null, e.g.:
       

       AsyncWebServicesRequest<String, MemberInfo> request = new AsyncWebServicesRequest<String, MemberInfo>(ASYNC_WS_URL, "", MemberInfo.class);
       
       

6. after constructed request object, pass it on to the WebServicesHelper.persistAndInvoke method.
   

   Connection connection = createDbConnection();
   try {
       WebServicesHelper.persistAndInvoke(connection, request);
   } finally {
       if (connection != null) {
           connection.close();
       }
   }
   
   

   • an established database connection is needed because the request will be stored into database before it actually get processed
7. proceed to the next part to develop the callback component, which will be used to capture the response of the submitted request

Callback component

1. this component must be placed
   • in the web application and,
   • use the same database connection as the one that used in the application which triggered request and,
   • accepts HTTP POST method
2. after confirmed where to place the component, create a servlet or JSP and include the following codes:
   

   WebServicesHelper.updateEventLogStatus(connection, request);
   
   

   • connection - an established database connection. release it after used
   • request - an HTTPServletRequest object
3. this newly created servlet/JSP will be used as a callback URL for the application
4. done

Project Dependencies¶

• com.springsource.org.aopalliance-1.0.0.jar
• commons-codec-1.2.jar
• commons-httpclient-3.1.jar
• commons-lang-2.6.jar
• connector-client-utils.jar
• jcl-over-slf4j-1.6.1.jar
• org.springframework.aop-3.0.5.RELEASE.jar
• org.springframework.asm-3.0.5.RELEASE.jar
• org.springframework.beans-3.0.5.RELEASE.jar
• org.springframework.context.support-3.0.5.RELEASE.jar
• org.springframework.context-3.0.5.RELEASE.jar
• org.springframework.core-3.0.5.RELEASE.jar
• org.springframework.expression-3.0.5.RELEASE.jar
• org.springframework.web.servlet-3.0.5.RELEASE.jar
• org.springframework.web-3.0.5.RELEASE.jar
• slf4j-api-1.6.1.jar
• jackson-core-asl-1.9.0.jar
• jackson-jaxrs-1.9.0.jar
• jackson-mapper-asl-1.9.0.jar
• servlet-api-2.4.jar
• commons-io-2.1.jar

These dependencies can be found in:

• Nexus
• download this web_service_client_libs.zip and put it the project's library folder

API Reference¶

Synchronous Web Service Client¶

Method Signature:

public static <E, T> T invoke(WebServicesRequest<E, T> request)

Input Parameter¶

• request - the request object consists of
  • E - the type of the request entity
  • T - the type of the response entity
  • requestEntity - the request entity, it can be a String or Object
  • requestUrl - the URL of the web service
  • httpMethod - either POST, GET, PUT and etc.
  • responseType - the type of the response entity, it can be a String or Object

Output Parameter¶

based on the provided input fields

Asynschronous Web Service Client¶

Method Signature:

public static <E, T> void persistAndInvoke(Connection connection,
            AsyncWebServicesRequest<E, T> request)

Input Parameter¶

• request - the request object consists of
  • E - the type of the request entity
  • T - the type of the response entity
  • connection - an established database connection. release it after done
  • requestEntity - the request entity, it can be a String or Object
  • requestUrl - the URL of the web service
  • httpMethod - either POST, GET, PUT and etc.
  • responseType - the type of the response entity, it can be a String or Object
  • asyncWebServiceUrl - the request will first send this URL and then the "forwarder" will forward the request to request URL
  • callback URL - this URL will capture the response of the submitted request
  • (optional) mall indicator - the indicator of the Mall in which triggered the request
  • (optional) transaction type - the type of the request
  • (optional) client transaction ID - the client unique reference of the request

Output Parameter¶

based on the provided input fields