Project

General

Profile

Programming Guide » History » Version 21

chin-yeh, 09/29/2011 10:53 AM

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