docs/faq-xs.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE faqs SYSTEM 'dtd/faqs.dtd'>
<faqs title='Using XML Schemas'>

  <faq title="Usage">
    <q>How do I validate against XML schema?</q>
    <a>
      <p>In this release, schema validation has been integrated with the 
	regular SAXParser and DOMParser classes. No special classes are 
	required to parse documents that use a schema.</p>
      <p>Each document that uses XML Schema grammars must specify the location of the
	grammars it uses by using an xsi:schemaLocation attribute if they use
	namespaces, and an xsi:noNamespaceSchemaLocation attribute
	otherwise.  These are usually placed on the root / top-level element 
	in the document, though they may occur on any element; for more details see XML
	Schema Part 1 section 4.3.2. 
	Here is an example with no target namespace: </p>
      <source>&lt;document
    xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
    xsi:noNamespaceSchemaLocation='document.xsd'&gt;
    ...
&lt;/document&gt;</source>
      <p>Here is an example with a target namespace. Note that it is an
	error to specify a different namespace than the target namespace
	defined in the Schema.</p>
      <source>&lt;document
    xmlns='http://my.com'
    xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
    xsi:schemaLocation='http://my.com document.xsd'&gt;
    ...
&lt;/document&gt;</source>
      <p>Review the sample file, 'data/personal.xsd' for an example of an XML 
	Schema grammar.</p>
      
    </a>
  </faq>

  <faq title="Using Entities and CDATA Sections">
    <q>How does XML Schema processor treats entities and CDATA secptions?</q>
    <a> 
      <p>According to the XML Infoset the infoset items contributing to the 
	<jump href='http://www.w3.org/TR/xml-infoset/#infoitem.character'>[character
	  information item]</jump> are: characters in the document, whether literally, as
	a character reference, or within a CDATA section, or within Entity
	Reference. The XML Schema specification 
	"requires as a precondition for assessment
	an information set as defined in [XML-Infoset]" 
	<jump href='http://www.w3.org/TR/xmlschema-1/#infoset'>(Appendix D)</jump> and thus Xerces might attempt to normalize data in an entity
	reference or CDATA section.  To preserve character data within entity references and 
	CDATA sections, 
	turn off http://apache.org/xml/features/validation/schema/normalized-value feature.
      </p>
    </a>
  </faq>

  <faq title="XML Schema API">
    <q>Does Xerces provide access to the post schema validation infoset (PSVI)?</q>
    <a>
      <p>
	Xerces defines an <link idref="api" anchor="xml-schema-api-documentation">XML Schema API</link>
	for accessing and querying the post schema validation infoset (PSVI) defined in 
	<jump href='http://www.w3.org/TR/xmlschema-1/#PSVI_contributions'>
	  Contributions to the post-schema-validation infoset (Appendix C.2)</jump>. 
	The interfaces defined in the <code>org.apache.xerces.xs</code> package allow 
	developers to access the XML Schema components, which follow as a consequence 
	of validation and/or assessment and also provide a means for accessing the
	PSVI from a document instance.
      </p>
    </a>
  </faq>
  
  <faq title="Changes to PSVI">
    <q>What happened to the PSVI interfaces in org.apache.xerces.xni.psvi?</q>
    <a>
      <p>
        The PSVI interfaces which used to be part of the <code>org.apache.xerces.xni.psvi</code>
        and <code>org.apache.xerces.impl.xs.psvi</code> packages were modified and have been moved
        into the <link idref="api" anchor="xml-schema-api-documentation">XML Schema API</link>.
      </p>
    </a>
  </faq>

  <faq title="Accessing PSVI via XNI">
    <q>How do I access PSVI via XNI?</q>
    <a> <p>From within an <code>XMLDocumentHandler</code>, one can retrieve PSVI
	information while in the scope of the document handler start/end element calls:</p>
      <source>import org.apache.xerces.xs.*;

...

public void startElement(QName element, XMLAttributes attributes,
    Augmentations augs) {
    ElementPSVI elemPSVI = (ElementPSVI)augs.getItem("ELEMENT_PSVI");
    // get PSVI items of this element out of elemPSVI
    short attemp = elemPSVI.getValidationAttempted();
    short validity = elemPSVI.getValidity();
    ...
}</source>
      <note>For more information, please refer to the API documentation
	of the PSVI interfaces.</note>
      
      <p>The above code shows how to retrieve PSVI information after
	elements/attributes are assessed. The other kind of information PSVI
	offers is the property
	<jump href="http://www.w3.org/TR/xmlschema-1/#e-schema_information">[schema information]</jump>.
	This property exposes all schema components in the schema that are used for
	assessment. These components and the schema itself are represented by
	interfaces in the <code>org.apache.xerces.xs</code> package.</p>
      <p>[schema information] property is only available on the
	<code>endElement</code> method for the validation root. When this method
	is called, information about various components can be retrieved by</p>
      <source>import org.apache.xerces.xs.*;

...

public void endElement(QName element, Augmentations augs) {
    ElementPSVI elemPSVI = (ElementPSVI)augs.getItem("ELEMENT_PSVI");
    XSModel xsModel = elemPSVI.getSchemaInformation();
    // get a list of [namespace schema information information item]s,
    // one for each namespace.
    XSNamespaceItemList nsItems = xsModel.getNamespaceItems();
    ...
    
    // get an element declaration of the specified name and namespace
    XSElementDeclaration elemDecl = xsModel.getElementDeclaration
        (namespace, name);
    ...
}</source>
    </a>
  </faq>


  <faq title="Accessing PSVI via DOM">
    <q>How do I access PSVI via DOM?</q>  
    <a><anchor name="dom3-psvi"/><p>Use  
	the <link idref='properties' anchor="dom.document-class-name">http://apache.org/xml/properties/dom/document-class-name</link> property
 	to set <code>org.apache.xerces.dom.PSVIDocumentImpl</code> as the implementation 
        of the <code>org.w3c.dom.Document</code> interface. In the resulting DOM tree, you may cast 
        <code>org.w3c.dom.Element</code> to the 
        <code>org.apache.xerces.xs.ElementPSVI</code> and  
        <code>org.w3c.dom.Attr</code> to the 
        <code>org.apache.xerces.xs.AttributePSVI</code>. 
      </p>
      <source>import org.apache.xerces.xs.ElementPSVI;
import org.apache.xerces.xs.XSModel;
import org.apache.xerces.xs.XSNamedMap;

...

Document document = parser.getDocument();
Element root = document.getDocumentElement();

// retrieve PSVI for the root element
ElementPSVI rootPSVI = (ElementPSVI)root;

// retrieve the schema used in validation of this document
XSModel schema = rootPSVI.getSchemaInformation();
XSNamedMap elementDeclarations =
    schema.getComponents(XSConstants.ELEMENT_DECLARATION);

// get schema normalized value
String normalizedValue = rootPSVI.getSchemaNormalizedValue();</source>
    </a>
  </faq>


  <faq title="Accessing PSVI via SAX">
    <q>How do I access PSVI via SAX?</q>
    <a> <p>The Xerces SAX parser also implements the
	<code>org.apache.xerces.xs.PSVIProvider</code> interface.
	Within the scope of the methods handling the start 
	(<code>org.xml.sax.ContentHandler.startElement</code>) and 
	end (<code>org.xml.sax.ContentHandler.endElement</code>) of an element, 
	applications may use the <code>PSVIProvider</code> to retrieve the PSVI 
	related to the element and its attributes.
      </p>
      <source>import org.apache.xerces.xs.PSVIProvider;
import javax.xml.parsers.SAXParser;
import javax.xml.parsers.SAXParserFactory;

...

SAXParserFactory factory = SAXParserFactory.newInstance();
SAXParser parser = factory.newSAXParser();
PSVIProvider psviProvider = (PSVIProvider)parser;</source>
    </a>
  </faq>
  <faq title="Parsing and analyzing an XML schema">
    <q>How do I parse and analyze an XML schema?</q>
    <a> <p>Please, refer to the <link idref='faq-grammars'>Examining Grammars</link> FAQ.</p>
    </a>
  </faq>
</faqs>