http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Home

Readme
Installation

API Docs
Samples
Programming
FAQs

Releases
Caveats
Feedback

Building the Samples
 

Xerces-C comes packaged with nine sample applications that demonstrate salient features of the parser using simple applications written on top of the SAX and DOM APIs provided by the parser.

Once you have set up your PATH variable, you can run the samples by opening a command window (or your shell prompt for UNIX environments). Sample XML data files are provided in the samples/data directory.

The installation process for the samples is same on all UNIX platforms. Note that runConfigure is just a helper script and you are free to use ./configure with the correct parameters to make it work on any platform-compiler combination of your choice. The script needs the following parameters:

    Usage: runConfigure "options"
           where options may be any of the following:
           -p <platform> (accepts 'aix', 'linux', 'solaris', 'hp-10', 'hp-11')
           -c <C compiler name> (e.g. gcc, xlc_r, cc or aCC)
           -x <C++ compiler name> (e.g. g++, xlC_r, CC or aCC)
           -d (specifies that you want to build debug version)
           -h (get help on the above commands)
    
NoteNOTE:The code samples in this section assume that you are are working on the Linux binary drop. If you are using some other UNIX flavor, please replace '-linux' with the appropriate platform name in the code samples.

SAXCount
 

SAXCount is the simplest application that counts the elements and characters of a given XML file using the (event based) SAX API.

Building on Windows
 

Load the xerces-c-1_0-win32\samples\Projects\Win32\VC6\samples.dsw Microsoft Visual C++ workspace inside your MSVC IDE. Then build the project marked SAXCount.


Building on UNIX
 
        cd xerces-c-1_0-linux/samples
        ./runConfigure -p<platform> -c<C_compiler> -x<C++_compiler>
        cd SAXCount
        gmake
        

This will create the object files in the current directory and the executable named SAXCount in 'xerces-c-1_0-linux/bin' directory.

To delete all the generated object files and executables, type

        gmake clean
        

Running SAXCount
 

The SAXCount sample parses an XML file and prints out a count of the number of elements in the file. To run SAXCount, enter the following

               SAXCount <XML File>
          

To use the validating parser, use

               SAXCount -v <XML file>
          

Here is a sample output from SAXCount

          cd xerces-c-1_0-linux/samples/data
          SAXCount -v personal.xml
          personal.xml: 60 ms (37 elems, 12 attrs, 134 spaces, 134 chars)
          

Running SAXCount with the validating parser gives a different result because ignorable white-space is counted separately from regular characters.

          SAXCount personal.xml
          personal.xml: 10 ms (37 elems, 12 attrs, 0 spaces, 268 chars)
          

Note that the sum of spaces and chracters in both versions is the same.

NoteThe time reported by the program may be different depending on your machine processor.


SAXPrint
 

SAXPrint uses the SAX APIs to parse an XML file and print it back. Notice that the output of this file is not exactly the same as the input (in terms of white spaces), but the output has the same information content as the input.

Building on Windows
 

Load the xerces-c-1_0-win32\samples\Projects\Win32\VC6\samples.dsw Microsoft Visual C++ workspace inside your MSVC IDE. Then build the project marked SAXPrint.


Building on UNIX
 
        cd xerces-c-1_0-linux/samples
        ./runConfigure -p<platform> -c<C_compiler> -x<C++_compiler>
        cd SAXPrint
        gmake
        

This will create the object files in the current directory and the executable named SAXPrint in 'xerces-c-1_0-linux/bin' directory.

To delete all the generated object files and executables, type

        gmake clean
        

Running SAXPrint
 

The SAXPrint sample parses an XML file and prints out a count of the number of elements in the file. To run SAXPrint, enter the following

               SAXPrint <XML file>
          

To use the validating parser, use

               SAXPrint -v <XML file>
          

Here is a sample output from SAXPrint

cd xerces-c-1_0-linux/samples/data
SAXPrint -v personal.xml

<personnel>

  <person id="Big.Boss">
    <name><family>Boss</family> <given>Big</given></name>
    <email>chief@foo.com</email>
    <link subordinates="one.worker two.worker three.worker four.worker five.worker"></link>
  </person>

  <person id="one.worker">
    <name><family>Worker</family> <given>One</given></name>
    <email>one@foo.com</email>
    <link manager="Big.Boss"></link>
  </person>

  <person id="two.worker">
    <name><family>Worker</family> <given>Two</given></name>
    <email>two@foo.com</email>
    <link manager="Big.Boss"></link>
  </person>

  <person id="three.worker">
    <name><family>Worker</family> <given>Three</given></name>
    <email>three@foo.com</email>
    <link manager="Big.Boss"></link>
  </person>

  <person id="four.worker">
    <name><family>Worker</family> <given>Four</given></name>
    <email>four@foo.com</email>
    <link manager="Big.Boss"></link>
  </person>

  <person id="five.worker">
    <name><family>Worker</family> <given>Five</given></name>
    <email>five@foo.com</email>
    <link manager="Big.Boss"></link>
  </person>

</personnel>
NoteNote that SAXPrint does not reproduce the original XML file. Also SAXPrint and DOMPrint produce different results because of the way the two APIs store data and capture events.


DOMCount
 

DOMCount uses the provided DOM API to parse an XML file, constructs the DOM tree and walks through the tree counting the elements (using just one API call).

Building on Windows
 

Load the xerces-c-1_0-win32\samples\Projects\Win32\VC6\samples.dsw Microsoft Visual C++ workspace inside your MSVC IDE. Then build the project marked DOMCount.


Building on UNIX
 
        cd xerces-c-1_0-linux/samples
        ./runConfigure -p<platform> -c<C_compiler> -x<C++_compiler>
        cd DOMCount
        gmake
        

This will create the object files in the current directory and the executable named DOMCount in ' xerces-c-1_0-linux/bin' directory.

To delete all the generated object files and executables, type

        gmake clean
        

Running DOMCount
 

The DOMCount sample parses an XML file and prints out a count of the number of elements in the file. To run DOMCount, enter the following

               DOMCount <XML file>
          

To use the validating parser, use

               DOMCount -v <XML file>
          

Here is a sample output from DOMCount

          cd xerces-c-1_0-linux/samples/data
          DOMCount -v personal.xml
          personal.xml: 20 ms (37 elems)
          

The output of both versions should be same.

NoteThe time reported by the system may be different, depending on your processor type.


DOMPrint
 

DOMPrint parses an XML file, constructs the DOM tree, and walks through the tree printing each element. It thus dumps the XML back (output same as SAXPrint).

Building on Windows
 

Load the xerces-c-1_0-win32\samples\Projects\Win32\VC6\samples.dsw Microsoft Visual C++ workspace inside your MSVC IDE. Then build the project marked DOMPrint.


Building on UNIX
 
        cd xerces-c-1_0-linux/samples
        ./runConfigure -p<platform> -c<C_compiler> -x<C++_compiler>
        cd DOMPrint
        gmake
        

This will create the object files in the current directory and the executable named DOMPrint in ' xerces-c-1_0-linux/bin' directory.

To delete all the generated object files and executables, type

        gmake clean
        

Running DOMPrint
 

The DOMPrint sample parses an XML file, using either a validating or non-validating DOM parser configuration, builds a DOM tree, and then walks the tree and outputs the contents of the nodes in a 'canonical' format. To run DOMPrint, enter the following:

               DOMPrint [-v] <XML file>
          

The -v option is used when you wish to use a validating parser. Here is a sample output for DOMPrint when the validating parser is used:

               cd xerces-c-1_0-linux/samples/data
               DOMPrint -v personal.xml
          

Here is a sample output from DOMPrint

          cd xerces-c-1_0-linux/samples/data
          DOMPrint -v personal.xml


         <?xml version='1.0' encoding='utf-8?>
         <!-- Revision: 63 1.7 samples/data/personal.xml, xml4c2Docs, xml4c2, xml4c2_1_0_d2 -->
         <personnel>

           <person id="Big.Boss">
             <name><family>Boss</family> <given>Big</given></name>
             <email>chief@foo.com</email>
             <link subordinates="one.worker two.worker three.worker four.worker five.worker"></link>
           </person>

           <person id="one.worker">
             <name><family>Worker</family> <given>One</given></name>
             <email>one@foo.com</email>
             <link manager="Big.Boss"></link>
           </person>

           <person id="two.worker">
             <name><family>Worker</family> <given>Two</given></name>
             <email>two@foo.com</email>
             <link manager="Big.Boss"></link>
           </person>

           <person id="three.worker">
             <name><family>Worker</family> <given>Three</given></name>
             <email>three@foo.com</email>
             <link manager="Big.Boss"></link>
           </person>

           <person id="four.worker">
             <name><family>Worker</family> <given>Four</given></name>
             <email>four@foo.com</email>
             <link manager="Big.Boss"></link>
           </person>

           <person id="five.worker">
             <name><family>Worker</family> <given>Five</given></name>
             <email>five@foo.com</email>
             <link manager="Big.Boss"></link>
           </person>

           </personnel>

          

Note that DOMPrint does not reproduce the original XML file. Also DOMPrint and SAXPrint produce different results because of the way the two APIs store data and capture events.



MemParse
 

MemParse uses the Validating SAX Parser to parse a memory buffer containing XML statements, and reports the number of elements and attributes found.

Building on Windows
 

Load the xerces-c-1_0-win32\samples\Projects\Win32\VC6\samples.dsw Microsoft Visual C++ workspace inside your MSVC IDE. Then build the project marked MemParse.


Building on UNIX
 
        cd xerces-c-1_0-linux/samples
        ./runConfigure -p<platform> -c<C_compiler> -x<C++_compiler>
        cd MemParse
        gmake
        

This will create the object files in the current directory and the executable named MemParse in ' xerces-c-1_0-linux/bin' directory.

To delete all the generated object files and executables, type

        gmake clean
        

Running MemParse
 

This program uses the SAX Parser to parse a memory buffer containing XML statements, and reports the number of elements and attributes found.

               MemParse [-v]
          

The -v option is used to invoke the Validating SAX Parser instead. When invoked with a validating parser:

               cd xerces-c-1_0-linux/samples/data
               MemParse -v
          

The output is the following:


          Finished parsing the memory buffer containing the following XML statements:

          <?xml version='1.0' encoding='ascii'?>
          <!DOCTYPE company [
          <!ELEMENT company     (product,category,developedAt)>
          <!ELEMENT product     (#PCDATA)>
          <!ELEMENT category    (#PCDATA)>
          <!ATTLIST category idea CDATA #IMPLIED>
          <!ELEMENT developedAt (#PCDATA)>
          ]>


         <company>
             <product>Xerces-C</product>
             <category idea='great'>XML Parsing Tools</category>
             <developedAt>
               IBM Center for Java Technology, Silicon Valley, Cupertino, CA
             </developedAt>
         </company>

        Parsing took 0 ms (4 elements, 1 attributes, 16 spaces, 95 characters).

          


Redirect
 

Redirect uses the SAX EntityResolver handler to redirect the input stream for external entities. It installs an entity resolver, traps the call to the external DTD file and redirects it to another specific file which contains the actual DTD.

Building on Windows
 

Load the xerces-c-1_0-win32\samples\Projects\Win32\VC6\samples.dsw Microsoft Visual C++ workspace inside your MSVC IDE. Then build the project marked Redirect.


Building on UNIX
 
        cd xerces-c-1_0-linux/samples
        ./runConfigure -p<platform> -c<C_compiler> -x<C++_compiler>
        cd Redirect
        gmake
        

This will create the object files in the current directory and the executable named Redirect in 'xerces-c-1_0-linux/bin' directory.

To delete all the generated object files and executables, type

        gmake clean
        

Running Redirect
 

This program illustrates how a XML application can use the SAX EntityResolver handler to redirect the input stream for external entities. It installs an entity resolver, traps the call to the external DTD file and redirects it to another specific file which contains the actual DTD.

The program then counts and reports the number of elements and attributes in the given XML file.

               Redirect [-v] <XML file>
          

The -v option is used to invoke the Validating SAX Parser instead.

When invoked as follows:

               cd xerces-c-1_0-linux/samples/data
               Redirect -v personal.xml
          

The output is the following:

          cd xerces-c-1_0-linux/samples/data
          Redirect -v personal.xml
          personal.xml: 30 ms (37 elems, 12 attrs, 134 spaces, 134 chars)
          

External files required to run this sample are 'personal.xml', 'personal.dtd' and 'redirect.dtd', which are all present in the 'samples/data' directory. Make sure that you run redirect in the samples/data directory.

The 'resolveEntity' callback in this sample looks for an external entity with system id as 'personal.dtd'. When it is asked to resolve this particular external entity, it creates and returns a new InputSource for the file 'redirect.dtd'.

A real-world XML application can similarly do application specific processing when encountering external entities. For example, an application might want to redirect all references to entities outside of its domain to local cached copies.



PParse
 

Demonstrates progressive parsing.

In this example, the programmer doesn't have to depend upon throwing an exception to terminate the parsing operation. Calling parseFirst() will cause the DTD to be parsed (both internal and external subsets) and any pre-content, i.e. everything up to but not including the root element. Subsequent calls to parseNext() will cause one more piece of markup to be parsed, and spit out from the core scanning code to the parser. You can quit the parse any time by just not calling parseNext() anymore and breaking out of the loop. When you call parseNext() and the end of the root element is the next piece of markup, the parser will continue on to the end of the file and return false, to let you know that the parse is done.

Building on Windows
 

Load the xerces-c-1_0win32\samples\Projects\Win32\VC6\samples.dsw Microsoft Visual C++ workspace inside your MSVC IDE. Then build the project marked PParse.


Building on UNIX
 
        cd xerces-c-1_0-linux/samples
        ./runConfigure -p<platform> -c<C_compiler> -x<C++_compiler>
        cd PParse
        gmake
        

This will create the object files in the current directory and the executable named PParse in ' xerces-c-1_0-linux/bin' directory.

To delete all the generated object files and executables, type

        gmake clean
        

Running PParse
 

The program looks for the first 16 elements of the XML file, and reports if successful.

               PParse [-v] <XML file>
          

The output is the following:

          Got the required 16 elements.
          


StdInParse
 

Demonstrates streaming XML data from the standard input.

Building on Windows
 

Load the xerces-c-1_0-win32\samples\Projects\Win32\VC6\samples.dsw Microsoft Visual C++ workspace inside your MSVC IDE. Then build the project marked StdInParse.


Building on UNIX
 
        cd xerces-c-1_0-linux/samples
        ./runConfigure -p<platform> -c<C_compiler> -x<C++_compiler>
        cd StdInParse
        gmake
        

This will create the object files in the current directory and the executable named StdInParse in ' xerces-c-1_0-linux/bin' directory.

To delete all the generated object files and executables, type

        gmake clean
        

Running StdInParse
 

The StdInParse sample parses an XML file and prints out a count of the number of elements in the file. To run StdInParse, enter the following

               StdInParse < <XML file>
          

Here is a sample output from StdInParse

          cd xerces-c-1_0-linux/samples/data
          StdInParse < personal.xml
          personal.xml: 60 ms (37 elems, 12 attrs, 0 spaces, 268 chars)
          
NoteThe time reported by the program may be different depending on your machine processor.


EnumVal
 

Shows how to enumerate the markup decls in a DTD Validator.

Building on Windows
 

Load the xerces-c-1_0-win32\samples\Projects\Win32\VC6\samples.dsw Microsoft Visual C++ workspace inside your MSVC IDE. Then build the project marked EnumVal.


Building on UNIX
 
        cd xerces-c-1_0-linux/samples
        ./runConfigure -p<platform> -c<C_compiler> -x<C++_compiler>
        cd EnumVal
        gmake
        

This will create the object files in the current directory and the executable named EnumVal in ' xerces-c-1_0-linux/bin' directory.

To delete all the generated object files and executables, type

        gmake clean
        

Running EnumVal
 

This program parses a file, then shows how to enumerate the contents of the validator pools. To run EnumVal, enter the following

               EnumVal <XML file>
          

Here is a sample output from EnumVal

cd xerces-c-1_0-linux/samples/data
EnumVal personal.xml

ELEMENTS:
----------------------------
  Name: personnel
  Content Model: (person)+

  Name: person
  Content Model: (name,email*,url*,link?)
  Attributes:
    Name:id, Type: ID

  Name: name
  Content Model: (#PCDATA|family|given)*

  Name: email
  Content Model: (#PCDATA)*

  Name: url
  Content Model: EMPTY
  Attributes:
    Name:href, Type: CDATA

  Name: link
  Content Model: EMPTY
  Attributes:
    Name:subordinates, Type: IDREF(S)
    Name:manager, Type: IDREF(S)

  Name: family
  Content Model: (#PCDATA)*

  Name: given
  Content Model: (#PCDATA)*

          



Copyright © 1999 The Apache Software Foundation. All Rights Reserved.