Programming Guide » History » Version 10
chin-yeh, 08/25/2011 11:18 AM
1 | 2 | chin-yeh | {{toc}} |
---|---|---|---|
2 | |||
3 | 1 | chin-yeh | h1. Programming Guide |
4 | 2 | chin-yeh | |
5 | 3 | chin-yeh | There are number of APIs provided by VP. All of these APIs are wrapped and exposed through a client application, [[documentation#list-of-components|vp-client]]. Refer to the following sub sections for more information. |
6 | 1 | chin-yeh | |
7 | 3 | chin-yeh | The Javadoc of *vp-client*: |
8 | > http://192.168.2.13:50000/vp_client_apidocs/ |
||
9 | |||
10 | 4 | chin-yeh | The binary or source files of *vp-client*: |
11 | > [[wiki#SCM|SCM]] |
||
12 | |||
13 | 3 | chin-yeh | Demo application of *vp-client*: |
14 | > http://192.168.2.66:8080/vp-test/index.html |
||
15 | |||
16 | 2 | chin-yeh | h2. VP Registration |
17 | 1 | chin-yeh | |
18 | 3 | chin-yeh | This method is only applicable for *new registration*, which means the member/shopper ID *is not yet registered* with VP before. |
19 | 1 | chin-yeh | |
20 | 3 | chin-yeh | h3. Input Parameters |
21 | |||
22 | 5 | chin-yeh | See "performRegistration":http://192.168.2.13:50000/vp_client_apidocs/com/ecosway/vp_client/VPServicesUtils.html#performRegistration%28java.sql.Connection,%20java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String,%20java.math.BigDecimal,%20java.util.Date,%20java.util.Date,%20java.util.Date%29 |
23 | 3 | chin-yeh | |
24 | h3. Output Parameters |
||
25 | |||
26 | The return object, *TransactionResponse* consists of the following fields value: |
||
27 | * *process* - For registration, the possible value is *VRegister* |
||
28 | * *transactionId* - The unique reference that passed in by the caller |
||
29 | * *countryId* - The country ID/code that passed in by the caller |
||
30 | * *centerId* - To differentiate if the caller are from POS system or online |
||
31 | * *memberId* - The member/shopper ID |
||
32 | * *status* - The status of the transaction. If success, returns *0000* |
||
33 | ** _refer to document:"VP Web Service Format" for other possible status_ |
||
34 | * *errorCode* - the error code of the transaction. if success, returns *00000* |
||
35 | ** _refer to document:"VP Web Service Format" for other possible error code_ |
||
36 | * *errorMessage* - the detailed description of the error code |
||
37 | ** _refer to document:"VP Web Service Format" for other possible description_ |
||
38 | |||
39 | h3. Code Snippet |
||
40 | |||
41 | *Important note:* One should modify the following code to cater existing program so do not copy & paste it directly. |
||
42 | |||
43 | <pre> |
||
44 | <code class="JAVA"> |
||
45 | Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2"); |
||
46 | TransactionResponse vpResponse = new TransactionResponse(); |
||
47 | |||
48 | try { |
||
49 | vpResponse = VPServicesUtils.performRegistration(dbConnection, trxId, |
||
50 | 7 | chin-yeh | countryId, memberId, memberName, vpAmount, trxDate, regDate, expDate); |
51 | 3 | chin-yeh | |
52 | } catch (RemoteException ex) { |
||
53 | // do not ignore. either log the full stack trace or handle it |
||
54 | LOGGER.error(ex); |
||
55 | } catch (SQLException ex) { |
||
56 | // do not ignore. either log the full stack trace or handle it |
||
57 | LOGGER.error(ex); |
||
58 | } finally { |
||
59 | if (dbConnection != null) { |
||
60 | dbConnection.close(); |
||
61 | } |
||
62 | } |
||
63 | </code> |
||
64 | </pre> |
||
65 | |||
66 | 1 | chin-yeh | h2. VP Renewal |
67 | 4 | chin-yeh | |
68 | 9 | chin-yeh | This method is only applicable for renewal. If the member is not exist, VP will create the record in the background. |
69 | 4 | chin-yeh | |
70 | h3. Input Parameters |
||
71 | |||
72 | 6 | chin-yeh | See "performRenewal":http://192.168.2.13:50000/vp_client_apidocs/com/ecosway/vp_client/VPServicesUtils.html#performRenewal(java.sql.Connection,%20java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String,%20java.math.BigDecimal,%20java.util.Date,%20java.util.Date,%20java.util.Date) |
73 | 4 | chin-yeh | |
74 | h3. Output Parameters |
||
75 | |||
76 | The return object, *TransactionResponse* consists of the following fields value: |
||
77 | * *process* - For registration/renewal, the possible value is *VRegister* |
||
78 | * *transactionId* - The unique reference that passed in by the caller |
||
79 | * *countryId* - The country ID/code that passed in by the caller |
||
80 | * *centerId* - To differentiate if the caller are from POS system or online |
||
81 | * *memberId* - The member/shopper ID |
||
82 | * *status* - The status of the transaction. If success, returns *0000* |
||
83 | ** _refer to document:"VP Web Service Format" for other possible status_ |
||
84 | * *errorCode* - the error code of the transaction. if success, returns *00000* |
||
85 | ** _refer to document:"VP Web Service Format" for other possible error code_ |
||
86 | * *errorMessage* - the detailed description of the error code |
||
87 | ** _refer to document:"VP Web Service Format" for other possible description_ |
||
88 | |||
89 | h3. Code Snippet |
||
90 | |||
91 | *Important note:* One should modify the following code to cater existing program so do not copy & paste it directly. |
||
92 | |||
93 | <pre> |
||
94 | <code class="JAVA"> |
||
95 | Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2"); |
||
96 | TransactionResponse vpResponse = new TransactionResponse(); |
||
97 | |||
98 | try { |
||
99 | vpResponse = VPServicesUtils.performRenewal(dbConnection, trxId, |
||
100 | 7 | chin-yeh | countryId, memberId, memberName, vpAmount, trxDate, regDate, expDate); |
101 | 4 | chin-yeh | |
102 | } catch (RemoteException ex) { |
||
103 | // do not ignore. either log the full stack trace or handle it |
||
104 | LOGGER.error(ex); |
||
105 | } catch (SQLException ex) { |
||
106 | // do not ignore. either log the full stack trace or handle it |
||
107 | 1 | chin-yeh | LOGGER.error(ex); |
108 | 4 | chin-yeh | } finally { |
109 | 1 | chin-yeh | if (dbConnection != null) { |
110 | 4 | chin-yeh | dbConnection.close(); |
111 | } |
||
112 | } |
||
113 | </code> |
||
114 | </pre> |
||
115 | |||
116 | |||
117 | 10 | chin-yeh | h2. Exception Handling Strategies |
118 | 4 | chin-yeh | |
119 | 10 | chin-yeh | The APIs would throw the following exceptions: |
120 | 4 | chin-yeh | * *RemoteException* - if there's any issue in communicating with VP |
121 | * *SQLException* - if there's any issue in persisting or updating the event |
||
122 | * *unchecked exception* - e.g. NullPointerException. This is more like a programming errors so do not catch it for whatever reasons. |
||
123 | 8 | chin-yeh | ** _note: catch the *Exception* will catch both checked & unchecked exception_ |
124 | 4 | chin-yeh | |
125 | The above exceptions should never be ignored, at least, the full error stack trace should be logged. |