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