Programming Guide » History » Version 13
chin-yeh, 08/26/2011 10:46 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 | 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 | 1 | 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 | |||
296 | h3. Input Parameters |
||
297 | 6 | chin-yeh | |
298 | See "vipDetailsPage":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/utils/DpRedirectUtils.html |
||
299 | 3 | chin-yeh | |
300 | h3. Output Parameters |
||
301 | 1 | chin-yeh | |
302 | 13 | chin-yeh | The return object, *TransactionResponse* consists of: |
303 | |||
304 | 3 | chin-yeh | h3. Code Snippet |
305 | 1 | chin-yeh | |
306 | 13 | chin-yeh | <pre> |
307 | <code class="JAVA"> |
||
308 | </code> |
||
309 | </pre> |
||
310 | 3 | chin-yeh | |
311 | |||
312 | h2. Exception Handling Strategies |
||
313 | |||
314 | The APIs would throw the following exceptions: |
||
315 | 4 | chin-yeh | * *RemoteException* - if there's any issue in communicating with the DP |
316 | 3 | chin-yeh | * *SQLException* - if there's any issue in persisting or updating the event |
317 | * *unchecked exception* - e.g. NullPointerException. This is more like a programming errors so do not catch it for whatever reasons. |
||
318 | ** _note: catch the *Exception* will catch both checked & unchecked exception_ |
||
319 | |||
320 | The above exceptions should never be ignored, at least, the full error stack trace should be logged. |