Prerequisites for using the XML schema processor are covered.

This section assumes that you have working knowledge of these technologies:

• document type definition (DTD). An XML document type definition (DTD) defines the legal structure of an XML document.

• XML Schema language. XML Schema defines the legal structure of an XML document.

To learn more about these technologies, consult the XML resources in Related Documents.

XML Schema is a World Wide Web Consortium (W3C) standard.

The Oracle XML Schema processor supports the W3C XML Schema specifications:

• XML Schema Part 0: Primer

• XML Schema Part 1: Structures

• XML Schema Part 2: Datatypes

Document type definition (DTDs) were originally developed for SGML. XML DTDs are a subset of those available in SGML and provide a mechanism for declaring constraints on XML markup. XML DTDs enable the specification of:

• Which elements can be in your XML documents.

• The content model of an XML element, that is, whether the element contains only data or has a set of subelements that defines its structure. DTDs can define whether a subelement is optional or mandatory and whether it can occur only once or multiple times.

• Attributes of XML elements. DTDs can also specify whether attributes are optional or mandatory.

• Entities that are legal in your XML documents.

An XML DTD is not itself written in XML, but is a context-independent grammar for defining the structure of an XML document. You can declare a DTD in an XML document itself or in a separate file from the XML document.

Validation is the process by which you verify an XML document against its associated DTD, ensuring that the structure, use of elements, and use of attributes are consistent with the definitions in the DTD. Thus, applications that handle XML documents can assume that the data matches the definition.

Using XDK, you can write an application that includes a validating XML parser; that is, a program that parses and validates XML documents against a DTD. Depending on its implementation, a validating parser may:

• Either stop processing when it encounters an error, or continue.

• Either report warnings and errors as they occur or in summary form at the end of processing.

• Enable or disable validation mode

  Most processors can enable or disable validation mode, but they must still process entity definitions and other constructs of DTDs.

Concepts involving validation using XML schemas are introduced.

The XML Schema language, also known as XML Schema Definition, was created by the W3C to use XML syntax to describe the content and the structure of XML documents. An XML schema is an XML document written in the XML Schema language. An XML schema document contains rules describing the structure of an input XML document, called an instance document. An instance document is valid if and only if it conforms to the rules of the XML schema.

The XML Schema language defines such things as:

• Which elements and attributes are legal in the instance document

• Which elements can be children of other elements

• The order and number of child elements

• Data types for elements and attributes

• Default and fixed values for elements and attributes

A validating XML parser tries to determine whether an instance document conforms to the rules of its associated XML schema. Using XDK you can write a validating parser that performs this schema validation. Depending on its implementation, a validating parser may:

• Either stop processing when it encounters an error, or continue.

• Either report warnings and errors as they occur or in summary form at the end of processing.

The processor must consider entity definitions and other constructs that are defined in a DTD that is included by the instance document. The XML Schema language does not define what must occurs when an instance document includes both an XML schema and a DTD. Thus, the behavior of the application in such cases depends on the implementation.

The XML Schema language includes most of the capabilities of the DTD specification. An XML schema serves a similar purpose to a DTD, but is more flexible in specifying document constraints.

Table 17-1 compares some features between the two validation mechanisms.

These reasons are probably the most persuasive for choosing XML schema validation over DTD validation:

• The XML Schema language enables you to define rules for the content of elements and attributes. You achieve control over content by using data types. With XML Schema data types you can more easily perform actions such as:

  • Declare which elements are to contain which types of data, for example, positive integers in one element and years in another

  • Process data obtained from a database

  • Define restrictions on data, for example, a number between 10 and 20

  • Define data formats, for example, dates in the form MM-DD-YYYY

  • Convert data between different data types, for example, strings to dates

• Unlike DTD grammar, documents written in the XML Schema language are themselves written in XML. Thus, you can perform these actions:

  • Use your XML parser to parse your XML schema

  • Process your XML schema with the XML Document Object Model (DOM)

  • Transform your XML document with Extensible Stylesheet Language Transformation (XSLT)

  • Reuse your XML schemas in other XML schemas

  • Extend your XML schema by adding elements and attributes

  • Reference multiple XML schemas from the same document

XDK packages that are important for applications that process XML schemas are described.

These are the important packages for applications that process XML schemas:

• oracle.xml.parser.v2, which provides APIs for XML parsing

• oracle.xml.parser.schema, which provides APIs for XML Schema processing

The most important classes in the oracle.xml.parser.schema package are described in Table 17-2. These form the core of most XML schema applications.

Figure 17-1 depicts the basic process of validating an instance document with the XML Schema processor for Java.

Figure 17-1 XML Schema Processor for Java

Description of "Figure 17-1 XML Schema Processor for Java"

The XML Schema processor performs these major tasks:

1. A builder (XSDBuilder object) assembles the XML schema from an input XML schema document. Although instance documents and schemas need not exist specifically as files on the operating system, they are commonly referred to as files. They may exist as streams of bytes, fields in a database record, or collections of XML Infoset "Information Items."

   This task involves parsing the schema document into an object. The builder creates the schema object explicitly or implicitly:

   • In explicit mode, you pass in an XML schema when you invoke the processor. Validating Against Externally Referenced XML Schemas explains how to build the schema object in explicit mode.

   • In implicit mode, you do not pass in an XML schema when you invoke the processor because the schema is internally referenced by the instance document. Validating Against Internally Referenced XML Schemas explains how to create the schema object in implicit mode.

2. The XML schema validator uses the schema object to validate the instance document. This task has these steps:

   1. A Simple API for XML (SAX) parser parses the instance document into SAX events, which it passes to the validator.

   2. The validator receives SAX events as input and validates them against the schema object, sending an error message if it finds invalid XML components.

      Validation in the XML Parser describes the validation modes that you can use when validating the instance document. If you do not explicitly set a schema for validation with the XSDBuilder class, then the instance document must have the correct xsi:schemaLocation attribute pointing to the schema file. Otherwise, the program does not perform the validation. If the processor encounters errors, it generates error messages.

   3. The validator sends input SAX events, default values, or post-schema validation information to a DOM builder or application.

Demo programs for the XML Schema processor for Java are included in $ORACLE_HOME/xdk/demo/java/schema.

cat.xsd

catalogue.xml

catalogue_e.xml

DTD2Schema.java

embeded_xsql.xsd

embeded_xsql.xml

juicer1.xml

juicer1.xsd

juicer2.xml

juicer2.xsd

report.xml

report.xsd

report_e.xml

xsddom.java

xsdent.java

xsdent.xml

xsdent.xsd

xsdent-1.xsd

xsdproperty.java

xsdsax.java

XSDLax.java

XSDSample.java

XSDSetSchema.java

1. Change into the $ORACLE_HOME/xdk/demo/java/schema directory (UNIX) or %ORACLE_HOME%\xdk\demo\java\schema directory (Windows).
2. Run make (UNIX) or Make.bat (Windows) at the command line.
3. Add xmlparserv2.jar, xschema.jar, and the current directory to the CLASSPATH. These JAR files are located in $ORACLE_HOME/lib (UNIX) and %ORACLE_HOME%\lib (Windows). For example, you can set the CLASSPATH with the tcsh shell on UNIX:

   setenv CLASSPATH
    "$CLASSPATH":$ORACLE_HOME/lib/xmlparserv2.jar:$ORACLE_HOME/lib/schema.jar:.

   Note:

   The XML Schema processor requires JDK version 1.2 or later, and it is usable on any operating system with Java 1.2 support.

4. Run the sample programs with the XML files that are included in the directory:

   • These examples use report.xsd to validate the contents of report.xml:

     java XSDSample report.xml
     java XSDSetSchema report.xsd report.xml
     

   • This example validates an instance document in Lax mode:

     java XSDLax embeded_xsql.xsd embeded_xsql.xml
     

   • These examples use cat.xsd to validate the contents of catalogue.xml:

     java XSDSample catalogue.xml
     java XSDSetSchema cat.xsd catalogue.xml
     

   • These examples generates error messages:

     java XSDSample catalogue_e.xml
     java XSDSample report_e.xml
     

   • This example uses the schemaLocation attribute in xsdent.xsd to redirect the XML schema to xsdent-1.xsd for validation:

     java xsdent xsdent.xml xsdent.xsd
     

   • This example generates a SAX stream from report.xml and validates it against the XML schema defined in report.xsd:

     java xsdsax report.xsd report.xml
     

   • This example creates a DOM representation of report.xml and validates it against the XML schema defined in report.xsd:

     java xsddom report.xsd report.xml
     

   • These examples configure validation starting with an element declaration or complex type definition:

     java xsdproperty juicer1.xml juicer1.xsd http://www.juicers.org \
     juicersType false > juicersType.out
                                                                                            
     java xsdproperty juicer2.xml juicer2.xsd http://www.juicers.org \ 
     Juicers true > juicers_e.out
     

   • This example converts a DTD (dtd2schema.dtd) into an XML schema and uses it to validate an instance document (dtd2schema.xml):

     java DTD2Schema dtd2schema.dtd dtd2schema.xml

You can use the XML parser command-line utility (oraxml) to validate instance documents against XML schemas and DTDs.

$ORACLE_HOME/xdk/demo/java/schema/XSDSample.java shows how to validate against an implicit XML Schema. The validation mode is implicit because the XML schema is referenced in the instance document itself.

1. Create a DOM parser to use for the validation of an instance document. this code fragment from XSDSample.java shows how to create the DOMParser object:

   public class XSDSample
   {
      public static void main(String[] args) throws Exception
      {
         if (args.length != 1)
         {
            System.out.println("Usage: java XSDSample <filename>");
            return;
         }
         process (args[0]);
      }
   
      public static void process (String xmlURI) throws Exception
      {
         DOMParser dp  = new DOMParser();
         URL       url = createURL(xmlURI);
         ...
      }
   ...
   }
   

   createURL() is a helper method that constructs a URL from a file name passed to the program as an argument.

2. Set the validation mode for the validating DOM parser with the DOMParser.setValidationMode() method. For example, XSDSample.java shows how to specify XML schema validation:

   dp.setValidationMode(XMLParser.SCHEMA_VALIDATION);
   dp.setPreserveWhitespace(true);
   

3. Set the output error stream with the DOMParser.setErrorStream() method. For example, XSDSample.java sets the error stream for the DOM parser object:

   dp.setErrorStream (System.out);
   

4. Validate the instance document with the DOMParser.parse() method. You do not have to create an XML schema object explicitly because the schema is internally referenced by the instance document. For example, XSDSample.java validates the instance document:

   try
   {
     System.out.println("Parsing "+xmlURI);
     dp.parse(url);
     System.out.println("The input file <"+xmlURI+"> parsed without errors");
   }
   catch (XMLParseException pe)
   {
     System.out.println("Parser Exception: " + pe.getMessage());
   }
   catch (Exception e)
   {
     System.out.println("NonParserException: " + e.getMessage());
   }

$ORACLE_HOME/xdk/demo/java/schema/XSDSetSchema.java shows how to validate an XML schema explicitly. The validation mode is explicit because you use the XSDBuilder class to specify the schema to use for validation: the schema is not specified in the instance document as in implicit validation.

1. Build an XML schema object from the XML schema document with the XSDBuilder.build() method. This code fragment from XSDSetSchema.java shows how to create the object:

   public class XSDSetSchema
   {
      public static void main(String[] args) throws Exception
      {
         if (args.length != 2)
         {
            System.out.println("Usage: java XSDSample <schema_file> <xml_file>");
            return;
         }
    
         XSDBuilder builder = new XSDBuilder();
         URL    url =  createURL(args[0]);
    
         // Build XML Schema Object
         XMLSchema schemadoc = (XMLSchema)builder.build(url);
         process(args[1], schemadoc);
      }
   . . .
   

   The createURL() method is a helper method that constructs a URL from the schema document file name specified on the command line.

2. Create a DOM parser to use for validation of the instance document. This code from XSDSetSchema.java shows how to pass the instance document file name and XML schema object to the process() method:

   public static void process(String xmlURI, XMLSchema schemadoc)throws Exception{
      DOMParser dp  = new DOMParser();
      URL       url = createURL (xmlURI);
      . . .
   

3. Specify the schema object to use for validation with the DOMParser.setXMLSchema() method. This step is not necessary in implicit validation mode because the instance document already references the schema. For example, XSDSetSchema.java specifies the schema:

   dp.setXMLSchema(schemadoc);
   

4. Set the validation mode for the DOM parser object with the DOMParser.setValidationMode() method. For example, XSDSample.java shows how to specify XML schema validation:

   dp.setValidationMode(XMLParser.SCHEMA_VALIDATION);
   dp.setPreserveWhitespace(true);
   

5. Set the output error stream for the parser with the DOMParser.setErrorStream() method. For example, XSDSetSchema.java sets it:

   dp.setErrorStream (System.out);
   

6. Validate the instance document against the XML schema with the DOMParser.parse() method. For example, XSDSetSchema.java includes this code:

   try
   {
      System.out.println("Parsing "+xmlURI);
      dp.parse (url);
      System.out.println("The input file <"+xmlURI+"> parsed without errors");
   }
   catch (XMLParseException pe)
   {
      System.out.println("Parser Exception: " + pe.getMessage());
   }
   catch (Exception e)
   {
      System.out.println ("NonParserException: " + e.getMessage());
   }

In LAX mode, you can validate parts of an XML document without validating all of it. LAX parsing validates elements in a document that are declared in an associated XML schema. The processor does not consider the instance document invalid if it contains no elements declared in the schema.

1. Build an XML schema object from the user-specified XML schema document.
2. Create a DOM parser to use for validation of the instance document.
3. Specify the XML schema to use for validation.
4. Set the validation mode for the DOM parser object.
5. Set the output error stream for the parser.
6. Validate the instance document against the XML schema by invoking DOMParser.parse().

dp.setXMLSchema(schemadoc);
dp.setValidationMode(XMLParser.SCHEMA_LAX_VALIDATION);
dp.setPreserveWhitespace (true);
. . .

java XSDLax embeded_xsql.xsd embeded_xsql.xml

$ORACLE_HOME/xdk/demo/java/schema/xsdsax.java shows how to validate an XML document received as a SAX stream. You instantiate an XSDValidator and register it with the SAX parser as the content handler.

1. Build an XML schema object from the user-specified XML schema document by invoking the XSDBuilder.build() method. This code fragment shows how to create the object:

   XSDBuilder builder = new XSDBuilder();
   URL    url =  XMLUtil.createURL(args[0]);
   
   // Build XML Schema Object
   XMLSchema schemadoc = (XMLSchema)builder.build(url);      
   process(args[1], schemadoc);
   . . .
   

   createURL() is a helper method that constructs a URL from the file name specified on the command line.

2. Create a SAX parser (SAXParser object) to use for validation of the instance document. This code fragment from saxxsd.java passes the handles to the XML document and schema document to the process() method:

   process(args[1], schemadoc);...public static void process(String xmlURI, XMLSchema schemadoc)
   throws Exception 
   {
       SAXParser dp  = new SAXParser();
   ...
   

3. Configure the SAX parser. This code fragment sets the validation mode for the SAX parser object with the XSDBuilder.setValidationMode() method:

   dp.setPreserveWhitespace (true);
   dp.setValidationMode(XMLParser.NONVALIDATING);
   

4. Create and configure a validator (XSDValidator object). This code fragment shows this technique:

   XMLError err;... err = new XMLError();
   ...
   XSDValidator validator = new XSDValidator();
   ...
   validator.setError(err);
   

5. Specify the XML schema to use for validation by invoking the XSDBuilder.setXMLProperty() method. The first argument is the name of the property, which is fixedSchema, and the second is the reference to the XML schema object. This code fragment shows this technique:

   validator.setXMLProperty(XSDNode.FIXED_SCHEMA, schemadoc);
   ...
   

6. Register the validator as the SAX content handler for the parser. This code fragment shows this technique:

   dp.setContentHandler(validator);
   ...
   

7. Validate the instance document against the XML schema by invoking the SAXParser.parse() method. This code fragment shows this technique:

   dp.parse (url);

$ORACLE_HOME/xdk/demo/java/schema/xsddom.java shows how to validate an instance document by get a DOM representation of the document and using an XSDValidator object to validate it.

1. Build an XML schema object from the user-specified XML schema document by invoking the XSDBuilder.build() method. This code fragment shows how to create the object:

   XSDBuilder builder = new XSDBuilder();
   URL    url =  XMLUtil.createURL(args[0]);
   
   XMLSchema schemadoc = (XMLSchema)builder.build(url);      
   process(args[1], schemadoc);
   

   createURL() is a helper method that constructs a URL from the file name specified on the command line.

2. Create a DOM parser (DOMParser object) to use for validation of the instance document. This code fragment from domxsd.java passes the handles to the XML document and schema document to the process() method:

   process(args[1], schemadoc);...public static void process(String xmlURI, XMLSchema schemadoc)
   throws Exception 
   {
       DOMParser dp  = new DOMParser();
       . . .
   

3. Configure the DOM parser. This code fragment sets the validation mode for the parser object with the DOMParser.setValidationMode() method:

   dp.setPreserveWhitespace (true);
   dp.setValidationMode(XMLParser.NONVALIDATING);
   dp.setErrorStream (System.out);
   

4. Parse the instance document. This code fragment shows this technique:

   dp.parse (url);
   

5. Get the DOM representation of the input document. This code fragment shows this technique:

   XMLDocument doc = dp.getDocument();
   

6. Create and configure a validator (XSDValidator object). This code fragment shows this technique:

   XMLError err;... err = new XMLError();
   ...
   XSDValidator validator = new XSDValidator();
   ...
   validator.setError(err);
   

7. Specify the schema object to use for validation by invoking the XSDBuilder.setXMLProperty() method. The first argument is the name of the property, which in this example is fixedSchema, and the second is the reference to the schema object. This code fragment shows this technique:

   validator.setXMLProperty(XSDNode.FIXED_SCHEMA, schemadoc);
   . . .
   

8. Get the root element (XMLElement) of the DOM tree and validate. This code fragment shows this technique:

   XMLElement root = (XMLElement)doc.getDocumentElement();
   XMLElement copy = (XMLElement)root.validateContent(validator, true);
   copy.print(System.out);

$ORACLE_HOME/xdk/demo/java/schema/xsdproperty.java shows how to configure the XML Schema processor to validate an XML document based on a complex type or element declaration.

When XSDBuilder builds a schema, it might need to include or import other schemas that are specified as URLs in a schemaLocation attribute. In some situations, you might want to override the schema locations specified in <import> and supply the builder with the required schema documents.

xsi:schemaLocation =  "http://www.example.com/BookCatalogue
                       xsdent.xsd">

<schema xmlns="http://www.w3.org/2001/XMLSchema"
               targetNamespace="http://www.example.com/BookCatalogue"
               xmlns:catd = "http://www.example.com/Digest"
               xmlns:cat  = "http://www.example.com/BookCatalogue"
               elementFormDefault="qualified">
<import namespace = "http://www.example.com/Digest"
        schemaLocation = "xsdent-1.xsd" />

1. Create a new XML schema builder:

   XSDBuilder builder = new XSDBuilder(); 
      

2. Set the builder to your entity resolver. An entity resolver is a class that implements the EntityResolver interface. The purpose of the resolver is to enable the XML reader to intercept any external entities before including them. This code fragment creates an entity resolver and sets it in the builder:

   builder.setEntityResolver(new sampleEntityResolver1());
   

   The sampleEntityResolver1 class implements the resolveEntity() method. You can use this method to redirect external system identifiers to local URIs. The source code is:

   class sampleEntityResolver1 implements EntityResolver
   {
      public InputSource resolveEntity (String targetNS,  String systemId)
      throws SAXException, IOException
      {
         // perform any validation check if needed based on targetNS & systemId 
         InputSource mySource = null;
         URL u = XMLUtil.createURL(systemId); 
         // Create input source with InputStream as input
         mySource = new InputSource(u.openStream());
         mySource.setSystemId(systemId);
         return mySource;
      }
   }
   

   The sampleEntityResolver1 class initializes the InputSource with a stream.

3. Build the XML schema object. This code shows this technique:

   schemadoc = builder.build(url);
   

4. Validate the instance document against the XML schema. The program executes this statement:

   process(xmlfile, schemadoc);
   

   The process() method creates a DOM parser, configures it, and invokes the parse() method. The method is implemented:

   public static void process(String xmlURI, Object schemadoc)
       throws Exception
   {
     DOMParser dp  = new DOMParser();
     URL       url = XMLUtil.createURL (xmlURI);
    
     dp.setXMLSchema(schemadoc);
     dp.setValidationMode(XMLParser.SCHEMA_VALIDATION);
     dp.setPreserveWhitespace (true);
     dp.setErrorStream (System.out);
     try {
        dp.parse (url);
        ...
   }

Because of the power and flexibility of the XML Schema language, you may want to convert your existing DTDs to XML schema documents. You can use XDK to perform this transformation.

java DTD2Schema dtd2schema.dtd dtd2schema.xml

1. Parse the DTD with the DOMParser.parseDTD() method. This code fragment from DTD2Schema.java shows how to create the DTD object:

   XSDBuilder builder = new XSDBuilder(); 
   URL dtdURL = createURL(args[0]);
   DTD dtd = getDTD(dtdURL, "abc");
      

   The getDTD() method is implemented:

   private static DTD getDTD(URL dtdURL, String rootName)
      throws Exception
   {
      DOMParser parser = new DOMParser();
      DTD dtd;
      parser.setValidationMode(true);
      parser.setErrorStream(System.out);
      parser.showWarnings(true);
      parser.parseDTD(dtdURL, rootName);
      dtd = (DTD)parser.getDoctype();
      return dtd;
   }
   

2. Convert the DTD to an XML schema DOM tree with the DTD.convertDTD2Sdhema() method. This code fragment from DTD2Schema.java shows this technique:

   XMLDocument dtddoc = dtd.convertDTD2Schema();
   

3. Write the XML schema DOM tree to an output stream with the XMLDocument.print() method. This code fragment from DTD2Schema.java shows this technique:

   FileOutputStream fos = new FileOutputStream("dtd2schema.xsd.out");
   dtddoc.print(fos);
   

4. Create an XML schema object from the schema DOM tree with the XSDBuilder.build() method. This code fragment from DTD2Schema.java shows this technique:

   XMLSchema schemadoc = (XMLSchema)builder.build(dtddoc, null);
   

5. Validate an instance document against the XML schema with the DOMParser.parse() method. This code fragment from DTD2Schema.java shows this technique:

   validate(args[1], schemadoc);
   

   The validate() method is implemented:

   DOMParser dp  = new DOMParser();
   URL       url = createURL (xmlURI); 
   dp.setXMLSchema(schemadoc);
   dp.setValidationMode(XMLParser.SCHEMA_VALIDATION);
   dp.setPreserveWhitespace (true);
   dp.setErrorStream (System.out);
   try
   {
      System.out.println("Parsing "+xmlURI);
      dp.parse (url);
      System.out.println("The input file <"+xmlURI+"> parsed without errors");
   }
   ...