Programming Guide » History » Revision 11
Revision 10 (chin-yeh, 08/25/2011 05:42 PM) → Revision 11/21 (chin-yeh, 08/26/2011 10:08 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.
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); // 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) {
LOGGER.error("Error in connecting to web services", 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) {
LOGGER.error("Error in connecting web services", ex); // do not ignore. either log the full stack trace or handle it
LOGGER.error(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 be invoked by 2 separate processes 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
* *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);
// do not ignore. either log the full stack trace or handle it
LOGGER.error(ex);
} catch (SQLException ex) {
LOGGER.error("Error in persisting
// do not ignore. either log the event", ex);
full stack trace or handle it
LOGGER.error(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
* *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
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.