regina::NXMLTreeResolver Class Reference
Basic Packet Types

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 IDMap & | ids () 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:

- The top-level routine managing the file I/O constructs a new NXMLTreeResolver. This resolver is then passed to each NXMLPacketReader in turn as each individual packet is read.
- If an NXMLPacketReader is not able to fully flesh out its data because it requires information that is not yet available, it should create a new NXMLTreeResolutionTask and queue this task to the resolver via NXMLTreeResolver::queueTask().
- Once the entire packet tree has been read, the top-level file I/O manager will call NXMLTreeResolver::resolve(). This will run NXMLTreeResolutionTask::resolve() for each task in turn, whereby any missing data for individual packets can be resolved.

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

  task | the 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

  id | the internal ID of the given packet, as stored in the data file.
  packet | the corresponding packet.

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

- packet/nxmltreeresolver.h

Copyright © 1999-2013, 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).