Project

General

Profile

Programming Guide » History » Revision 16

Revision 15 (chin-yeh, 08/26/2011 12:10 PM) → Revision 16/21 (chin-yeh, 08/26/2011 12:17 PM)

{{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 

 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.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 possibly be invoked by 2 different process 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 

 The return object, *TransactionResponse* consists of: 
 * *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 

 The return object, *TransactionResponse* consists of: 
 * *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 

 This method upgrades the VIP to BO. After upgraded, you have to use the *new member ID* for the subsequence operation, e.g. DP balance. Besides that, one must utilize all of the remaining DP balance in the limited period of time. The period is determined by DP. 

 h3. Input Parameters 

 See "performVipUpgrade":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* - Change 
 * *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 
 * *expiryDate* - the return value is in *yyyyMMdd* format. This indicates the validity of the remaining DP balance  


 h3. Code Snippet 

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

 try { 
	 dpResponse = DPServicesUtils.performVipUpgrade(dbConnection, trxId, countryCode, 
			 memberName, shopperId, newShopperId, trxDate); 

 } 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. Generate the redirect URL for VIP Details page 

 Generates the required form data which is needed to redirect member to the *DP VIP Details* page. 

 *Important Notes:*  
 * *Important:* At the moment, DP accepts *HTTP POST* method only. 
 * Prevent unauthorized access to the page or function which is being used to invoke this method. For example, retrieve the member ID from session instead of page request parameters. 

 h3. Input Parameters 

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

 h3. Output Parameters 

 The return object, key-value pairs consist of: 
 * *memberid* - the member/shopper ID 
 * *pin* - the PIN that provided by DP 
 * *expirydate* - when would the request expires 
 * *fingerprint* - the fingerprint of the request, it is an one-way hash value 

 One have to make use of the key-value pairs to construct the form. See *Code Snippet* section for the example. 

 h3. Code Snippet 

 Must use *HTTP POST* method to submit the request to DP: 
 <pre> 
 <code class="JAVA"> 
 <% 
	 Map<String, String> formData =  
		 DpRedirectUtils.vipDetailsPage(request.getParameter("shopperId")); 
 %> 

 <form id="frm" name="frm" method="<%=formData.get("method") %>" action="<%=formData.get("action") %>"> 
	 <input name="memberid" type="hidden" value="<%=formData.get("memberid") %>"/> 
	 <input name="pin" type="hidden" value="<%=formData.get("pin") %>"/> 
	 <input name="expirydate" type="hidden" value="<%=formData.get("expirydate") %>"/> 
	 <input name="fingerprint" type="hidden" value="<%=formData.get("fingerprint") %>"/> 
 </form> 

 <h3> 
 Please wait while we redirecting you to VIP Details page...  
 </h3> 

 <script language='javascript'> 
 function submitForm(){ 
    document.frm.submit(); 
 } 

 window.onload=submitForm ; 
 </script> 
 </code> 
 </pre> 


 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.