Introduction

This document explains the concept of AppCode and how it can be used to build DBSync Adapters
The following step by step story board explains the following:
1: What is AppCode ?
2: How to write an AppCode project and create an AppCode Service ?
3. How to write a test case for an AppCode Service?
4: How to build and deploy an AppCode project on dbsync2 ?
5: How to use it in dbsync profiles and execute a process flow?

Pre-Requisites

1. JDK 7
2. Eclipse IDE (Enterprise developers)
3. Local DBSync setup

StoryBoard

1. Create a new Java Project in Eclipse IDE

2.Now add the dbysnc-sdk.jar in the dependencies lib folder and other necessary jar files

3. Now add the jars to the project dependencies class path and configure the build path in eclipse by using "Add Jars" button and then adding the jars present in the lib folder

4. Now create your main AppCode Implementation class.

Note : Each AppCode implementation must implement com.appmashups.appcode.AppCode interface

5. Now implement the default methods exposed by the AppCode interface

5.1 Open – Method called , from the JavaAdapter to initialize the adaper resources if any so that the latter can be used during the sync operation
5.2 Close – Method called by JavaAdapter to close the AppCode service and release its resources if it is holding up any

5.3 setContext – Utility method exposed to allow Java Adapter to set the context with the necessary properties



6. Now see an example of how we have implemented app-code for MSNav.

7.Please note that before we start writing any reader or writer methods in the app code service we need to import the SOAP WSDL classes into the project for being able to access the necessary entities and their fields and mappings

For this we can make use of the build script "appcode-deploy,xml" which is checked in under msnav2013 module under dbsync2_1 project in the CVS repository. The same needs to be copied into the "appcode-build" folder under the project

8.Now change the relevant values in the appcode-deploy.xml file to point to the relevant locations and set the necessary properties

<!-- set global properties for this build -->
<!-- Setup Deployment specific properties -->
<property name="appcode.name" value="MyTestMsNavSvc" /> 
– The name of the appcode project —
<property name="appcode" location="/AvankiaWS2/MyAppCodeSvc"/>
— The location of the appcode project in your machine —
<property name="environment" value="sandbox" />
— The environment under which the jars will be deployed in dbsync2 ( folder under the profile folder) —
<property name="profile" value="profile_test" />
---- Name of the profile ----
<property name="dbsync.server.url" value="http://localhost:8080/dbsync2"/>
— DBSync2 server URL -----
<property name="dbsync.server.username" value="localhost@avankia.com"/>
— DBSync2 UID ----
<property name="dbsync.server.password" value="avankia"/>
---- DBsync2 Password — 

Note: The DBSync2 Properties are actually required to deploy the zip file in DBSync2 server location which the DBSync2 server is running

9. Assuming we are trying to do a a SOAP call in our AppCode Service implementation, we need to run a wsimport task to download the binding classes into our project and for future use for reading, writing and getmetadata operations

<!-- Additional properties to pass the wsdl filenames -->
<property name="customer_wsdl" value="Customer.wsdl"> </property>
<property name="salesinv_wsdl" value="SalesInvoice.wsdl"> </property> 
<!-- added for running wsimport -->
<property name="java_home" value="/Library/Java/JavaVirtualMachines/jdk1.7.0_55.jdk/Contents/Home"/> 

<target name="wsimport" depends="init">
<exec executable="$\{java_home\}/bin/wsimport">
<arg line="-keep -s $\{appcode\}/generated-src -d $\{appcode\}/generated-classes $\{appcode\}/$\{customer_wsdl\}"/>
</exec> 
<exec executable="$\{java_home\}/bin/wsimport">
<arg line="-keep -s $\{appcode\}/generated-src -d $\{appcode\}/generated-classes $\{appcode\}/$\{salesinv_wsdl\}"/>
</exec> 
<jar destfile="$\{appcode.lib\}/generatedwsdlclasses.jar" basedir="$\{appcode\}/generated-classes"/>
</target> 

<target name="init">
<!-- Create the time stamp -->
<tstamp/>
<mkdir dir="$\{deploy.dir\}"/>
<mkdir dir="$\{compile.dir\}"/>
<mkdir dir="$\{deploy.dir\}/zip"/>
<!-- add src and target files -->
<delete dir="$\{appcode\}/generated-src"/>
<delete dir="$\{appcode\}/generated-classes"/>
<mkdir dir="$\{appcode\}/generated-src"/>
<mkdir dir="$\{appcode\}/generated-classes"/> 

<delete file="$\{deploy.dir\}/$\{appcode.name\}.jar"></delete> 
<delete file="$\{deploy.dir\}/zip/$\{appcode.name\}.zip"></delete> 
<delete file="$\{appcode.lib\}/generatedwsdlclasses.jar"></delete> 
</target> 

Run the ant task with target as wsimport to generate the SOAP binding classes along with the classes and source code


You can see the sample output below:

10. Now you can start using the generated classes in your AppCode project



Note: Due to limitations in the existing DbSync mapping algorithm which cannot allow certain nested hierarchies, we need to create DBSync Compatible Wrapper classes to allow the metadata binding with the conversion processor
Please refer to msnav2013 project where we have created necessary wrapper classes to do the metadata binding

The main functions of the wrapper classes are to convert from the DBSync compatible type to the underlying SOAP type and Vice Versa

public class Customer {
<properties
and methods
public static Customer createCustomer(CustomerCard card) {
Customer newObject = new Customer();
newObject.setKey(card.getKey());
newObject.setNo(card.getNo());
////Set other attributes
return newObject;
}
public static CustomerCard createCustomerCard(Customer customer) throws DatatypeConfigurationException {
CustomerCard card = new CustomerCard();
 card.setKey(customer.getKey());
 card.setNo(customer.getNo());  
//set other attributes
return card;
}
}

11. Build the filter classes to be used in the reader classes 

They will be responsible for filtering the data in the read queries. Please refer to CustomerFilter and SalesInvoiceFilter in MsNav

 public class CustomerFilter{
     public CustomerFilter(){}
     public String key;
     public String No;
     public String Name;
}