Taiwan Services » VP Client

{{toc}}

h1. Programming Guide

There are number of APIs provided by VP. All of these APIs are wrapped and exposed through a client application, [[documentation#list-of-components|vp-client]]. Refer to the following sub sections for more information.

The Javadoc of *vp-client*:

> http://192.168.2.13:50000/vp_client_apidocs/

The binary or source files of *vp-client*:

> [[wiki#SCM|SCM]]

Demo application of *vp-client*:

> http://192.168.2.66:8080/vp-test/index.html

h2. VP Registration

This method is only applicable for *new registration*, which means the member/shopper ID *is not yet registered* with VP before.

_Method Signature:_

<pre>

<code class="JAVA">

public static TransactionResponse performRegistration(java.sql.Connection connection,

                                                      java.lang.String trxId,

                                                      java.lang.String countryId,

                                                      java.lang.String memberId,

                                                      java.lang.String memberName,

                                                      java.math.BigDecimal vpAmount,

                                                      java.util.Date trxDate,

                                                      java.util.Date regDate,

                                                      java.util.Date expDate)

                                               throws java.rmi.RemoteException,

                                                      java.sql.SQLException

</code>

</pre>

h3. Input Parameters

See "performRegistration":http://192.168.2.13:50000/vp_client_apidocs/com/ecosway/vp_client/VPServicesUtils.html#performRegistration%28java.sql.Connection,%20java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String,%20java.math.BigDecimal,%20java.util.Date,%20java.util.Date,%20java.util.Date%29

h3. Output Parameters

The return object, *TransactionResponse* consists of the following fields value:

* *process* - For registration, the possible value is *VRegister*

* *transactionId* - The unique reference that passed in by the caller

* *countryId* - The country ID/code that passed in by the caller

* *centerId* - To differentiate if the caller are from POS system or online

* *memberId* - The member/shopper ID

* *status* - The status of the transaction. If success, returns *0000* 

** _refer to document:"VP Web Service Format" for other possible status_

* *errorCode* - the error code of the transaction. if success, returns *00000* 

** _refer to document:"VP Web Service Format" for other possible error code_

* *errorMessage* - the detailed description of the error code 

** _refer to document:"VP Web Service Format" for other possible description_

h3. Code Snippet

*Important note:* One should modify the following code to cater existing program so do not copy & paste it directly.

<pre>

<code class="JAVA">

Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2");

TransactionResponse vpResponse = new TransactionResponse();

try {

	vpResponse = VPServicesUtils.performRegistration(dbConnection, trxId, 

			countryId, memberId, memberName, vpAmount, trxDate, regDate, expDate);

} catch (RemoteException ex) {

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

  LOGGER.error(ex);

} catch (SQLException ex) {

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

  LOGGER.error(ex);

} finally {

	if (dbConnection != null) {

		dbConnection.close();

	}

}

</code>

</pre>

h2. VP Renewal

This method is only applicable for renewal. If the member is not exist, VP will create the record in the background.

_Method Signature:_

<pre>

<code class="JAVA">

public static TransactionResponse performRenewal(java.sql.Connection connection,

                                                 java.lang.String trxId,

                                                 java.lang.String countryId,

                                                 java.lang.String memberId,

                                                 java.lang.String memberName,

                                                 java.math.BigDecimal vpAmount,

                                                 java.util.Date trxDate,

                                                 java.util.Date regDate,

                                                 java.util.Date expDate)

                                          throws java.rmi.RemoteException,

                                                 java.sql.SQLException

</code>

</pre>

h3. Input Parameters

See "performRenewal":http://192.168.2.13:50000/vp_client_apidocs/com/ecosway/vp_client/VPServicesUtils.html#performRenewal(java.sql.Connection,%20java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String,%20java.math.BigDecimal,%20java.util.Date,%20java.util.Date,%20java.util.Date)

h3. Output Parameters

The return object, *TransactionResponse* consists of the following fields value:

* *process* - For registration/renewal, the possible value is *VRegister*

* *transactionId* - The unique reference that passed in by the caller

* *countryId* - The country ID/code that passed in by the caller

* *centerId* - To differentiate if the caller are from POS system or online

* *memberId* - The member/shopper ID

* *status* - The status of the transaction. If success, returns *0000* 

** _refer to document:"VP Web Service Format" for other possible status_

* *errorCode* - the error code of the transaction. if success, returns *00000* 

** _refer to document:"VP Web Service Format" for other possible error code_

* *errorMessage* - the detailed description of the error code 

** _refer to document:"VP Web Service Format" for other possible description_

h3. Code Snippet

*Important note:* One should modify the following code to cater existing program so do not copy & paste it directly.

<pre>

<code class="JAVA">

Connection dbConnection = DBConnectionFactory.createDbConnection("java:/DB2DS2");

TransactionResponse vpResponse = new TransactionResponse();

try {

	vpResponse = VPServicesUtils.performRenewal(dbConnection, trxId, 

			countryId, memberId, memberName, vpAmount, trxDate, regDate, expDate);

} catch (RemoteException ex) {

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

  LOGGER.error(ex);

} catch (SQLException ex) {

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

  LOGGER.error(ex);

} finally {

	if (dbConnection != null) {

		dbConnection.close();

	}

}

</code>

</pre>

h2. Exception Handling Strategies

The APIs would throw the following exceptions:

* *RemoteException* - if there's any issue in communicating with VP

* *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.