Programming Guide » History » Revision 19
Revision 18 (chin-yeh, 09/06/2011 04:19 PM) → Revision 19/21 (chin-yeh, 09/23/2011 10:10 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. _Method Signature:_ <pre> <code class="JAVA"> public static TransactionResponse queryBalance(java.lang.String countryCode, java.lang.String memberId) throws java.rmi.RemoteException </code> </pre> 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 Snippets 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. _Method Signature:_ <pre> <code class="JAVA"> public static TransactionResponse imposeSalesLock(java.lang.String transactionId, java.lang.String countryCode, java.lang.String memberId) throws java.rmi.RemoteException </code> </pre> 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 Snippets 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. _Method Signature:_ <pre> <code class="JAVA"> public static TransactionResponse releaseSalesLock(java.lang.String transactionId, java.lang.String countryCode, java.lang.String memberId) throws java.rmi.RemoteException </code> </pre> 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 Snippets 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. _Method Signature:_ <pre> <code class="JAVA"> public static TransactionResponse performSalesCommit(java.sql.Connection dbConnection, java.lang.String transactionId, java.lang.String countryCode, java.lang.String memberId, java.util.Date trxDate, java.math.BigDecimal dpAmount, java.math.BigDecimal invoiceAmount) throws java.rmi.RemoteException, java.sql.SQLException </code> </pre> 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 Snippets 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*. _Method Signature:_ <pre> <code class="JAVA"> public static TransactionResponse performSalesReturn(java.sql.Connection connection, java.lang.String transactionId, java.lang.String countryCode, java.lang.String memberId, java.util.Date trxDate, java.math.BigDecimal dpAmount, java.math.BigDecimal invoiceAmount) throws java.rmi.RemoteException, java.sql.SQLException </code> </pre> 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 Snippets 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. _Method Signature:_ <pre> <code class="JAVA"> public static TransactionResponse performVipUpgrade(java.sql.Connection connection, java.lang.String trxId, java.lang.String countryCode, java.lang.String memberName, java.lang.String memberId, java.lang.String newMemberId, java.util.Date trxDate) throws java.rmi.RemoteException, java.sql.SQLException </code> </pre> 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 Snippets 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:* * 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. _Method Signature:_ <pre> <code class="JAVA"> public static java.util.Map<java.lang.String,java.lang.String> vipDetailsPage(java.lang.String memberId) </code> </pre> 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 Snippets* Snippet* section for the example. h3. Code Snippets 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")); // Do Not use parameter. This is for demo purpose only. // Should get the shopper ID from session to prevent someone from hijack this page %> <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.