<?xml version='1.0' encoding='UTF-8'?>
<!--
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
-->
<!DOCTYPE faqs SYSTEM 'dtd/faqs.dtd'>
<faqs title='Configuring Parser'>
 <faq title='Validation and infoset augmentation'>
  <q>What's the result of having a DTD validator or XML Schema validator in the pipeline?</q>
  <a>
   <p>
    If a validator is included in the pipeline, the assessment is
    done, whether the validation feature is set to true or false.
    The validation feature only enables the validation constraint error 
    reporting and it does not control the infoset augmentation: if a 
    validator is included in the pipeline the parser will augment the 
    infoset according to the grammar specified for the instance document. 
   </p>
  </a>
 </faq>

 <faq title='Default Parser Configuration'>
  <q>What validation behavior do I expect from the default parser configuration?</q>
  <a>
   <p>
    The default configuration (&DefaultConfigLong;) includes the DTD validator 
    and the document scanner (which are both capable of namespace binding). Thus, the 
    <link idref='features' anchor="validation">validation feature</link> will enable 
    validation against a DTD only. To allow validation against XML Schemas you must turn 
    on the <link idref='features' anchor="validation">validation feature</link> and the 
    <link idref='features' anchor="validation.schema">schema feature</link>, and 
    XML Schema Validator will be inserted in the pipeline. if you've created your own 
    configuration which does not extend &DefaultConfig; (or another
    suitable configuration included with the parser), you must make sure that your 
    configuration inserts all needed validators in the pipeline.
   </p>
  </a>
 </faq>

 <faq title='Validation Features'>
  <q>What happens if I set both validation and schema validation features on?</q>
  <a>
   <p>
     If both validators are present in the pipeline (this is the default behavior), then
   </p>
   <ul>
    <li>if the instance document has only a DTD grammar
        (DOCTYPE before the root element), then only DTD
        validation errors are reported;</li>
    <li>if the instance document has only XML Schema grammars,
        then only XML Schema validation errors are reported</li>
    <li>if the instance document has both DTD and XML Schema
        grammars, validation errors for both DTD and XML
        Schema are reported;</li>
    <li>if no grammar can be found for the instance document,
        the last validator in the pipeline will report validation errors.
    </li>
   </ul>
   <p>
     An application may choose to create a configuration that does not have a DTD 
     validator but has an XML Schema validator. This will turn Xerces into a 
     non-compliant processor according to XML 1.0 and XML Schema specifications, 
     thus the validation/augmentation outcome is undefined.
   </p>

  </a>
</faq>
<faq title='Validation against a specific schema language'>
  <q>How can I tell the parser to validate against XML Schema and not to report DTD validation errors?</q>
  <a>
   <p>
    Using JAXP you can instruct the parser to validate against XML Schema only. The JAXP 1.4
    Validation API allows you to build an in-memory representation of an XML Schema which 
    you can then set on a parser factory. Parsers created from the factory will validate
    documents using the schema object you specified.
   </p>
   <p>By doing the following you can configure a SAX parser or DocumentBuilder to validate against XML Schema only:</p>
   <source>import javax.xml.XMLConstants;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.SAXParser;
import javax.xml.parsers.SAXParserFactory;
import javax.xml.transform.stream.StreamSource;
import javax.xml.validation.Schema;
import javax.xml.validation.SchemaFactory;

...

StreamSource[] sources = /* created by your application */;

SchemaFactory factory = 
    SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
Schema schema = factory.newSchema(sources);

/** Setup SAX parser for schema validation. */
SAXParserFactory spf = SAXParserFactory.newInstance();
spf.setNamespaceAware(true);
spf.setSchema(schema);
SAXParser parser = spf.newSAXParser();

/** Setup DocumentBuilder for schema validation. */
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
dbf.setSchema(schema);
DocumentBuilder db = dbf.newDocumentBuilder();

...
</source>
   <p>
    Changing the value of the schema language parameter passed to <code>SchemaFactory.newInstance()</code>
    to <code>http://www.w3.org/XML/XMLSchema/v1.1</code> will create a processor which supports XML Schema 1.1.
   </p>
   <source>import javax.xml.transform.stream.StreamSource;
import javax.xml.validation.Schema;
import javax.xml.validation.SchemaFactory;

...

StreamSource[] sources = /* created by your application */;

SchemaFactory factory = 
    SchemaFactory.newInstance("http://www.w3.org/XML/XMLSchema/v1.1");
Schema schema = factory.newSchema(sources);

...
</source>  
   <p>
    Another option is to use the JAXP schema language property defined by JAXP 1.2. If the schema
    language property has been set to <code>http://www.w3.org/2001/XMLSchema</code>
    and the parser has been configured to validate then your documents will be validated against 
    XML Schema only, even if they have a DTD.
   </p>
   <p>By doing the following you can configure a SAX parser to validate against XML Schema only:</p>
   <source>import javax.xml.parsers.SAXParser;
import javax.xml.parsers.SAXParserFactory;

...
SAXParserFactory spf = SAXParserFactory.newInstance();
spf.setValidating(true);
spf.setNamespaceAware(true);
SAXParser parser = spf.newSAXParser();
parser.setProperty(
    "http://java.sun.com/xml/jaxp/properties/schemaLanguage",
    "http://www.w3.org/2001/XMLSchema");
...
</source>
   <p>For a DocumentBuilder this can be accomplished by doing the following:</p>
   <source>import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;

...
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
dbf.setValidating(true);
dbf.setAttribute(
    "http://java.sun.com/xml/jaxp/properties/schemaLanguage",
    "http://www.w3.org/2001/XMLSchema");
DocumentBuilder docBuilder = dbf.newDocumentBuilder();
...
</source>
  </a>
 </faq>

</faqs>
