Project

General

Profile

Programming Guide » History » Version 9

chin-yeh, 08/25/2011 02:58 PM

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
  // do not ignore. either log the full stack trace or handle it
51
  LOGGER.error(ex);
52
}
53
</code>
54
</pre>
55 3 chin-yeh
56
h2. Impose Sales Lock
57
58 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.
59
60 3 chin-yeh
h3. Input Parameters
61
62 6 chin-yeh
See "imposeSalesLock":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
63
64 3 chin-yeh
h3. Output Parameters
65
66 8 chin-yeh
The return object, *TransactionResponse* consists of:
67
* *process* - Sales1
68
* *transactionId* - the unique reference that passed in by the caller
69
* *countryId* - the country ID that passed in by the caller
70
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
71
* *memberId* - the member/shopper ID
72
* *status* - the status of the transaction. If success, returns *0000*
73
** refer to document:"DP Web Services" for other possible status
74
* *balance* - the available DP balance
75
* *errorCode* - the error code of the transaction. if success, returns *00000*
76
** refer to document:"DP Web Services" for other possible error code
77
* *errorMessage* - the detailed description of the error code 
78
** refer to document:"DP Web Services" for other possible description
79
80 3 chin-yeh
h3. Code Snippet
81
82 8 chin-yeh
<pre>
83
<code class="JAVA">
84
TransactionResponse dpResponse;
85
try {
86
  dpResponse = DPServicesUtils.imposeSalesLock(trxId, countryCode, shopperId);
87
88
} catch (RemoteException ex) {
89
  // do not ignore. either log the full stack trace or handle it
90
  LOGGER.error(ex);
91
}
92
</code>
93
</pre>
94
95 3 chin-yeh
h2. Release Sales Lock
96
97 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*.
98
99
And, this method will return success status regardless if there's *Sales Lock* or not.
100
101 3 chin-yeh
h3. Input Parameters
102
103 7 chin-yeh
See "releaseSalesLock":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
104
105 3 chin-yeh
h3. Output Parameters
106
107 8 chin-yeh
* *process* - Sales1
108
* *transactionId* - the unique reference that passed in by the caller
109
* *countryId* - the country ID that passed in by the caller
110
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
111
* *memberId* - the member/shopper ID
112
* *status* - the status of the transaction. If success, returns *0000*
113
** refer to document:"DP Web Services" for other possible status
114
* *balance* - the available DP balance
115
* *errorCode* - the error code of the transaction. if success, returns *00000*
116
** refer to document:"DP Web Services" for other possible error code
117
* *errorMessage* - the detailed description of the error code 
118
** refer to document:"DP Web Services" for other possible description
119
120 3 chin-yeh
h3. Code Snippet
121 8 chin-yeh
122
<pre>
123
<code class="JAVA">
124
TransactionResponse dpResponse;
125
try {
126
  dpResponse = DPServicesUtils.releaseSalesLock(trxId, countryCode, shopperId);
127
128
} catch (RemoteException ex) {
129
  // do not ignore. either log the full stack trace or handle it
130
  LOGGER.error(ex);
131
}
132
</code>
133
</pre>
134
135 3 chin-yeh
136
h2. Commit Sales
137 1 chin-yeh
138 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. 
139
140
The *Commit Sales* and *Impose Sales Lock* could be invoked by 2 separate processes but both must use the same transaction ID.
141
142
This method will persist the transaction details into database.
143
144 3 chin-yeh
h3. Input Parameters
145
146 6 chin-yeh
See "performSalesCommit":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
147
148 3 chin-yeh
h3. Output Parameters
149 1 chin-yeh
150 9 chin-yeh
* *process* - Sales2
151
* *transactionId* - the unique reference that passed in by the caller
152
* *countryId* - the country ID that passed in by the caller
153
* *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall.
154
* *memberId* - the member/shopper ID
155
* *status* - the status of the transaction. If success, returns *0000*
156
** refer to document:"DP Web Services" for other possible status
157
* *balance* - the available DP balance
158
* *errorCode* - the error code of the transaction. if success, returns *00000*
159
** refer to document:"DP Web Services" for other possible error code
160
* *errorMessage* - the detailed description of the error code 
161
** refer to document:"DP Web Services" for other possible description
162
163 3 chin-yeh
h3. Code Snippet
164 1 chin-yeh
165 9 chin-yeh
<pre>
166
<code class="JAVA">
167
Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2");
168
TransactionResponse dpResponse = new TransactionResponse();
169
try {
170
	// impose sales lock before commit
171
	dpResponse = DPServicesUtils.imposeSalesLock(trxId, countryCode, shopperId);
172
		
173
	dpResponse = DPServicesUtils.performSalesCommit(dbConnection,
174
				trxId, countryCode, shopperId,
175
				trxDate, dpAmount, invoiceAmount);
176
} catch (RemoteException ex) {
177
   // do not ignore. either log the full stack trace or handle it
178
  LOGGER.error(ex);
179
180
} catch (SQLException ex) {
181
   // do not ignore. either log the full stack trace or handle it
182
  LOGGER.error(ex);
183
184
} finally {		
185
	if (dbConnection != null) {
186
	   dbConnection.close();
187
	}
188
}
189
190
// release the Sales Lock in the event of exception 
191
if (dpResponse == null || !"0000".equals(dpResponse.getStatus())) {
192
   DPServicesUtils.releaseSalesLock(trxId, countryCode, shopperId);
193
}
194
195
</code>
196
</pre>
197 3 chin-yeh
198 6 chin-yeh
h2. Sales Return / Sales Exchange
199
200
h3. Input Parameters
201
202
See "performSalesReturn":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
203
204
h3. Output Parameters
205
206
h3. Code Snippet
207
208
209
h2. VIP Upgrade to BO
210
211
h3. Input Parameters
212
213
See "performVipUpgrade":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html
214
215
h3. Output Parameters
216
217
h3. Code Snippet
218
219
220 3 chin-yeh
h2. Generate the redirect URL for VIP Details page
221
222
h3. Input Parameters
223 6 chin-yeh
224
See "vipDetailsPage":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/utils/DpRedirectUtils.html
225 3 chin-yeh
226
h3. Output Parameters
227
228
h3. Code Snippet
229
230
231
232
h2. Exception Handling Strategies
233
234
The APIs would throw the following exceptions:
235 4 chin-yeh
* *RemoteException* - if there's any issue in communicating with the DP
236 3 chin-yeh
* *SQLException* - if there's any issue in persisting or updating the event
237
* *unchecked exception* - e.g. NullPointerException. This is more like a programming errors so do not catch it for whatever reasons.
238
** _note: catch the *Exception* will catch both checked & unchecked exception_
239
240
The above exceptions should never be ignored, at least, the full error stack trace should be logged.