QConnector

{{toc}}

h1. Programming Guide - Web Services Client (RESTful)

This guide describes how to develop the client for RESTful-based web services. And, it's applicable to *Java project* and *Java Web Application project*.

There are 2 types of web services client:

* [[Programming_Guide_-_Web_Services_Client_(RESTful)#Step-By-Step|Synchronous based]] - the client invoke the request and get the response in the *same session*

* [[Programming_Guide_-_Web_Services_Client_(RESTful)#Step-By-Step|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:

!rest_json_with_queue.png!

h2. Step-By-Step

Assume that you have setup the [[General Info:Setup Development Environment|Eclipse environment]].

This section contains 2 parts:

* Web Services Client

* Web Services Client (Asynchronous)

** Callback of Web Services Invocation

h3. Web Services Client

# launch *Eclipse*

# 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

# import all of the [[Programming_Guide_-_Web_Services_Client_(RESTful)#Project-Dependencies|dependencies]] into the project 

# obtain the following information from the web service provider:

** refer to [[Programming_Guide_-_Web_Services_Client_(RESTful)#Synchronous-Web-Service-Client|Input Parameter]] section

# use those information to construct the <code>WebServicesRequest<E, T></code> request object, for example:

<pre>

<code class="JAVA">

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");

</code>

</pre>

** <code>E</code> - is the *type* of the request entity, e.g. <code>MemberInfo</code>

** <code>T</code> - is the *type* of the response entity, e.g. <code>Boolean</code>

*** note: if the request entity is *empty* or not needed, just pass in an empty <code>String</code> object, *not null*, e.g.:

<pre>

<code class="JAVA">

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

</code>

</pre>

# after constructed request object, pass it on to the [[Programming_Guide_-_Web_Services_Client_(RESTful)#Synchronous-Web-Service-Client|WebServicesHelper.invoke]] method.

<pre>

<code class="JAVA">

WebServicesRequest<MemberInfo, Boolean> request = createRegisterMemberRequest();

Boolean response = WebServicesHelper.invoke(request);

</code>

</pre>

# done

h3. Web Services Client (Asynchronous)

> See also [[Programming_Guide_-_Web_Services_Client_(RESTful)#Web-Services-Client|Web Services Client]]

_Web Service Client_

# launch *Eclipse*

# 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

# import all of the [[Programming_Guide_-_Web_Services_Client_(RESTful)#Project-Dependencies|dependencies]] into the project 

# obtain the following information from the web service provider:

** refer to [[Programming_Guide_-_Web_Services_Client_(RESTful)#Asynschronous-Web-Service-Client|Input Parameter]] section

# use those information to construct the <code>AsyncWebServicesRequest<E, T></code> request object, for example:

<pre>

<code class="JAVA">

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");

</code>

</pre>

** <code>E</code> - is the *type* of the request entity, e.g. <code>MemberInfo</code>

** <code>T</code> - is the *type* of the response entity, e.g. <code>Boolean</code>

*** note: if the request entity is *empty* or not needed, just pass in an empty <code>String</code> object, *not null*, e.g.:

<pre>

<code class="JAVA">

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

</code>

</pre>

# after constructed request object, pass it on to the [[Programming_Guide_-_Web_Services_Client_(RESTful)#Asynschronous-Web-Service-Client|WebServicesHelper.persistAndInvoke]] method.

<pre>

<code class="JAVA">

Connection connection = createDbConnection();

try {

	WebServicesHelper.persistAndInvoke(connection, request);

} finally {

	if (connection != null) {

		connection.close();

	}

}

</code>

</pre>

** *an established database connection is needed* because the request will be stored into database before it actually get processed

# *proceed to the next part* to develop the callback component, which will be used to capture the response of the submitted request

_Callback component_

# 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

# after confirmed where to place the component, create a *servlet* or *JSP* and include the following codes:

<pre>

<code class="JAVA">

WebServicesHelper.updateEventLogStatus(connection, request);

</code>

</pre>

** *connection* - an established database connection. release it after used

** *request* - <code>an HTTPServletRequest</code> object

# this newly created *servlet/JSP* will be used as a *callback URL* for the application

# done

h2. Project Dependencies

Refer to [[Deployment Guide - connector-client-utils]]

h1. API Reference

h2. Synchronous Web Service Client

_Method Signature:_

<pre>

<code class="JAVA">

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

</code>

</pre>

h3. Input Parameter

* *request* - the request object consists of

** <code>E</code> - the type of the request entity

** <code>T</code> - the type of the response entity

** *requestEntity* - the request entity, it can be a <code>String</code> or <code>Object</code>

** *requestUrl* - the URL of the web service

** *httpMethod* - either <code>POST</code>, <code>GET</code>, <code>PUT</code> and etc.

** *responseType* - the type of the response entity, it can be a <code>String</code> or <code>Object</code>

h3. Output Parameter

based on the provided input fields

h2. Asynschronous Web Service Client

_Method Signature:_

<pre>

<code class="JAVA">

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

			AsyncWebServicesRequest<E, T> request)

</code>

</pre>

h3. Input Parameter

* *request* - the request object consists of

** <code>E</code> - the type of the request entity

** <code>T</code> - the type of the response entity

** *connection* - an established database connection. release it after done

** *requestEntity* - the request entity, it can be a <code>String</code> or <code>Object</code>

** *requestUrl* - the URL of the web service

** *httpMethod* - either <code>POST</code>, <code>GET</code>, <code>PUT</code> and etc.

** *responseType* - the type of the response entity, it can be a <code>String</code> or <code>Object</code>

** *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

h3. Output Parameter

based on the provided input fields