OutputDevice Class Reference

#include <OutputDevice.h>

Inheritance diagram for OutputDevice:

---

Detailed Description

Static storage of an output device and its base (abstract) implementation.

OutputDevices are basically a capsule around an std::ostream, which give a unified access to sockets, files and stdout.

Usually, an application builds as many output devices as needed. Each output device may also be used to save outputs from several sources (several detectors, for example). Building is done using OutputDevice::getDevice() what also parses the given output description in order to decide what kind of an OutputDevice shall be built. OutputDevices are closed via OutputDevice::closeAll(), normally called at the application's end.

Although everything that can be written to a stream can also be written to an OutputDevice, there is special support for XML tags (remembering all open tags to close them at the end). OutputDevices are still lacking support for function pointers with the '<<' operator (no endl, use '
'). The most important method to implement in subclasses is getOStream, the most used part of the interface is the '<<' operator.

The Boolean markers are used rarely and might get removed in future versions.

Definition at line 65 of file OutputDevice.h.

static members
typedef std::map< std::string, OutputDevice * >	DeviceMap
	Definition of a map from names to output devices.
static DeviceMap	myOutputDevices
	map from names to output devices
OutputDevice member methods
void	close () throw ()
	Closes the device and removes it from the dictionary.
bool	closeTag (bool abbreviated=false) throw ()
	Closes the most recently opened tag.
OutputDevice &	indent () throw ()
	Adds indentation.
void	inform (const std::string &msg)
	Retrieves a message to this device.
virtual bool	ok () throw ()
	returns the information whether one can write into the device
OutputDevice &	openTag (const std::string &xmlElement) throw ()
	Opens an XML tag.
template<class T>
OutputDevice &	operator<< (const T &t)
	Abstract output operator.
	OutputDevice () throw (IOError)
	Constructor.
void	setPrecision (unsigned int precision=OUTPUT_ACCURACY) throw ()
	Sets the precison or resets it to default.
bool	writeXMLHeader (const std::string &rootElement, const bool writeConfig=true, const std::string &attrs="", const std::string &comment="") throw ()
	Writes an XML header with optional configuration.
virtual	~OutputDevice () throw ()
	Destructor.
virtual std::ostream &	getOStream ()=0 throw ()
	Returns the associated ostream.
virtual void	postWriteHook () throw ()
	Called after every write access.
Static Public Member Functions
static access methods to OutputDevices
static void	closeAll () throw ()
static bool	createDeviceByOption (const std::string &optionName, const std::string &rootElement="") throw (IOError)
	Creates the device using the output definition stored in the named option.
static OutputDevice &	getDevice (const std::string &name, const std::string &base="") throw (IOError)
	Returns the described OutputDevice.
static OutputDevice &	getDeviceByOption (const std::string &name) throw (IOError, InvalidArgument)
	Returns the device described by the option.
Private Attributes
Non-static members of each OutputDevice
std::vector< std::string >	myXMLStack
	The stack of begun xml elements.

---

Member Typedef Documentation

typedef std::map<std::string, OutputDevice*> OutputDevice::DeviceMap [private]

Definition of a map from names to output devices.

Definition at line 245 of file OutputDevice.h.

---

Constructor & Destructor Documentation

OutputDevice::OutputDevice

(

)

throw (IOError) [inline]

Constructor.

Definition at line 133 of file OutputDevice.h.

{ }

virtual OutputDevice::~OutputDevice

(

)

throw () [inline, virtual]

Destructor.

Definition at line 137 of file OutputDevice.h.

{ }

---

Member Function Documentation

void OutputDevice::close

(

)

throw ()

Closes the device and removes it from the dictionary.

Definition at line 133 of file OutputDevice.cpp.

References closeTag(), and myOutputDevices.

Referenced by RONet::closeOutput(), GUIDialog_ViewSettings::onCmdExportSetting(), GUIParameterTracker::onCmdSave(), GUIDialog_Breakpoints::onCmdSave(), RODFDetectorCon::save(), PCPolyContainer::save(), GUISelectedStorage::save(), GUISelectedStorage::SingleTypeSelections::save(), RODFDetectorCon::saveAsPOIs(), GUIDialog_ViewSettings::saveDecals(), NBNodeCont::savePlain(), NBEdgeCont::savePlain(), RODFDetectorCon::saveRoutes(), RODFDetector::writeEmitterDefinition(), RODFDetectorCon::writeEmitterPOIs(), RODFDetectorCon::writeEmitters(), RODFDetectorCon::writeEndRerouterDetectors(), RODFDetector::writeSingleSpeedTrigger(), RODFDetectorCon::writeSpeedTrigger(), and RODFDetectorCon::writeValidationDetectors().

                            {
    while (closeTag());
    for (DeviceMap::iterator i=myOutputDevices.begin(); i!=myOutputDevices.end(); ++i) {
        if (i->second == this) {
            myOutputDevices.erase(i);
            break;
        }
    }
    delete this;
}

void OutputDevice::closeAll

(

)

throw () [static]

Closes all registered devices

Definition at line 115 of file OutputDevice.cpp.

References myOutputDevices.

Referenced by GUIRunThread::deleteSim(), and main().

                               {
    while (myOutputDevices.size()!=0) {
        myOutputDevices.begin()->second->close();
    }
    myOutputDevices.clear();
}

bool OutputDevice::closeTag

(

bool

abbreviated = false

)

throw ()

Closes the most recently opened tag.

The topmost xml-element from the stack is written into the stream as a closing element ("</" + element + ">") and is then removed from the stack. If abbreviated closing is requested, only "/>" is the output.

Parameters:

[in]

name

whether abbreviated closing is performed

Returns:

Whether a further element existed in the stack and could be closed

Todo:

it is not verified that the topmost element was closed

Definition at line 188 of file OutputDevice.cpp.

References getOStream(), indent(), myXMLStack, and postWriteHook().

Referenced by close(), MSPersonControl::erase(), ROVehicle::saveAllAsXML(), MSVehicleControl::scheduleVehicleRemoval(), RORouteDef_Complete::writeXMLDefinition(), RORouteDef_Alternatives::writeXMLDefinition(), and RORoute::writeXMLDefinition().

                                               {
    if (!myXMLStack.empty()) {
        if (abbreviated) {
            getOStream() << "/>" << std::endl;
        } else {
            std::string indent(4*(myXMLStack.size()-1), ' ');
            getOStream() << indent << "</" << myXMLStack.back() << ">" << std::endl;
        }
        myXMLStack.pop_back();
        postWriteHook();
        return true;
    }
    return false;
}

bool OutputDevice::createDeviceByOption	(	const std::string &	optionName,
		const std::string &	rootElement = ""
	)			throw (IOError) [static]

Creates the device using the output definition stored in the named option.

Creates and returns the device named by the option. Asks whether the option and retrieves the name from the option if so. Optionally the XML header gets written as well. Returns whether a device was created (option was set).

Please note, that we do not have to consider the "application base" herein, because this call is only used to get file names of files referenced within XML-declarations of structures which paths already is aware of the cwd.

Parameters:

[in]	optionName	The name of the option to use for retrieving the output definition
[in]	rootElement	The root element to use (XML-output)

Returns:

Whether a device was built (the option was set)

Exceptions:

IOError

If the output could not be built for any reason (error message is supplied)

Definition at line 91 of file OutputDevice.cpp.

References getDevice(), OptionsCont::getOptions(), and writeXMLHeader().

Referenced by MSFrame::buildStreams(), NBNetBuilder::compute(), NBNodeCont::computeNodeShapes(), and main().

                                                                                {
    if (!OptionsCont::getOptions().isSet(optionName)) {
        return false;
    }
    OutputDevice& dev = OutputDevice::getDevice(OptionsCont::getOptions().getString(optionName));
    if (rootElement != "") {
        dev.writeXMLHeader(rootElement);
    }
    return true;
}

OutputDevice & OutputDevice::getDevice	(	const std::string &	name,
		const std::string &	base = ""
	)			throw (IOError) [static]

Returns the described OutputDevice.

Creates and returns the named device. "stdout" and "-" refer to standard out, "hostname:port" initiates socket connection. Otherwise a filename is assumed and the second parameter may be used to give a base directory. If there already is a device with the same name this one is returned.

Parameters:

[in]	name	The description of the output name/port/whatever
[in]	base	The base path the application is run within

Returns:

The corresponding (built or existing) device

Exceptions:

IOError

If the output could not be built for any reason (error message is supplied)

Definition at line 60 of file OutputDevice.cpp.

References TplConvert< E >::_2int(), FileHelpers::checkForRelativity(), getOStream(), FileHelpers::isSocket(), and setPrecision().

Referenced by NLHandler::addE1Detector(), NLHandler::addE2Detector(), NLHandler::addEdgeLaneMeanData(), NLHandler::addRouteProbeDetector(), NLHandler::addVTypeProbeDetector(), NLHandler::beginE3Detector(), NBNetBuilder::buildLoaded(), NLDiscreteEventBuilder::buildSaveTLStateCommand(), NLDiscreteEventBuilder::buildSaveTLSwitchesCommand(), NLDiscreteEventBuilder::buildSaveTLSwitchStatesCommand(), createDeviceByOption(), getDeviceByOption(), MsgHandler::initOutputOptions(), GUIDialog_ViewSettings::onCmdExportSetting(), GUIParameterTracker::onCmdSave(), GUIDialog_EditViewport::onCmdSave(), GUIDialog_Breakpoints::onCmdSave(), RONet::openOutput(), RODFDetectorCon::save(), PCPolyContainer::save(), GUISelectedStorage::save(), GUISelectedStorage::SingleTypeSelections::save(), RODFDetectorCon::saveAsPOIs(), GUIDialog_ViewSettings::saveDecals(), NBNodeCont::savePlain(), NBEdgeCont::savePlain(), RODFDetectorCon::saveRoutes(), RODFDetector::writeEmitterDefinition(), RODFDetectorCon::writeEmitterPOIs(), RODFDetectorCon::writeEmitters(), RODFDetectorCon::writeEndRerouterDetectors(), RODFDetector::writeSingleSpeedTrigger(), RODFDetectorCon::writeSpeedTrigger(), and RODFDetectorCon::writeValidationDetectors().

                                                              {
    // check whether the device has already been aqcuired
    if (myOutputDevices.find(name)!=myOutputDevices.end()) {
        return *myOutputDevices[name];
    }
    // build the device
    OutputDevice *dev = 0;
    // check whether the device shall print to stdout
    if (name=="stdout" || name=="-") {
        dev = new OutputDevice_COUT();
    } else if (FileHelpers::isSocket(name)) {
        try {
            int port = TplConvert<char>::_2int(name.substr(name.find(":")+1).c_str());
            dev = new OutputDevice_Network(name.substr(0, name.find(":")), port);
        } catch (NumberFormatException &) {
            throw IOError("Given port number '" + name.substr(name.find(":")+1) + "' is not numeric.");
        } catch (EmptyData &) {
            throw IOError("No port number given.");
        }
    } else {
        dev = new OutputDevice_File(FileHelpers::checkForRelativity(name, base));
    }
    dev->setPrecision();
    dev->getOStream() << std::setiosflags(std::ios::fixed);
    myOutputDevices[name] = dev;
    return *dev;
}

OutputDevice & OutputDevice::getDeviceByOption

(

const std::string &

name

)

throw (IOError, InvalidArgument) [static]

Returns the device described by the option.

Returns the device named by the option. If the option is unknown, unset or the device was not created before, InvalidArgument is thrown.

Please note, that we do not have to consider the "application base" herein.

Parameters:

[in]

name

The name of the option to use for retrieving the output definition

Returns:

The corresponding (built or existing) device

Exceptions:

	IOError	If the output could not be built for any reason (error message is supplied)
	InvalidArgument	If the option with the given name does not exist

Definition at line 105 of file OutputDevice.cpp.

References getDevice(), OptionsCont::getOptions(), and OptionsCont::getString().

Referenced by NBNodeShapeComputer::compute(), NBNodeShapeComputer::computeNodeShapeByCrosses(), MSPersonControl::erase(), main(), MSVehicleControl::scheduleVehicleRemoval(), NBNode::sortNodesEdges(), and MSNet::writeOutput().

                                                                                           {
    std::string devName = OptionsCont::getOptions().getString(optionName);
    if (myOutputDevices.find(devName)==myOutputDevices.end()) {
        throw InvalidArgument("Device '" + devName + "' has not been created.");
    }
    return OutputDevice::getDevice(devName);
}

virtual std::ostream& OutputDevice::getOStream

(

)

throw () [protected, pure virtual]

Returns the associated ostream.

Implemented in MsgRetrievingFunction< T >, OutputDevice_COUT, OutputDevice_File, OutputDevice_Network, OutputDevice_String, and OutputDeviceMock.

Referenced by closeTag(), getDevice(), indent(), inform(), ok(), openTag(), operator<<(), setPrecision(), and writeXMLHeader().

OutputDevice & OutputDevice::indent

(

)

throw ()

Adds indentation.

An intendation, depending on the current xml-element-stack size, is written.

Returns:

The OutputDevice for further processing

Definition at line 171 of file OutputDevice.cpp.

References getOStream(), myXMLStack, and postWriteHook().

Referenced by closeTag().

                             {
    getOStream() << std::string(4*myXMLStack.size(), ' ');
    postWriteHook();
    return *this;
}

void OutputDevice::inform

(

const std::string &

msg

)

Retrieves a message to this device.

Implementation of the MessageRetriever interface. Writes the given message to the output device.

Parameters:

[in]

msg

The msg to write to the device

Definition at line 209 of file OutputDevice.cpp.

References getOStream(), and postWriteHook().

                                         {
    getOStream() << msg << '\n';
    postWriteHook();
}

bool OutputDevice::ok

(

)

throw () [virtual]

returns the information whether one can write into the device

Returns:

Whether the device can be used (stream is good)

Definition at line 128 of file OutputDevice.cpp.

References getOStream().

                         {
    return getOStream().good();
}

OutputDevice & OutputDevice::openTag

(

const std::string &

xmlElement

)

throw ()

Opens an XML tag.

An intendation, depending on the current xml-element-stack size, is written followed by the given xmlelement ("<" + xmlElement) The xmlelement is added to the stack, then.

Parameters:

[in]

xmlElement

Name of element to open

Returns:

The OutputDevice for further processing

Definition at line 179 of file OutputDevice.cpp.

References getOStream(), myXMLStack, and postWriteHook().

Referenced by MSPersonControl::erase(), MSVehicleControl::scheduleVehicleRemoval(), RORouteDef_Complete::writeXMLDefinition(), RORouteDef_Alternatives::writeXMLDefinition(), RORoute::writeXMLDefinition(), writeXMLHeader(), and MSVehicle::writeXMLRoute().

                                                         {
    getOStream() << std::string(4*myXMLStack.size(), ' ') << "<" << xmlElement;
    postWriteHook();
    myXMLStack.push_back(xmlElement);
    return *this;
}

template<class T>

OutputDevice& OutputDevice::operator<<

(

const T &

t

)

[inline]

Abstract output operator.

Returns:

The OutputDevice for further processing

Definition at line 222 of file OutputDevice.h.

References getOStream(), and postWriteHook().

                                         {
        getOStream() << t;
        postWriteHook();
        return *this;
    }

void OutputDevice::postWriteHook

(

)

throw () [protected, virtual]

Called after every write access.

Default implementation does nothing.

Reimplemented in MsgRetrievingFunction< T >, and OutputDevice_Network.

Definition at line 205 of file OutputDevice.cpp.

Referenced by closeTag(), indent(), inform(), openTag(), and operator<<().

{}

void OutputDevice::setPrecision

(

unsigned int

precision = OUTPUT_ACCURACY

)

throw ()

Sets the precison or resets it to default.

Parameters:

[in]

precision

The accuracy (number of digits behind '.') to set

Definition at line 146 of file OutputDevice.cpp.

References getOStream().

Referenced by MSVTypeProbe::execute(), getDevice(), NBNodeCont::savePlain(), RORouteDef_Alternatives::writeXMLDefinition(), and RORoute::writeXMLDefinition().

                                                         {
    getOStream() << std::setprecision(precision);
}

bool OutputDevice::writeXMLHeader	(	const std::string &	rootElement,
		const bool	writeConfig = true,
		const std::string &	attrs = "",
		const std::string &	comment = ""
	)			throw ()

Writes an XML header with optional configuration.

If something has been written (myXMLStack is not empty), nothing is written and false returned.

Parameters:

[in]	rootElement	The root element to use
[in]	writeConfig	Whether the configuration used while this file was generated shall be saved
[in]	attrs	Additional attributes to save within the rootElement
[in]	comment	Additional comment (saved in front the rootElement)

Todo:

Check which parameter is used herein

Todo:

Describe what is saved

Definition at line 152 of file OutputDevice.cpp.

References OptionsCont::getOptions(), getOStream(), myXMLStack, openTag(), and OptionsCont::writeXMLHeader().

Referenced by createDeviceByOption(), RONet::openOutput(), RODFDetectorCon::save(), PCPolyContainer::save(), RODFDetectorCon::saveAsPOIs(), NBNodeCont::savePlain(), NBEdgeCont::savePlain(), RODFDetectorCon::saveRoutes(), RODFDetector::writeEmitterDefinition(), RODFDetectorCon::writeEmitterPOIs(), RODFDetectorCon::writeEmitters(), RODFDetectorCon::writeEndRerouterDetectors(), RODFDetector::writeSingleSpeedTrigger(), RODFDetectorCon::writeSpeedTrigger(), and RODFDetectorCon::writeValidationDetectors().

                                                                                       {
    if (myXMLStack.empty()) {
        OptionsCont::getOptions().writeXMLHeader(getOStream(), writeConfig);
        if (comment != "") {
            getOStream() << comment << "\n";
        }
        openTag(rootElement);
        if (attrs != "") {
            getOStream() << " " << attrs;
        }
        getOStream() << ">\n";
        return true;
    }
    return false;
}

---

Field Documentation

OutputDevice::DeviceMap OutputDevice::myOutputDevices [static, private]

map from names to output devices

Definition at line 248 of file OutputDevice.h.

Referenced by close(), and closeAll().

std::vector<std::string> OutputDevice::myXMLStack [private]

The stack of begun xml elements.

Definition at line 257 of file OutputDevice.h.

Referenced by closeTag(), indent(), openTag(), and writeXMLHeader().

---

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

• OutputDevice.h
• OutputDevice.cpp