An Example CAM Validation
With a template in hand, you may now validate an XML file against the template. The W3C site, besides providing the sample purchase order schema, kindly provides a sample purchase order instance (PurchaseOrder/po.xml
)—but the download contains one typographic error. Figure 4
highlights the error. If you attempt to open or validate a malformed XML file, the CAM editor displays a stack dump and an error message (also shown in Figure 4
), and refuses to load the file.
|Figure 4. Malformed XML: The figure shows why the original po.xml file is not well-formed; loading it into the CAM editor results in the ugly error popup shown.|
|Figure 5. The XML View: When you open an XML file it is rendered in an XML view showing the tree structure of the document with icons to collapse and expand the tree portions.|
After you correct the error by swapping the exclamation point and the left angle bracket (the corrected file is PurchaseOrder/po_corrected.xml
) you can load the XML file using the CAM editor's XML → Open XML menu item. The CAM Editor displays the file in an XML view, rendering it in a style similar to the structure view (see Figure 5
). The same elements are present as in the template, but now appear with actual values rather than placeholders (the descriptive terms surrounded by percent signs).
To validate the document select Run → Run JCam. You'll see the Run JCam dialog shown in Figure 6. By default JCam selects the loaded XML file, and should identify its structure ID as purchaseOrder (the root of this structure). Click Finish to close the dialog and run the validation; the results appear in the Run Results view at the bottom of the main window. Notice that the validation indicates two errors, although only one is in view in Figure 6. If you look closely you'll see that nodes with errors have a tiny yellow or red error icon attached to them and their antecedents. In this case, because the error occurs on the <zip> element, its parent <shipTo> element also displays an error icon, as does the root <purchaseOrder> element. Similarly, you can deduce that the second error is buried within the <billTo> element.
|Figure 6. Performing a Validation: Validation results appear in the Run Results view. Each element or attribute that fails validation has an attached error symbol; its antecedents have a warning symbol.|
This XML file validates with no errors in any XML Schema editor. Why does it fail here? The error in the Run Results view indicates the zip code is not valid according to the CAM template. The template is looking for a floating point number with 2 decimal places whereas zip codes in the US, of course, are 5-digit or 9-digit integers. The CAM template rule for the zip code came from the XSD specification, which states simply that a zip code is a decimal. You can see this in Listing 1
: Look for the zip field within the USAddress complex type. The CAM template generator could do only as good as a job as its input allowed (a mild case of GIGO). While you might disagree, I submit that the XSD specification is too forgiving; the datatype should have been an integer rather than a decimal. The next section discusses how to correct this error in the CAM Editor.
As you follow along with the examples in this article or explore on your own, you might run into a template that is not behaving as expected. There are a couple things to check in that event.
- Invoke the Tools → Validate CAM Template menu item to look for any issues from the editor's perspective.
- If you press Finish in the Run JCam dialog box and nothing seems to happen, press Cancel to close the dialog, and then take a look at the Console view for any error messages. If, for example, you neglected to specify an XML file to validate, the dialog does not disable the Finish button but rather lets you press it, and reports the misleading error "template is null" in the Console view. (Other conditions may cause that error as well.) If the Console view is not visible, nothing appears to happen.