Latest revision as of 11:33, 29 April 2008

Overview

The SDD Validator is an Eclipse plug-in that provides functionality for validating XML against various types of rule sets. Currently supported types of rules are XML Schema rules, Schematron rules and custom user created rules written in Java. The Validator also provides the ability to read XML into SDOs, and write the SDOs back out to XML. While intended primarily for working with SDDs, the Validator is flexible enough to handle any arbitrary XML.

There are two methods available for using the Validator. First, an Eclipse based application may require the Validator as plug-in dependency and use the provided APIs. Second, the Validator includes the ability to run as an Eclipse Rich Client Platform (RCP) application with a command line interface.

Rules

All rules must implement the ValidationRule interface, which contains a single method: validate(). A rule may perform any kind of validation action desired, provided it takes an InputStream as input and returns an array of XMLValidationError. Below are the pre-written rule types included with the Validator.

XML Schema Rules

SchemaValidationRule provides functionality for validating against one or more XML Schemas. A SchemaValidationRule is constructed with an array of either Files or InputStreams containing the schemas against which the XML will be validated. Schemas may be added to or removed from the rule at any time. It is also possible to get a list of all schema Files or InputStreams associated with an instance of SchemaValidationRule.

SchemaValidationRule performs validation using the Java API for XML Processing (JAXP), which allows the validation to be independent of the underlying XML parser and thus run the same on different JRE versions and implementations.

Schematron Rules

SchematronValidationRule provides functionality for validating against an ISO Schematron rules file. A SchematronValidationRule is constructed with a Schematron rules file and a Schematron skeleton file. The provided implementation is tied to the Schematron Text validator, which extends the base ISO Schematron skeleton file. Users would need to create a Custom Rule if another type of Schematron error reporting is desired.

Briefly, a Schematron skeleton is an XSL Transform that can be thought of as a compiler for rules files. The result of transforming the rules file with the skeleton is another XSL Transform, which can then be applied against an XML file to generate an error report. SchematronValidationRule takes care of compiling the rules file and parsing the generated error report.

SDD Specific Rules

More info goes here about rules required to ensure compliance with SDD spec, above what the Schema requires.

Custom Java Rules

Users can create their own rules to perform other types of validation beyond what the included rule types provide. There is no restriction on what custom rules can do, other than that they must implement the ValidationRule interface.

Interfaces

API

The Validator API provides two different levels of functionality:

1. A low level API for reading, writing and validating generic XML or a single Package or Deployment Descriptor. This capability is available through the XML_DAS and SDD_DAS interfaces.
2. A high level API for handling entire SDDs, meaning one or more Package Descriptors and one or more Deployment Descriptors. This capability is provided by the SDDManager interface.

A more detailed description of each interface is provided below.

XML_DAS

DataGraph loadDataGraph(InputStream inputStream, String[] schemaFiles)

Creates an SDO DataGraph representing the XML in the given InputStream. Since some basic validation occurs during loading of the XML, a list of Schema files referenced by the XML is required. An XMLValidationException may be thrown, but lack of an exception does not necessarily mean the XML is valid.

void saveDataGraph(DataGraph dataGraph, OutputStream outputStream, String rootElementName, String rootElementURI,
String encoding)

Converts the DataGraph to XML and writes it to the given OutputStream. Requires the desired Root Element Name and URI to be specified since that information is not stored in the DataGraph. Optionally, a character encoding can be specified, or null results in the default encoding. This method validates the XML before writing it out.

void saveDataGraph(DataGraph dataGraph, OutputStream outputStream, String rootElementName, String rootElementURI,
String encoding, boolean performValidation)

Converts the DataGraph to XML and writes it to the given OutputStream. Requires the desired Root Element Name and URI to be specified since that information is not stored in the DataGraph. Optionally, a character encoding can be specified, or null results in the default encoding. This method allows a choice of whether the XML is validated before being written out.

XMLValidationError[] validate(DataGraph dataGraph, String rootElementName, String rootElementURI)

Validates the given DataGraph by running all the ValidationRules associated with the XML_DAS. Since the DataGraph will be converted to XML before validation, the Root Element Name and URI are required. Returns a list of validation errors found, or an empty list if the XML is valid.

void addValidation(ValidationRule validationRule)

Adds a ValidationRule to the list of rules associated with the XML_DAS.

void removeValidation(ValidationRule validationRule)

Removes a ValidationRule from the list of rules associated with the XML_DAS.

ValidationRule[] getValidationRules()

Returns a list of all ValidationRules associated with an XML_DAS.

SDD_DAS

DataGraph loadDataGraph(InputStream inputStream)

Creates an SDO DataGraph representing the XML in the given InputStream. The SDD Schema files are used for the basic validation that occurs during loading of the XML. An XMLValidationException may be thrown, but lack of an exception does not necessarily mean the XML is valid.

void saveDataGraph(DataGraph dataGraph, OutputStream outputStream, String encoding)

Converts the DataGraph to XML and writes it to the given OutputStream. The appropriate Root Element Name and URI are used depending on whether the DataGraph is a Package Descriptor or Deployment Descriptor. Optionally, a character encoding can be specified, or null results in the default encoding. This method validates the XML before writing it out.

void saveDataGraph(DataGraph dataGraph, OutputStream outputStream, String encoding, boolean performValidation)

Converts the DataGraph to XML and writes it to the given OutputStream. The appropriate Root Element Name and URI are used depending on whether the DataGraph is a Package Descriptor or Deployment Descriptor. Optionally, a character encoding can be specified, or null results in the default encoding. This method allows a choice of whether the XML is validated before being written out.

XMLValidationError[] validate(DataGraph dataGraph)

Validates the given DataGraph by running all the ValidationRules associated with the SDD_DAS. Returns a list of validation errors found, or an empty list if the XML is valid.

void addValidation(ValidationRule validationRule)

Adds a ValidationRule to the list of rules associated with the SDD_DAS.

void removeValidation(ValidationRule validationRule)

Removes a ValidationRule from the list of rules associated with the SDD_DAS.

ValidationRule[] getValidationRules()

Returns a list of all ValidationRules associated with an SDD_DAS.

SDDManager

void addDescriptorFromDataGraph(DataGraph descriptorGraph, File descriptorFile)

Adds a DataGraph to the list of descriptors maintained by the SDDManager. Any validation rules which are already associated with the SDDManager will be applied to the new descriptor, in addition to all additional rules added after the descriptor is added. The File argument is the file the descriptor will be written to when one of the writeDescriptors() or writeAllDescriptors() methods is called.

DataGraph addDescriptorFromFile(File descriptorFile)

Loads XML from the given File into a DataGraph and adds it to the descriptor list maintained by the SDDManager. Any validation rules which are already associated with the SDDManager will be applied to the new descriptor, in addition to all additional rules added after the descriptor is added. When any of the writeDescriptors or writeAllDescriptors methods is called, the descriptor will be written back to the file from which it was loaded.

void removeDescriptor(DataGraph descriptorGraph)

Removes the given DataGraph from the list of descriptors maintained by the SDDManager.

void writeAllDescriptors()

Writes all the descriptors in the SDDManager's descriptor list out to their associated XML files. This method performs validation on each descriptor before writing it to the output file.

void writeAllDescriptors(boolean performValidation)

Writes all the descriptors in the SDDManager's descriptor list out to their associated XML files. This method allows a choice of whether the descriptors are validated before being written.

void writeDescriptors(DataGraph [] descriptorGraphs)

Writes the given descriptors out to their associated XML files. If any DataGraphs are in the list provided but not in the list maintained by the SDDManager, then they are ignored silently. This method performs validation on each descriptor before writing it to the output file.

void writeDescriptors(DataGraph [] descriptorGraphs, boolean performValidation)

Writes the given descriptors out to their associated XML files. If any DataGraphs are in the list provided but not in the list maintained by the SDDManager, then they are ignored silently. This method allows a choice of whether the descriptors are validated before being written.

XMLValidationError[] validateAllDescriptors()

Validates all descriptors associated with the SDDManager, and returns a list of XMLValidationErrors. Validation means running each of the ValidationRules in the SDDManager's list against all descriptors of the appropriate type (either Package or Deployment).

XMLValidationError[] validateDescriptors(DataGraph [] descriptorGraphs)

Validates the given descriptors and returns a list of XMLValidationErrors. If any DataGraphs are in the list provided but not in the list maintained by the SDDManager, then they are ignored silently. Validation means running each of the ValidationRules in the SDDManager's list against all descriptors of the appropriate type (either Package or Deployment).

void addValidation(ValidationRule validationRule, int descriptorType)

Adds a ValidationRule to the list maintained by the SDDManager. Rules can be associated with one of the descriptor types, either PACKAGE_DESCRIPTOR or DEPLOYMENT_DESCRIPTOR.

void removeValidation(ValidationRule validationRule, int descriptorType)

Removes a ValidationRule from the list maintained by the SDDManager. The descriptor type must be specified to tell the SDDManager wheter to remove the rule from the DEPLOYMENT_DESCRIPTOR list or the PACKAGE_DESCRIPTOR list.

DataGraph [] getPackageDescriptorGraphs()

Returns a list of all Package Descriptor DataGraphs associated with the SDDManager.

DataGraph [] getDeploymentDescriptorGraphs()

Returns a list of all Deployment Descriptor DataGraphs associated with the SDDManager.

DataGraph [] getAllDescriptorGraphs()

Returns a list of all DataGraphs (both Deployment Descriptors and Package Descriptors) associated with the SDDManager.

ValidationRule [] getPackageDescriptorRules()

Returns the SDDManager's list of ValidationRules which are targeted to Package Descriptors.

ValidationRule [] getDeploymentDescriptorRules()

Returns the SDDManager's list of ValidationRules which are targeted to Deployment Descriptors.

ValidationRule [] getAllValidationRules()

Returns the SDDManager's list of ValidationRules, for both Package and Deployment Descriptors.

void setEncoding(String encoding)

Sets the encoding to use when writing descriptors out to XML. A null value will cause the default encoding to be used, as will writing out descriptors before calling this method.

Command Line

More info about command line interface goes here.