| <?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'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.4 APIs;</li> |
| <li><code>xercesImpl.jar</code> contains the implementation of |
| these API'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.4 on JDK 1.4 and above"> |
| <q>How can I use JAXP 1.4 on JDK 1.4 and above?</q> |
| <a> |
| <p> |
| Use the <jump href="http://download.oracle.com/javase/1.4.2/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-N100EF">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® 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&m=107593381313807&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://jcp.org/en/jsr/summary?id=206">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.bootstrap.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://jcp.org/en/jsr/summary?id=206">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't need all the features Xerces provides, but I'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 jar files instead of our traditionally |
| uncompressed files. But if you still need a smaller jar, and |
| don'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 |
| <code>org.apache.xerces.parsers.SAXParser</code> or |
| <code>org.apache.xerces.parsers.DOMParser</code>. |
| <br/><br/> |
| <code>parser.setFeature("http://xml.org/sax/features/validation", true);</code> |
| </p> |
| </a> |
| </faq> |
| |
| <!-- |
| <faq title='PSVI'> |
| <q>How do I get access to the PSVI?</q> |
| <a> |
| <p>Xerces provides a sample component PSVIWriter that intercepts document |
| handler events and collects PSVI information. For more information read <link |
| idref="samples-xni">samples documentation</link> on how to use xni.parser.PSVIParser |
| and xni.parser.PSVIConfiguration. |
| </p> |
| <note>Xerces only produces light-weight PSVI.</note> |
| </a> |
| </faq> |
| --> |
| |
| |
| <faq title='International Encodings'> |
| <q>What international encodings are supported by &ParserName;?</q> |
| <a> |
| <ul> |
| <li>UTF-8</li> |
| <li>UTF-16 Big Endian and Little Endian</li> |
| <li>UCS-2 (ISO-10646-UCS-2) Big Endian and Little Endian</li> |
| <li>UCS-4 (ISO-10646-UCS-4) Big Endian and Little Endian</li> |
| <li>IBM-1208</li> |
| <li>ISO Latin-1 (ISO-8859-1)</li> |
| <li> |
| ISO Latin-2 (ISO-8859-2) [Bosnian, Croatian, Czech, |
| Hungarian, Polish, Romanian, Serbian (in Latin transcription), |
| Serbocroatian, Slovak, Slovenian, Upper and Lower Sorbian] |
| </li> |
| <li>ISO Latin-3 (ISO-8859-3) [Maltese, Esperanto]</li> |
| <li>ISO Latin-4 (ISO-8859-4)</li> |
| <li>ISO Latin Cyrillic (ISO-8859-5)</li> |
| <li>ISO Latin Arabic (ISO-8859-6)</li> |
| <li>ISO Latin Greek (ISO-8859-7)</li> |
| <li>ISO Latin Hebrew (ISO-8859-8)</li> |
| <li>ISO Latin-5 (ISO-8859-9) [Turkish]</li> |
| <li>ISO Latin-7 (ISO-8859-13)</li> |
| <li>ISO Latin-9 (ISO-8859-15)</li> |
| <li>Extended Unix Code, packed for Japanese (euc-jp, eucjis)</li> |
| <li>Japanese Shift JIS (shift-jis)</li> |
| <li>Chinese (big5)</li> |
| <li>Chinese for PRC (mixed 1/2 byte) (gb2312)</li> |
| <li>Japanese ISO-2022-JP (iso-2022-jp)</li> |
| <li>Cyrillic (koi8-r)</li> |
| <li>Extended Unix Code, packed for Korean (euc-kr)</li> |
| <li>Russian Unix, Cyrillic (koi8-r)</li> |
| <li>Windows Thai (cp874)</li> |
| <li>Latin 1 Windows (cp1252) (and all other cp125? encodings recognized by IANA)</li> |
| <li>cp858</li> |
| <li>EBCDIC encodings:</li> |
| <ul> |
| <li>EBCDIC US (ebcdic-cp-us)</li> |
| <li>EBCDIC Canada (ebcdic-cp-ca)</li> |
| <li>EBCDIC Netherland (ebcdic-cp-nl)</li> |
| <li>EBCDIC Denmark (ebcdic-cp-dk)</li> |
| <li>EBCDIC Norway (ebcdic-cp-no)</li> |
| <li>EBCDIC Finland (ebcdic-cp-fi)</li> |
| <li>EBCDIC Sweden (ebcdic-cp-se)</li> |
| <li>EBCDIC Italy (ebcdic-cp-it)</li> |
| <li>EBCDIC Spain, Latin America (ebcdic-cp-es)</li> |
| <li>EBCDIC Great Britain (ebcdic-cp-gb)</li> |
| <li>EBCDIC France (ebcdic-cp-fr)</li> |
| <li>EBCDIC Hebrew (ebcdic-cp-he)</li> |
| <li>EBCDIC Switzerland (ebcdic-cp-ch)</li> |
| <li>EBCDIC Roece (ebcdic-cp-roece)</li> |
| <li>EBCDIC Yugoslavia (ebcdic-cp-yu)</li> |
| <li>EBCDIC Iceland (ebcdic-cp-is)</li> |
| <li>EBCDIC Urdu (ebcdic-cp-ar2)</li> |
| <li>Latin 0 EBCDIC</li> |
| <li>EBCDIC Arabic (ebcdic-cp-ar1)</li> |
| </ul> |
| </ul> |
| </a> |
| </faq> |
| |
| <faq title='Accessing Documents on the Internet'> |
| <q>Why is the parser unable to access schema documents or external entities available on the Internet?</q> |
| <a> |
| <p> |
| The parser may not be able to access various external entities or schema documents |
| (imported, included etc...) available on the Internet, such as the Schema for Schemas |
| "http://www.w3.org/2001/XMLSchema.xsd" or the schema defining xml:base, xml:lang attributes etc... |
| "http://www.w3.org/2001/xml.xsd" or any other external entity available on the Internet. There |
| are various reasons one could experience such a problem. |
| <br/> |
| <br/> |
| One of the reasons could be that your proxy settings do not allow the parser to make |
| URL connections through a proxy server. To solve this problem, before parsing a document, |
| the application must set the two system properties: "http.proxyHost" and "http.proxyPort". |
| Another reason could be due to strict firewall settings that do not allow any URL connection |
| to be made to the outside web. The problem may also be caused by a server that is offline or |
| inaccessible on the network, preventing documents hosted by the server from being accessed. |
| </p> |
| </a> |
| </faq> |
| |
| <faq title='JDK Compatibility'> |
| <q>What JDK level is required for Xerces?</q> |
| <a> |
| <p> |
| As of version 2.10.0, Xerces requires JDK 1.3 or later to run and also requires JDK 1.3 or |
| later to build the source code. Starting with the Xerces 2.11.0 release, the XML Schema 1.1 |
| distribution requires JDK 1.4 or later to run and also to build the source code. |
| </p> |
| </a> |
| </faq> |
| |
| </faqs> |