Project

General

Profile

Programming Guide » History » Revision 10

Revision 9 (chin-yeh, 08/17/2011 03:20 PM) → Revision 10/13 (chin-yeh, 08/25/2011 11:18 AM)

{{toc}} 

 h1. Programming Guide 

 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. 

 The Javadoc of *vp-client*: 
 > http://192.168.2.13:50000/vp_client_apidocs/ 

 The binary or source files of *vp-client*: 
 > [[wiki#SCM|SCM]] 

 Demo application of *vp-client*: 
 > http://192.168.2.66:8080/vp-test/index.html 

 h2. VP Registration 

 This method is only applicable for *new registration*, which means the member/shopper ID *is not yet registered* with VP before. 

 h3. Input Parameters 

 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 

 h3. Output Parameters 

 The return object, *TransactionResponse* consists of the following fields value: 
 * *process* - For registration, the possible value is *VRegister* 
 * *transactionId* - The unique reference that passed in by the caller 
 * *countryId* - The country ID/code that passed in by the caller 
 * *centerId* - To differentiate if the caller are from POS system or online 
 * *memberId* - The member/shopper ID 
 * *status* - The status of the transaction. If success, returns *0000*  
 ** _refer to document:"VP Web Service Format" for other possible status_ 
 * *errorCode* - the error code of the transaction. if success, returns *00000*  
 ** _refer to document:"VP Web Service Format" for other possible error code_ 
 * *errorMessage* - the detailed description of the error code  
 ** _refer to document:"VP Web Service Format" for other possible description_ 

 h3. Code Snippet 

 *Important note:* One should modify the following code to cater existing program so do not copy & paste it directly. 

 <pre> 
 <code class="JAVA"> 
 Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2"); 
 TransactionResponse vpResponse = new TransactionResponse(); 

 try { 
	 vpResponse = VPServicesUtils.performRegistration(dbConnection, trxId,  
			 countryId, memberId, memberName, vpAmount, trxDate, regDate, expDate); 

 } catch (RemoteException ex) { 
   // do not ignore. either log the full stack trace or handle it 
   LOGGER.error(ex); 
 } catch (SQLException ex) { 
   // do not ignore. either log the full stack trace or handle it 
   LOGGER.error(ex); 
 } finally { 
	 if (dbConnection != null) { 
		 dbConnection.close(); 
	 } 
 } 
 </code> 
 </pre> 

 h3. Exception Handling Strategies 

 This method would throws the following exceptions: 
 * *RemoteException* - if there's any issue in communicating with VP 
 * *SQLException* - if there's any issue in persisting or updating the event 
 * *unchecked exception* - e.g. NullPointerException. This is more like a programming errors so do not catch it for whatever reasons. 
 ** _note: catch the *Exception* will catch both checked & unchecked exception_ 

 The above exceptions should never be ignored, at least, the full error stack trace should be logged. 

 h2. VP Renewal 

 This method is only applicable for renewal. If the member is not exist, VP will create the record in the background. 

 h3. Input Parameters 

 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) 

 h3. Output Parameters 

 The return object, *TransactionResponse* consists of the following fields value: 
 * *process* - For registration/renewal, the possible value is *VRegister* 
 * *transactionId* - The unique reference that passed in by the caller 
 * *countryId* - The country ID/code that passed in by the caller 
 * *centerId* - To differentiate if the caller are from POS system or online 
 * *memberId* - The member/shopper ID 
 * *status* - The status of the transaction. If success, returns *0000*  
 ** _refer to document:"VP Web Service Format" for other possible status_ 
 * *errorCode* - the error code of the transaction. if success, returns *00000*  
 ** _refer to document:"VP Web Service Format" for other possible error code_ 
 * *errorMessage* - the detailed description of the error code  
 ** _refer to document:"VP Web Service Format" for other possible description_ 

 h3. Code Snippet 

 *Important note:* One should modify the following code to cater existing program so do not copy & paste it directly. 

 <pre> 
 <code class="JAVA"> 
 Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2"); 
 TransactionResponse vpResponse = new TransactionResponse(); 

 try { 
	 vpResponse = VPServicesUtils.performRenewal(dbConnection, trxId,  
			 countryId, memberId, memberName, vpAmount, trxDate, regDate, expDate); 

 } catch (RemoteException ex) { 
   // do not ignore. either log the full stack trace or handle it 
   LOGGER.error(ex); 
 } catch (SQLException ex) { 
   // do not ignore. either log the full stack trace or handle it 
   LOGGER.error(ex); 
 } finally { 
	 if (dbConnection != null) { 
		 dbConnection.close(); 
	 } 
 } 
 </code> 
 </pre> 


 h2. h3. Exception Handling Strategies 

 The APIs This method would throw throws the following exceptions: 
 * *RemoteException* - if there's any issue in communicating with VP 
 * *SQLException* - if there's any issue in persisting or updating the event 
 * *unchecked exception* - e.g. NullPointerException. This is more like a programming errors so do not catch it for whatever reasons. 
 ** _note: catch the *Exception* will catch both checked & unchecked exception_ 

 The above exceptions should never be ignored, at least, the full error stack trace should be logged.