docs/faq-xinclude.xml - xerces2-j - Git at Google

 <?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='Using XInclude'>

   <faq title="Usage">
     <q>How do I enable XInclude processing?</q>
     <a>
      <p>
       Applications using JAXP 1.3 can enable XInclude processing by setting
       XInclude awareness on the parser factory. The following demonstrates
       how to accomplish this with SAX:
      </p>
      <source>import javax.xml.parsers.SAXParserFactory;

 SAXParserFactory spf = SAXParserFactory.newInstance();
 spf.setNamespaceAware(true);
 spf.setXIncludeAware(true);
 ...
 </source>
      <p>
       You can also enable XInclude processing by turning on the
       <link idref='features' anchor="xinclude">XInclude feature</link>.
      </p>
     </a>
   </faq>

   <faq title="XInclude and validation">
    <q>How do the validation features interact with XInclude processing?</q>
    <a>
     <p>
      If the <link idref='features' anchor="validation">validation feature</link>
      is turned on then DTD validation will be performed on each source document
      (to the XInclude processor) against their respective DTDs.
     </p>
     <p>
      If both the <link idref='features' anchor="validation">validation feature</link>
      and the <link idref='features' anchor="validation.schema">schema validation
      feature</link> are turned on then schema validation will be performed on the
      result infoset generated by the XInclude processor. DTD validation will be
      performed on each source document which contains a DTD. No DTD validation errors
      will be reported for source documents which have no DTD.
     </p>
    </a>
   </faq>

   <faq title="xml:base attributes and XML Schema validation">
     <q>Why are xml:base attributes added, which make Schema validation fail?</q>
     <a>
      <p>
       According to the specification for XInclude, processors must add an <code>xml:base</code>
       attribute to elements included from locations with a different base URI.  Without
       these attributes, the resulting infoset information would be incorrect.  Unfortunately,
       these attributes make XInclude processing not transparent to Schema validation.
      </p>
      <p>
       One solution to this is to modify your schema to allow <code>xml:base</code>
       attributes to appear on elements that might be included from different base URIs.
       There is a similar problem with <code>xml:lang</code> attributes that are added as a result
       of language fixup. If the addition of <code>xml:base</code> and/or <code>xml:lang</code>
       is undesired by your application, you can disable
       <link idref='features' anchor='xinclude.fixup-base-uris'>base URI fixup</link> and
       <link idref='features' anchor='xinclude.fixup-language'>language fixup</link> so that
       these attributes will not be added.
      </p>
     </a>
   </faq>

   <faq title="XML Base Support">
     <q>Does the XInclude processor recognize xml:base attributes?</q>
     <a>
      <p>
       Yes. The XInclude specification requires processors to use the base URI
       (as specified in the <jump href="http://www.w3.org/TR/xmlbase/">XML Base</jump>
       recommendation) to resolve relative IRIs to compute the
       <jump href="http://www.w3.org/TR/2006/REC-xinclude-20061115/#include-location">include location</jump>.
       Support for XML Base was added to the XInclude implementation in Xerces-J 2.6.0.
      </p>
     </a>
   </faq>

   <faq title="Language Fixup">
     <q>Does the XInclude processor perform language fixup?</q>
     <a>
      <p>
       Yes. The XInclude processor will preserve language information on a top-level included element
       by adding an <code>xml:lang</code> attribute if its include parent has a different [language]
       property. Support for language fixup was added to the XInclude implementation in Xerces-J 2.7.0.
      </p>
     </a>
   </faq>

   <faq title="References Property Fixup">
     <q>Does the XInclude processor perform references property fixup?</q>
     <a>
      <p>
       Section <jump href="http://www.w3.org/TR/2006/REC-xinclude-20061115/#references-property">4.5.3</jump>
       of the XInclude 1.0 W3C Recommendation describes fixup of the [references] property
       of an attribute information item. For IDREF/IDREFS the property contains an ordered
       list of element information items. Xerces provides no mechanism for accessing this
       property nor does it keep an internal representation. It should be noted that neither
       the SAX or DOM APIs have native support for the [references] property. For Xerces,
       references property fixup is a no-op.
      </p>
     </a>
   </faq>

   <faq title="Document Fragments">
     <q>Does the XInclude processor support XPointer?</q>
     <a>
      <p>
       Yes. The XInclude processor supports the
       <jump href="http://www.w3.org/TR/2003/REC-xptr-framework-20030325/">XPointer Framework</jump>
       and the
       <jump href="http://www.w3.org/TR/2003/REC-xptr-element-20030325/">XPointer element() Scheme</jump>.
       The XPointer xpointer() Scheme is currently not supported.
      </p>
     </a>
   </faq>

   <faq title="XPointer and IDs">
     <q>What types of IDs are currently supported for XPointers?</q>
     <a>
      <p>
       For shorthand pointers and element() XPointers, currently only
       <jump href="http://www.w3.org/TR/xptr-framework/#term-ddi">DTD-determined ID</jump>s
       are supported. <jump href="http://www.w3.org/TR/xptr-framework/#term-sdi">schema-determined ID</jump>s
       may be supported in a future release.
      </p>
     </a>
   </faq>

   <faq title="Content Negotiation">
     <q>Are the values of the content negotiation attributes used in an HTTP request?</q>
     <a>
      <p>
       Yes, the values of the <code>accept</code> and <code>accept-language</code> attributes
       from an <jump href="http://www.w3.org/TR/2006/REC-xinclude-20061115/#include_element">include</jump>
       element are included as request properties in an HTTP request. Support for content negotiation
       when parse="xml" was added to the XInclude implementation in Xerces-J 2.7.0.
      </p>
     </a>
   </faq>

   <faq title="The Namespace: 'http://www.w3.org/2003/XInclude'">
     <q>Will the XInclude processor process include elements from the 'http://www.w3.org/2003/XInclude' namespace?</q>
     <a>
      <p>
       No. The namespace for XInclude was changed back to <code>http://www.w3.org/2001/XInclude</code>
       in the <jump href="http://www.w3.org/TR/2004/CR-xinclude-20040413/">Candidate Recommendation (April 2004)</jump>.
       The <code>http://www.w3.org/2003/XInclude</code> is no longer recognized.
      </p>
     </a>
   </faq>

 </faqs>
	<?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='Using XInclude'>

	<faq title="Usage">
	<q>How do I enable XInclude processing?</q>
	<a>
	<p>
	Applications using JAXP 1.3 can enable XInclude processing by setting
	XInclude awareness on the parser factory. The following demonstrates
	how to accomplish this with SAX:
	</p>
	<source>import javax.xml.parsers.SAXParserFactory;

	SAXParserFactory spf = SAXParserFactory.newInstance();
	spf.setNamespaceAware(true);
	spf.setXIncludeAware(true);
	...
	</source>
	<p>
	You can also enable XInclude processing by turning on the
	<link idref='features' anchor="xinclude">XInclude feature</link>.
	</p>
	</a>
	</faq>

	<faq title="XInclude and validation">
	<q>How do the validation features interact with XInclude processing?</q>
	<a>
	<p>
	If the <link idref='features' anchor="validation">validation feature</link>
	is turned on then DTD validation will be performed on each source document
	(to the XInclude processor) against their respective DTDs.
	</p>
	<p>
	If both the <link idref='features' anchor="validation">validation feature</link>
	and the <link idref='features' anchor="validation.schema">schema validation
	feature</link> are turned on then schema validation will be performed on the
	result infoset generated by the XInclude processor. DTD validation will be
	performed on each source document which contains a DTD. No DTD validation errors
	will be reported for source documents which have no DTD.
	</p>
	</a>
	</faq>

	<faq title="xml:base attributes and XML Schema validation">
	<q>Why are xml:base attributes added, which make Schema validation fail?</q>
	<a>
	<p>
	According to the specification for XInclude, processors must add an <code>xml:base</code>
	attribute to elements included from locations with a different base URI. Without
	these attributes, the resulting infoset information would be incorrect. Unfortunately,
	these attributes make XInclude processing not transparent to Schema validation.
	</p>
	<p>
	One solution to this is to modify your schema to allow <code>xml:base</code>
	attributes to appear on elements that might be included from different base URIs.
	There is a similar problem with <code>xml:lang</code> attributes that are added as a result
	of language fixup. If the addition of <code>xml:base</code> and/or <code>xml:lang</code>
	is undesired by your application, you can disable
	<link idref='features' anchor='xinclude.fixup-base-uris'>base URI fixup</link> and
	<link idref='features' anchor='xinclude.fixup-language'>language fixup</link> so that
	these attributes will not be added.
	</p>
	</a>
	</faq>

	<faq title="XML Base Support">
	<q>Does the XInclude processor recognize xml:base attributes?</q>
	<a>
	<p>
	Yes. The XInclude specification requires processors to use the base URI
	(as specified in the <jump href="http://www.w3.org/TR/xmlbase/">XML Base</jump>
	recommendation) to resolve relative IRIs to compute the
	<jump href="http://www.w3.org/TR/2006/REC-xinclude-20061115/#include-location">include location</jump>.
	Support for XML Base was added to the XInclude implementation in Xerces-J 2.6.0.
	</p>
	</a>
	</faq>

	<faq title="Language Fixup">
	<q>Does the XInclude processor perform language fixup?</q>
	<a>
	<p>
	Yes. The XInclude processor will preserve language information on a top-level included element
	by adding an <code>xml:lang</code> attribute if its include parent has a different [language]
	property. Support for language fixup was added to the XInclude implementation in Xerces-J 2.7.0.
	</p>
	</a>
	</faq>

	<faq title="References Property Fixup">
	<q>Does the XInclude processor perform references property fixup?</q>
	<a>
	<p>
	Section <jump href="http://www.w3.org/TR/2006/REC-xinclude-20061115/#references-property">4.5.3</jump>
	of the XInclude 1.0 W3C Recommendation describes fixup of the [references] property
	of an attribute information item. For IDREF/IDREFS the property contains an ordered
	list of element information items. Xerces provides no mechanism for accessing this
	property nor does it keep an internal representation. It should be noted that neither
	the SAX or DOM APIs have native support for the [references] property. For Xerces,
	references property fixup is a no-op.
	</p>
	</a>
	</faq>

	<faq title="Document Fragments">
	<q>Does the XInclude processor support XPointer?</q>
	<a>
	<p>
	Yes. The XInclude processor supports the
	<jump href="http://www.w3.org/TR/2003/REC-xptr-framework-20030325/">XPointer Framework</jump>
	and the
	<jump href="http://www.w3.org/TR/2003/REC-xptr-element-20030325/">XPointer element() Scheme</jump>.
	The XPointer xpointer() Scheme is currently not supported.
	</p>
	</a>
	</faq>

	<faq title="XPointer and IDs">
	<q>What types of IDs are currently supported for XPointers?</q>
	<a>
	<p>
	For shorthand pointers and element() XPointers, currently only
	<jump href="http://www.w3.org/TR/xptr-framework/#term-ddi">DTD-determined ID</jump>s
	are supported. <jump href="http://www.w3.org/TR/xptr-framework/#term-sdi">schema-determined ID</jump>s
	may be supported in a future release.
	</p>
	</a>
	</faq>

	<faq title="Content Negotiation">
	<q>Are the values of the content negotiation attributes used in an HTTP request?</q>
	<a>
	<p>
	Yes, the values of the <code>accept</code> and <code>accept-language</code> attributes
	from an <jump href="http://www.w3.org/TR/2006/REC-xinclude-20061115/#include_element">include</jump>
	element are included as request properties in an HTTP request. Support for content negotiation
	when parse="xml" was added to the XInclude implementation in Xerces-J 2.7.0.
	</p>
	</a>
	</faq>

	<faq title="The Namespace: 'http://www.w3.org/2003/XInclude'">
	<q>Will the XInclude processor process include elements from the 'http://www.w3.org/2003/XInclude' namespace?</q>
	<a>
	<p>
	No. The namespace for XInclude was changed back to <code>http://www.w3.org/2001/XInclude</code>
	in the <jump href="http://www.w3.org/TR/2004/CR-xinclude-20040413/">Candidate Recommendation (April 2004)</jump>.
	The <code>http://www.w3.org/2003/XInclude</code> is no longer recognized.
	</p>
	</a>
	</faq>

	</faqs>