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. 

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

  // do not ignore. either log the full stack trace or handle it

  LOGGER.error(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) {

  // do not ignore. either log the full stack trace or handle it

  LOGGER.error(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) {

  // do not ignore. either log the full stack trace or handle it

  LOGGER.error(ex);

}

</code>

</pre>

h2. Commit Sales

h3. Input Parameters

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

h3. Output Parameters

h3. Code Snippet

h2. Sales Return / Sales Exchange

h3. Input Parameters

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

h3. Output Parameters

h3. Code Snippet

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.