org.jdom2.contrib.schema

## Class Schema

- java.lang.Object
- - org.jdom2.contrib.schema.Schema

-     public class Schema
      extends java.lang.Object

  The compiled representation of a schema definition capable of performing in-memory validation of JDOM documents and elements.

  This class relies on JARV (Java API for RELAX Verifiers) and requires an implementation of this API at runtime, such as Sun's Multi-Schema Validator.

  To validate a document against a W3C XML Schema definition:

       import org.jdom2.contrib.schema.Schema;

          String uri = <The URL of the schema document>;
          Document doc = <a JDOM document>;

          Schema schema = Schema.parse(uri, Schema.W3C_XML_SCHEMA);
          List errors = schema.validate(doc);
          if (errors != null) {
            // Validation errors
            for (Iterator i=errors.iterator(); i.hasNext(); ) {
              ValidationError e = i.next();
              System.out.println(e);
            }
          }
          // Else: No error, document is valid.

  The current limitations are those of JARV, i.e. no support for validating a document against multiple schemas. This can be work around for elements (calling validate(Element) on another Schema) but not for attributes.

  Author:
    Laurent Bihanic

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Schema.Type` Class to support type-safe enumeration design pattern to represent schema types

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Schema.Type` | `RELAX_CORE` Type for RELAX Core schema definitions.
    `static Schema.Type` | `RELAX_NAMESPACE` Type for RELAX Namespace schema definitions.
    `static Schema.Type` | `RELAX_NG` Type for RELAX NG schema definitions.
    `static Schema.Type` | `TREX` Type for TREX schema definitions.
    `static Schema.Type` | `W3C_XML_SCHEMA` Type for W3C XML Schema definitions.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Schema.Type` | `getType()` Returns the schema type.
    `java.lang.String` | `getURI()` Returns the location of the schema document, if known.
    `static Schema` | `parse(java.io.File file, Schema.Type type)` Parses a schema definition from the specified file according to the specified schema type and returns a compiled schema object.
    `static Schema` | `parse(org.xml.sax.InputSource source, Schema.Type type)` Parses a schema definition from the specified SAX input source according to the specified schema type and returns a compiled schema object.
    `static Schema` | `parse(java.io.InputStream byteStream, Schema.Type type, java.lang.String uri)` Parses a schema definition from the specified byte stream according to the specified schema type and returns a compiled schema object.
    `static Schema` | `parse(java.io.Reader reader, Schema.Type type, java.lang.String uri)` Parses a schema definition from the specified character stream according to the specified schema type and returns a compiled schema object.
    `static Schema` | `parse(java.lang.String uri, Schema.Type type)` Parses a schema definition located at the specified URI according to the specified schema type and returns a compiled schema object.
    `java.util.List<ValidationError>` | `validate(org.jdom2.Document doc)` Validates a JDOM document against this schema.
    `java.util.List<ValidationError>` | `validate(org.jdom2.Element element)` Validates a JDOM element against this schema.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### W3C_XML_SCHEMA

          public static final Schema.Type W3C_XML_SCHEMA

      Type for W3C XML Schema definitions.

    - #### RELAX_NG

          public static final Schema.Type RELAX_NG

      Type for RELAX NG schema definitions.

    - #### RELAX_CORE

          public static final Schema.Type RELAX_CORE

      Type for RELAX Core schema definitions.

    - #### RELAX_NAMESPACE

          public static final Schema.Type RELAX_NAMESPACE

      Type for RELAX Namespace schema definitions.

    - #### TREX

          public static final Schema.Type TREX

      Type for TREX schema definitions.

  - ### Method Detail

    - #### getURI

          public java.lang.String getURI()

      Returns the location of the schema document, if known.
      Returns:
        the location of the schema document or `null` if inknown.

    - #### getType

          public Schema.Type getType()

      Returns the schema type.
      Returns:
        the schema type.

    - #### validate

          public java.util.List<ValidationError> validate(org.jdom2.Document doc)
                                                   throws org.jdom2.JDOMException

      Validates a JDOM document against this schema.
      Parameters:
        `doc` - the JDOM document to validate.
      Returns:
        a list of `ValidationError` objects or `null` if the document is compliant with this schema.
      Throws:
        `org.jdom2.JDOMException` - if errors were encountered that prevented the validation to proceed.

    - #### validate

          public java.util.List<ValidationError> validate(org.jdom2.Element element)
                                                   throws org.jdom2.JDOMException

      Validates a JDOM element against this schema.
      Parameters:
        `element` - the JDOM element to validate.
      Returns:
        a list of `ValidationError` objects or `null` if the element is compliant with this schema.
      Throws:
        `org.jdom2.JDOMException` - if errors were encountered that prevented the validation to proceed.

    - #### parse

          public static Schema parse(java.lang.String uri,
                     Schema.Type type)
                              throws org.jdom2.JDOMException,
                                     java.io.IOException

      Parses a schema definition located at the specified URI according to the specified schema type and returns a compiled schema object.
      Parameters:
        `uri` - the location of the schema document.
        `type` - the schema type.
      Returns:
        the compiled schema.
      Throws:
        `org.jdom2.JDOMException` - if the schema document can not be parsed according to the specfied type.
        `java.io.IOException` - if an I/O error occurred while reading the schema document.

    - #### parse

          public static Schema parse(java.io.InputStream byteStream,
                     Schema.Type type,
                     java.lang.String uri)
                              throws org.jdom2.JDOMException,
                                     java.io.IOException

      Parses a schema definition from the specified byte stream according to the specified schema type and returns a compiled schema object.
      Parameters:
        `byteStream` - the byte stream to read the schema definition from.
        `type` - the schema type.
        `uri` - the location of the schema document (optional).
      Returns:
        the compiled schema.
      Throws:
        `org.jdom2.JDOMException` - if the schema document can not be parsed according to the specfied type.
        `java.io.IOException` - if an I/O error occurred while reading the schema document.

    - #### parse

          public static Schema parse(java.io.Reader reader,
                     Schema.Type type,
                     java.lang.String uri)
                              throws org.jdom2.JDOMException,
                                     java.io.IOException

      Parses a schema definition from the specified character stream according to the specified schema type and returns a compiled schema object.
      Parameters:
        `reader` - the character stream to read the schema definition from.
        `type` - the schema type.
        `uri` - the location of the schema document (optional).
      Returns:
        the compiled schema.
      Throws:
        `org.jdom2.JDOMException` - if the schema document can not be parsed according to the specfied type.
        `java.io.IOException` - if an I/O error occurred while reading the schema document.

    - #### parse

          public static Schema parse(java.io.File file,
                     Schema.Type type)
                              throws org.jdom2.JDOMException,
                                     java.io.IOException

      Parses a schema definition from the specified file according to the specified schema type and returns a compiled schema object.
      Parameters:
        `file` - the file to read the schema definition from.
        `type` - the schema type.
      Returns:
        the compiled schema.
      Throws:
        `org.jdom2.JDOMException` - if the schema document can not be parsed according to the specfied type.
        `java.io.IOException` - if an I/O error occurred while reading the schema document.

    - #### parse

          public static Schema parse(org.xml.sax.InputSource source,
                     Schema.Type type)
                              throws org.jdom2.JDOMException,
                                     java.io.IOException

      Parses a schema definition from the specified SAX input source according to the specified schema type and returns a compiled schema object.
      Parameters:
        `source` - the SAX inout source to read the schema definition from.
        `type` - the schema type.
      Returns:
        the compiled schema.
      Throws:
        `org.jdom2.JDOMException` - if the schema document can not be parsed according to the specfied type.
        `java.io.IOException` - if an I/O error occurred while reading the schema document.