<commit_before><?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='General FAQs'>
  <faq title="Querying Xerces Version">
    <q>How do I find out which Xerces version I am using?</q>
    <a> <p>To find out the release version of Xerces, execute the following:
         <code>java org.apache.xerces.impl.Version</code>.
    </p>
    </a>
  </faq>
  <faq title="JIRA">
    <q>How do I use JIRA to report bugs?</q>
    <a> <p>
    Please refer to the <link idref="jira">Reporting bugs in JIRA</link>.
    </p>
    </a>
  </faq>

    <faq title="Jar file changes">
    <q>What happened to xerces.jar?</q>
    <a>
        <p>In order to take advantage of the fact that this parser is 
        very often used in conjunction with other XML technologies, 
        such as XSLT processors, which also rely on standard
        API&apos;s like DOM and SAX, xerces.jar was split into two
        jarfiles:
        </p>
        <ul>
        <li><code>xml-apis.jar</code> contains the DOM level 3,
        SAX 2.0.2 and the JAXP 1.3 APIs;</li>
        <li><code>xercesImpl.jar</code> contains the implementation of
        these API&apos;s as well as the XNI API.
        </li>
        </ul>
        <p>For backwards compatibility, we have retained the ability
        to generate xerces.jar.  For instructions, see <link
        idref="install">the installation documentation</link>.
        </p>
    </a>
 </faq>
 <faq title="Using JAXP 1.3 on JDK 1.4">
  <q>How can I use JAXP 1.3 on JDK 1.4?</q>
  <a>
   <p>
    Use the <jump href="http://java.sun.com/j2se/1.4/docs/guide/standards/">Endorsed Standards Override Mechanism</jump>
    to specify xml-apis.jar and xercesImpl.jar. This will override the version of JAXP in the JDK. A more complete 
    description is available <jump href="http://xml.apache.org/xalan-j/faq.html#faq-N100CC">here</jump>.
   </p>
   <p>
     The following methods <strong>do not work</strong>:
     <ul>
      <li>Using the CLASSPATH environment variable or using -classpath to place the new classes in the classpath.</li>
      <li>Using the -jar option to explicitly execute the classes inside the new jar files.</li>
     </ul>
   </p>
  </a>
 </faq>
 <faq title="ClassCastException using Xerces">
   <q>Why do I get a ClassCastException when I use Xerces and WebSphere Application Server?</q>
   <a>
     <p>
      Xerces uses the <code>ObjectFactory</code> class to load some classes dynamically, e.g. the parser configuration.
      The <code>ObjectFactory</code> finds the specified implementation class by querying the system property, reading
      <code>META-INF/services/factoryId</code> file or using a fallback classname. After the implementation is found, the 
      <code>ObjectFactory</code> tries to load the file using the context classloader and if it is null, the 
      <code>ObjectFactory</code> uses the system classloader. 
     </p>
     <p>
      If you run Xerces in an environment, such as WebSphere&#xAE; Application Server, that has multiple classloaders you may 
      get ClassCastExceptions thrown from Xerces because different classloaders might get involved in loading Xerces classes.
      For example, ClassCastExceptions may occur when utility EAR classes that use Xerces load Xerces classes from WAR modules. 
     </p>
     <p>
      We suggest you read the <jump href="http://www-106.ibm.com/developerworks/websphere/library/techarticles/0310_searle/searle.html">"Avoiding ClassCastExceptions..."</jump>
      article which explains a workaround for this problem. Also you might want to read the
      <jump href="http://www-106.ibm.com/developerworks/websphere/library/techarticles/0112_deboer/deboer.html">"J2EE Class Loading Demystified"</jump>
      article that explains how multiple classloaders work in WebSphere Application Server.
    </p>
  </a>
 </faq>
 <faq title="Xerces HTML, XHTML, and XML Serializers">
   <q>What can I use instead of Xerces' HTML, XHTML, or XML serializers?
 </q>
 <a>
<p>
If you want to achieve interoperability, you should not be using Xerces serialization code directly. 
Instead, the <jump href="http://java.sun.com/xml/jaxp/index.jsp">JAXP</jump> Transformer API should be used to serialize HTML, XHTML, and SAX. The <jump href="http://www.w3.org/DOM/DOMTR">DOM</jump> Level 3 Load and Save API (or JAXP Transformer API) should be used to serialize DOM.
</p>

    <p>Using <jump href="http://java.sun.com/xml/jaxp/index.jsp">JAXP</jump> you can serialize HTML and XHTML as follows:</p>

<source>
// Create an "identity" transformer - copies input to output
Transformer t = TransformerFactory.newInstance().newTransformer();

// for "XHTML" serialization, use the output method "xml"
// and set publicId as shown
t.setOutputProperty(OutputKeys.METHOD, "xml");

t.setOutputProperty(OutputKeys.DOCTYPE_PUBLIC,
                    "-//W3C//DTD XHTML 1.0 Transitional//EN");

t.setOutputProperty(OutputKeys.DOCTYPE_SYSTEM,
               "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd");

// For "HTML" serialization, use
t.setOutputProperty(OutputKeys.METHOD, "html");

// Serialize DOM tree
t.transform(new DOMSource(doc), new StreamResult(System.out));
</source>

<p>

You can find more details about the future of Xerces' serializers in the <jump href="http://marc.theaimsgroup.com/?l=xalan-dev&amp;m=107593381313807&amp;w=2">archives</jump>.
</p>
<note>The HTML and XHTML serializers (<code>org.apache.xml.serialize</code>) have been <code>deprecated</code> in the Xerces 2.6.2 release. We might deprecate <code>XMLSerializer</code> in a future release.</note>
  </a>
 </faq>
 <faq title="Obtaining smaller jars">
   <q>I don&apos;t need all the features Xerces provides, but I&apos;m
   running in an environment where space is at a premium.  Is there
   anything I can do?
 </q>
 <a>
    <p>
    Partially to address this issue, we've recently begun to
    distribute compressed jarfiles instead of our traditionally
    uncompressed files.  But if you still need a smaller jar, and
    don&apos;t need things like support for XML Schema or the WML/HTML
    DOM implementations that Xerces provides, then look at the
    <code>dtdjars</code> target in our
    buildfile. 
    </p>
  </a>
 </faq>
 <faq title='Validation against DTD'>
  <q>How do I turn on DTD validation?</q>
  <a>
   <p>
    You can turn validation on and off via methods available
    on the SAX2 <code>XMLReader</code> interface. While only the 
    <code>SAXParser</code> implements the <code>XMLReader</code>
    interface, the methods required for turning on validation
    are available to both parser classes, DOM and SAX.
    <br/>
    The code snippet below shows how to turn validation on -- assume
    that <ref>parser</ref> is an instance of either <commit_msg>Updating the serialization FAQ to reflect the recent move to the shared  Xalan serializer and the deprecation of Xerces' native serializer.<commit_after><?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='General FAQs'>
  <faq title="Querying Xerces Version">
    <q>How do I find out which Xerces version I am using?</q>
    <a> <p>To find out the release version of Xerces, execute the following:
         <code>java org.apache.xerces.impl.Version</code>.
    </p>
    </a>
  </faq>
  <faq title="JIRA">
    <q>How do I use JIRA to report bugs?</q>
    <a> <p>
    Please refer to the <link idref="jira">Reporting bugs in JIRA</link>.
    </p>
    </a>
  </faq>

    <faq title="Jar file changes">
    <q>What happened to xerces.jar?</q>
    <a>
        <p>In order to take advantage of the fact that this parser is 
        very often used in conjunction with other XML technologies, 
        such as XSLT processors, which also rely on standard
        API&apos;s like DOM and SAX, xerces.jar was split into two
        jarfiles:
        </p>
        <ul>
        <li><code>xml-apis.jar</code> contains the DOM level 3,
        SAX 2.0.2 and the JAXP 1.3 APIs;</li>
        <li><code>xercesImpl.jar</code> contains the implementation of
        these API&apos;s as well as the XNI API.
        </li>
        </ul>
        <p>For backwards compatibility, we have retained the ability
        to generate xerces.jar.  For instructions, see <link
        idref="install">the installation documentation</link>.
        </p>
    </a>
 </faq>
 <faq title="Using JAXP 1.3 on JDK 1.4">
  <q>How can I use JAXP 1.3 on JDK 1.4?</q>
  <a>
   <p>
    Use the <jump href="http://java.sun.com/j2se/1.4/docs/guide/standards/">Endorsed Standards Override Mechanism</jump>
    to specify xml-apis.jar and xercesImpl.jar. This will override the version of JAXP in the JDK. A more complete 
    description is available <jump href="http://xml.apache.org/xalan-j/faq.html#faq-N100CC">here</jump>.
   </p>
   <p>
     The following methods <strong>do not work</strong>:
     <ul>
      <li>Using the CLASSPATH environment variable or using -classpath to place the new classes in the classpath.</li>
      <li>Using the -jar option to explicitly execute the classes inside the new jar files.</li>
     </ul>
   </p>
  </a>
 </faq>
 <faq title="ClassCastException using Xerces">
   <q>Why do I get a ClassCastException when I use Xerces and WebSphere Application Server?</q>
   <a>
     <p>
      Xerces uses the <code>ObjectFactory</code> class to load some classes dynamically, e.g. the parser configuration.
      The <code>ObjectFactory</code> finds the specified implementation class by querying the system property, reading
      <code>META-INF/services/factoryId</code> file or using a fallback classname. After the implementation is found, the 
      <code>ObjectFactory</code> tries to load the file using the context classloader and if it is null, the 
      <code>ObjectFactory</code> uses the system classloader. 
     </p>
     <p>
      If you run Xerces in an environment, such as WebSphere&#xAE; Application Server, that has multiple classloaders you may 
      get ClassCastExceptions thrown from Xerces because different classloaders might get involved in loading Xerces classes.
      For example, ClassCastExceptions may occur when utility EAR classes that use Xerces load Xerces classes from WAR modules. 
     </p>
     <p>
      We suggest you read the <jump href="http://www-106.ibm.com/developerworks/websphere/library/techarticles/0310_searle/searle.html">"Avoiding ClassCastExceptions..."</jump>
      article which explains a workaround for this problem. Also you might want to read the
      <jump href="http://www-106.ibm.com/developerworks/websphere/library/techarticles/0112_deboer/deboer.html">"J2EE Class Loading Demystified"</jump>
      article that explains how multiple classloaders work in WebSphere Application Server.
    </p>
  </a>
 </faq>
 <faq title="Xerces XML, HTML and XHTML Serializers">
   <q>What should I be using instead of Xerces' XML, HTML or XHTML serializers?
 </q>
 <a>
<p>
As of the 2.9.0 release Xerces-J began sharing a common serialization codebase with Xalan and now includes <code>serializer.jar</code> 
with its distribution for DOM Level 3 serialization support. The entire <code>org.apache.xml.serialize</code> package was 
<strong>deprecated</strong> in Xerces 2.9.0. The HTML and XHTML serializers were previously <strong>deprecated</strong> in the 
Xerces 2.6.2 release. You can find more details about the rationale for this decision here in the 
<jump href="http://marc.theaimsgroup.com/?l=xalan-dev&amp;m=107593381313807&amp;w=2">archives</jump>.
</p>

<p>
If you want to achieve interoperability and avoid using deprecated APIs, you should not be using Xerces serialization code directly.
Instead, the <jump href="http://java.sun.com/xml/jaxp/index.jsp">JAXP</jump> Transformer API should be used to serialize HTML, XHTML, and SAX. The <jump href="http://www.w3.org/DOM/DOMTR">DOM</jump> Level 3 Load and Save API (or JAXP Transformer API) should be used to serialize DOM.
</p>

    <p>Using <jump href="http://www.w3.org/DOM/DOMTR">DOM</jump> Level 3 you can serialize XML as follows:</p>

<source>import org.w3c.dom.DOMImplementationRegistry;
import org.w3c.dom.Document;
import org.w3c.dom.ls.DOMImplementationLS;
import org.w3c.dom.ls.LSSerializer;
import org.w3c.dom.ls.LSOutput;

...

DOMImplementationRegistry registry = DOMImplementationRegistry.newInstance();

DOMImplementationLS impl = 
    (DOMImplementationLS)registry.getDOMImplementation("LS");

...     

LSSerializer writer = impl.createLSSerializer();
LSOutput output = impl.createLSOutput();
output.setByteStream(System.out);
writer.write(document, output);</source>

    <p>Using <jump href="http://java.sun.com/xml/jaxp/index.jsp">JAXP</jump> you can serialize HTML and XHTML as follows:</p>

<source>
// Create an "identity" transformer - copies input to output
Transformer t = TransformerFactory.newInstance().newTransformer();

// for "XHTML" serialization, use the output method "xml"
// and set publicId as shown
t.setOutputProperty(OutputKeys.METHOD, "xml");

t.setOutputProperty(OutputKeys.DOCTYPE_PUBLIC,
                    "-//W3C//DTD XHTML 1.0 Transitional//EN");

t.setOutputProperty(OutputKeys.DOCTYPE_SYSTEM,
               "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd");

// For "HTML" serialization, use
t.setOutputProperty(OutputKeys.METHOD, "html");

// Serialize DOM tree
t.transform(new DOMSource(doc), new StreamResult(System.out));</source>


  </a>
 </faq>
 <faq title="Obtaining smaller jars">
   <q>I don&apos;t need all the features Xerces provides, but I&apos;m
   running in an environment where space is at a premium.  Is there
   anything I can do?
 </q>
 <a>
    <p>
    Partially to address this issue, we've recently begun to
    distribute compressed jarfiles instead of our traditionally
    uncompressed files.  But if you still need a smaller jar, and
    don&apos;t need things like support for XML Schema or the WML/HTML
    DOM implementations that Xerces provides, then look at the
    <code>dtdjars</code> target in our
    buildfile. 
    </p>
  </a>
 </faq>
 <faq title='Validation against DTD'>
  <q>How do I turn on DTD validation?</q>
  <a>
   <p>
    You can turn validation on and off via methods available
    on the SAX2 <code>XMLReader</code> interface. While only the 
    <code>SAXParser</code> implements the <code>XMLReader</code>
    interface, the methods required for turning on validation
    are available to both parser classes, DOM and SAX.
    <br/>
    The code snippet below shows how to turn validation on -- assume
    that <ref>parser</ref> is an instance of either 
{'fraction_non_alphanumeric': 0.10426686397829572, 'fraction_numerical': 0.00949562214823036, 'mean_word_length': 3.4508781558726676, 'pattern_counts': {'":': 0, '<': 305, '<?xml version=': 2, '>': 305, 'https://': 0, 'lorem ipsum': 0, 'www.': 11, 'xml': 18}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4970033', 'n_tokens_mistral': 5142, 'n_tokens_neox': 4917, 'n_words': 1847}