Taiwan Services » DP Client

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

<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

<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

<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

<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

<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

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

h3. Code Snippets

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.