xerces-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mrgla...@apache.org
Subject cvs commit: xml-xerces/java/docs sax.xml faq-sax.xml faq-general.xml docs-book.xml faq-write.xml
Date Fri, 13 Feb 2004 18:32:41 GMT
mrglavas    2004/02/13 10:32:40

  Modified:    java/docs faq-general.xml docs-book.xml faq-write.xml
  Added:       java/docs sax.xml faq-sax.xml
  Log:
  Committing documentation patch from James Littlejohn.
  Thanks James.
  
  - Added a new SAX section
  - Added a SAX FAQ
  - Moved some FAQs into the SAX FAQ
  
  Revision  Changes    Path
  1.38      +1 -61     xml-xerces/java/docs/faq-general.xml
  
  Index: faq-general.xml
  ===================================================================
  RCS file: /home/cvs/xml-xerces/java/docs/faq-general.xml,v
  retrieving revision 1.37
  retrieving revision 1.38
  diff -u -r1.37 -r1.38
  --- faq-general.xml	17 Nov 2003 20:56:32 -0000	1.37
  +++ faq-general.xml	13 Feb 2004 18:32:40 -0000	1.38
  @@ -171,65 +171,5 @@
      </p>
     </a>
    </faq> 
  - 
  -  <faq title='Incomplete character data is received via SAX'>
  -  <q>Why does the SAX parser lose some character data or why is the data split 
  -  into several chunks?</q>
  -  <a>
  -  <p>If you read the <jump href='http://www.saxproject.org/apidoc/org/xml/sax/ContentHandler.html#characters(char[],%20int,%20int)'>SAX</jump>

  -  documentation, you will find that SAX may deliver contiguous text as multiple calls to

  -characters(), for reasons having to do with parser efficiency and input 
  -buffering. It is the programmer's responsibility to deal with that 
  -appropriately, e.g. by accumulating text until the next non-characters() 
  -event.
  - </p>
  -  </a>
  -  </faq>
  -  <faq title="Encodings and XML Version Via SAX">
  -    <q>Is there any way I can determine what encoding an entity was
  -    written in, or what XML version the document conformed to, if I'm
  -    using SAX?
  -    </q>
  -    <a>
  -        <p>The answer to this question is that, yes there is a way, but it's
  -        not particularly beautiful.  There is no way in SAX 2.0.0 or
  -        2.0.1 to get hold of these pieces of information; the SAX
  -        Locator2 interface from the 1.1 extensions--still in Alpha at
  -        the time of writing--does provide methods to accomplish this,
  -        but since Xerces is required to support precisely SAX 2.0.0 by
  -        Sun TCK rules, we cannot ship this interface.  However, we can
  -        still support the appropriate methods on the objects we
  -        provide to implement the SAX Locator interface.  Therefore,
  -        assuming <code>Locator</code> is an instance of the SAX
  -        Locator interface that Xerces has passed back in a
  -        <code>setDocumentLocator</code> call, 
  -        you can use a method like this to determine the encoding of
  -        the entity currently being parsed:
  -        </p>
  -        <source> 
  -    import java.lang.reflect.Method;
  -    private String getEncoding(Locator locator) {
  -        String encoding = null;
  -        Method getEncoding = null;
  -        try {
  -            getEncoding = locator.getClass().getMethod("getEncoding", new Class[]{});
  -            if(getEncoding != null) {
  -                encoding = (String)getEncoding.invoke(locator, null);
  -            }
  -        } catch (Exception e) {
  -            // either this locator object doesn't have this
  -            // method, or we're on an old JDK
  -        }
  -        return encoding;
  -    } 
  -        </source>
  -        <p>This code has the advantage that it will compile on JDK
  -        1.1.8, though it will only produce non-null results on 1.2.x
  -        JDK's and later.  Substituting <code>getXMLVersion</code> for
  -        <code>getEncoding</code> will enable you to determine the
  -        version of XML to which the instance document conforms.
  -        </p>
  -    </a>
  -  </faq>
  -  
  +
   </faqs>
  
  
  
  1.25      +3 -0      xml-xerces/java/docs/docs-book.xml
  
  Index: docs-book.xml
  ===================================================================
  RCS file: /home/cvs/xml-xerces/java/docs/docs-book.xml,v
  retrieving revision 1.24
  retrieving revision 1.25
  diff -u -r1.24 -r1.25
  --- docs-book.xml	26 Jan 2004 23:26:36 -0000	1.24
  +++ docs-book.xml	13 Feb 2004 18:32:40 -0000	1.25
  @@ -43,6 +43,8 @@
          id='faq-build' source='faq-build.xml'/>
     <faq title='Writing Applications FAQs' 
          id='faq-write' source='faq-write.xml'/>
  +  <faq title='Programming with SAX' 
  +       id='faq-sax' source='faq-sax.xml'/>
     <faq title='Programming with DOM' 
          id='faq-dom' source='faq-dom.xml'/>
     <faq title='Using XML Schemas' 
  @@ -65,6 +67,7 @@
    <document label='XNI Manual' title='Xerces Native Interface'
              id='xni' source='xni.xml'/>
    <document   label='XML Schema' title='XML Schema' id='xml-schema' source='xml-schema.xml'/>
  + <document label ='SAX' title='Simple API for XML' id='sax' source='sax.xml'/>
    <document label ='DOM' title='The Document Object Model' id='dom' source='dom.xml'/>
    <hidden title='DOM Level 3 Implementation' id='dom3' source='dom3.xml'/>
    <document label='Limitations' title='Parser Limitations'
  
  
  
  1.24      +0 -37     xml-xerces/java/docs/faq-write.xml
  
  Index: faq-write.xml
  ===================================================================
  RCS file: /home/cvs/xml-xerces/java/docs/faq-write.xml,v
  retrieving revision 1.23
  retrieving revision 1.24
  diff -u -r1.23 -r1.24
  --- faq-write.xml	14 Nov 2003 20:41:32 -0000	1.23
  +++ faq-write.xml	13 Feb 2004 18:32:40 -0000	1.24
  @@ -1,44 +1,7 @@
   <?xml version='1.0' encoding='UTF-8'?>
   <!DOCTYPE faqs SYSTEM 'dtd/faqs.dtd'>
   <faqs title='Writing Application FAQs'>
  - <faq title="Creating a SAX Parser">
  -  <q>How do I create a SAX parser?</q>
  -  <a>
  -   <p>
  -    You can create a SAX parser by using the Java APIs for
  -    XML Processing (JAXP). The following source code shows
  -    how:
  -   </p>
  -   <source>import java.io.IOException; 
  -import javax.xml.parsers.FactoryConfigurationError;
  -import javax.xml.parsers.ParserConfigurationException;
  -import javax.xml.parsers.SAXParser;
  -import javax.xml.parsers.SAXParserFactory;
  -import org.xml.sax.SAXException;
  -import org.xml.sax.helpers.DefaultHandler;
   
  -  ...
  -
  -String xmlFile = &quot;file:///&parserdir;/data/personal.xml&quot;; 
  -try {
  -    SAXParserFactory factory = SAXParserFactory.newInstance();
  -    SAXParser parser = factory.newSAXParser();
  -    DefaultHandler handler = /* custom handler class */;
  -    parser.parse(xmlFile, handler);
  -} 
  -catch (FactoryConfigurationError e) {
  -    // unable to get a document builder factory
  -} 
  -catch (ParserConfigurationException e) {
  -    // parser was unable to be configured
  -catch (SAXException e) {
  -    // parsing error
  -} 
  -catch (IOException e) {
  -    // i/o error
  -}</source>
  -  </a>
  - </faq>
    <!--
      - REVISIT: make sure that JAXP implementation can handle
      -          passing features and properties through to the
  
  
  
  1.1                  xml-xerces/java/docs/sax.xml
  
  Index: sax.xml
  ===================================================================
  <?xml version="1.0" standalone="no"?>
  <!DOCTYPE s1 SYSTEM "./dtd/document.dtd">
  <s1 title="SAX">
  <s2 title="Introduction">
  <p>SAX 1.0 and SAX 2.0 Information</p>
  <ul>
  <li><jump href='http://www.saxproject.org/?selected=sax1'>SAX 1.0 Overview</jump></li>
  <li><jump href='http://www.saxproject.org/?selected=sax2'>SAX 2.0 Changes</jump></li>
  <li><jump href='http://www.saxproject.org/?selected=ext'>SAX 2.0 Extensions</jump></li>
  </ul>
  </s2>
  
  
  <s2 title="SAX Programmer's Guide">
  <p>This section provides the following topics:</p>
  
  <ul>
  <li><jump href='http://www.saxproject.org'>About SAX</jump></li>
  <li><link idref='faq-sax'>How do I?</link> -- the most frequently asked
questions about SAX.</li>
  <li><link idref='samples-sax'>SAX Samples</link> -- documents various
SAX samples included with Xerces.</li>
  </ul>
  </s2>
  </s1>
  
  
  
  1.1                  xml-xerces/java/docs/faq-sax.xml
  
  Index: faq-sax.xml
  ===================================================================
  <?xml version='1.0' encoding='UTF-8'?>
  <!DOCTYPE faqs SYSTEM 'dtd/faqs.dtd'>
  <faqs title='Programming with SAX'>
  
   <faq title="Creating a SAX Parser">
    <q>How do I create a SAX parser?</q>
    <a>
     <p>
      You can create a SAX parser by using the Java APIs for
      XML Processing (JAXP). The following source code shows
      how:
     </p>
     <source>import java.io.IOException; 
  import javax.xml.parsers.FactoryConfigurationError;
  import javax.xml.parsers.ParserConfigurationException;
  import javax.xml.parsers.SAXParser;
  import javax.xml.parsers.SAXParserFactory;
  import org.xml.sax.SAXException;
  import org.xml.sax.helpers.DefaultHandler;
  
    ...
  
  String xmlFile = &quot;file:///&parserdir;/data/personal.xml&quot;; 
  try {
      SAXParserFactory factory = SAXParserFactory.newInstance();
      SAXParser parser = factory.newSAXParser();
      DefaultHandler handler = /* custom handler class */;
      parser.parse(xmlFile, handler);
  } 
  catch (FactoryConfigurationError e) {
      // unable to get a document builder factory
  } 
  catch (ParserConfigurationException e) {
      // parser was unable to be configured
  catch (SAXException e) {
      // parsing error
  } 
  catch (IOException e) {
      // i/o error
  }</source>
    </a>
   </faq>
  
    <faq title='Incomplete character data is received via SAX'>
    <q>Why does the SAX parser lose some character data or why is the data split 
    into several chunks?</q>
    <a>
    <p>If you read the <jump href='http://www.saxproject.org/apidoc/org/xml/sax/ContentHandler.html#characters(char[],%20int,%20int)'>SAX</jump>

    documentation, you will find that SAX may deliver contiguous text as multiple calls to

  characters(), for reasons having to do with parser efficiency and input 
  buffering. It is the programmer's responsibility to deal with that 
  appropriately, e.g. by accumulating text until the next non-characters() 
  event.
   </p>
    </a>
    </faq>
  
    <faq title="Encodings and XML Version Via SAX">
      <q>Is there any way I can determine what encoding an entity was
      written in, or what XML version the document conformed to, if I'm
      using SAX?
      </q>
      <a>
          <p>The answer to this question is that, yes there is a way, but it's
          not particularly beautiful.  There is no way in SAX 2.0.0 or
          2.0.1 to get hold of these pieces of information; the SAX
          Locator2 interface from the 1.1 extensions--still in Alpha at
          the time of writing--does provide methods to accomplish this,
          but since Xerces is required to support precisely SAX 2.0.0 by
          Sun TCK rules, we cannot ship this interface.  However, we can
          still support the appropriate methods on the objects we
          provide to implement the SAX Locator interface.  Therefore,
          assuming <code>Locator</code> is an instance of the SAX
          Locator interface that Xerces has passed back in a
          <code>setDocumentLocator</code> call, 
          you can use a method like this to determine the encoding of
          the entity currently being parsed:
          </p>
          <source> 
      import java.lang.reflect.Method;
      private String getEncoding(Locator locator) {
          String encoding = null;
          Method getEncoding = null;
          try {
              getEncoding = locator.getClass().getMethod("getEncoding", new Class[]{});
              if(getEncoding != null) {
                  encoding = (String)getEncoding.invoke(locator, null);
              }
          } catch (Exception e) {
              // either this locator object doesn't have this
              // method, or we're on an old JDK
          }
          return encoding;
      } 
          </source>
          <p>This code has the advantage that it will compile on JDK
          1.1.8, though it will only produce non-null results on 1.2.x
          JDK's and later.  Substituting <code>getXMLVersion</code> for
          <code>getEncoding</code> will enable you to determine the
          version of XML to which the instance document conforms.
          </p>
      </a>
    </faq>
    
  
  </faqs>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-cvs-help@xml.apache.org


Mime
View raw message