XMLSubSys Class Reference

#include <XMLSubSys.h>

Detailed Description

Utility methods for initialising, closing and using the XML-subsystem.

The Xerces-parsers need an initialisation and should also be closed.

As we use xerces for both the input files and the configuration we would have to check whether the system was initialised before. Instead, we call XMLSubSys::init(bool) once at the beginning of our application and XMLSubSys::close() at the end.

Closing and initialising the XML subsystem is necessary. Still, we never encountered any problems with it. Once, after some modifications, SUMO crashed when closing the XML sub system. The reason was a memory leak within the microsim-module. On initialisation, a SAX2XMLReader is built which can be used during later process. It is destroyed when the subsystem is closed.

In addition to initialisation and shutdown, this module allows to build SAXReaders and/or running a given handler on a given file without dealing with the reader at all.

Todo:: make schema checking optional

Definition at line 71 of file XMLSubSys.h.


Static Public Member Functions
static void	close () throw ()
	Closes the xml-subsystem.
static XERCES_CPP_NAMESPACE_QUALIFIER SAX2XMLReader *	getSAXReader (SUMOSAXHandler &handler) throw ()
	Builds a reader and assigns the handler to it.
static void	init (bool enableValidation) throw (ProcessError)
	Initialises the xml-subsystem, returns whether the initialisation succeeded.
static bool	runParser (GenericSAXHandler &handler, const std::string &file) throw ()
	Runs the given handler on the given file; returns if everything's ok.
static void	setHandler (GenericSAXHandler &handler)
	Sets the given handler for the default reader.
Static Protected Member Functions
static XERCES_CPP_NAMESPACE_QUALIFIER SAX2XMLReader *	getSAXReader () throw ()
	Builds a reader.
static void	setFeature (XERCES_CPP_NAMESPACE_QUALIFIER SAX2XMLReader &reader, const std::string &feature, bool value) throw ()
	Sets the named feature of the given reader to the given value.
Static Private Attributes
static bool	myEnableValidation
	Information whether built reader/parser shall validate XML-documents against schemata.
static unsigned int	myNextFreeReader
	Information whether the reader is parsing.
static std::vector < XERCES_CPP_NAMESPACE_QUALIFIER SAX2XMLReader * >	myReaders
	The XML Readers used for repeated parsing.

Member Function Documentation

void XMLSubSys::close ( ) throw () [static]

Closes the xml-subsystem.

Deletes the built reader and calls XMLPlatformUtils::Terminate();

Definition at line 68 of file XMLSubSys.cpp.

References myReaders.

Referenced by SystemFrame::close().

00068                          {
00069     for (std::vector<SAX2XMLReader*>::iterator i=myReaders.begin(); i!=myReaders.end(); ++i) {
00070         delete *i;
00071     }
00072     myReaders.clear();
00073     XMLPlatformUtils::Terminate();
00074 }

SAX2XMLReader * XMLSubSys::getSAXReader ( ) throw () [static, protected]

Builds a reader.

Tries to build a SAX2XMLReader using XMLReaderFactory::createXMLReader. If this fails, 0 is returned. Otherwise the validation is set matching the value of "myEnableValidation". If validation is not wanted, a WFXMLScanner is used (see http://www.ibm.com/developerworks/library/x-xercesperf.html).

Returns:: The built Xerces-SAX-reader, 0 if something failed

Definition at line 124 of file XMLSubSys.cpp.

References MsgHandler::getErrorInstance(), MsgHandler::inform(), myEnableValidation, and setFeature().

Referenced by getSAXReader(), GUISettingsHandler::GUISettingsHandler(), PCNetProjectionLoader::loadIfSet(), NILoader::loadXMLType(), MSRouteLoader::MSRouteLoader(), MSTriggeredXMLReader::myInit(), runParser(), and traci::TraCIServer::TraCIServer().

00124                                 {
00125     SAX2XMLReader *reader = XMLReaderFactory::createXMLReader();
00126     if (reader==0) {
00127         MsgHandler::getErrorInstance()->inform("The XML-parser could not be build");
00128         return 0;
00129     }
00130     if (!myEnableValidation) {
00131         reader->setProperty(XMLUni::fgXercesScannerName, (void *)XMLUni::fgWFXMLScanner);
00132     }
00133     setFeature(*reader, "http://xml.org/sax/features/namespaces", false);
00134     setFeature(*reader, "http://apache.org/xml/features/validation/schema", myEnableValidation);
00135     setFeature(*reader, "http://apache.org/xml/features/validation/schema-full-checking", myEnableValidation);
00136     setFeature(*reader, "http://xml.org/sax/features/validation", myEnableValidation);
00137     setFeature(*reader, "http://apache.org/xml/features/validation/dynamic", myEnableValidation);
00138     return reader;
00139 }

SAX2XMLReader * XMLSubSys::getSAXReader ( SUMOSAXHandler & handler ) throw () [static]

Builds a reader and assigns the handler to it.

Tries to build a SAX2XMLReader using "getSAXReader()". If this fails, 0 is returned. Otherwise, the given handler is assigned to the reader as the current DefaultHandler and ErrorHandler.

Parameters:

[in] handler The handler to assign to the built reader

Returns:: The built Xerces-SAX-reader, 0 if something failed

See also:: getSAXReader()

Definition at line 78 of file XMLSubSys.cpp.

References getSAXReader().

00078                                                        {
00079     SAX2XMLReader *reader = getSAXReader();
00080     if (reader==0) {
00081         return 0;
00082     }
00083     reader->setContentHandler(&handler);
00084     reader->setErrorHandler(&handler);
00085     return reader;
00086 }

void XMLSubSys::init ( bool enableValidation ) throw (ProcessError) [static]

Initialises the xml-subsystem, returns whether the initialisation succeeded.

Calls XMLPlatformUtils::Initialize(). If this fails, the exception is caught and its content is reported using a ProcessError. Otherwise, a static SAX2XMLReader is built using "getSAXReader()" (stored in "myReader").

The information whether validationis wanted is stored in "myEnableValidation" for later usage.

Parameters:

[in] enableValidation Whether validation of XML-documents against schemata shall be enabled

Exceptions:

ProcessError

If the initialisation fails

See also:: getSAXReader()

Definition at line 55 of file XMLSubSys.cpp.

Referenced by main().

00055                                                          {
00056     myEnableValidation = enableValidation;
00057     try {
00058         XMLPlatformUtils::Initialize();
00059         myReaders.push_back(getSAXReader());
00060         myNextFreeReader = 0;
00061     } catch (const XMLException& e) {
00062         throw ProcessError("Error during XML-initialization:\n " + TplConvert<XMLCh>::_2str(e.getMessage()));
00063     }
00064 }

bool XMLSubSys::runParser	(	GenericSAXHandler &	handler,
		const std::string &	file
	)			throw () `[static]`

Runs the given handler on the given file; returns if everything's ok.

Uses the reader built on init() which is stored in myReader to parse the given file.

All exceptions are catched and reported to the error-instance of the MsgHandler. Also, if the reader could not be built, this is reported.

The method returns true if everything went ok. This means, that the reader could be built, no exception was caught, and nothing was reported to the error-instance of the MsgHandler.

Parameters:

`[in]`	handler	The handler to assign to the built reader
`[in]`	file	The file to run the parser at

Returns:: true if the parsing was done without errors, false otherwise (error was printed)

Definition at line 97 of file XMLSubSys.cpp.

References MsgHandler::getErrorInstance(), getSAXReader(), MsgHandler::inform(), myNextFreeReader, myReaders, setHandler(), and MsgHandler::wasInformed().

Referenced by NLBuilder::build(), GUISettingsHandler::GUISettingsHandler(), NLBuilder::load(), loadDistricts(), PCLoaderXML::loadIfSet(), PCLoaderOSM::loadIfSet(), loadJTRDefinitions(), ROLoader::loadNet(), NIImporter_SUMO::loadNetwork(), NIImporter_OpenStreetMap::loadNetwork(), NIImporter_OpenDrive::loadNetwork(), ROLoader::loadWeights(), main(), MSLaneSpeedTrigger::MSLaneSpeedTrigger(), MSTriggeredRerouter::MSTriggeredRerouter(), readDetectors(), and GenericSAXHandler::startElement().

00098                                                     {
00099     try {
00100         if (myNextFreeReader == myReaders.size()) {
00101             myReaders.push_back(getSAXReader());
00102         }
00103         myNextFreeReader++;
00104         setHandler(handler);
00105         std::string prevFile = handler.getFileName();
00106         handler.setFileName(file);
00107         myReaders[myNextFreeReader-1]->parse(file.c_str());
00108         handler.setFileName(prevFile);
00109         myNextFreeReader--;
00110     } catch (ProcessError &e) {
00111         if (std::string(e.what())!=std::string("Process Error") && std::string(e.what())!=std::string("")) {
00112             MsgHandler::getErrorInstance()->inform(e.what());
00113         }
00114         return false;
00115     } catch (...) {
00116         MsgHandler::getErrorInstance()->inform("An error occured.");
00117         return false;
00118     }
00119     return !MsgHandler::getErrorInstance()->wasInformed();
00120 }

void XMLSubSys::setFeature	(	XERCES_CPP_NAMESPACE_QUALIFIER SAX2XMLReader &	reader,
		const std::string &	feature,
		bool	value
	)			throw () `[static, protected]`

Sets the named feature of the given reader to the given value.

The given feature name is translated into an XMLCh* and set.

Parameters:

`[in]`	reader	The reader to set the feature of
`[in]`	feature	Name of the feature to set
`[in]`	value	Value of the feature to set

Definition at line 143 of file XMLSubSys.cpp.

Referenced by getSAXReader().

00144                                                                     {
00145     XMLCh *xmlFeature = XMLString::transcode(feature.c_str());
00146     reader.setFeature(xmlFeature, value);
00147     XMLString::release(&xmlFeature);
00148 }

void XMLSubSys::setHandler ( GenericSAXHandler & handler ) [static]

Sets the given handler for the default reader.

Uses the reader built on init() which is stored in myReader.

Parameters:

[in] handler The handler to assign to the built reader

Definition at line 90 of file XMLSubSys.cpp.

References myNextFreeReader, and myReaders.

Referenced by GenericSAXHandler::endElement(), GenericSAXHandler::registerParent(), and runParser().

00090                                                 {
00091     myReaders[myNextFreeReader-1]->setContentHandler(&handler);
00092     myReaders[myNextFreeReader-1]->setErrorHandler(&handler);
00093 }