Programming Guide » History » Version 12
chin-yeh, 08/26/2011 10:09 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 | 12 | chin-yeh | LOGGER.error("Error in connecting to 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. |