Understanding AppCode and its Usage

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

JDK 7
Eclipse IDE (Enterprise developers)
Local DBSync setup

StoryBoard

Create a new Java Project in Eclipse IDE

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

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

Now create your main AppCode Implementation class.

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

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

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

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

Now change the relevant values in the appcode-deploy.xml file to point to the relevant locations and set the necessary 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

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

<property name="customer_wsdl" value="Customer.wsdl"> </property>
<property name="salesinv_wsdl" value="SalesInvoice.wsdl"> </property>

<property name="java_home" value="/Library/Java/JavaVirtualMachines/jdk1.7.0_55.jdk/Contents/Home"/>

<target name="wsimport" depends="init">
<exec executable="$

Unknown macro: {java_home}

/bin/wsimport">
<arg line="-keep -s $

Unknown macro: {appcode}

/generated-src -d $

/generated-classes $

Unknown macro: {appcode}

/$

Unknown macro: {customer_wsdl}

"/>
</exec>
<exec executable="$

/bin/wsimport">
<arg line="-keep -s $

Unknown macro: {appcode}

/generated-src -d $

/generated-classes $

Unknown macro: {appcode}

/$

Unknown macro: {salesinv_wsdl}

"/>
</exec>
<jar destfile="$

Unknown macro: {appcode.lib}

/generatedwsdlclasses.jar" basedir="$

/generated-classes"/>
</target>

<target name="init">

<tstamp/>
<mkdir dir="$

Unknown macro: {deploy.dir}

"/>
<mkdir dir="$

Unknown macro: {compile.dir}

"/>
<mkdir dir="$

/zip"/>

<delete dir="$

Unknown macro: {appcode}

/generated-src"/>
<delete dir="$

/generated-classes"/>
<mkdir dir="$

Unknown macro: {appcode}

/generated-src"/>
<mkdir dir="$

/generated-classes"/>

<delete file="$

Unknown macro: {deploy.dir}

/$

Unknown macro: {appcode.name}

.jar"></delete>
<delete file="$

/zip/$

Unknown macro: {appcode.name}

.zip"></delete>
<delete file="$

Unknown macro: {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
E.g.
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;

}

12. Open Method
This method is the place where all the authentication happens. Each AppCode can by default take the following three parameters as Adapter Properties
userName = ctx.getPropertyAsString("username"); //User name for accessing service
password = ctx.getPropertyAsString("password"); //Password for accessing the service
baseURL = ctx.getPropertyAsString("baseURL"); //BaseUrl for making the soap call
In this method the actual authentication happens which is more of a one time in the reader and writer call

Authenticator.setDefault(new MyAuthenticator());
try {
log.finer("Customer Service: INIT");
URL customerURL = new URL(baseURL + "/CustomerCard");
QName customerQName = new QName(
"urn:microsoft-dynamics-schemas/page/customercard",
"CustomerCard_Service");
CustomerCardService customerCardService = new CustomerCardService(
customerURL, customerQName);
customerCardPort = customerCardService.getCustomerCardPort();
log.finer("SalesInvoice Service: INIT");
URL salesInvoiceURL = new URL(baseURL + "/SalesInvoice");
QName salesInvoiceQName = new QName(
"urn:microsoft-dynamics-schemas/page/salesinvoice",
"SalesInvoice_Service");
SalesInvoiceService sis = new SalesInvoiceService(salesInvoiceURL,
salesInvoiceQName);
sip = sis.getSalesInvoicePort();
batchSize = Integer.parseInt(ctx.getPropertyAsString("batchSize"));
} catch (Exception e) {
log.log(Level.SEVERE,
"Customer/SalesInvoice Service Initialization Failed", e);
e.printStackTrace();
throw new RemoteException(
"Customer/SalesInvoice Service Initialization Failed", e);
}

13. Read and Write Methods
An AppCode implementation service can either have a read or write method exposed for reader and writer
The Reader Syntax is as follows:
/*
* Method to read a list of customers in MsNav Takes in a variable arguments
* of CustomerFilter as input and returns a list of Customer objects
*/
public List<Customer> readCustomer(CustomerFilter filter) throws Exception {

//Read operation
}
Inside a reader method, data is fetched using a relevant SOAP call with the necessary filter applied and the data fetched from the SOAP call is wrapped into the dbsync compatible output wrapper class

try {
// Modified by Sambit to check for null for the filter object
if (null != filter) {
for (Field field : CustomerFilter.class.getFields()) {
CustomerCardFilter cusCardFilter = null;
Object value = getFieldValue(field, filter);
if (value != null
&& !((String) value).trim().equalsIgnoreCase("")) {
cusCardFilter = new CustomerCardFilter();
String fldName = field.getName().substring(
field.getName().lastIndexOf(".") + 1);
// CustomerCardFields.valueOf(CustomerCardFields.NO.toString());
//System.out.println(CustomerCardFields.NO.toString());
cusCardFilter.setField(CustomerCardFields
.valueOf(fldName.toUpperCase()));
cusCardFilter.setCriteria((String) value);
custCardFilterList.add(cusCardFilter);
}
}//for
}//if(null != filter)
// if there are more elements to read or it is the first read
if (repositionKey == null || hasMoreElements()) {
CustomerCardList cList = null;
if (repositionKey == null) {
cList = customerCardPort.readMultiple(custCardFilterList,
"", batchSize);
} else {
cList = customerCardPort.readMultiple(custCardFilterList,
repositionKey, batchSize);
}
int cCount = cList.getCustomerCard().size();
for (int i = 0; i < cCount; i++) {
CustomerCard cusCard = (CustomerCard) cList
.getCustomerCard().get(i);
/*
* Customer cusw = new Customer();
* cusw.setCustomerCard(cusCard);
*/
// Customer cusw =
// (Customer)ClassConverter.convertToClass(cusCard,
// Customer.class);
Customer cusw = Customer.createCustomer(cusCard);
customers.add(cusw);
}
if (customers.size() == batchSize) {
// Get the last element in the list of customers to get the
// repositionkey
Customer cusw = customers.get(batchSize - 1);
repositionKey = cusw.getKey();
} else {
repositionKey = "-1";
}
}
} catch (Exception e) {
e.printStackTrace();
log.log(Level.SEVERE, "Error while reading customers from MSNAV", e);
throw e;
}

return customers;
Note: Please note that it is important for the service to implement its own batching mechanism as otherwise the calls can go to an infinite loop as the JavaAdapter keeps on calling the service class till it gets a null or an empty list assuming the batching is handled by the latter

The Writer Syntax is as follows:

public SaveResult[] createCustomer(List<Customer> custList) {
}
It takes a list of entities as the input and returns back an array of saveresults.
In the process, the input entities are converted into the relevant SOAP types and then are sent as a part of the SOAP request to perform a create or an update operation
Batching is not mandatory in this case as already the conversion processor performs necessary batching

List<SaveResult> saveResultList = new ArrayList<SaveResult>();
try {
CustomerCardList customerCardList = new CustomerCardList();
// int batchVal = 0;
// Keep a list of batches to flush at the end of the
// for loop
// List<Holder> batchHolders = new ArrayList<Holder>();
// This the counter for each batch
int eachBatchCounter = 0;
Holder<CustomerCardList> holder = new Holder<CustomerCardList>();
for (Customer ccw : custList) {
// Customer ccw = custList.get<ac:emoticon ac:name="information" />;
++eachBatchCounter; // Increment the counter
// Added by sambit for key
if (ccw.getNo() != null) {
if (ccw.getNo().trim().equals("")) {
ccw.setNo(null);
}
}
/*
* CustomerCard cc0 = ccw.getCustomerCard();
*
* ccl.getCustomerCard().add(cc0);
*/
// CustomerCard cc0 =
// (CustomerCard)ClassConverter.convertToClass(ccw,
// CustomerCard.class);
CustomerCard cc0 = Customer.createCustomerCard(ccw);
customerCardList.getCustomerCard().add(cc0);
// If the batch limit is reached or the last element is being
// read
if (hasBatchLimitReached(eachBatchCounter)

isEndOfList(custList.size(), eachBatchCounter)) {
// Set the holder value
holder.value = customerCardList;
// flush the batch
flushCustomerBatch(holder, saveResultList, true);
// now clear the list
customerCardList.getCustomerCard().clear();
// and reset the counter and holder object
holder.value = null;
eachBatchCounter = 0;
}
/*
* if (customer.getCustomerCard().size() == batchSize) {
* customerCardPort.createMultiple(hccl);
*
* List<CustomerCard> ccs = hccl.value.getCustomerCard();
*
* // Resetting local Variables ccl = new CustomerCardList();
* hccl = new Holder<CustomerCardList>(); SaveResult sr = null;
* for (int j = 0; j < ccs.size(); j++) { // SaveResults sr =
* new SaveResult(); sr.success = true; String id =

ccs.get(j).getNo(); sr.newid = id; srArray[batchVal] = sr;

* batchVal++; } }
*/
}
/*
* if (customerCardList.getCustomerCard().size() > 0) {
*
* // Do batching now Holder<CustomerCardList> batchholder = new
* Holder<CustomerCardList>();
*
* customerCardPort.createMultiple(hccl); List<CustomerCard> ccs =
* hccl.value.getCustomerCard(); SaveResult sr = null; for (int j =
* 0; j < ccs.size(); j+) { +sr = new SaveResult(); sr.success =
* true; String id = ccs.get(j).getNo(); sr.newid = id;

srArray[batchVal] = sr; batchVal++; } }

*/
} catch (Exception e) {
e.printStackTrace();
log.severe("Error while creating customers in MSNav:"
+ e.getMessage());
}
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="0d60f311-9c53-42f7-8eb2-d7c67f4a448d"><ac:plain-text-body><![CDATA[ return saveResultList.toArray(new SaveResult[] {});]]></ac:plain-text-body></ac:structured-macro>
}

14. Deployment Process
The AppCode is bundled into a zip file and is deployed as a zip file into the environment specified in the appcode-deploy.xml file.
The environment name is specified in the "environment" attribute
<property name = "environment" value = "sandbox" />
The details about the appcode-deployx.xml parameters has been mentioned previously
By default the target is deploy which does the following:

init
wsimport
build
zip
deploy

For the deploy target to work, your dbsync location which you have specified in the appcode-deploy.xml file must be running

15. Viewing the Profile List
Select the profile which you have used to deploy the AppCode. In this case it is profile_test

16. Java Adapter Properties
Set the adapter properties for the Java Adapter
Classpath – same as environment
Username – SOAP Service username
Password – SOAP Service Password
BaseURL – SOAP Service BaseURL

17. View the Metadata
View the metadata of the service to select and map

Page tree

Understanding-AppCode

Introduction

Pre-Requisites

StoryBoard