Project

General

Profile

Programming Guide » History » Version 19

chin-yeh, 09/23/2011 10:10 AM

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 19 chin-yeh
_Method Signature:_
21
<pre>
22
<code class="JAVA">
23
public static TransactionResponse queryBalance(java.lang.String countryCode,
24
                                               java.lang.String memberId)
25
                                        throws java.rmi.RemoteException
26
</code>
27
</pre>
28
29
30 3 chin-yeh
h3. Input Parameters
31 1 chin-yeh
32 5 chin-yeh
See "queryBalance":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
33
34 3 chin-yeh
h3. Output Parameters
35 1 chin-yeh
36 5 chin-yeh
The return object, *TransactionResponse* consists of:
37
* *process* - Sales1
38
* *transactionId* - the unique reference that passed in by the caller
39
* *countryId* - the country ID that passed in by the caller
40
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
41
* *memberId* - the member/shopper ID
42
* *status* - the status of the transaction. If success, returns *0000*
43
** refer to document:"DP Web Services" for other possible status
44
* *balance* - the available DP balance
45
* *errorCode* - the error code of the transaction. if success, returns *00000*
46
** refer to document:"DP Web Services" for other possible error code
47
* *errorMessage* - the detailed description of the error code 
48
** refer to document:"DP Web Services" for other possible description
49
50 1 chin-yeh
51 19 chin-yeh
h3. Code Snippets
52 5 chin-yeh
53
<pre>
54
<code class="JAVA">
55
TransactionResponse dpResponse;
56
try {
57
  dpResponse = DPServicesUtils.queryBalance(countryCode, shopperId); 
58
59
} catch (RemoteException ex) {
60 11 chin-yeh
  LOGGER.error("Error in connecting to web services", ex);
61 5 chin-yeh
}
62
</code>
63
</pre>
64 3 chin-yeh
65
h2. Impose Sales Lock
66
67 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.
68 1 chin-yeh
69 19 chin-yeh
_Method Signature:_
70
<pre>
71
<code class="JAVA">
72
public static TransactionResponse imposeSalesLock(java.lang.String transactionId,
73
                                                  java.lang.String countryCode,
74
                                                  java.lang.String memberId)
75
                                           throws java.rmi.RemoteException
76
</code>
77
</pre>
78
79
80 3 chin-yeh
h3. Input Parameters
81 6 chin-yeh
82
See "imposeSalesLock":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
83 3 chin-yeh
84
h3. Output Parameters
85 8 chin-yeh
86
The return object, *TransactionResponse* consists of:
87
* *process* - Sales1
88
* *transactionId* - the unique reference that passed in by the caller
89
* *countryId* - the country ID that passed in by the caller
90
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
91
* *memberId* - the member/shopper ID
92
* *status* - the status of the transaction. If success, returns *0000*
93
** refer to document:"DP Web Services" for other possible status
94
* *balance* - the available DP balance
95
* *errorCode* - the error code of the transaction. if success, returns *00000*
96
** refer to document:"DP Web Services" for other possible error code
97
* *errorMessage* - the detailed description of the error code 
98 1 chin-yeh
** refer to document:"DP Web Services" for other possible description
99 8 chin-yeh
100 19 chin-yeh
h3. Code Snippets
101 3 chin-yeh
102 8 chin-yeh
<pre>
103
<code class="JAVA">
104
TransactionResponse dpResponse;
105
try {
106
  dpResponse = DPServicesUtils.imposeSalesLock(trxId, countryCode, shopperId);
107 1 chin-yeh
108 8 chin-yeh
} catch (RemoteException ex) {
109 11 chin-yeh
  LOGGER.error("Error in connecting to web services", ex);
110 8 chin-yeh
}
111
</code>
112
</pre>
113
114 3 chin-yeh
h2. Release Sales Lock
115
116 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*.
117
118 1 chin-yeh
And, this method will return success status regardless if there's *Sales Lock* or not.
119
120 19 chin-yeh
_Method Signature:_
121
<pre>
122
<code class="JAVA">
123
public static TransactionResponse releaseSalesLock(java.lang.String transactionId,
124
                                                   java.lang.String countryCode,
125
                                                   java.lang.String memberId)
126
                                            throws java.rmi.RemoteException
127
</code>
128
</pre>
129
130
131 3 chin-yeh
h3. Input Parameters
132 7 chin-yeh
133
See "releaseSalesLock":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
134 3 chin-yeh
135
h3. Output Parameters
136 13 chin-yeh
137 8 chin-yeh
The return object, *TransactionResponse* consists of:
138
* *process* - Sales1
139
* *transactionId* - the unique reference that passed in by the caller
140
* *countryId* - the country ID that passed in by the caller
141
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
142
* *memberId* - the member/shopper ID
143
* *status* - the status of the transaction. If success, returns *0000*
144
** refer to document:"DP Web Services" for other possible status
145
* *balance* - the available DP balance
146
* *errorCode* - the error code of the transaction. if success, returns *00000*
147
** refer to document:"DP Web Services" for other possible error code
148 1 chin-yeh
* *errorMessage* - the detailed description of the error code 
149 8 chin-yeh
** refer to document:"DP Web Services" for other possible description
150
151 19 chin-yeh
h3. Code Snippets
152 8 chin-yeh
153
<pre>
154
<code class="JAVA">
155
TransactionResponse dpResponse;
156 1 chin-yeh
try {
157 8 chin-yeh
  dpResponse = DPServicesUtils.releaseSalesLock(trxId, countryCode, shopperId);
158
159 12 chin-yeh
} catch (RemoteException ex) {
160 8 chin-yeh
  LOGGER.error("Error in connecting to web services", ex);
161
}
162
</code>
163
</pre>
164 3 chin-yeh
165
166 1 chin-yeh
h2. Commit Sales
167 9 chin-yeh
168 1 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. 
169 13 chin-yeh
170 9 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.
171 1 chin-yeh
172
This method will persist the transaction details into database.
173
174 19 chin-yeh
_Method Signature:_
175
<pre>
176
<code class="JAVA">
177
public static TransactionResponse performSalesCommit(java.sql.Connection dbConnection,
178
                                                     java.lang.String transactionId,
179
                                                     java.lang.String countryCode,
180
                                                     java.lang.String memberId,
181
                                                     java.util.Date trxDate,
182
                                                     java.math.BigDecimal dpAmount,
183
                                                     java.math.BigDecimal invoiceAmount)
184
                                              throws java.rmi.RemoteException,
185
                                                     java.sql.SQLException
186
</code>
187
</pre>
188
189
190 3 chin-yeh
h3. Input Parameters
191 6 chin-yeh
192
See "performSalesCommit":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
193 3 chin-yeh
194 1 chin-yeh
h3. Output Parameters
195 13 chin-yeh
196 9 chin-yeh
The return object, *TransactionResponse* consists of:
197
* *process* - Sales2
198
* *transactionId* - the unique reference that passed in by the caller
199
* *countryId* - the country ID that passed in by the caller
200
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
201
* *memberId* - the member/shopper ID
202
* *status* - the status of the transaction. If success, returns *0000*
203
** refer to document:"DP Web Services" for other possible status
204
* *balance* - the available DP balance
205
* *errorCode* - the error code of the transaction. if success, returns *00000*
206 1 chin-yeh
** refer to document:"DP Web Services" for other possible error code
207 9 chin-yeh
* *errorMessage* - the detailed description of the error code 
208
** refer to document:"DP Web Services" for other possible description
209
210 19 chin-yeh
h3. Code Snippets
211 1 chin-yeh
212 9 chin-yeh
<pre>
213
<code class="JAVA">
214
Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2");
215
TransactionResponse dpResponse = new TransactionResponse();
216
try {
217 14 chin-yeh
	// impose sales lock before commit
218 9 chin-yeh
	// dpResponse = DPServicesUtils.imposeSalesLock(trxId, countryCode, shopperId);
219 1 chin-yeh
		
220 9 chin-yeh
	dpResponse = DPServicesUtils.performSalesCommit(dbConnection,
221
				trxId, countryCode, shopperId,
222
				trxDate, dpAmount, invoiceAmount);
223 11 chin-yeh
} catch (RemoteException ex) {
224 9 chin-yeh
	LOGGER.error("Error in connecting to web service", ex);
225 11 chin-yeh
} catch (SQLException ex) {
226 9 chin-yeh
	LOGGER.error("Error in persisting the event", ex);
227
} finally {		
228
	if (dbConnection != null) {
229
	   dbConnection.close();
230
	}
231
}
232
233
// release the Sales Lock in the event of exception 
234
if (dpResponse == null || !"0000".equals(dpResponse.getStatus())) {
235
   DPServicesUtils.releaseSalesLock(trxId, countryCode, shopperId);
236
}
237
238
</code>
239 3 chin-yeh
</pre>
240 10 chin-yeh
241 1 chin-yeh
h2. Sales Return / Cancel Sales
242
243
This method is used to adjust the DP balance. There's no need to impose the *Sales Lock*.
244
245 19 chin-yeh
_Method Signature:_
246
<pre>
247
<code class="JAVA">
248
public static TransactionResponse performSalesReturn(java.sql.Connection connection,
249
                                                     java.lang.String transactionId,
250
                                                     java.lang.String countryCode,
251
                                                     java.lang.String memberId,
252
                                                     java.util.Date trxDate,
253
                                                     java.math.BigDecimal dpAmount,
254
                                                     java.math.BigDecimal invoiceAmount)
255
                                              throws java.rmi.RemoteException,
256
                                                     java.sql.SQLException
257
</code>
258
</pre>
259
260
261 6 chin-yeh
h3. Input Parameters
262
263
See "performSalesReturn":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
264
265 13 chin-yeh
h3. Output Parameters
266 10 chin-yeh
267
The return object, *TransactionResponse* consists of:
268
* *process* - SReturn
269
* *transactionId* - the unique reference that passed in by the caller
270 1 chin-yeh
* *countryId* - the country ID that passed in by the caller
271
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
272
* *memberId* - the member/shopper ID
273
* *status* - the status of the transaction. If success, returns *0000*
274
** refer to document:"DP Web Services" for other possible status
275 10 chin-yeh
* *balance* - the available DP balance
276 1 chin-yeh
* *errorCode* - the error code of the transaction. if success, returns *00000*
277
** refer to document:"DP Web Services" for other possible error code
278
* *errorMessage* - the detailed description of the error code 
279
** refer to document:"DP Web Services" for other possible description
280
281
282 19 chin-yeh
h3. Code Snippets
283 11 chin-yeh
284
<pre>
285
<code class="JAVA">
286
Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2");
287
	
288 1 chin-yeh
TransactionResponse dpResponse = new TransactionResponse();
289 11 chin-yeh
290
try {
291
	dpResponse = DPServicesUtils.performSalesReturn(dbConnection, trxId, countryCode, 
292
			shopperId,trxDate, dpAmount, invoiceAmount);	
293
294
} catch (RemoteException ex) {
295
	LOGGER.error("Error in connecting to web service", ex);
296
} catch (SQLException ex) {
297
	LOGGER.error("Error in persisting the event", ex);
298
} finally {
299
	if (dbConnection != null) {
300
		dbConnection.close();
301
	}
302
}
303
304
</code>
305 6 chin-yeh
</pre>
306
307 1 chin-yeh
308
h2. VIP Upgrade to BO
309
310
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.
311
312 19 chin-yeh
_Method Signature:_
313
<pre>
314
<code class="JAVA">
315
public static TransactionResponse performVipUpgrade(java.sql.Connection connection,
316
                                                    java.lang.String trxId,
317
                                                    java.lang.String countryCode,
318
                                                    java.lang.String memberName,
319
                                                    java.lang.String memberId,
320
                                                    java.lang.String newMemberId,
321
                                                    java.util.Date trxDate)
322
                                             throws java.rmi.RemoteException,
323
                                                    java.sql.SQLException
324
</code>
325
</pre>
326
327
328 6 chin-yeh
h3. Input Parameters
329
330 1 chin-yeh
See "performVipUpgrade":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
331 13 chin-yeh
332
h3. Output Parameters
333
334
The return object, *TransactionResponse* consists of:
335
* *process* - Change
336
* *transactionId* - the unique reference that passed in by the caller
337
* *countryId* - the country ID that passed in by the caller
338
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
339
* *memberId* - the member/shopper ID
340
* *status* - the status of the transaction. If success, returns *0000*
341
** refer to document:"DP Web Services" for other possible status
342
* *balance* - the available DP balance
343
* *errorCode* - the error code of the transaction. if success, returns *00000*
344 1 chin-yeh
** refer to document:"DP Web Services" for other possible error code
345 13 chin-yeh
* *errorMessage* - the detailed description of the error code 
346
** refer to document:"DP Web Services" for other possible description
347
* *expiryDate* - the return value is in *yyyyMMdd* format. This indicates the validity of the remaining DP balance 
348 6 chin-yeh
349 1 chin-yeh
350 19 chin-yeh
h3. Code Snippets
351 13 chin-yeh
352
<pre>
353
<code class="JAVA">
354
Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2");
355 1 chin-yeh
	
356 13 chin-yeh
TransactionResponse dpResponse = new TransactionResponse();
357
358
try {
359
	dpResponse = DPServicesUtils.performVipUpgrade(dbConnection, trxId, countryCode,
360
			memberName, shopperId, newShopperId, trxDate);
361
362
} catch (RemoteException ex) {
363
	LOGGER.error("Error in connecting to web service", ex);
364
} catch (SQLException ex) {
365
	LOGGER.error("Error in persisting the event", ex);
366
} finally {
367
	if (dbConnection != null) {
368
		dbConnection.close();
369
	}
370
}
371
</code>
372 3 chin-yeh
</pre>
373 1 chin-yeh
374 14 chin-yeh
h2. Generate the redirect URL for VIP Details page
375
376 1 chin-yeh
Generates the required form data which is needed to redirect member to the *DP VIP Details* page.
377
378
*Important Notes:* 
379
* DP accepts *HTTP POST* method only.
380
* 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.
381
382 19 chin-yeh
_Method Signature:_
383
<pre>
384
<code class="JAVA">
385
public static java.util.Map<java.lang.String,java.lang.String> vipDetailsPage(java.lang.String memberId)
386
</code>
387
</pre>
388
389
390 6 chin-yeh
h3. Input Parameters
391 3 chin-yeh
392 1 chin-yeh
See "vipDetailsPage":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/utils/DpRedirectUtils.html
393
394 15 chin-yeh
h3. Output Parameters
395 1 chin-yeh
396
The return object, key-value pairs consist of:
397 14 chin-yeh
* *memberid* - the member/shopper ID
398
* *pin* - the PIN that provided by DP
399
* *expirydate* - when would the request expires
400
* *fingerprint* - the fingerprint of the request, it is an one-way hash value
401 1 chin-yeh
402 19 chin-yeh
One have to make use of the key-value pairs to construct the form. See *Code Snippets* section for the example.
403 15 chin-yeh
404 19 chin-yeh
h3. Code Snippets
405 1 chin-yeh
406 15 chin-yeh
Must use *HTTP POST* method to submit the request to DP:
407 13 chin-yeh
<pre>
408 1 chin-yeh
<code class="JAVA">
409 15 chin-yeh
<%
410
	Map<String, String> formData = 
411
		DpRedirectUtils.vipDetailsPage(request.getParameter("shopperId"));
412 18 chin-yeh
        // Do Not use parameter. This is for demo purpose only.
413 17 chin-yeh
        // Should get the shopper ID from session to prevent someone from hijack this page
414 15 chin-yeh
%>
415
416
<form id="frm" name="frm" method="<%=formData.get("method") %>" action="<%=formData.get("action") %>">
417
	<input name="memberid" type="hidden" value="<%=formData.get("memberid") %>"/>
418
	<input name="pin" type="hidden" value="<%=formData.get("pin") %>"/>
419
	<input name="expirydate" type="hidden" value="<%=formData.get("expirydate") %>"/>
420
	<input name="fingerprint" type="hidden" value="<%=formData.get("fingerprint") %>"/>
421
</form>
422
423
<h3>
424
Please wait while we redirecting you to VIP Details page... 
425
</h3>
426
427
<script language='javascript'>
428
function submitForm(){
429
   document.frm.submit();
430
}
431
432
window.onload=submitForm ;
433
</script>
434 13 chin-yeh
</code>
435
</pre>
436 3 chin-yeh
437
438
h2. Exception Handling Strategies
439
440
The APIs would throw the following exceptions:
441 4 chin-yeh
* *RemoteException* - if there's any issue in communicating with the DP
442 3 chin-yeh
* *SQLException* - if there's any issue in persisting or updating the event
443
* *unchecked exception* - e.g. NullPointerException. This is more like a programming errors so do not catch it for whatever reasons.
444
** _note: catch the *Exception* will catch both checked & unchecked exception_
445
446
The above exceptions should never be ignored, at least, the full error stack trace should be logged.