Java knowledge (and experience with additional libraries such as XMLBeans, SAX, DOM) is more commonly available than XQuery knowledge.

XQuery is very good at mining data from the source document and putting it into the destination document. However, it does not excel at complex flow logic, modularization, or computation. If you require any of these, you have two options:

• Write your basic flow in XQuery, as well as any simple transforms, and write the more complex parts in Java. Call the Java methods from XQuery.

  or

• Write everything in Java.

The size of the Service Model and Device Model depend on a number of factors:

• The number of instances of services of this kind that will go on one device.

• The size of an individual instance (for example, some PHB instances can get very large).

• The number of commands generated for an instance.

Typically, the larger the model, the more Java has to figure in the transformation, either through an XQuery framework seeded with Java callouts, or by using only Java.

With knowledgeable developers, XQuery typically delivers working cartridges earlier than Java. Prototyping is typically easier with XQuery.

The advantages of using XQuery are:

• Faster development cycles (at least, initially)

• Very rich language for the functionality it covers

• Easily field modifiable

The disadvantages to using XQuery are:

• Very primitive modularization concepts (and object orientation concepts)

• No schema awareness, limited type checking

• Control flow structures are difficult to use, especially beyond simple flow control

• Runtime exceptions come from Saxon and are difficult to debug

• Additional IDE for full developer convenience required (e.g. oXygen, XMLspy)

• Very easy to write sub-optimal code and XPath expressions (both in terms of memory use and execution time)

• Code flow must mimic the sequence and structure of the output XML document which leads to convoluted (spaghetti) code without a lot of constant effort

The advantages of using Java are:

• Full fledged programming language

• Multiple ways to deal with XML data

• Easier to layout responsibilities for behavior and data abstraction

• Can be written much faster

• Standard Java development, debugging, and profiling tools are enough

• Allows developer to greatly optimize the generation of the Device Model from the Service Model by viewing it as a set of modifications to be performed on (a copy of) the Last Device Model, rather than as a complete re-generation of the new Device Model

XQuery is not a procedural language, so care must be taken to not write code in a procedural fashion. The XQuery engines implement performance optimizations that can often cause side-effects when attempting to write procedural code with XQuery.

Consider the code below:

declare function myFunction($source as element()*) as xs:boolean
  {
  let $list := for $item in $source
    return
    $item/itemvalue
  return
    if (fn:count($list) > 0) then
      true()
    else
      false()
  ;

This code returns the correct Boolean value, but the inner loop may not execute on all possible items in the source. Optimizations may cause the loop to terminate once the following ‘if' expression is fully satisfied (i.e. there is something in the list).

This is just one example of how the optimizations take place. Many more can occur and most are driven by determining dependencies and the engine only evaluating things that need to be evaluated.

Another optimization example follows:

declare function myFunction2($source as element()*) as xs:boolean
  {
  let $list := myFunctionA ($source/element)
  let $list2 := myFunctionB ($source/element2)
  return
    $list
  

This can evaluate $list by calling the function myFunctionA, but the return value specifies only $list and not $list2 so myFunctionB may never be called.

Care must be taken while creating XQuery searches. XQuery always checks for all possible search combinations. In some cases, the application designer is aware that there is only a single match for something for a search item, but XQuery does not provide an accurate representation of it. Instead, it evaluates all the possible combinations. The easiest way to reduce the performance cost of a search is to be careful about the scope of all searches.

For more efficient searches, avoid searching with “//" as this causes two problems:

• Performance impact

• Can unexpectedly return results at different levels in the document. It is always better to be more explicit about scope.

The following points define the best practices while writing codes in XQuery:

• Care should be taken while writing loops, especially nested loops. Nested looping, even when constrained with a ‘where' clause, can be very risky. The behavior is very similar to general searching where all the possible combinations are evaluated.

• It is advisable to break code into separate modules, and use smaller functions wherever possible.

• Some functions are not always appropriate for implementing in XQuery. Very complex methods are more appropriate to do in Java. For example, cases where data can be held and stored in Maps instead of continually searching, are more appropriately done in Java.

You can enter any characters from the ASCII character set (0-255) in any text editor using the following procedure:

1. On your keyboard, press the Num Lock key so that Num Lock is turned on

2. Press and hold the Alt key

3. Using the keypad on your keyboard, enter the decimal code of the character as a 3 digit number, padded on the left with zeros, if necessary (for example, 009 for tab)

4. Release the Alt key

Alternatively, many text editors allow you to select control characters from a list for insertion. For example, in TextPad, use the command View->Clip Library.

In addition to entering ASCII characters on Windows editors like Notepad and Wordpad, there are ways to enter these characters in UNIX editors like vi and emacs.

For example:

• Ctrl + I = horizontal TAB (numerical decimal value = 9)

• Ctrl + J = Line Feed (10)

• Ctrl + M = carriage return (13)

Similar to the best practices for XQuery, the same care should be taken when using XPath statements to search for objects. This is most important when constructing the device model. Since you are creating the device model using Java, unlike with XQuery, you have random access to any part of the device model that you have already created. To improve search performance, use XmlCursor or even better, XmlBookmarks as you are creating the device model. The bookmarks allows you to quickly go back to a part of the device model you have created without using XPath to search for it.

When implementing an Sm2Dm transform in Java, you will need to create a class that extends the ModelTransformer class. Then you will need to provide two methods. The first is transform(), which the Network Processor will look for and call to perform the service model to device model transform.

The second method you must supply is getAppInfo(). This method is used to get the version of your device model. This value is used to determine if any upgrade procedures need to be done to your device model between releases of your cartridge.

An example of a skeleton Sm2Dm class follows:

public class Sm2dm extends ModelTransformer {
  public XmlObject transform(
    XmlObject doc,
    Map params,
    Map uris) throws Exception {
 
    // get the last DM
      com.metasolv.serviceactivator.devicemodel.DeviceDocument lastDm;
      try {
        lastDm = (com.metasolv.serviceactivator.devicemodel.DeviceDocument)((com.metasolv.serviceactivator.devicemodel.DeviceDocument)uris.get("last_dm")).copy();
      } catch (Exception e) {
      lastDm = null;
    }
 
    com.metasolv.serviceactivator.servicemodel.DeviceDocument sm;
    sm = (com.metasolv.serviceactivator.servicemodel.DeviceDocument)doc.copy();
 
    com.metasolv.serviceactivator.devicemodel.DeviceDocument targetDm;
 
    // Your transform here.
 
    return targetDm;
  }
 
  public XmlObject getAppInfo() {

    AppInfo appInfo = AppInfo.Factory.newInstance();
    appInfo.setVersion("1.0.0");
    return appInfo;
  }
}

When implementing a Dm2Cli transform in Java, you will need to create a class that extends the ModelTransformer class. Then, you will need to provide a method called transform() that the network processor will look for and call to perform the device mAn example of a skeleton Dm2Cli class is shown below:

An example of a skeleton Dm2Cli class is shown below:

public class AnnotatedDm2Cli extends ModelTransformer {
  public XmlObject transform(XmlObject doc, Map params, Map uris) throws Exception {
    com.metasolv.serviceactivator.devicemodel.DeviceDocument lastDm;
    try {
      lastDm = (com.metasolv.serviceactivator.devicemodel.DeviceDocument)uris.get("last_dm");
    } catch (Exception e) {
    lastDm = null;
  } 
 
  XmlObject annotatedDm = doc.copy();
 
  CommandSessionDocument commandSessionDoc;
 
  // Your transform here.
 
  return commandSessionDoc;
}odel to CLI transform.