Project

General

Profile

Programming Guide » History » Version 11

chin-yeh, 08/26/2011 10:08 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 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 8 chin-yeh
* *process* - Sales1
106
* *transactionId* - the unique reference that passed in by the caller
107
* *countryId* - the country ID that passed in by the caller
108
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
109
* *memberId* - the member/shopper ID
110
* *status* - the status of the transaction. If success, returns *0000*
111
** refer to document:"DP Web Services" for other possible status
112
* *balance* - the available DP balance
113
* *errorCode* - the error code of the transaction. if success, returns *00000*
114
** refer to document:"DP Web Services" for other possible error code
115
* *errorMessage* - the detailed description of the error code 
116
** refer to document:"DP Web Services" for other possible description
117
118 3 chin-yeh
h3. Code Snippet
119 8 chin-yeh
120
<pre>
121
<code class="JAVA">
122
TransactionResponse dpResponse;
123 1 chin-yeh
try {
124 8 chin-yeh
  dpResponse = DPServicesUtils.releaseSalesLock(trxId, countryCode, shopperId);
125
126
} catch (RemoteException ex) {
127 11 chin-yeh
  LOGGER.error("Error in connecting web services", ex);
128 8 chin-yeh
}
129
</code>
130
</pre>
131
132 3 chin-yeh
133
h2. Commit Sales
134 1 chin-yeh
135 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. 
136
137
The *Commit Sales* and *Impose Sales Lock* could be invoked by 2 separate processes but both must use the same transaction ID.
138
139
This method will persist the transaction details into database.
140
141 3 chin-yeh
h3. Input Parameters
142
143 6 chin-yeh
See "performSalesCommit":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
144
145 3 chin-yeh
h3. Output Parameters
146 1 chin-yeh
147 9 chin-yeh
* *process* - Sales2
148
* *transactionId* - the unique reference that passed in by the caller
149
* *countryId* - the country ID that passed in by the caller
150
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
151
* *memberId* - the member/shopper ID
152
* *status* - the status of the transaction. If success, returns *0000*
153
** refer to document:"DP Web Services" for other possible status
154
* *balance* - the available DP balance
155
* *errorCode* - the error code of the transaction. if success, returns *00000*
156
** refer to document:"DP Web Services" for other possible error code
157
* *errorMessage* - the detailed description of the error code 
158
** refer to document:"DP Web Services" for other possible description
159
160 3 chin-yeh
h3. Code Snippet
161 1 chin-yeh
162 9 chin-yeh
<pre>
163
<code class="JAVA">
164
Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2");
165
TransactionResponse dpResponse = new TransactionResponse();
166
try {
167
	// impose sales lock before commit
168 1 chin-yeh
	dpResponse = DPServicesUtils.imposeSalesLock(trxId, countryCode, shopperId);
169 9 chin-yeh
		
170 1 chin-yeh
	dpResponse = DPServicesUtils.performSalesCommit(dbConnection,
171 9 chin-yeh
				trxId, countryCode, shopperId,
172
				trxDate, dpAmount, invoiceAmount);
173
} catch (RemoteException ex) {
174 11 chin-yeh
	LOGGER.error("Error in connecting to web service", ex);
175 9 chin-yeh
} catch (SQLException ex) {
176 11 chin-yeh
	LOGGER.error("Error in persisting the event", ex);
177 9 chin-yeh
} finally {		
178
	if (dbConnection != null) {
179
	   dbConnection.close();
180
	}
181
}
182
183
// release the Sales Lock in the event of exception 
184
if (dpResponse == null || !"0000".equals(dpResponse.getStatus())) {
185
   DPServicesUtils.releaseSalesLock(trxId, countryCode, shopperId);
186
}
187
188
</code>
189
</pre>
190 3 chin-yeh
191 10 chin-yeh
h2. Sales Return / Cancel Sales
192 1 chin-yeh
193 10 chin-yeh
This method is used to adjust the DP balance. There's no need to impose the *Sales Lock*.
194
195 6 chin-yeh
h3. Input Parameters
196
197
See "performSalesReturn":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
198
199
h3. Output Parameters
200 1 chin-yeh
201 10 chin-yeh
* *process* - SReturn
202
* *transactionId* - the unique reference that passed in by the caller
203
* *countryId* - the country ID that passed in by the caller
204
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
205 1 chin-yeh
* *memberId* - the member/shopper ID
206
* *status* - the status of the transaction. If success, returns *0000*
207
** refer to document:"DP Web Services" for other possible status
208
* *balance* - the available DP balance
209
* *errorCode* - the error code of the transaction. if success, returns *00000*
210 10 chin-yeh
** refer to document:"DP Web Services" for other possible error code
211 1 chin-yeh
* *errorMessage* - the detailed description of the error code 
212
** refer to document:"DP Web Services" for other possible description
213
214
215
h3. Code Snippet
216
217 11 chin-yeh
<pre>
218
<code class="JAVA">
219
Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2");
220
	
221
TransactionResponse dpResponse = new TransactionResponse();
222 1 chin-yeh
223 11 chin-yeh
try {
224
	dpResponse = DPServicesUtils.performSalesReturn(dbConnection, trxId, countryCode, 
225
			shopperId,trxDate, dpAmount, invoiceAmount);	
226
227
} catch (RemoteException ex) {
228
	LOGGER.error("Error in connecting to web service", ex);
229
} catch (SQLException ex) {
230
	LOGGER.error("Error in persisting the event", ex);
231
} finally {
232
	if (dbConnection != null) {
233
		dbConnection.close();
234
	}
235
}
236
237
</code>
238
</pre>
239 6 chin-yeh
240
241
h2. VIP Upgrade to BO
242
243
h3. Input Parameters
244
245
See "performVipUpgrade":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
246
247
h3. Output Parameters
248
249
h3. Code Snippet
250
251
252 3 chin-yeh
h2. Generate the redirect URL for VIP Details page
253
254
h3. Input Parameters
255 6 chin-yeh
256
See "vipDetailsPage":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/utils/DpRedirectUtils.html
257 3 chin-yeh
258
h3. Output Parameters
259
260
h3. Code Snippet
261
262
263
264
h2. Exception Handling Strategies
265
266
The APIs would throw the following exceptions:
267 4 chin-yeh
* *RemoteException* - if there's any issue in communicating with the DP
268 3 chin-yeh
* *SQLException* - if there's any issue in persisting or updating the event
269
* *unchecked exception* - e.g. NullPointerException. This is more like a programming errors so do not catch it for whatever reasons.
270
** _note: catch the *Exception* will catch both checked & unchecked exception_
271
272
The above exceptions should never be ignored, at least, the full error stack trace should be logged.