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

#include <XMLSubSys.h>

Static Public Member Functions
static void	close ()
	Closes the xml-subsystem.

static SUMOSAXReader *	getSAXReader (SUMOSAXHandler &handler, const bool isNet=false, const bool isRoute=false)
	Builds a reader and assigns the handler to it.

static void	init ()
	Initialises the xml-subsystem.

static bool	runParser (GenericSAXHandler &handler, const std::string &file, const bool isNet=false, const bool isRoute=false, const bool isExternal=false, const bool catchExceptions=true)
	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 void	setValidation (const std::string &validationScheme, const std::string &netValidationScheme, const std::string &routeValidationScheme)
	Enables or disables validation.

static std::string	transcode (const XMLCh *const data, int length=-1)
	converts a 0-terminated XMLCh* array (usually UTF-16, stemming from Xerces) into std::string in UTF-8

static std::string	transcodeFromLocal (const std::string &localString)
	convert a string from the local codepage to UTF-8

static std::string	transcodeToLocal (const std::string &utf8String)
	convert a string from UTF-8 to the local codepage

Static Private Member Functions
static std::string	warnLocalScheme (const std::string &newScheme, const bool haveSUMO_HOME)

Static Private Attributes
static XERCES_CPP_NAMESPACE::XMLGrammarPool *	myGrammarPool = nullptr
	Schema cache to be used for grammars which are not declared.

static XERCES_CPP_NAMESPACE::XMLLCPTranscoder *	myLCPTranscoder = nullptr
	reusable transcoder for local <-> UTF-8 conversions

static bool	myNeedsValidationWarning = true
	Whether a warning about missing SUMO_HOME should be emitted.

static std::string	myNetValidationScheme = "local"
	Information whether built reader/parser shall validate SUMO networks against schemata.

static int	myNextFreeReader
	Information whether the reader is parsing.

static std::vector< SUMOSAXReader * >	myReaders
	The XML Readers used for repeated parsing.

static std::string	myRouteValidationScheme = "local"
	Information whether built reader/parser shall validate SUMO routes against schemata.

static std::string	myValidationScheme = "local"
	Information whether built reader/parser shall validate XML-documents against schemata.

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.

Definition at line 62 of file XMLSubSys.h.

Member Function Documentation

◆ close()

void XMLSubSys::close ( )

static

Closes the xml-subsystem.

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

Definition at line 124 of file XMLSubSys.cpp.

References myGrammarPool, myLCPTranscoder, and myReaders.

Referenced by SystemFrame::close().

Here is the caller graph for this function:

◆ getSAXReader()

SUMOSAXReader * XMLSubSys::getSAXReader	(	SUMOSAXHandler &	handler,
		const bool	isNet = `false`,
		const bool	isRoute = `false`
	)

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
[in]	isNet	whether a network gets loaded
[in]	isRoute	whether routes get loaded

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

See also: getSAXReader()

Definition at line 137 of file XMLSubSys.cpp.

References myGrammarPool, myNetValidationScheme, myRouteValidationScheme, and myValidationScheme.

Referenced by MSStateHandler::MSStateTimeHandler::getTime(), GUISettingsHandler::GUISettingsHandler(), MSDevice_FCDReplay::init(), NIImporter_OpenStreetMap::load(), PCNetProjectionLoader::load(), NITypeLoader::load(), main(), and SUMORouteLoader::SUMORouteLoader().

Here is the caller graph for this function:

◆ init()

void XMLSubSys::init ( )

static

Initialises the xml-subsystem.

Calls XMLPlatformUtils::Initialize(). If this fails, the exception is caught and its content is reported using a ProcessError.

Exceptions

ProcessError If the initialisation fails

Definition at line 61 of file XMLSubSys.cpp.

References myNextFreeReader, and transcode().

Referenced by LIBSUMO_NAMESPACE::Simulation::load(), main(), and main().

Here is the caller graph for this function:

◆ runParser()

bool XMLSubSys::runParser	(	GenericSAXHandler &	handler,
		const std::string &	file,
		const bool	isNet = `false`,
		const bool	isRoute = `false`,
		const bool	isExternal = `false`,
		const bool	catchExceptions = `true`
	)

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
[in]	isNet	whether a network gets loaded
[in]	isRoute	whether routes get loaded
[in]	isExternal	whether it is an external file like matsim or opendrive
[in]	catchExceptions	whether exceptions on parsing should be caught or transferred into a ProcessError

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

Definition at line 153 of file XMLSubSys.cpp.

References MsgHandler::clear(), MsgHandler::getErrorInstance(), GenericSAXHandler::getFileName(), myGrammarPool, myNetValidationScheme, myNextFreeReader, myReaders, myRouteValidationScheme, myValidationScheme, GenericSAXHandler::setFileName(), TL, TLF, transcode(), MsgHandler::wasInformed(), WRITE_ERROR, and WRITE_MESSAGEF.

Referenced by NIImporter_SUMO::_loadNetwork(), NLBuilder::build(), GUISettingsHandler::GUISettingsHandler(), AGActivityGen::importInfoCity(), NIImporter_Vissim::load(), NLBuilder::load(), NITypeLoader::load(), ODDistrictCont::loadDistricts(), GUINet::loadEdgeData(), ShapeHandler::loadFiles(), PCLoaderOSM::loadIfSet(), PCLoaderXML::loadIfSet(), loadJTRDefinitions(), ODMatrix::loadMatrix(), NLBuilder::loadMesoEdgeTypes(), loadNet(), ROLoader::loadNet(), NIImporter_ITSUMO::loadNetwork(), NIImporter_MATSim::loadNetwork(), NIImporter_OpenDrive::loadNetwork(), RealisticEngineModel::loadParameters(), ODMatrix::loadRoutes(), MSNet::loadState(), ROLoader::loadWeights(), main(), MSCalibrator::MSCalibrator(), MSLaneSpeedTrigger::MSLaneSpeedTrigger(), NIImporter_OpenDrive::myStartElement(), GNEParametersDialog::ParametersOperations::onCmdLoadParameters(), GNETLSEditorFrame::TLSFile::onCmdLoadTLSProgram(), GUIApplicationWindow::onCmdOpenShapes(), ROLoader::openTypedRoutes(), DataHandler::parse(), GeneralHandler::parse(), GNETLSEditorFrame::parseTLSPrograms(), MSNet::quickReload(), readDetectors(), single(), and GenericSAXHandler::startElement().

Here is the caller graph for this function:

◆ setHandler()

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 147 of file XMLSubSys.cpp.

References myNextFreeReader, and myReaders.

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

Here is the caller graph for this function:

◆ setValidation()

void XMLSubSys::setValidation	(	const std::string &	validationScheme,
		const std::string &	netValidationScheme,
		const std::string &	routeValidationScheme
	)

static

Enables or disables validation.

The setting is only valid for parsers created after the call. Existing parsers are not adapted.

Parameters

[in]	validationScheme	Whether validation of XML-documents against schemata shall be enabled
[in]	netValidationScheme	Whether validation of SUMO networks against schemata shall be enabled

Definition at line 88 of file XMLSubSys.cpp.

References FileHelpers::isReadable(), myGrammarPool, myNeedsValidationWarning, myNetValidationScheme, myRouteValidationScheme, myValidationScheme, TL, warnLocalScheme(), WRITE_WARNING, and WRITE_WARNINGF.

Here is the caller graph for this function:

◆ transcode()

std::string XMLSubSys::transcode	(	const XMLCh *const	data,
		int	length = `-1`
	)

static

converts a 0-terminated XMLCh* array (usually UTF-16, stemming from Xerces) into std::string in UTF-8

Parameters

[in] length number of XMLCh code units to transcode, or -1 to derive from the null-terminator

Exceptions

EmptyData if the given pointer is 0

Definition at line 205 of file XMLSubSys.cpp.

Referenced by GenericSAXHandler::buildErrorMessage(), OptionsLoader::characters(), GenericHandler::characters(), GenericSAXHandler::characters(), SUMOSAXAttributesImpl_Xerces::clone(), GenericHandler::endElement(), GenericSAXHandler::endElement(), TemplateHandler::error(), OptionsLoader::error(), TemplateHandler::fatalError(), OptionsLoader::fatalError(), SUMOSAXAttributesImpl_Xerces::getAttributeNames(), SUMOSAXAttributesImpl_Xerces::getFloat(), OptionsIO::getRoot(), SUMOSAXAttributesImpl_Xerces::getString(), SUMOSAXAttributesImpl_Xerces::getStringSecure(), init(), NITypeLoader::load(), OptionsIO::loadConfiguration(), GNEOptionsEditor::loadConfiguration(), GNEPythonTool::loadConfiguration(), GNEApplicationWindowHelper::GNENetconvertConfigHandler::loadNetconvertConfig(), GNEApplicationWindowHelper::GNENeteditConfigHandler::loadNeteditConfig(), GNEApplicationWindowHelper::GNESumoConfigHandler::loadSumoConfig(), main(), TemplateHandler::parseTemplate(), SUMOSAXReader::LocalSchemaResolver::resolveEntity(), runParser(), SUMOSAXAttributesImpl_Xerces::serialize(), TemplateHandler::startElement(), OptionsLoader::startElement(), GenericHandler::startElement(), GenericSAXHandler::startElement(), transcodeFromLocal(), TemplateHandler::warning(), and OptionsLoader::warning().

Here is the caller graph for this function:

◆ transcodeFromLocal()

std::string XMLSubSys::transcodeFromLocal ( const std::string & localString )

static

convert a string from the local codepage to UTF-8

Definition at line 232 of file XMLSubSys.cpp.

References myLCPTranscoder, and transcode().

Referenced by OptionsIO::setArgs().

Here is the caller graph for this function:

◆ transcodeToLocal()

std::string XMLSubSys::transcodeToLocal ( const std::string & utf8String )

static

convert a string from UTF-8 to the local codepage

Definition at line 248 of file XMLSubSys.cpp.

References myLCPTranscoder.

Referenced by OptionsIO::getRoot(), FileHelpers::isDirectory(), FileHelpers::isReadable(), OptionsIO::loadConfiguration(), GNEOptionsEditor::loadConfiguration(), GNEPythonTool::loadConfiguration(), GNEApplicationWindowHelper::GNENetconvertConfigHandler::loadNetconvertConfig(), GNEApplicationWindowHelper::GNENeteditConfigHandler::loadNeteditConfig(), GNEApplicationWindowHelper::GNESumoConfigHandler::loadSumoConfig(), GUIApplicationWindow::onCmdSaveConfig(), GNEApplicationWindow::onCmdSaveNeteditConfig(), GNEOptionsEditor::onCmdSaveOptions(), GNEApplicationWindow::onCmdSaveSumoConfig(), OutputDevice_File::OutputDevice_File(), SUMOSAXReader::parse(), SUMOSAXReader::parseFirst(), OptionsCont::processMetaOptions(), GNEExternalRunner::run(), and SysUtils::runHiddenCommand().

Here is the caller graph for this function:

◆ warnLocalScheme()

std::string XMLSubSys::warnLocalScheme	(	const std::string &	newScheme,
		const bool	haveSUMO_HOME
	)

staticprivate

Definition at line 72 of file XMLSubSys.cpp.

References myNeedsValidationWarning, TL, and WRITE_WARNING.

Referenced by setValidation().

Here is the caller graph for this function:

Field Documentation

◆ myGrammarPool

XERCES_CPP_NAMESPACE::XMLGrammarPool * XMLSubSys::myGrammarPool = nullptr

staticprivate

Schema cache to be used for grammars which are not declared.

Definition at line 180 of file XMLSubSys.h.

Referenced by close(), getSAXReader(), runParser(), and setValidation().

◆ myLCPTranscoder

XERCES_CPP_NAMESPACE::XMLLCPTranscoder * XMLSubSys::myLCPTranscoder = nullptr

staticprivate

reusable transcoder for local <-> UTF-8 conversions

Definition at line 186 of file XMLSubSys.h.

Referenced by close(), transcodeFromLocal(), and transcodeToLocal().

◆ myNeedsValidationWarning

bool XMLSubSys::myNeedsValidationWarning = true

staticprivate

Whether a warning about missing SUMO_HOME should be emitted.

Definition at line 183 of file XMLSubSys.h.

Referenced by setValidation(), and warnLocalScheme().

◆ myNetValidationScheme

std::string XMLSubSys::myNetValidationScheme = "local"

staticprivate

Information whether built reader/parser shall validate SUMO networks against schemata.

Definition at line 174 of file XMLSubSys.h.

Referenced by getSAXReader(), runParser(), and setValidation().

◆ myNextFreeReader

int XMLSubSys::myNextFreeReader

staticprivate

Information whether the reader is parsing.

Definition at line 168 of file XMLSubSys.h.

Referenced by init(), runParser(), and setHandler().

◆ myReaders

std::vector< SUMOSAXReader * > XMLSubSys::myReaders

staticprivate

The XML Readers used for repeated parsing.

Definition at line 165 of file XMLSubSys.h.

Referenced by close(), runParser(), and setHandler().

◆ myRouteValidationScheme

std::string XMLSubSys::myRouteValidationScheme = "local"

staticprivate

Information whether built reader/parser shall validate SUMO routes against schemata.

Definition at line 177 of file XMLSubSys.h.

Referenced by getSAXReader(), runParser(), and setValidation().

◆ myValidationScheme

std::string XMLSubSys::myValidationScheme = "local"

staticprivate

Information whether built reader/parser shall validate XML-documents against schemata.

Definition at line 171 of file XMLSubSys.h.

Referenced by getSAXReader(), runParser(), and setValidation().

The documentation for this class was generated from the following files:

Static Public Member Functions

Static Private Member Functions

Static Private Attributes

Detailed Description

Member Function Documentation

◆ close()

◆ getSAXReader()

◆ init()

◆ runParser()

◆ setHandler()

◆ setValidation()

◆ transcode()

◆ transcodeFromLocal()

◆ transcodeToLocal()

◆ warnLocalScheme()

Field Documentation

◆ myGrammarPool

◆ myLCPTranscoder

◆ myNeedsValidationWarning

◆ myNetValidationScheme

◆ myNextFreeReader

◆ myReaders

◆ myRouteValidationScheme

◆ myValidationScheme