Two Minute Tutorial

Having seen in the One Minute Tutorial how to creat a simple CAM template there is a need to understand a few more of the functions and also some of the other jCam options that are available to the user.

The following is a list of the functions available to the CAM template developer:

        <as:constraint action="setDateMask(//t:maskTests/t:time,'HH MI SS')"/>
        <as:constraint action="setChoice(//t:choices/*)"/>
        <as:constraint action="setChoice(//t:choices1/*)"/>
        <as:constraint action="setChoice(//t:choices2/*)"/>
        <as:constraint action="setChoice(//t:choices3/*)"/>
        <as:constraint action="makeMandatory(//t:mandatoryField)"/>
        <as:constraint action="makeOptional(//t:optionalField)"/>
        <as:constraint action="makeOptional(//t:optionalField2)"/>
        <!-- special case of needing single quotes around the the values-->
        <as:constraint action="restrictValues(//t:restrictValuesField,'A'|'B'|'C')"/>
        <as:constraint action="setValue(//t:setValueField,Value)"/>
        <as:constraint action="setLength(//t:setLengthField,10)"/>
        <as:constraint action="setID(//t:setIDField,'IDfield')"/>
        <as:constraint action="setDateMask(//t:dateMask,'YYYY-MM-DDTHH:MI:SS-HH:MI')"/>
        <as:constraint action="setNumberMask(//t:numberMask,'####')"/>
        <as:constraint action="setStringMask(//t:stringMask,'XXXXXX')"/>
        <as:constraint action="makeRepeatable(//t:repeatUnlimited)"/>
        <as:constraint action="makeRepeatable(//t:repeatLimited)"/>
        <as:constraint action="setLimit(//t:repeatLimited,3)"/>
        <as:constraint action="makeRepeatable(//t:repeatSection)"/>
        <as:constraint action="excludeElement(//t:excluded)"/>
        <as:constraint action="excludeTree(//t:toBeExcludedasTree/t:tree)"/>
        <as:constraint action="useElement(//t:toBeUsedasElement/t:used)"/>
        <as:constraint action="useTree(//t:toBeUsedasTree/t:useTree)"/>
        <as:constraint action="useChoice(//t:useChoice/t:chosen)"/>
        <as:constraint action="makeMandatory(//t:occursTests/@mandatory)"/>
        <as:constraint action="makeOptional(//t:occursTests/@optional)"/>
        <as:constraint action="setValue(//t:contentTests/@value,'requiredValue')"/>
        <as:constraint action="restrictValues(//t:contentTests/@options,'one'|'two')"/>
        <as:constraint action="setLength(//t:contentTests/@options,5)"/>
        <as:constraint action="excludeAttribute(//t:attributeUsage/@toBeExcluded)"/>
        <as:constraint action="useAttribute(//t:attributeUsage/@toBeUsed)"/>
        <as:constraint action="setDateMask(//t:maskTests/@date,'DD-MM-YYYY')"/>
        <as:constraint action="setDateMask(//t:maskTests/@dateTime,'YYYYMMDDTHH:MI:SS')"/>
        <as:constraint action="setDateMask(//t:maskTests/@time,'HH:MI:SS')"/>
        <as:constraint action="setNumberMask(//t:maskTests/@integer,'#8')"/>
        <as:constraint action="setNumberMask(//t:maskTests/@float,'####.00')"/>
        <as:constraint action="setStringMask(//t:maskTests/@string,'UU0# 0UU')"/>

Figure 1 Constraints

The list above is taken from a template included in the jCAM distribution called TestCAM.cam. It can be seen that the functions may have one or more parameters. In most cases the second parameter's value is fairly obvious from the name of the function. The CAM specification gives fuller details of each function. In the JCam implementation the use of single quotes for those functions where values are specified is mandatory. The mask functions are similar to the 'pattern' in XML Schema except it allows for alternative date formats to be used other than the standard date that is the only option in XML schema.

The makeRepeatable function only applies to elements as XML only allows elements to be repeated. The number of repeats can be limited with the setLimit function.

Choices have represented a difficulty in other example based solutions (such as Examplotron). CAM takes the approach that to make something a choice all possibilities are expanded in the example defined in the AssemblyStructure. Then the setChoice function is used to describe the elements in the choice. Although the example shows all the element below, for example the //t:choices3 element it is possible to use the xpath 'and' functions to create quite complex xpaths that select a subsection of child nodes. The power of xpath becomes the limiting factor in the developer's armory.

Simple guide to Xpath

It is worth learnign XPath 1.0 as it is one of the keys to jCam strengths as a validation engine. Xpath is a tool that allows element and attributes to be addressed.

It is based on a hierarchical format starting with '/' for the root of the document. Consider the following XML.

<?xml version="1.0"?>
<parent>
  <childOne>
    <childOnesChild anAttribute="value"/>
  </childOne>
  <childTwo>
    <childTwoChild>Value</childTwoChild>
    <childTwoChild>ValueTwo</childTwoChild>
  </childTwo>
</parent>

Figure 2 simple XML Example

To address the root node 'parent' you can would use '/parent'. To refer to all elements you would use the following short notation of '//*'. The use of the '//' means any is short hand for any node. So to refer to the two children of childTwo you could either use '/parent/childtwo/*' or simply '//childTwo/*'. The second form meaning any childTwo in the documents where the first means any childTwo that is the direct decendant of parent. It is worth noting the difference as this may catch you out. You could refer just to the second childTwoChild using '/parent/childTwo/childTwoChild[2]' or '//childTwoChild[2]'. The number two refers to the position of the element in the group.

XPath also allows you to reference attributes. To refer to the only attribute above you could use the general '//@*' or '//childOnesChild/@*' or '//@anAttribute' or the full path /parent/childOnesChild/anAttribute'.

XPath allows the use of function itself. These are beyond the scope of this tutorial.

Using Context

Cam allows condition based contexts. There are three forms.

  1. as:Context condition="xpath" where the xpath refers to a node in the AssemblyStructure.
  2. as:Context condition="booleanExpression" where the booleanExpression is an XPath that return true or false.
  3. as:Context condition="boolean" scope="xpath" scope must refer to a node of set of nodes that exist in the AssemblyStructure.

    Any of these Context nodes may contain any number of the constraints as defined in the function section above.

    In the first form the condition XPath is prepended to any xpath expressions used in the enclosed constraints. In the second format the constraints are only applied if the boolean expression return true and in the final form the boolean expression is worked out only at when the node refered to by the xpath are encountered. This allows for rules to be applied when different values as they occur in the XMl document being validated. For more details of this see the TestCAM.cam example.

XPath as Boolean Expressions

Xpath enable various checks to be used that return a true or false result. This can be for simple existence for example in Figure 2 the xpath /parent can be intepreted as simply a check for the existence of the parent node. JCam uses this when the xpath is placed in the condition attribute of either a Context node or a constraint.

Cam also allows for parameters to be defined in the Header of a template. These parameters can be refered to by name prepending a dollar symbol. So in TestCAM.cam there are two parameters one called test and one called variable. To compare the value of test the expresion would look like "$test='One'". This would return true of the value of test is equal to One. In the TestCAM.cam test is refered to as a Global paremeter that must be passed into JCam to do this you use the follwing command line option:

jcam -T newTemplate.cam -O TemplateOutput.cam -P test=One

Figure 3 jcam with parameters (note the value is not surround by quotes)

The other parameter 'variable' is refered to as a Local parameter. This means that JCam will calculate it value from evaluating the XPath expression defined in the parameter definition. As already seen this can be scoped in a Context node. The example TestCAM.cam uses this scoped mode and the value of the variable parameter is only evaluated when the enclosing 't:repeatSection' node is found. The value of the xpath for the parameter points at the value in the node 't:variable' and this is evaluated to see which constraints are applied.

Conclusion

In summary this tutorial has aimed to broaden the knowledge that a CAM template developer needs to be able to produce a Template that will be rich enough to handle any of the XML validations they require. It has explained some of the rudiments of XPath and the use of Parameters, Contexts and Conditions. It has exposed the TestCAM.cam as a good example of each of the CAM constructs for XML Validation.