Project

General

Profile

Programming Guide - Web Services Client (RESTful) » History » Version 3

chin-yeh, 12/02/2011 04:52 PM

1 1 chin-yeh
{{toc}}
2
3
h1. Programming Guide - Web Services Client (RESTful)
4
5
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*.
6
7
There are 2 types of web services client:
8
* [[Programming_Guide_-_Web_Services_Client_(RESTful)#Step-By-Step|Synchronous based]] - the client invoke the request and get the response in the *same session*
9
* [[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)_
10
11 2 chin-yeh
Refer to the below diagram to have a better understanding how the Web Services works:
12
!rest_json_with_queue.png!
13 1 chin-yeh
14
h2. Step-By-Step
15
16
Assume that you have setup the [[General Info:Setup Development Environment|Eclipse environment]].
17
18
This section contains 2 parts:
19
* Web Services Client
20
* Web Services Client (Asynchronous)
21
** Callback of Web Services Invocation
22
23
h3. Web Services Client
24
25
# launch *Eclipse*
26
# you can either:
27
** create a new *Java Project*, or
28
*** _JDK_ compiler compliance version should set to _5.0_ or above
29
** create a new *Dynamic Web Project*, or
30
*** _Dynamic web module version_ should set to _2.4_ or above
31
*** _JDK_ compiler compliance version should set to _5.0_ or above
32
** use the existing project
33
*** _JDK_ compiler compliance version should set to _5.0_ or above
34
# import all of the [[Programming_Guide_-_Web_Services_Client_(RESTful)#Project-Dependencies|dependencies]] into the project 
35
# obtain the following information from the web service provider:
36
** *request paramater* - it can be a object, string, integer and etc
37
** *response parameter* - it can be a object, string, integer and etc
38
** *HTTP method* - POST, GET, PUT, and etc
39
** *request URL* - http://www.google.com/rest/shopper
40
# use those information to construct the <code>WebServicesRequest<E, T></code> request object, for example:
41
<pre>
42
<code class="JAVA">
43
WebServicesRequest<MemberInfo, Boolean> request = new WebServicesRequest<MemberInfo, Boolean>(
44
					memberInfo, Boolean.class);
45
request.setHttpMethod(HttpMethod.POST);
46
request.setRequestUrl("http://foo.bar.com/webapp/reg-services/shopper");
47
</code>
48
</pre>
49
** <code>E</code> - is the *type* of the request entity, e.g. <code>MemberInfo</code>
50
** <code>T</code> - is the *type* of the response entity, e.g. <code>Boolean</code>
51
*** note: if the request entity is *empty* or not needed, just pass in an empty <code>String</code> object, *not null*, e.g.:
52
<pre>
53
<code class="JAVA">
54
WebServicesRequest<String, MemberInfo> request = new WebServicesRequest<String, MemberInfo>("", MemberInfo.class);
55
</code>
56
</pre>
57
# after constructed request object, pass it on to the <code>WebServicesHelper.invoke</code> method.
58
<pre>
59
<code class="JAVA">
60
WebServicesRequest<MemberInfo, Boolean> request = createRegisterMemberRequest();
61
		
62
Boolean response = WebServicesHelper.invoke(request);
63
</code>
64
</pre>
65
# done
66
67
h3. Web Services Client (Asynchronous)
68
69
> See also [[Programming_Guide_-_Web_Services_Client_(RESTful)#Web-Services-Client|Web Services Client]]
70
71
_Web Service Client_
72
# launch *Eclipse*
73
# you can either:
74
** create a new *Java Project*, or
75
*** _JDK_ compiler compliance version should set to _5.0_ or above
76
** create a new *Dynamic Web Project*, or
77
*** _Dynamic web module version_ should set to _2.4_ or above
78
*** _JDK_ compiler compliance version should set to _5.0_ or above
79
** use the existing project
80
*** _JDK_ compiler compliance version should set to _5.0_ or above
81
# import all of the [[Programming_Guide_-_Web_Services_Client_(RESTful)#Project-Dependencies|dependencies]] into the project 
82
# obtain the following information from the web service provider:
83
** *request paramater* - it can be a object, string, integer and etc
84
** *response parameter* - it can be a object, string, integer and etc
85
** *HTTP method* - POST, GET, PUT, and etc
86
** *request URL* - http://www.google.com/rest/shopper
87
** *URL of the asynchronous web services* - the request will first send this URL and then the "forwarder" will forward the request to *request URL*
88
** *callback URL* - this URL will capture the response of the submitted request
89
** _(optional)_ *mall indicator* - the indicator of the Mall which trigger the request
90
** _(optional)_ *transaction type* - the type of the request
91
** _(optional)_ *client transaction ID* - the client unique reference of the request
92
# use those information to construct the <code>AsyncWebServicesRequest<E, T></code> request object, for example:
93
<pre>
94
<code class="JAVA">
95
AsyncWebServicesRequest<MemberInfo, Boolean> request = new AsyncWebServicesRequest<MemberInfo, Boolean>(ASYNC_WS_URL,
96
					memberInfo, Boolean.class);
97
request.setHttpMethod(HttpMethod.POST);
98
request.setRequestUrl("http://foo.bar.com/reg-services/shopper");
99
request.setCallbackUrl("http://192.168.2.68:8080/dummy-mall/callback.jsp");
100
request.setMallIndicator("840");
101
request.setTrxType("MEMBER REGISTRATION");
102
request.setClientTrxId("REG-123");
103
</code>
104
</pre>
105
** <code>E</code> - is the *type* of the request entity, e.g. <code>MemberInfo</code>
106
** <code>T</code> - is the *type* of the response entity, e.g. <code>Boolean</code>
107
*** note: if the request entity is *empty* or not needed, just pass in an empty <code>String</code> object, *not null*, e.g.:
108
<pre>
109
<code class="JAVA">
110
AsyncWebServicesRequest<String, MemberInfo> request = new AsyncWebServicesRequest<String, MemberInfo>(ASYNC_WS_URL, "", MemberInfo.class);
111
</code>
112
</pre>
113
# after constructed request object, pass it on to the <code>WebServicesHelper.persistAndInvoke</code> method.
114
<pre>
115
<code class="JAVA">
116
Connection connection = createDbConnection();
117
try {
118
	WebServicesHelper.persistAndInvoke(connection, request);
119
} finally {
120
	if (connection != null) {
121
		connection.close();
122
	}
123
}
124
</code>
125
</pre>
126
** *an established database connection is needed* because the request will be stored into database before it actually get processed
127
# *proceed to the next part* to develop the callback component, which will be used to capture the response of the submitted request
128
129
_Callback component_
130
# this component must be placed 
131
** in the *web application* and, 
132
** use the same *database connection* as the one that used in the application which triggered request and,
133
** accepts HTTP *POST*  method
134
# after confirmed where to place the component, create a *servlet* or *JSP* and include the following codes:
135
<pre>
136
<code class="JAVA">
137
WebServicesHelper.updateEventLogStatus(connection, request);
138
</code>
139
</pre>
140
** *connection* - an established database connection. release it after used
141
** *request* - <code>an HTTPServletRequest</code> object
142
# this newly created *servlet/JSP* will be used as a *callback URL* for the application
143
# done
144
145
h2. Project Dependencies
146
147
* com.springsource.org.aopalliance-1.0.0.jar
148
* commons-codec-1.2.jar
149
* commons-httpclient-3.1.jar
150
* commons-lang-2.6.jar
151
* attachment:connector-client-utils.jar
152
* jcl-over-slf4j-1.6.1.jar
153
* org.springframework.aop-3.0.5.RELEASE.jar
154
* org.springframework.asm-3.0.5.RELEASE.jar
155
* org.springframework.beans-3.0.5.RELEASE.jar
156
* org.springframework.context.support-3.0.5.RELEASE.jar
157
* org.springframework.context-3.0.5.RELEASE.jar
158
* org.springframework.core-3.0.5.RELEASE.jar
159
* org.springframework.expression-3.0.5.RELEASE.jar
160
* org.springframework.web.servlet-3.0.5.RELEASE.jar
161
* org.springframework.web-3.0.5.RELEASE.jar
162
* slf4j-api-1.6.1.jar
163
* jackson-core-asl-1.9.0.jar
164
* jackson-jaxrs-1.9.0.jar
165
* jackson-mapper-asl-1.9.0.jar
166
* servlet-api-2.4.jar
167
* commons-io-2.1.jar
168
169
These dependencies can be found in:
170
* [[General Info:SearchBrowse_artifact|Nexus]]
171
* download this attachment:web_service_client_libs.zip and put it the *project's library folder*
172
173
174
h1. API Reference
175 3 chin-yeh
176
h2. Synchronous Web Service Client
177
178
_Method Signature:_
179
<pre>
180
<code class="JAVA">
181
public static <E, T> T invoke(WebServicesRequest<E, T> request)
182
</code>
183
</pre>
184
185
h3. Input Parameter
186
187
* *request* - the request object consists of
188
** <code>E</code> - the type of the request entity
189
** <code>T</code> - the type of the response entity
190
** *requestEntity* - the request entity, it can be a <code>String</code> or <code>Object</code>
191
** *requestUrl* - the URL of the web service
192
** *httpMethod* - either <code>POST</code>, <code>GET</code>, <code>PUT</code> and etc.
193
** *responseType* - the type of the response entity, it can be a <code>String</code> or <code>Object</code>
194
195
h3. Output Parameter
196
197
based on the provided input fields
198
199
h2. Asynschronous Web Service Client
200
201
_Method Signature:_
202
<pre>
203
<code class="JAVA">
204
public static <E, T> void persistAndInvoke(Connection connection,
205
			AsyncWebServicesRequest<E, T> request)
206
</code>
207
</pre>
208
209
h3. Input Parameter
210
211
* *request* - the request object consists of
212
** <code>E</code> - the type of the request entity
213
** <code>T</code> - the type of the response entity
214
** *requestEntity* - the request entity, it can be a <code>String</code> or <code>Object</code>
215
** *requestUrl* - the URL of the web service
216
** *httpMethod* - either <code>POST</code>, <code>GET</code>, <code>PUT</code> and etc.
217
** *responseType* - the type of the response entity, it can be a <code>String</code> or <code>Object</code>
218
219
220
221
h3. Output Parameter
222
223
based on the provided input fields