Listing 1: Header file for WU_XMLFactory

#ifndef WU_XMLFACTORY_H
#define WU_XMLFACTORY_H

/************************************************************
*****          Quantin' Leap Ltd    *****
*****   Copyright (c) 2001, All Rights Reserved     *****
*************************************************************/

#include <sax/SAXException.hpp>
#include <sax/SAXParseException.hpp>
#include <dom/DOM_Document.hpp>
#include <dom/DOM_DOMException.hpp>
#include <parsers/DOMParser.hpp>
#include <string>
#include "WU_Array.h"
#include "WU_Container.h"


using std::string;

//the following should be changed into non-legacy containers 
//such as typedef std::vector<string> STRINGVECTOR;  
typedef WU_Array<string> STRINGVECTOR;  

enum XMLSource
{
  XML_FILE = 0,
  XML_MEMORY
};

class WU_XMLFactory
{
public:
  //constructors

  /*! constructor
     \param xml a string which either contains the name of 
    the XML input file, or which is instead a string memory
    buffer to be directly parsed. The value of the third 
    parameter determines which of the two behaviours.
     \param container a pointer to the persistent container 
    where components can be stored
     \param source if this enumeration is equal to XML_FILE
    then the xml string contains the name of the XML input
    file. If source == XML_MEMORY then the xml string is 
    directly the xml input which should be parsed
     \throws XMLException, DOM_DOMException, and "Unexpected 
    exception during parsing"
  */
  WU_XMLFactory(string xml, WU_Container* container,
    XMLSource source = XML_FILE);

  /*! destructor*/
  virtual ~WU_XMLFactory();

  //accessor functions
  string getXMLSource() {return m_XMLSource;}
  void setXMLSource(string xml) {m_XMLSource = xml;}
  /*! Returns the DOM document produced after parsing the XML file*/
  DOM_Document& getDOMDocument() {return m_doc;}
  WU_Container* getContainer() {return m_container;}

  //public function
  /*! Returns the value of an XML node in the DOM document. 
    The name of the node must be unique within the XML file.
    \param nodeName the node name
    \return a string containing the node value
  */
  //to extract the value from a subnode
  string getNodeValue(string nodeName);  

  /*! Returns the value of an XML node in the DOM document, 
    starting to search from a node with name "parent". 
    This function is used when the name of the sub-node is
    not unique in the XML file. By giving the parent name 
    the ambiguity is resolved.
    \param parent the name of the parent node
    \param subNode the name of the subnode
    \return a string containing the node value
  */  
  string getSubNodeValue(string parent, string subNode); 

  /*! Returns a vector of string values contained under an 
    XML node in the DOM document.
    (e.g. XML input is ...<nodeName><item>1</item><item>2</item><item>3</item></nodeName>
    Then the function returns a vector of three strings:  
    "1", "2" and "3")
    The name of the node must be unique within the XML file.
    \param nodeName the node name
    \return a vector of strings containing the node values
  */
  STRINGVECTOR getNodeArray(string nodeName); 

  /*! Returns a vector of string values contained under 
    an XML node in the DOM document.
    (e.g. XML input is ...<subNode><item>1</item><item>2</item><item>3</item></subNode>
    Then the function returns a vector of three strings:
    "1", "2" and "3")
    This function is used when the name of the sub-node 
    is not unique in the XML file.
    By giving the parent name the ambiguity is resolved.
    \param parent the name of the parent node
    \param subNode the name of the subnode
    \return a vector of strings containing the node values
  */
  STRINGVECTOR getSubNodeArray(string parent, string subNode);
  
  /*! Pure virtual function which should be defined by the 
    derived classes. This function is called to construct 
    the factory object.
  */
  virtual void build()=0;           

protected:
  /*! This function is used internally for navigating the 
    DOM tree. It recursively crosses the tree to find a 
    given subnode.
    \param parent the node from which the search starts
    \param subNodeName the name of the subnode to be found
    \return the DOM_Node with name subNodeName
    \throws WU_Exception "field <subNodeName> not found"
  */
  virtual DOM_Node getNodeRecursive(DOM_Node parent, 
    string subNodeName);
  
protected:
  /*!< the source of XML input, either a file name or an XML string*/
  string m_XMLSource; 
  /*!< the DOM tree created by parsing the XML input*/
  DOM_Document m_doc; 
  /*!< the type of XML input, either XML_FILE or XML_MEMORY*/
  XMLSource m_sourceType; 
  /*!< a pointer to the persistent container, where 
     components are stored*/
  WU_Container* m_container; 
};

#endif WU_XMLFACTORY_H