Project

General

Profile

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