Project

General

Profile

Programming Guide » History » Revision 12

Revision 11 (chin-yeh, 08/26/2011 10:08 AM) → Revision 12/21 (chin-yeh, 08/26/2011 10:09 AM)

{{toc}} 

 h1. Programming Guide 

 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. 

 The Javadoc of *dp-client*: 
 > http://192.168.2.13:50000/dp_client_apidocs/ 

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

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

 h2. Query DP balance 

 Queries the available DP balance.  

 h3. Input Parameters 

 See "queryBalance":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html 

 h3. Output Parameters 

 The return object, *TransactionResponse* consists of: 
 * *process* - Sales1 
 * *transactionId* - the unique reference that passed in by the caller 
 * *countryId* - the country ID that passed in by the caller 
 * *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall. 
 * *memberId* - the member/shopper ID 
 * *status* - the status of the transaction. If success, returns *0000* 
 ** refer to document:"DP Web Services" for other possible status 
 * *balance* - the available DP balance 
 * *errorCode* - the error code of the transaction. if success, returns *00000* 
 ** refer to document:"DP Web Services" for other possible error code 
 * *errorMessage* - the detailed description of the error code  
 ** refer to document:"DP Web Services" for other possible description 


 h3. Code Snippet 

 <pre> 
 <code class="JAVA"> 
 TransactionResponse dpResponse; 
 try { 
   dpResponse = DPServicesUtils.queryBalance(countryCode, shopperId);  

 } catch (RemoteException ex) { 
   LOGGER.error("Error in connecting to web services", ex); 
 } 
 </code> 
 </pre> 

 h2. Impose Sales Lock 

 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. 

 h3. Input Parameters 

 See "imposeSalesLock":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html 

 h3. Output Parameters 

 The return object, *TransactionResponse* consists of: 
 * *process* - Sales1 
 * *transactionId* - the unique reference that passed in by the caller 
 * *countryId* - the country ID that passed in by the caller 
 * *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall. 
 * *memberId* - the member/shopper ID 
 * *status* - the status of the transaction. If success, returns *0000* 
 ** refer to document:"DP Web Services" for other possible status 
 * *balance* - the available DP balance 
 * *errorCode* - the error code of the transaction. if success, returns *00000* 
 ** refer to document:"DP Web Services" for other possible error code 
 * *errorMessage* - the detailed description of the error code  
 ** refer to document:"DP Web Services" for other possible description 

 h3. Code Snippet 

 <pre> 
 <code class="JAVA"> 
 TransactionResponse dpResponse; 
 try { 
   dpResponse = DPServicesUtils.imposeSalesLock(trxId, countryCode, shopperId); 

 } catch (RemoteException ex) { 
   LOGGER.error("Error in connecting to web services", ex); 
 } 
 </code> 
 </pre> 

 h2. Release Sales Lock 

 To be able to release the *Sales Lock*, one must provide the same *transaction ID*, which being used to impose the *Sales Lock*. 

 And, this method will return success status regardless if there's *Sales Lock* or not. 

 h3. Input Parameters 

 See "releaseSalesLock":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html 

 h3. Output Parameters 

 * *process* - Sales1 
 * *transactionId* - the unique reference that passed in by the caller 
 * *countryId* - the country ID that passed in by the caller 
 * *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall. 
 * *memberId* - the member/shopper ID 
 * *status* - the status of the transaction. If success, returns *0000* 
 ** refer to document:"DP Web Services" for other possible status 
 * *balance* - the available DP balance 
 * *errorCode* - the error code of the transaction. if success, returns *00000* 
 ** refer to document:"DP Web Services" for other possible error code 
 * *errorMessage* - the detailed description of the error code  
 ** refer to document:"DP Web Services" for other possible description 

 h3. Code Snippet 

 <pre> 
 <code class="JAVA"> 
 TransactionResponse dpResponse; 
 try { 
   dpResponse = DPServicesUtils.releaseSalesLock(trxId, countryCode, shopperId); 

 } catch (RemoteException ex) { 
   LOGGER.error("Error in connecting to web services", ex); 
 } 
 </code> 
 </pre> 


 h2. Commit Sales 

 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.  

 The *Commit Sales* and *Impose Sales Lock* could be invoked by 2 separate processes but both must use the same transaction ID. 

 This method will persist the transaction details into database. 

 h3. Input Parameters 

 See "performSalesCommit":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html 

 h3. Output Parameters 

 * *process* - Sales2 
 * *transactionId* - the unique reference that passed in by the caller 
 * *countryId* - the country ID that passed in by the caller 
 * *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall. 
 * *memberId* - the member/shopper ID 
 * *status* - the status of the transaction. If success, returns *0000* 
 ** refer to document:"DP Web Services" for other possible status 
 * *balance* - the available DP balance 
 * *errorCode* - the error code of the transaction. if success, returns *00000* 
 ** refer to document:"DP Web Services" for other possible error code 
 * *errorMessage* - the detailed description of the error code  
 ** refer to document:"DP Web Services" for other possible description 

 h3. Code Snippet 

 <pre> 
 <code class="JAVA"> 
 Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2"); 
 TransactionResponse dpResponse = new TransactionResponse(); 
 try { 
	 // impose sales lock before commit 
	 dpResponse = DPServicesUtils.imposeSalesLock(trxId, countryCode, shopperId); 
		
	 dpResponse = DPServicesUtils.performSalesCommit(dbConnection, 
				 trxId, countryCode, shopperId, 
				 trxDate, dpAmount, invoiceAmount); 
 } catch (RemoteException ex) { 
	 LOGGER.error("Error in connecting to web service", ex); 
 } catch (SQLException ex) { 
	 LOGGER.error("Error in persisting the event", ex); 
 } finally { 		
	 if (dbConnection != null) { 
	    dbConnection.close(); 
	 } 
 } 

 // release the Sales Lock in the event of exception  
 if (dpResponse == null || !"0000".equals(dpResponse.getStatus())) { 
    DPServicesUtils.releaseSalesLock(trxId, countryCode, shopperId); 
 } 

 </code> 
 </pre> 

 h2. Sales Return / Cancel Sales 

 This method is used to adjust the DP balance. There's no need to impose the *Sales Lock*. 

 h3. Input Parameters 

 See "performSalesReturn":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html 

 h3. Output Parameters 

 * *process* - SReturn 
 * *transactionId* - the unique reference that passed in by the caller 
 * *countryId* - the country ID that passed in by the caller 
 * *centerId* - possible value is *ONLINE*. It's used to differentiate if the caller are from POS system or online mall. 
 * *memberId* - the member/shopper ID 
 * *status* - the status of the transaction. If success, returns *0000* 
 ** refer to document:"DP Web Services" for other possible status 
 * *balance* - the available DP balance 
 * *errorCode* - the error code of the transaction. if success, returns *00000* 
 ** refer to document:"DP Web Services" for other possible error code 
 * *errorMessage* - the detailed description of the error code  
 ** refer to document:"DP Web Services" for other possible description 


 h3. Code Snippet 

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

 try { 
	 dpResponse = DPServicesUtils.performSalesReturn(dbConnection, trxId, countryCode,  
			 shopperId,trxDate, dpAmount, invoiceAmount); 	

 } catch (RemoteException ex) { 
	 LOGGER.error("Error in connecting to web service", ex); 
 } catch (SQLException ex) { 
	 LOGGER.error("Error in persisting the event", ex); 
 } finally { 
	 if (dbConnection != null) { 
		 dbConnection.close(); 
	 } 
 } 

 </code> 
 </pre> 


 h2. VIP Upgrade to BO 

 h3. Input Parameters 

 See "performVipUpgrade":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/dp_client/DPServicesUtils.html 

 h3. Output Parameters 

 h3. Code Snippet 


 h2. Generate the redirect URL for VIP Details page 

 h3. Input Parameters 

 See "vipDetailsPage":http://192.168.2.13:50000/dp_client_apidocs/com/ecosway/utils/DpRedirectUtils.html 

 h3. Output Parameters 

 h3. Code Snippet 



 h2. Exception Handling Strategies 

 The APIs would throw the following exceptions: 
 * *RemoteException* - if there's any issue in communicating with the DP 
 * *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.