Project

General

Profile

Programming Guide » History » Version 18

chin-yeh, 09/06/2011 04:19 PM

1 2 chin-yeh
{{toc}}
2
3 1 chin-yeh
h1. Programming Guide
4 2 chin-yeh
5
There are number of APIs provided by DP. All of these APIs are wrapped and exposed through a client application, [[documentation#list-of-components|dp-client]]. Refer to the following sub sections for more information.
6
7
The Javadoc of *dp-client*:
8
> http://192.168.2.13:50000/dp_client_apidocs/
9
10
The binary or source files of *dp-client*:
11
> [[wiki#SCM|SCM]]
12
13
Demo application of *dp-client*:
14
> http://192.168.2.66:8080/dp-test/index.html
15 3 chin-yeh
16 5 chin-yeh
h2. Query DP balance
17 1 chin-yeh
18 5 chin-yeh
Queries the available DP balance. 
19
20 3 chin-yeh
h3. Input Parameters
21 1 chin-yeh
22 5 chin-yeh
See "queryBalance":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
23
24 3 chin-yeh
h3. Output Parameters
25 1 chin-yeh
26 5 chin-yeh
The return object, *TransactionResponse* consists of:
27
* *process* - Sales1
28
* *transactionId* - the unique reference that passed in by the caller
29
* *countryId* - the country ID that passed in by the caller
30
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
31
* *memberId* - the member/shopper ID
32
* *status* - the status of the transaction. If success, returns *0000*
33
** refer to document:"DP Web Services" for other possible status
34
* *balance* - the available DP balance
35
* *errorCode* - the error code of the transaction. if success, returns *00000*
36
** refer to document:"DP Web Services" for other possible error code
37
* *errorMessage* - the detailed description of the error code 
38
** refer to document:"DP Web Services" for other possible description
39
40
41 1 chin-yeh
h3. Code Snippet
42 5 chin-yeh
43
<pre>
44
<code class="JAVA">
45
TransactionResponse dpResponse;
46
try {
47
  dpResponse = DPServicesUtils.queryBalance(countryCode, shopperId); 
48
49
} catch (RemoteException ex) {
50 11 chin-yeh
  LOGGER.error("Error in connecting to web services", ex);
51 5 chin-yeh
}
52
</code>
53
</pre>
54 3 chin-yeh
55
h2. Impose Sales Lock
56
57 6 chin-yeh
Imposes the *Sales Lock* on the particular member ID. This method is usually to be used conjunction with *Commit Sales*. Without sales lock, the *Commit Sales* won't succeed.
58
59 3 chin-yeh
h3. Input Parameters
60
61 6 chin-yeh
See "imposeSalesLock":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
62
63 3 chin-yeh
h3. Output Parameters
64
65 8 chin-yeh
The return object, *TransactionResponse* consists of:
66
* *process* - Sales1
67
* *transactionId* - the unique reference that passed in by the caller
68
* *countryId* - the country ID that passed in by the caller
69
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
70
* *memberId* - the member/shopper ID
71
* *status* - the status of the transaction. If success, returns *0000*
72
** refer to document:"DP Web Services" for other possible status
73
* *balance* - the available DP balance
74
* *errorCode* - the error code of the transaction. if success, returns *00000*
75
** refer to document:"DP Web Services" for other possible error code
76
* *errorMessage* - the detailed description of the error code 
77
** refer to document:"DP Web Services" for other possible description
78
79 3 chin-yeh
h3. Code Snippet
80
81 8 chin-yeh
<pre>
82
<code class="JAVA">
83
TransactionResponse dpResponse;
84
try {
85
  dpResponse = DPServicesUtils.imposeSalesLock(trxId, countryCode, shopperId);
86 1 chin-yeh
87 8 chin-yeh
} catch (RemoteException ex) {
88 11 chin-yeh
  LOGGER.error("Error in connecting to web services", ex);
89 8 chin-yeh
}
90
</code>
91
</pre>
92
93 3 chin-yeh
h2. Release Sales Lock
94
95 8 chin-yeh
To be able to release the *Sales Lock*, one must provide the same *transaction ID*, which being used to impose the *Sales Lock*.
96
97
And, this method will return success status regardless if there's *Sales Lock* or not.
98
99 3 chin-yeh
h3. Input Parameters
100
101 7 chin-yeh
See "releaseSalesLock":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
102
103 3 chin-yeh
h3. Output Parameters
104
105 13 chin-yeh
The return object, *TransactionResponse* consists of:
106 8 chin-yeh
* *process* - Sales1
107
* *transactionId* - the unique reference that passed in by the caller
108
* *countryId* - the country ID that passed in by the caller
109
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
110
* *memberId* - the member/shopper ID
111
* *status* - the status of the transaction. If success, returns *0000*
112
** refer to document:"DP Web Services" for other possible status
113
* *balance* - the available DP balance
114
* *errorCode* - the error code of the transaction. if success, returns *00000*
115
** refer to document:"DP Web Services" for other possible error code
116
* *errorMessage* - the detailed description of the error code 
117
** refer to document:"DP Web Services" for other possible description
118
119 3 chin-yeh
h3. Code Snippet
120 8 chin-yeh
121
<pre>
122
<code class="JAVA">
123
TransactionResponse dpResponse;
124 1 chin-yeh
try {
125 8 chin-yeh
  dpResponse = DPServicesUtils.releaseSalesLock(trxId, countryCode, shopperId);
126
127
} catch (RemoteException ex) {
128 12 chin-yeh
  LOGGER.error("Error in connecting to web services", ex);
129 8 chin-yeh
}
130
</code>
131
</pre>
132
133 3 chin-yeh
134
h2. Commit Sales
135 1 chin-yeh
136 9 chin-yeh
This method is used to deduct DP balance according to the provided amount. The [[Programming Guide#Impose-Sales-Lock|Impose Sales Lock]] must be invoked prior that. 
137 1 chin-yeh
138 13 chin-yeh
The *Commit Sales* and *Impose Sales Lock* could possibly be invoked by 2 different process but both must use the same transaction ID.
139 9 chin-yeh
140
This method will persist the transaction details into database.
141
142 3 chin-yeh
h3. Input Parameters
143
144 6 chin-yeh
See "performSalesCommit":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
145
146 3 chin-yeh
h3. Output Parameters
147 1 chin-yeh
148 13 chin-yeh
The return object, *TransactionResponse* consists of:
149 9 chin-yeh
* *process* - Sales2
150
* *transactionId* - the unique reference that passed in by the caller
151
* *countryId* - the country ID that passed in by the caller
152
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
153
* *memberId* - the member/shopper ID
154
* *status* - the status of the transaction. If success, returns *0000*
155
** refer to document:"DP Web Services" for other possible status
156
* *balance* - the available DP balance
157
* *errorCode* - the error code of the transaction. if success, returns *00000*
158
** refer to document:"DP Web Services" for other possible error code
159
* *errorMessage* - the detailed description of the error code 
160
** refer to document:"DP Web Services" for other possible description
161
162 3 chin-yeh
h3. Code Snippet
163 1 chin-yeh
164 9 chin-yeh
<pre>
165
<code class="JAVA">
166
Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2");
167
TransactionResponse dpResponse = new TransactionResponse();
168
try {
169
	// impose sales lock before commit
170 14 chin-yeh
	// dpResponse = DPServicesUtils.imposeSalesLock(trxId, countryCode, shopperId);
171 9 chin-yeh
		
172 1 chin-yeh
	dpResponse = DPServicesUtils.performSalesCommit(dbConnection,
173 9 chin-yeh
				trxId, countryCode, shopperId,
174
				trxDate, dpAmount, invoiceAmount);
175
} catch (RemoteException ex) {
176 11 chin-yeh
	LOGGER.error("Error in connecting to web service", ex);
177 9 chin-yeh
} catch (SQLException ex) {
178 11 chin-yeh
	LOGGER.error("Error in persisting the event", ex);
179 9 chin-yeh
} finally {		
180
	if (dbConnection != null) {
181
	   dbConnection.close();
182
	}
183
}
184
185
// release the Sales Lock in the event of exception 
186
if (dpResponse == null || !"0000".equals(dpResponse.getStatus())) {
187
   DPServicesUtils.releaseSalesLock(trxId, countryCode, shopperId);
188
}
189
190
</code>
191
</pre>
192 3 chin-yeh
193 10 chin-yeh
h2. Sales Return / Cancel Sales
194 1 chin-yeh
195 10 chin-yeh
This method is used to adjust the DP balance. There's no need to impose the *Sales Lock*.
196
197 6 chin-yeh
h3. Input Parameters
198
199
See "performSalesReturn":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
200
201
h3. Output Parameters
202 1 chin-yeh
203 13 chin-yeh
The return object, *TransactionResponse* consists of:
204 10 chin-yeh
* *process* - SReturn
205
* *transactionId* - the unique reference that passed in by the caller
206
* *countryId* - the country ID that passed in by the caller
207
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
208 1 chin-yeh
* *memberId* - the member/shopper ID
209
* *status* - the status of the transaction. If success, returns *0000*
210
** refer to document:"DP Web Services" for other possible status
211
* *balance* - the available DP balance
212
* *errorCode* - the error code of the transaction. if success, returns *00000*
213 10 chin-yeh
** refer to document:"DP Web Services" for other possible error code
214 1 chin-yeh
* *errorMessage* - the detailed description of the error code 
215
** refer to document:"DP Web Services" for other possible description
216
217
218
h3. Code Snippet
219
220 11 chin-yeh
<pre>
221
<code class="JAVA">
222
Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2");
223
	
224
TransactionResponse dpResponse = new TransactionResponse();
225 1 chin-yeh
226 11 chin-yeh
try {
227
	dpResponse = DPServicesUtils.performSalesReturn(dbConnection, trxId, countryCode, 
228
			shopperId,trxDate, dpAmount, invoiceAmount);	
229
230
} catch (RemoteException ex) {
231
	LOGGER.error("Error in connecting to web service", ex);
232
} catch (SQLException ex) {
233
	LOGGER.error("Error in persisting the event", ex);
234
} finally {
235
	if (dbConnection != null) {
236
		dbConnection.close();
237
	}
238
}
239
240
</code>
241
</pre>
242 6 chin-yeh
243
244
h2. VIP Upgrade to BO
245 1 chin-yeh
246 13 chin-yeh
This method upgrades the VIP to BO. After upgraded, you have to use the *new member ID* for the subsequence operation, e.g. DP balance. Besides that, one must utilize all of the remaining DP balance in the limited period of time. The period is determined by DP.
247
248 6 chin-yeh
h3. Input Parameters
249
250
See "performVipUpgrade":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
251
252
h3. Output Parameters
253 1 chin-yeh
254 13 chin-yeh
The return object, *TransactionResponse* consists of:
255
* *process* - Change
256
* *transactionId* - the unique reference that passed in by the caller
257
* *countryId* - the country ID that passed in by the caller
258
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
259
* *memberId* - the member/shopper ID
260
* *status* - the status of the transaction. If success, returns *0000*
261
** refer to document:"DP Web Services" for other possible status
262
* *balance* - the available DP balance
263
* *errorCode* - the error code of the transaction. if success, returns *00000*
264
** refer to document:"DP Web Services" for other possible error code
265
* *errorMessage* - the detailed description of the error code 
266
** refer to document:"DP Web Services" for other possible description
267
* *expiryDate* - the return value is in *yyyyMMdd* format. This indicates the validity of the remaining DP balance 
268
269
270 6 chin-yeh
h3. Code Snippet
271 1 chin-yeh
272 13 chin-yeh
<pre>
273
<code class="JAVA">
274
Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2");
275
	
276
TransactionResponse dpResponse = new TransactionResponse();
277 1 chin-yeh
278 13 chin-yeh
try {
279
	dpResponse = DPServicesUtils.performVipUpgrade(dbConnection, trxId, countryCode,
280
			memberName, shopperId, newShopperId, trxDate);
281
282
} catch (RemoteException ex) {
283
	LOGGER.error("Error in connecting to web service", ex);
284
} catch (SQLException ex) {
285
	LOGGER.error("Error in persisting the event", ex);
286
} finally {
287
	if (dbConnection != null) {
288
		dbConnection.close();
289
	}
290
}
291
</code>
292
</pre>
293
294 3 chin-yeh
h2. Generate the redirect URL for VIP Details page
295 1 chin-yeh
296 14 chin-yeh
Generates the required form data which is needed to redirect member to the *DP VIP Details* page.
297
298 16 chin-yeh
*Important Notes:* 
299
* DP accepts *HTTP POST* method only.
300
* Prevent unauthorized access to the page or function which is being used to invoke this method. For example, retrieve the member ID from session instead of page request parameters.
301 15 chin-yeh
302 3 chin-yeh
h3. Input Parameters
303 6 chin-yeh
304
See "vipDetailsPage":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/utils/DpRedirectUtils.html
305 3 chin-yeh
306 1 chin-yeh
h3. Output Parameters
307
308 15 chin-yeh
The return object, key-value pairs consist of:
309 14 chin-yeh
* *memberid* - the member/shopper ID
310
* *pin* - the PIN that provided by DP
311
* *expirydate* - when would the request expires
312
* *fingerprint* - the fingerprint of the request, it is an one-way hash value
313 1 chin-yeh
314 15 chin-yeh
One have to make use of the key-value pairs to construct the form. See *Code Snippet* section for the example.
315
316 3 chin-yeh
h3. Code Snippet
317 1 chin-yeh
318 15 chin-yeh
Must use *HTTP POST* method to submit the request to DP:
319 13 chin-yeh
<pre>
320 1 chin-yeh
<code class="JAVA">
321 15 chin-yeh
<%
322
	Map<String, String> formData = 
323
		DpRedirectUtils.vipDetailsPage(request.getParameter("shopperId"));
324 18 chin-yeh
        // Do Not use parameter. This is for demo purpose only.
325 17 chin-yeh
        // Should get the shopper ID from session to prevent someone from hijack this page
326 15 chin-yeh
%>
327
328
<form id="frm" name="frm" method="<%=formData.get("method") %>" action="<%=formData.get("action") %>">
329
	<input name="memberid" type="hidden" value="<%=formData.get("memberid") %>"/>
330
	<input name="pin" type="hidden" value="<%=formData.get("pin") %>"/>
331
	<input name="expirydate" type="hidden" value="<%=formData.get("expirydate") %>"/>
332
	<input name="fingerprint" type="hidden" value="<%=formData.get("fingerprint") %>"/>
333
</form>
334
335
<h3>
336
Please wait while we redirecting you to VIP Details page... 
337
</h3>
338
339
<script language='javascript'>
340
function submitForm(){
341
   document.frm.submit();
342
}
343
344
window.onload=submitForm ;
345
</script>
346 13 chin-yeh
</code>
347
</pre>
348 3 chin-yeh
349
350
h2. Exception Handling Strategies
351
352
The APIs would throw the following exceptions:
353 4 chin-yeh
* *RemoteException* - if there's any issue in communicating with the DP
354 3 chin-yeh
* *SQLException* - if there's any issue in persisting or updating the event
355
* *unchecked exception* - e.g. NullPointerException. This is more like a programming errors so do not catch it for whatever reasons.
356
** _note: catch the *Exception* will catch both checked & unchecked exception_
357
358
The above exceptions should never be ignored, at least, the full error stack trace should be logged.