~ubuntu-branches/ubuntu/karmic/libxerces2-java/karmic

<!--

 * Copyright 1999-2006 The Apache Software Foundation.

 *

 * Licensed 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.

-->

   the JAXP interfaces, the following instructions tell you how to

   set features on document builders and SAX parsers created from

   the JAXP interfaces.

   <code>setFeature(String,boolean)</code> method which 

   can be used to set features on the underlying parser.

   For example:

  <source>import javax.xml.parsers.DocumentBuilderFactory;

import javax.xml.parsers.DocumentBuilder;

DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();

dbf.setNamespaceAware(true);

 

    dbf.setFeature("http://apache.org/xml/features/allow-java-encodings", 

                   true);

catch (ParserConfigurationException e) {

   The SAXParserFactory interface contains a

   <code>setFeature(String,boolean)</code> method which can be used

   to set features on the underlying implementation of <code>XMLReader</code>.

   Once you create the SAXParser you can retrieve the underlying

   <code>XMLReader</code> allowing you to set and query features on it directly.

   For example:

  <feature name='http://xml.org/sax/features/use-entity-resolver2'

           id='use-entity-resolver2'>

   <true>

    The methods of the org.xml.sax.ext.EntityResolver2 interface will be used when an object implementing

    this interface is registered with the parser using setEntityResolver.

   </true>

   <false>

    The methods of the org.xml.sax.ext.EntityResolver2 interface will not be used.

   </false>

   <default value='true'/>

   <access general='read-write'/>

   <since value='&ParserName; 2.7.0'/>

   <note>

    If the <link anchor="disallow-doctype-decl">disallow DOCTYPE declaration</link> feature is set to true

    org.xml.sax.ext.EntityResolver2.getExternalSubset() will not be called when the document contains no

    DOCTYPE declaration.

   </note>

   <see idref='disallow-doctype-decl'/>

   <see idref='validation'/>

   <see idref='nonvalidating.load-external-dtd'/>

  </feature>

   <true>Turn on XML Schema validation by inserting an XML Schema validator into the pipeline.

   <note> Validation errors will only be reported if the <link anchor="validation">validation feature</link> is set to true. For more information, please, refer to the <link idref='faq-pcfp'>FAQ</link>

   </note>

   <note> 

    Checking of constraints on a schema grammar which are either time-consuming or memory intensive

    such as unique particle attribution will only occur if the

    <link anchor="validation.schema-full-checking">schema full checking feature</link> is set to true.

    which may be time-consuming or memory intensive. Currently, unique

    particle attribution constraint checking and particle derivation 

    restriction checking are controlled by this option. 

  <feature name='http://apache.org/xml/features/validation/schema/ignore-xsi-type-until-elemdecl'

           id='validation.schema.ignore-xsi-type-until-elemdecl'>

   <true>xsi:type attributes will be ignored until a global element declaration has been found, at which point xsi:type attributes will be processed on the element for which the global element declaration was found as well as its descendants.</true>

   <false>Do not ignore xsi:type attributes.</false>

   <default value='false'/>

   <access parsing='read-only' not-parsing='read-write'/>

   <since value='&ParserName; 2.8.0'/>

   <see idref='validation'/>

   <see idref='validation.schema'/>

  </feature>

  

  <feature name='http://apache.org/xml/features/generate-synthetic-annotations'

           id='generate-synthetic-annotations'>

   <true>Enable generation of synthetic annotations. A synthetic annotation will be generated when a schema component has non-schema attributes but no child annotation.</true>

   <false>Do not generate synthetic annotations.</false>

   <default value='false'/>

   <access parsing='read-only' not-parsing='read-write'/>

   <since value='&ParserName; 2.7.0'/>

   <see idref='validation'/>

   <see idref='validation.schema'/>

   <see idref='validate-annotations'/>

  </feature>

  

  <feature name='http://apache.org/xml/features/validate-annotations'

           id='validate-annotations'>

   <true>Schema annotations will be laxly validated against available schema components.</true>

   <false>Do not validate schema annotations.</false>

   <default value='false'/>

   <access parsing='read-only' not-parsing='read-write'/>

   <since value='&ParserName; 2.7.0'/>

   <see idref='validation'/>

   <see idref='validation.schema'/>

   <see idref='generate-synthetic-annotations'/>

  </feature>

  

  <feature name='http://apache.org/xml/features/honour-all-schemaLocations'

           id='honour-all-schemaLocations'>

    <true>All schema location hints will be used to locate the components for a given target namespace.</true>

    <false>Only the first schema location hint encountered by the processor will be used to locate the components for a given target namespace.</false>

    <default value='false'/>

    <access parsing='read-only' not-parsing='read-write'/>

    <since value='&ParserName; 2.7.0'/>

  </feature>

  <feature name='http://apache.org/xml/features/validation/balance-syntax-trees'

           id='validation.balance-syntax-trees'>

   <true>Construct an optimal representation for DTD content models to significantly 

         reduce the likelihood a StackOverflowError will occur when large content 

         models are processed.</true>

   <false>

    Do not invest processing time to construct an optimal representation for DTD content models.

   </false>

   <default value='false'/>

   <access parsing='read-only' not-parsing='read-write'/>

   <since value='&ParserName; 2.8.0'/>

   <note>

    Enabling this feature may cost your application some performance when DTDs are 

    processed so it is recommended that it only be turned on when necessary.

   </note>

  </feature>

  <feature name='http://apache.org/xml/features/validation/id-idref-checking'

           id='validation.id-idref-checking'>

   <true>Enable checking of ID/IDREF constraints.</true>

   <false>

    Disable checking of ID/IDREF constraints. Validation will not fail if 

    there are non-unique ID values or dangling IDREF values in the document.

   </false>

   <default value='true'/>

   <access parsing='read-only' not-parsing='read-write'/>

   <since value='&ParserName; 2.8.0'/>

   <note>This feature only applies to schema validation.</note>

   <see idref='validation'/>

   <see idref='validation.schema'/>

  </feature>

  <feature name='http://apache.org/xml/features/validation/identity-constraint-checking'

           id='validation.identity-constraint-checking'>

   <true>Enable identity constraint checking.</true>

   <false>Disable identity constraint checking.</false>

   <default value='true'/>

   <access parsing='read-only' not-parsing='read-write'/>

   <since value='&ParserName; 2.8.0'/>

   <see idref='validation'/>

   <see idref='validation.schema'/>

  </feature>

  <feature name='http://apache.org/xml/features/validation/unparsed-entity-checking'

           id='validation.unparsed-entity-checking'>

   <true>Check that each value of type ENTITY matches the name of an unparsed entity declared in the DTD.</true>

   <false>Do not check that each value of type ENTITY matches the name of an unparsed entity declared in the DTD.</false>

   <default value='true'/>

   <access parsing='read-only' not-parsing='read-write'/>

   <since value='&ParserName; 2.8.0'/>

   <note>This feature only applies to schema validation.</note>

   <see idref='validation'/>

   <see idref='validation.schema'/>

  </feature>

   <since value='&ParserName; 2.3.0'/>

   <since value='&ParserName; 2.3.0'/>

  

  <feature name='http://apache.org/xml/features/xinclude'

           id='xinclude'>

   <true>Enable XInclude processing.</true>

   <false>Do not perform XInclude processing.</false>

   <default value='false'/>

   <since value='&ParserName; 2.7.0'/>

   <see idref='xinclude.fixup-base-uris'/>

   <see idref='xinclude.fixup-language'/>

  </feature>

  

  <feature name='http://apache.org/xml/features/xinclude/fixup-base-uris'

           id='xinclude.fixup-base-uris'>

   <true>Perform base URI fixup as specified by the XInclude Recommendation.</true>

   <false>Do not perform base URI fixup. The XInclude processor will not add xml:base attributes.</false>

   <default value='true'/>

   <since value='&ParserName; 2.7.0'/>

   <see idref='xinclude'/>

  </feature>

  

  <feature name='http://apache.org/xml/features/xinclude/fixup-language'

           id='xinclude.fixup-language'>

   <true>Perform language fixup as specified by the XInclude Recommendation.</true>

   <false>Do not perform language fixup. The XInclude processor will not add xml:lang attributes.</false>

   <default value='true'/>

   <since value='&ParserName; 2.7.0'/>

   <see idref='xinclude'/>

  </feature>

   <note>In the <code>LSParser</code> implementation the default value of 

    nodes corresponding to their fully expanded substitution text will 

    <code>Text#isElementContentWhitespace():boolean</code> method. 

  <feature name='http://xml.org/sax/features/lexical-handler/parameter-entities'

           id='lexical-handler.parameter-entities'>

   <true>

    Report the beginning and end of parameter entities to a registered LexicalHandler.

   </true>

   <false>

    Do not report the beginning and end of parameter entities to a registered LexicalHandler.

   </false>

   <default value='true'/>

   <since value='&ParserName; 2.7.0'/>

  </feature>

  <feature name='http://xml.org/sax/features/is-standalone'

           id='is-standalone'>

   <true>

    The document specified standalone="yes" in its XML declaration.

   </true>

   <false>

    The document specified standalone="no" in its XML declaration or the 

    standalone document declaration was absent.

   </false>

   <access parsing='read-only' not-parsing='none'/>

   <since value='&ParserName; 2.7.0'/>

  </feature>

  <feature name='http://xml.org/sax/features/resolve-dtd-uris'

           id='resolve-dtd-uris'>

   <true>

    The system identifiers passed to the notationDecl, unparsedEntityDecl, and 

    externalEntityDecl events will be absolutized relative to their base URIs before reporting.

   </true>

   <false>

    System identifiers in declarations will not be absolutized before reporting.

   </false>

   <default value='true'/>

   <since value='&ParserName; 2.7.0'/>

   <note>

    This feature does not apply to EntityResolver.resolveEntity(), which is not used to report declarations, 

    or to LexicalHandler.startDTD(), which already provides the non-absolutized URI.

   </note>

  </feature>

  <feature name='http://xml.org/sax/features/unicode-normalization-checking'

           id='unicode-normalization-checking'>

   <true>

    Perform Unicode normalization checking (as described in section 2.13 and Appendix B 

    of the XML 1.1 Recommendation) and report normalization errors.

   </true>

   <false>

    Do not report Unicode normalization errors.

   </false>

   <default value='false'/>

   <since value='&ParserName; 2.7.0'/>

   <note>

    As there is currently no support for Unicode normalization checking, this 

    feature can only be set to false.

   </note>

  </feature>

  <feature name='http://xml.org/sax/features/use-attributes2'

           id='use-attributes2'>

   <true>

    The Attributes objects passed by the parser in org.xml.sax.ContentHandler.startElement() implement the org.xml.sax.ext.Attributes2 interface.

   </true>

   <false>

    The Attributes objects passed by the parser do not implement the org.xml.sax.ext.Attributes2 interface.

   </false>

   <access general='read-only'/>

   <since value='&ParserName; 2.7.0'/>

   <note>

    Xerces-J will always report Attributes objects that also implement org.xml.sax.ext.Attributes2

    so the value of this feature will always be true.

   </note>

  </feature>

  <feature name='http://xml.org/sax/features/use-locator2'

           id='use-locator2'>

   <true>

    The Locator objects passed by the parser in org.xml.sax.ContentHandler.setDocumentLocator() implement the org.xml.sax.ext.Locator2 interface.

   </true>

   <false>

    The Locator objects passed by the parser do not implement the org.xml.sax.ext.Locator2 interface.

   </false>

   <access general='read-only'/>

   <since value='&ParserName; 2.7.0'/>

   <note>

    Xerces-J will always report Locator objects that also implement org.xml.sax.ext.Locator2

    so the value of this feature will always be true.

   </note>

  </feature>

  <feature name='http://xml.org/sax/features/xmlns-uris'

           id='xmlns-uris'>

   <true>

    When the namespace-prefixes feature is set to true, namespace declaration attributes

    will be reported as being in the http://www.w3.org/2000/xmlns/ namespace.

   </true>

   <false>

    Namespace declaration attributes are reported as having no namespace.

   </false>

   <default value='false'/>

   <since value='&ParserName; 2.7.0'/>

   <see idref='namespaces'/>

   <see idref='namespace-prefixes'/>

  </feature>

  <feature name='http://xml.org/sax/features/xml-1.1'

           id='xml-1.1'>

   <true>

    The parser supports both XML 1.1 and XML 1.0.

   </true>

   <false>

    The parser supports only XML 1.0.

   </false>

   <access general='read-only'/>

   <since value='&ParserName; 2.7.0'/>

   <note>

    The value of this feature will depend on whether the

    parser configuration owned by the SAX parser is known

    to support XML 1.1.

   </note>

  </feature>

  

   <since value='&ParserName; 2.5.0'/>

    contact the j-users@xerces.apache.org mailing list.