Navajo Basics

To learn how to use Navajo, you should know about its document model, written in XTML and the Navajo script language referred to as either XTSL or in the less-verbose variant: Navascript. You should also learn a little bit about extending Navajo in Java by writing custom Adapters and Functions. This page will give you an overview of the Navajo basics.

XTML: The Navajo Service Interface

Inside Navajo everything evolves around XTML (eXtended Transfer Markup Language). The purpose of XTML is to specify in a structured and uniform manner data to be consumed and produced by Navajo Services. In other words, the Navajo/Tipi framework can read and write solely in XTML. This strict conformence to XTML makes it a lot easier to write easy to understand Navajo Service scripts (XTSL).

XTML only contains the following tags:

  • <message>
  • <property>
  • <option>
  • <methods>
  • <method>

A <message> tag is used to group messages and properties.

A simple message:

  <message name="Simple">
     <property name="SomeProperty" value="34"/>
  </message>

A message can have nested messages:

   <message name="Parent">
      <message name="Child">
        <property name="SomeProperty" value="36"/>
      </message>
   </message>

A special ‘array’ (with attribute type=”array”) message contains repeated submessages with the same structure:

  <message name="Array" type="array">
     <message name="Array">
        <property name="SomeProperty" value="34"/>
     </message>
     <message name="Array">
        <property name="SomeProperty" value="36"/>
     </message>
  </message>

A property holds data in its value attribute or, if binary data is concerned, in its text node as base64 encoded data.

A property has a certain type in its type attribute: string, boolean, date, integer, float, money, clocktime, stopwatchtime, percentage, binary

A property has client specific information, e.g. information about its length, a description and whether it’s read-only or not specified in the direction attribute.

A special type of property, called a ‘selection’ property (with type=”selection”) contains a list op name/value pairs defined as children <option> tags.

Examples of properties:

  <property name="SomeString" type="string" value="Hello there!" length="255" direction="out" description="Some welcome text"/>
  <property name="SomeImage" type="binary" subtype="mime=image/gif" length="102" direction="out" description="Some welcome text">
R0lGODdhrABuAPcAAAAAAAEBAQICAgMDAwQEBAUFBQYGBgcHBwgICAkJCQoKCgsLCwwMDA0NDQ4O
Dg8PDxAQEBERERISEhMTExQUFBUVFRYWFhcXFxgYGBkZGRoaGhsbGxwcHB0dHR4eHh8fHyAgICEh
  </property>
  <property name="ADropdown" type="selection" cardinality="1" direction="in" description="Choose from the list">
     <option name="Car" value="C" selected="1"/>
     <option name="Boat" value="B" selected="0"/>
     <option name="Plane" value="P" selected="0"/>
  </property>

Using the <methods> tag, subsequent Navajo Services can be defined. A subsequent service typically consumes the XTML that is contained in the current XTML document.

  <methods>
    <method name="person/ProcessSearchPerson"/>
  </methods>

A more comprehensive account of the Navajo Document model can be found here:

The Navajo Document Model

In the next section we will go in more detail about what exactly defines a method or better a Navajo Service.

XTSL: Consuming and Producing XTML

The cornerstone of the Navajo framework is the Navajo Script, aka XTSL. Scripts are located in the ‘scripts’ directory of your Navajo installation. The scripts directory can have subdirectories to store the scripts. Each script is an XML file. The name of a Navajo service corresponds to the path + filename of the script file. E.g., if we have a file called ‘ProcessSearchPersons.xml’ in the subdirectory persons in the scripts path:

$NAVAJO_INSTALLATION/scripts/person/ProcessSearchPersons.xml

the corresponding unique ‘name’ of the Navajo Service will be:

‘person/ProcessSearchPersons’

XTSL represents the ‘start at the center’ approach to multi-tier application development.

A very simple XTSL scripts looks like this:

  <tsl>
  <message name="GroupingOfSomeData">
     <property name="Name" direction="in">
        <expression value="'Hello there' + [/Input/Me]"/>
     </property>
  </message>
  </tsl>

The purpose of an XTSL script is to process an XTML request and to produce an XTML response. Let’s analyze the above script:

  • <message name="GroupingOfSomeData">

This creates an XTML message “GroupingOfSomeData”

  • <property name="Name" direction="in">
          <expression value="'Hello there ' + [/Input/Me]"/>
    </property>

Creates a property “Name” with value defined in expression. The expression produces a string ‘Hello there ' concatenated with an XTML request property in a message “Input” which contains a property “Me”. The complete XTML request could have been something like:

  <xtml>
  <message name="Input">
     <property name="Me" type="string" value="Harry"/>
  </message>
  </xtml>

The response XTML of the above script would be:

  <xtml>
  <message name="GroupingOfSomeData">
     <property name="Name" direction="in" type="string" value="Hello there Harry"/>
   </message>
  </xtml>

A property has an attribute direction that specifies whether the value of the property can be changed by the caller upon calling a subsequent service using this XTML as the next input. The value of direction is either “in” or “out”. A property has a type that specifies the type of data. Supported types are: string, integer, date, boolean, float, money, percentage, clocktime, stopwatchtime, binary.

Synopsis

  • <message>, creates a <message>. A message has a name defined by its attribute “name”. A message groups other messages and properties (see <property>).
  • <property>, creates a <property>. A property contains data. A property has a name, defined by that attribute. A property has a type, defined by an attribute. The “direction” attribute specifies whether the property value is read-only or not.
  • <expression>, contains an expression that will be evaluated to the value of its parent property.
  • [], used for addressing properties in the request XTML.

Extending Navajo

The Java Connection

An XTSL scripts processes an XTML request to produce an XTML response. In order to to do something usefull it is not enough to just manipulate some properties of the incoming response. Real usability enters when a connection with Java is made. In the context of XTSL Java objects are called adapters that can be accessed via the <map> construct:

  <tsl>  
  <message name="SomethingInteresting">
     <map object="MyJavaAdapter"> 
         <field name="yourString">
            <expression value="[/Input/Me]"/>
         </field>
         <property name="LengthOfStringTimesTen" direction="out">
            <expression value="$stringLength * 10"/>
         </property>
     </map>
  </message>
  </tsl>

Later on we will explain how this Java object MyJavaAdapter should be implemented. Think of MyJavaAdapter as being a bean like object with setters and getters. For now let’s assume that the Java object has a setter method, “setYourString()”, that accepts a string type as input. A getter method, “getStringLength()”, returns the length of the given string. Within the <map> a <field> tags is used to call a setter method by defining the name of the ‘field’ in the “name” attribute. Within an expression a ‘field’ can be read by specifing the ‘field’ prefixed by the ‘$’ sign. Hence, within expressions we can both access input XTML properties, using the [<some property>] construct or Java getters using the $<some field> construct. For our previous XTML request, the above script would produce the following XTML response:

  <message name="SomethingInteresting">
    <property name="LengthOfStringTimesTen" type="integer" direction="out" value="50"/>
  </message>

Synopsis

  • <map>, this tag is used to instantiate a Java object specified in the attribute “object”.
  • <field>, to set the value of a public field in the Java object specified in the attribute “name”. Java counterpart of the XTML <property>.
  • $, prefix to read a public field of a Java object. Counterpart of the [] construct to read XTML

properties.

Producing Sets and Lists using a database adapter

Two things could come to mind right now:

  1. What about sets, lists, how are they supported?
  2. Should I start writing some Java Adapter first, before I can do something usefull?

The first and second question can be answered by demonstrating the single most practical adapter in the Standard Navajo Adapter Library, the SQLMap adapter, for directly accessing databases using its preferred SQL statement language:

  <tsl>  
    <map object="com.dexels.navajo.adapter.SQLMap">
       <field name="datasource">
          <expression value="'somedatabase'"/>
       </field>
       <field name="query">
          <expression>
            SELECT id, firstname, lastname FROM person WHERE lastname like ?
          </expression>
       </field>
       <field name="parameter">
          <expression value="[/Input/Me]"/>
       </field>
       <param name="Index">
          <expression value="0"/>
       </param>
       <message name="MatchingPersons">
          <map ref="resultSet">
             <property name="Count" direction="out">
                <expression value="[/@Index]"/>
             </property>
             <property name="Id" direction="out">
                <expression value="$columnValue('id')"/>
             </property>
             <property name="Name" direction="out">
                <expression value="$columnValue('firstname') + ' ' + $columnValue('lastname')"/>
             </property>
             <property name="FirstName" direction="in">
                <expression value="$columnValue('firstname')"/>
             </property>
             <param name="Index">
                <expression value="[/@Index] + 1"/>
             </param>       
           </map>
        </message>
     </map>
   </tsl>

Two new things are introduced: <map ref=""> and <param> constructs. The <map ref=""> construct is used to ‘map’ a complex field to an XTML <message>. Two types of complex fields exist:

  1. A field that returns another Adapter.
  2. A field that returns an array of Adapters.

The first case does not need much explanation. It can be usefull to return an ‘object’ instead of a primitive value for a field. The second case gives us Sets, List, etc. An array of objects is returned. How is this represented in XTML? Well, by introducing a special message, the array message. It looks in the above case like this:

  <message name="MatchingPersons" type="array">
    <message name="MatchingPersons"> 
       <property name="Count" direction="out" type="integer" value="0"/>
       <property name="Id" direction="out" type="integer" value="3455"/>
       <property name="Name" direction="out" type="string" value="William Helmsman"/>
       <property name="FirstName" direction="in" type="string" value="William"/>
    </message>
    <message name="MatchingPersons"> 
       <property name="Count" direction="out" type="integer" value="1"/>
       <property name="Id" direction="out" type="integer" value="4356"/>
       <property name="Name" direction="out" type="string" value="Henry Hillford"/>
       <property name="FirstName" direction="in" type="string" value="Henry"/>
    </message>
  </message>

The runtime finds out whether the ‘mapped’ field is a single Adapter or an array of Adapters. In the first case it maps directly to the parent message definition. In the second case, an array message is created automatically using the defined message name.

The <param> tag can be used to store script local properties. Param properties can both be created and accessed within a script.

Synopsis

  • <map ref="">, used for mapping a ‘complex’ field like an adapter field or a field of array of adapters to a <message>.
  • <message type="array">, an array message. Array messages contain repetitive submessages with the same property structure
  • <param>, for storing local script data.

Consuming Array Messages and Nesting Adapters

Using the response XTML of the above script, we will demonstrate how to process an XTML request that contains an array message, take the XTML response of the previous paragraph.

  <tsl>
     <map object="com.dexels.navajo.adapter.MultipleEmptyMap">
        <field name="emptyMaps">
            <map ref="/MatchingPersons">
                <map object="com.dexels.navajo.adapter.SQLMap">
                   <field name="datasource">
                     <expression value="'somedatabase'"/>
                   </field>
                   <field name="update">
                     <expression>
                       UPDATE person
                       SET firstname = ?
                       WHERE id = ?
                     </expression>
                   </field>
                   <field name="parameter">
                      <expression value="[FirstName]"/>
                   </field>
                   <field name="parameter">
                      <expression value="[Id]"/>
                   </field>
                   <field name="doUpdate">
                      <expression value="true"/>
                   </field>
                </map>
            </map>
        </field>
     </map>
  </tsl>

Synopsis

  • <map ref="/">, used for mapping a message or an array message to a ‘complex’ field accepting an adapter(single message) or an array of adapters(array message).
  • <map> tags can be nested.
  • Properties can be accessed relatively from a ‘mapped’ array message using [<property name>] construct with the leading slash (/).

More about extending Navajo with Adapters and Functions

Take a look at the Standard Navajo Adapter Library

For writing your own adapters check out this.

Functions you can use can be found in the Standard Navajo Function Library

For writing your own functions check out this.

→ Next step: XTSL API

doc/navajotutorial.txt · Last modified: 2010/09/30 11:13 by matthijs
www.chimeric.de Creative Commons License Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0