Project

General

Profile

Programming Guide » History » Version 8

chin-yeh, 08/10/2011 03:40 PM

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
h3. Exception Handling Strategies
67 1 chin-yeh
68 4 chin-yeh
This method would throws the following exceptions:
69 3 chin-yeh
* *RemoteException* - if there's any issue in communicating with VP
70
* *SQLException* - if there's any issue in persisting or updating the event
71
* *unchecked exception* - e.g. NullPointerException. This is more like a programming errors so do not catch it for whatever reasons.
72 8 chin-yeh
** _note: catch the *Exception* will catch both checked & unchecked exception_
73 3 chin-yeh
74
The above exceptions should never be ignored, at least, the full error stack trace should be logged.
75 2 chin-yeh
76 1 chin-yeh
h2. VP Renewal
77 4 chin-yeh
78
This method is only applicable for renewal. The member/shopper ID should have already registered with VP before.
79
80
h3. Input Parameters
81
82 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)
83 4 chin-yeh
84
h3. Output Parameters
85
86
The return object, *TransactionResponse* consists of the following fields value:
87
* *process* - For registration/renewal, the possible value is *VRegister*
88
* *transactionId* - The unique reference that passed in by the caller
89
* *countryId* - The country ID/code that passed in by the caller
90
* *centerId* - To differentiate if the caller are from POS system or online
91
* *memberId* - The member/shopper ID
92
* *status* - The status of the transaction. If success, returns *0000* 
93
** _refer to document:"VP Web Service Format" for other possible status_
94
* *errorCode* - the error code of the transaction. if success, returns *00000* 
95
** _refer to document:"VP Web Service Format" for other possible error code_
96
* *errorMessage* - the detailed description of the error code 
97
** _refer to document:"VP Web Service Format" for other possible description_
98
99
h3. Code Snippet
100
101
*Important note:* One should modify the following code to cater existing program so do not copy & paste it directly.
102
103
<pre>
104
<code class="JAVA">
105
Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2");
106
TransactionResponse vpResponse = new TransactionResponse();
107
108
try {
109
	vpResponse = VPServicesUtils.performRenewal(dbConnection, trxId, 
110 7 chin-yeh
			countryId, memberId, memberName, vpAmount, trxDate, regDate, expDate);
111 4 chin-yeh
112
} catch (RemoteException ex) {
113
  // do not ignore. either log the full stack trace or handle it
114
  LOGGER.error(ex);
115
} catch (SQLException ex) {
116
  // do not ignore. either log the full stack trace or handle it
117
  LOGGER.error(ex);
118
} finally {
119
	if (dbConnection != null) {
120
		dbConnection.close();
121
	}
122
}
123
</code>
124
</pre>
125
126
127
h3. Exception Handling Strategies
128
129
This method would throws the following exceptions:
130
* *RemoteException* - if there's any issue in communicating with VP
131
* *SQLException* - if there's any issue in persisting or updating the event
132
* *unchecked exception* - e.g. NullPointerException. This is more like a programming errors so do not catch it for whatever reasons.
133 8 chin-yeh
** _note: catch the *Exception* will catch both checked & unchecked exception_
134 4 chin-yeh
135
The above exceptions should never be ignored, at least, the full error stack trace should be logged.