Five Minute Tutorial

This tutorial is designed to show how JCam can be integrated into other Java Applications. It presumes that CAM templates have been produced and proven to work from the Command line options shown in the One Minute Tutorial and the Two Minute Tutorial .

JCam is a Pure Java application that uses NanoContainer to enable inversion of control. This allows competant Java programmers to add their own code either alongside the base JCam code or in its place.

JCam use the following XML file to drive its default behaviour:

<container>
    <component-implementation class='uk.org.jcam.processor.dataObjects.Template'/>
    <component-implementation class='uk.org.jcam.processor.dataObjects.DataFile'/>
    <component-implementation class='uk.org.jcam.processor.validator.UnOrderedValidatorStrict'/>
    <component-implementation class='uk.org.jcam.processor.trimmer.DefaultTrimmer'/>
    <component-implementation class='uk.org.jcam.processor.adorner.DefaultAdorner'/>    
    <component-implementation class='uk.org.jcam.drools.DroolsDataValidator'/>
</container>

Figure 1 DefaultNanoConfig.xml - must exist in the same directory as the running application.

From version 0.9 onwards there are three possible Validators:

  • uk.org.jcam.processor.validator.UnOrderedValidatorStrict - the new Default Validator from 0.9.

    this validator now supports the new Unordered Elements policy of CAM 1.1 and also supports recursive elements. It is strict in that it will throw and error if extra elements appear in the XML document.

  • uk.org.jcam.processor.validator.UnOrderedValidatorLax

    this is the same CAM 1.1 behaviour without the checks for extra elements

  • uk.org.jcam.processor.validator.DefaultValidator

    this is the original Ordered Elements validator. It supports the CAM 1.0 behaviour.

Behaviours

JCam has implemented two default behaviours - Trimming, Validating.

Trimming

This is the process of applying the constraints defined in a template to an AssemblyStructure either in the presence of an XML file for validation or not. If no XML DataFile exists trimming may not be able to do a complete job if Local parameters or scope(d) contexts are defined. Running the trimming function can be useful as it allows the developer to document the effect of certain rules being applied to an AssemblyStructure.

Trimming can be performed from the command line as follows:

jcam -t -T newTemplate.cam -O TemplateOutput.cam

Validation

This is the major use case for JCam.

Java Integration

There are thre ways of handling Java Integration with JCAM they are:

Conclusion

JCam can be fully integrated into other applications. It has been successfully introduced into the HERMES ebXML message handler as a validation engine.

NOTE

The following section is no longer supported by the CAM specification. It may still work in the version 1.0 JCAM build, but is not supported by the editor

DataValidation

JCam implements its own DataValidation section that is not defined in the CAM Specification. To use it the Template must have the following section included:

<as:DataValidations>
   <as:includeRules language="drools">http://localhost/jcam/rules.drl</as:includeRules>         
   <as:applyRules scope="//t:repeatUnlimited"/>
</as:DataValidations>

Figure 2 DataValidations section for DROOLS integration

The includeRules and applyRules are nodes currently being discussed by the CAM Committee. The includeRules points at a DROOLS rules file. The applyRules defines which nodes will be passed to DROOLS to use as the set of elements upon which the rules will be applied. More than one applyRules elements may exist.

An example of a set of rules is as follows:

<?xml version="1.0"?>
<dr:rule-set name="cam"
  xmlns:dr="http://drools.org/rules"
  xmlns="http://drools.org/semantics/java">
  <import>java.lang.Object</import>
  <import>java.lang.String</import>
  <import>uk.org.jcam.drools.JCAMElement</import>
  <dr:rule name="Element change to mandatory">
    <dr:parameter identifier="element">
      <dr:class>JCAMElement</dr:class>
    </dr:parameter>
    <condition>element.isOptional()</condition>
    <consequence>
      element.setMandatory()
    </consequence>
  </dr:rule>
</dr:rule-set>

Figure 3 DROOLS Rules File

This file obviously duplicates the makeMandatory function of CAM. However once the break out to Java has been made the use of DROOLS is almost limitless in its application. It could be used to make calls to databases and further external systems such as making web services calls.

For more information see drools.org .

ExternalMapping

CAm defines quite complex sets of External Mappings. JCam implements two forms neither of which are completely CAM compliant. The first is the ability to use an XSLT sheet to transform the incoming XML into an alternative form. this is simply done from the command line by using teh following command:

jcam -c -T CamTemplate.cam -X xmlfile.xml -L tranforming.xsl -S output.xml

The other form of mapping is more complex and will not be explained here. It involves using substitution names and it is not really comprehensive enough to warrant serious consideration.

JCam also allows for errors to be out put in a pretty format for this use:

jcam -c -T CamTemplate.cam -X xmlfile.xml -Y tranforming.xsl -J output.xml