Project

General

Profile

Actions
History

Wiki » Documentation »

Programming Guide

Refer to the Programming Guide for Batch Program if integrating in batch program

There are number of APIs provided by DP. All of these APIs are wrapped and exposed through a client application, 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:

SCM

Demo application of dp-client:

http://192.168.2.66:8080/dp-test/index.html

Query DP balance

Queries the available DP balance.

Method Signature:

public static TransactionResponse queryBalance(java.lang.String countryCode,
                                               java.lang.String memberId)
                                        throws java.rmi.RemoteException

Input Parameters

See queryBalance

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
  • balance - the available DP balance
  • errorCode - the error code of the transaction. if success, returns 00000
  • errorMessage - the detailed description of the error code

Code Snippets

TransactionResponse dpResponse;
try {
  dpResponse = DPServicesUtils.queryBalance(countryCode, shopperId); 

} catch (RemoteException ex) {
  LOGGER.error("Error in connecting to web services", ex);
}

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:

public static TransactionResponse imposeSalesLock(java.lang.String transactionId,
                                                  java.lang.String countryCode,
                                                  java.lang.String memberId)
                                           throws java.rmi.RemoteException

Input Parameters

See imposeSalesLock

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
  • balance - the available DP balance
  • errorCode - the error code of the transaction. if success, returns 00000
  • errorMessage - the detailed description of the error code

Code Snippets

TransactionResponse dpResponse;
try {
  dpResponse = DPServicesUtils.imposeSalesLock(trxId, countryCode, shopperId);

} catch (RemoteException ex) {
  LOGGER.error("Error in connecting to web services", ex);
}

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:

public static TransactionResponse releaseSalesLock(java.lang.String transactionId,
                                                   java.lang.String countryCode,
                                                   java.lang.String memberId)
                                            throws java.rmi.RemoteException

Input Parameters

See releaseSalesLock

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
  • balance - the available DP balance
  • errorCode - the error code of the transaction. if success, returns 00000
  • errorMessage - the detailed description of the error code

Code Snippets

TransactionResponse dpResponse;
try {
  dpResponse = DPServicesUtils.releaseSalesLock(trxId, countryCode, shopperId);

} catch (RemoteException ex) {
  LOGGER.error("Error in connecting to web services", ex);
}

Commit Sales

This method is used to deduct DP balance according to the provided amount. The 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:

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

Input Parameters

See performSalesCommit

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
  • balance - the available DP balance
  • errorCode - the error code of the transaction. if success, returns 00000
  • errorMessage - the detailed description of the error code

Code Snippets

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);
}

Sales Return / Cancel Sales

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

Method Signature:

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

Input Parameters

See performSalesReturn

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
  • balance - the available DP balance
  • errorCode - the error code of the transaction. if success, returns 00000
  • errorMessage - the detailed description of the error code

Code Snippets

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();
    }
}

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 validity period is determined by DP.

Method Signature:

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

Input Parameters

See performVipUpgrade

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
  • balance - the available DP balance
  • errorCode - the error code of the transaction. if success, returns 00000
  • errorMessage - the detailed description of the error code
  • expiryDate - the return value is in yyyyMMdd format. This indicates the validity of the remaining DP balance

Code Snippets

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();
    }
}

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:

public static java.util.Map<java.lang.String,java.lang.String> vipDetailsPage(java.lang.String memberId)

Input Parameters

See vipDetailsPage

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 section for the example.

Code Snippets

Must use HTTP POST method to submit the request to DP:

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

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.

Updated by chin-yeh almost 13 years ago · 21 revisions