Regina Calculation Engine
|
Provides a mechanism to resolve dangling packet references after a complete packet tree has been read from an XML data file. More...
#include <packet/xmltreeresolver.h>
Public Types | |
typedef std::map< std::string, Packet * > | IDMap |
A type that maps internal IDs from the data file to the corresponding packets. More... | |
Public Member Functions | |
XMLTreeResolver () | |
Constructs a resolver with no tasks queued. More... | |
~XMLTreeResolver () | |
Destroys any tasks that were queued but not performed. More... | |
void | queueTask (XMLTreeResolutionTask *task) |
Queues a task for processing. More... | |
void | storeID (const std::string &id, Packet *packet) |
Stores the fact that the given packet is stored in the data file using the given internal ID. More... | |
const IDMap & | ids () const |
Returns the map from internal IDs to packets, as stored in the data file. More... | |
void | resolve () |
Calls XMLTreeResolutionTask::resolve() for all queued tasks. More... | |
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 XMLTreeResolver class. The complete process of reading an XML data file works as follows:
Each task should be an instance of a subclass of XMLTreeResolutionTask, whose virtual resolve() function is overridden to perform whatever "fleshing out" work is required for the type of packet under consideration.
typedef std::map<std::string, Packet*> regina::XMLTreeResolver::IDMap |
A type that maps internal IDs from the data file to the corresponding packets.
See ids() for details.
|
inline |
Constructs a resolver with no tasks queued.
|
inline |
Destroys any tasks that were queued but not performed.
|
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 Packet::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 XMLTreeResolutionTask::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).
|
inline |
Queues a task for processing.
When the file I/O manager calls resolve(), this will call XMLTreeResolutionTask::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 XMLTreeResolver is destroyed).
task | the task to be queued. |
|
inline |
Calls XMLTreeResolutionTask::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).
|
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 XMLPacketReader as it processes packet tags in the data file. Users and/or subclasses of XMLPacketReader do not need to call this function themselves.
id | the internal ID of the given packet, as stored in the data file. |
packet | the corresponding packet. |