Regina Calculation Engine
Public Types | Public Member Functions | List of all members
regina::NXMLTreeResolver Class Reference

Provides a mechanism to resolve dangling packet references after a complete packet tree has been read from an XML data file. More...

#include <packet/nxmltreeresolver.h>

Public Types

typedef std::map< std::string,
NPacket * > 
IDMap
 A type that maps internal IDs from the data file to the corresponding packets. More...
 

Public Member Functions

 NXMLTreeResolver ()
 Constructs a resolver with no tasks queued. More...
 
 ~NXMLTreeResolver ()
 Destroys any tasks that were queued but not performed. More...
 
void queueTask (NXMLTreeResolutionTask *task)
 Queues a task for processing. More...
 
void storeID (const std::string &id, NPacket *packet)
 Stores the fact that the given packet is stored in the data file using the given internal ID. More...
 
const IDMapids () const
 Returns the map from internal IDs to packets, as stored in the data file. More...
 
void resolve ()
 Calls NXMLTreeResolutionTask::resolve() for all queued tasks. More...
 

Detailed Description

Provides a mechanism to resolve dangling packet references after a complete packet tree has been read from an XML data file.

There are situations in which, when reading an XML data file, the data stored in an individual packet cannot be fully constructed until after the entire data file has been read. For instance, a packet might need to store pointers or references to other packets that could appear later in the packet tree (e.g., a script storing pointers to its variables).

This problem is solved by the NXMLTreeResolver class. The complete process of reading an XML data file works as follows:

Each task should be an instance of a subclass of NXMLTreeResolutionTask, whose virtual resolve() function is overridden to perform whatever "fleshing out" work is required for the type of packet under consideration.

Member Typedef Documentation

typedef std::map<std::string, NPacket*> regina::NXMLTreeResolver::IDMap

A type that maps internal IDs from the data file to the corresponding packets.

See ids() for details.

Constructor & Destructor Documentation

regina::NXMLTreeResolver::NXMLTreeResolver ( )
inline

Constructs a resolver with no tasks queued.

regina::NXMLTreeResolver::~NXMLTreeResolver ( )
inline

Destroys any tasks that were queued but not performed.

Member Function Documentation

const NXMLTreeResolver::IDMap & regina::NXMLTreeResolver::ids ( ) const
inline

Returns the map from internal IDs to packets, as stored in the data file.

Packets in a data file may have individual string IDs stored alongside them, in the id attribute of the <packet> tag. These strings are optional, and do not need to be human-readable. Although packets are not required to have IDs, any IDs that are stored must be unique (i.e., two different packets cannot share the same ID).

Note that IDs read from the data file need not bear any relation to the IDs that are returned from NPacket::internalID(), although this is typically how they are constructed when a file is saved.

This map will be fleshed out as the data file is read. In particular, since each task runs NXMLTreeResolutionTask::resolve() only after the entire tree has been read, tasks may assume that this map contains all IDs that were explicitly stored in the data file.

Only packets with IDs will appear in this map (i.e., there may well be packets in the data file that do not appear in this map at all).

Returns
the map from internal file IDs to packets.
void regina::NXMLTreeResolver::queueTask ( NXMLTreeResolutionTask task)
inline

Queues a task for processing.

When the file I/O manager calls resolve(), this will call NXMLTreeResolutionTask::resolve() for each task that has been queued.

This object will claim ownership of the given task, and will destroy it after resolve() has been called (or, if resolve() is never called, when this NXMLTreeResolver is destroyed).

Parameters
taskthe task to be queued.
void regina::NXMLTreeResolver::resolve ( )
inline

Calls NXMLTreeResolutionTask::resolve() for all queued tasks.

The tasks will then be destroyed and removed from the queue (so subsequent calls to resolve() are safe and will do nothing).

void regina::NXMLTreeResolver::storeID ( const std::string &  id,
NPacket packet 
)
inline

Stores the fact that the given packet is stored in the data file using the given internal ID.

Associations between IDs and packets can be queried through the ids() function. See ids() for further information on internal IDs.

This will be called automatically by NXMLPacketReader as it processes packet tags in the data file. Users and/or subclasses of NXMLPacketReader do not need to call this function themselves.

Parameters
idthe internal ID of the given packet, as stored in the data file.
packetthe corresponding packet.

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

Copyright © 1999-2014, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@debian.org).