Advanced User-Defined Functions

Use
Advanced user-defined functions can access more than just individual field values. Instead, you can
import a complete context or an entire queue for a field as an array before your function is called. This
enables you, for example, to perform calculations on all field values of a context as well as to divide up
the contexts themselves further by inserting context changes.
Integration
When the instance for a source structure is parsed, a message mapping works with queues.


There is a queue for each hierarchy level. A queue can have the following entries:
Possible Queue Entries
Value Meaning
(empty string) This is a queue for a structure field. In the queue there is an entry with an empty string each time the field appears in the XML instance. In the example above there is
such a queue for <A /> and <root />.
(string) Value of a value field
ResultList.CC Constant that shows a context change
ResultList.SUPPRESS Constant that causes a field and its subnode to be ignored during processing
(empty context) Context that does not contain any values (see the graphic below).
You can create special structure mappings by adding or removing context changes. The standard
functions SplitByValue and removeContexts() work by this principle.
See also: Structure Mappings by Setting the Context.
The following basic rule applies for nested structures: The number of contexts of a queue must be the
same as the number of values (empty strings) of the upper-level queue.

Features
Advanced user-defined functions can import either just one context into the input arrays, or complete
queues. Make your selection by selecting or deselecting the Cache Entire Queue checkbox in the
function editor.
Working with Contexts or Queues
Information in Cache Implications
Context Advanced functions that only import one context do not have an identifiable context change. You can of course insert a context change into the results list.
Queue Since one or more entire queues are imported in this case, this option is more memory-intensive and is not suitable for very large messages.
The input arrays do not contain the context change at the start and end of the context (or the queue).
These context changes are implicitly always available and cannot be identified or deleted from the user-
defined function.
Activities
1. Create an advanced user-defined function (see User-Defined Functions).
2. Process the values from the input arrays in the Java source text and create a results list by using
the ResultList object.


ResultList Object
Use
This object is used in advanced user-defined functions to return the result of the
function. If you save the entire queue before the call in the user-defined function, use
this object to either return a queue or to return the context of a queue.
Features
Methods of the Container Object
Method Use
void addValue(String value);
Appends a value to the results list
void addContextChange(); Appends a context change to the list. This can also be achieved if you append the constant ResultList.CC by
using addValue().
void addSuppress(); Appends the constant ResultList.SUPPRESS to the list. The generation of the target field and its sub nodes is
suppressed for such entries.
void clear(); Deletes all previously appended values from the list.
You can use the ResultList.CC constant to find context changes in the input array that
the function was transferred to, for example:
a[index].equals(ResultList.CC)
The following context changes are always available implicitly and are not part of the
input array.
If you only import one context into an input array before you call advanced functions, then the array
only contains values and no context change.
If you import an entire queue into an input array before you call the advanced functions, then there
is no context change at the start and the end of the array.
Example
This example shows the use of ResultList.SUPPRESS, in that the standard
function createIf() is programmed as an advanced user-defined function. This standard
function also works internally with the SUPPRESS constant:
If you specify true, an empty string is created for the field to be generated
If you specify false, createIf() creates the constant ResultList.SUPPRESS
If you implement this function as an advanced user-defined function, you just need to
import a constant from myCreateIf() prior to the call. The function has the following
source text:
public void myCreateIf(String[] a,
ResultList result,
Container container)
{
for ( int i = 0; i < a.length; i++ )
{
if( a[i].equals("true"))
result.addValue( );
else
result.addSuppress();
}
}