Programming Guide - Web Services Client (RESTful) » History » Revision 5
Revision 4 (chin-yeh, 12/02/2011 04:55 PM) → Revision 5/9 (chin-yeh, 12/02/2011 05:03 PM)
{{toc}}
h1. 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:
* [[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 *request paramater* - it can be a object, string, integer and etc
** *response parameter* - it can be a object, string, integer and etc
** *HTTP method* - POST, GET, PUT, and etc
** *request URL* - http://www.google.com/rest/shopper
# 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]] <code>WebServicesHelper.invoke</code> 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 *request paramater* - it can be a object, string, integer and etc
** *response parameter* - it can be a object, string, integer and etc
** *HTTP method* - POST, GET, PUT, and etc
** *request URL* - http://www.google.com/rest/shopper
** *URL of the asynchronous web services* - the request will first send this URL and then the "forwarder" will forward the request to [[Programming_Guide_-_Web_Services_Client_(RESTful)#Asynschronous-Web-Service-Client|Input Parameter]] section *request URL*
** *callback URL* - this URL will capture the response of the submitted request
** _(optional)_ *mall indicator* - the indicator of the Mall which trigger the request
** _(optional)_ *transaction type* - the type of the request
** _(optional)_ *client transaction ID* - the client unique reference of the request
# 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 <code>WebServicesHelper.persistAndInvoke</code> 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
* com.springsource.org.aopalliance-1.0.0.jar
* commons-codec-1.2.jar
* commons-httpclient-3.1.jar
* commons-lang-2.6.jar
* attachment: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:
* [[General Info:SearchBrowse_artifact|Nexus]]
* download this attachment:web_service_client_libs.zip and put it the *project's library folder*
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 which trigger 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