Saddle Integration

For mapping or manipulating the messages of the channels, Saddle provides a powerful API called MessageLib. Each channel that uses templates encapsulates it’s messages with this API.

For accessing the message content, the user has to first call the channel, which provides access to the API. E.g. for writing the name of a loan condition to the destination channel “LoanConditions”, the call might look like:

getLoanConditions().getField(“/LoanCondition/Dataset/Name”).setValue(“Condition 1”);

As the message structure templates are XML, the required field is accessed via the x-path no-tation. As x-paths are case sensitive, it is very important to respect lower and upper case characters for referencing the right fields.

The statement above will work but bears some constraints and weaknesses:

Instance creation

Before a value is written to a field, it has to be created. This is not the case in the example. The API creates the first instance of a field automatically, if not existent. But for adding further instances to a repeating field a call of addInstance() is mandatory before setting a value. Otherwise the value of the first instance is overwritten.

The following code adds two instances of the field “RatePerMonth” (which is defined as repeating):

getLoanConditions().getField(“/LoanCondition/Dataset/RatePerMonth”).addInstance(-1, 250);
getLoanConditions().getField(“/LoanCondition/Dataset/RatePerMonth”).addInstance(-1, 320);

Now the first instance of dataset has two instances of the field RatePerMonth.
The following call would return 2:

getLoanConditions().getField(“/LoanCondition/Dataset/RatePerMonth”).getNumberOfInstances(); 

Using Field
Besides the x-path expressions , the MessageLib API provides another, more efficient way to access message fields. Saddle parses the message templates into trees, which store them as a structure of Java objects called Fields. The API can address those Field objects directly instead of resolving the x-paths to the corresponding Field-object first.

With using Fields, the example for adding two instances of the field “RatePerMonth” would look like follows:

Field currentField = getLoanConditions().getField(“/LoanCondition/Dataset/RatePerMonth”);
currentField = currentField.addInstance(-1 ,250);
currentField = currentField.addInstance(-1, 320);

This code snippet looks quite similar to the last example but with an important difference. When the field is first accessed by using its x-path, the function returns a reference to the Field object that represents the field. This Field object is directly used in the subsequent call without resolving the x-path again.

In the example above, it might not make a big difference but when it comes to working with others than the first instance, the advantage becomes obvious.

The following snippet creates 2 instances of the branch “data” in the destination channel “LoanConditions” and sets the field “Name” in each branch. The first version accomplishes that solely by using x-path expressions for addressing the fields.

X-path version:

getLoanConditions().getField("/LoanConditions/Dataset").addInstance();
getLoanConditions().getField(“/LoanCondition/Dataset/Name”).addInstance(”Condition 1”);
getLoanConditions().getField("/LoanConditions/Dataset").addInstance();
getLoanConditions().getField(“/LoanCondition/Dataset”).getInstance(2).getChild("Name").addInstance(”Condition 2”);

When the second instance is filled, it has to be explicitly referenced by calling getInstance(2).

The second version does exactly the same but is using the Fields directly.

Field-version:

Field currentBranch = getLoanConditions().getField("/LoanConditions/Dataset").addInstance();
curretnBranch.setChildValue(“Name”,  “Condition 1”);
currentBranch = curretnBranch.addInstance();
currentBranch.setChildValue(“Name”,  “Condition 2”);

The advantage becomes even clearer, when the values of repeating fields are read. The following snippet shows how the values of the “RatePerMonth”-field are read and the total amount that has to be paid is calculated:

X-path version:

double total = 0d;
int numRates = getSalary().getField(“/LoanCondition/Dataset/RatePerMonth”).getNumberOfInstances();
for (int counter = 0; counter < numRates; counter++){
 total += getLoanConditions().getField(“/LoanCondition/Dataset/RatePerMonth").getInstance(counter).getValueAsDouble();
}

First the number of total instances has to be determined and then the appropriate instance has to be fetched before the value can be read.

Node-version:

double total = 0d;
Field currentInstance = getLoanConditions().getField("/LoanConditions/Dataset/RatePerMonth").addInstance();
while (currentInstance != null){
 total += currentInstance.getValueAsDouble();
 currentInstance = currentInstance.getNextInstance();
}

The Field example allows to simply iterate through all instances untill the function getNextInstance() returns null, which indicates that the last instance had been processed. The Field-version is significantly faster than the x-path variant.

The MessageLib API provides a multitude of other methods for treating messages, which are not yet elaborated here. Descriptions of all functions can be found in the MessageLib API Java-Doc.

Questions, feature requests, or bug reports can be posted and discussed in the forum.