src/jabber_whiteboard/node-tracker.h

   1 /**
   2  * Whiteboard session manager
   3  * XML node tracking facility
   4  *
   5  * Authors:
   6  * David Yip <yipdw@rose-hulman.edu>
   7  *
   8  * Copyright (c) 2005 Authors
   9  *
  10  * Released under GNU GPL, read the file 'COPYING' for more information
  11  */
  12
  13 #ifndef __WHITEBOARD_XML_NODE_TRACKER_H__
  14 #define __WHITEBOARD_XML_NODE_TRACKER_H__
  15
  16 #include "jabber_whiteboard/tracker-node.h"
  17 #include "jabber_whiteboard/typedefs.h"
  18
  19 #include <bitset>
  20 #include <cstring>
  21 #include <map>
  22 #include <glibmm.h>
  23
  24 namespace Inkscape {
  25
  26 namespace Whiteboard {
  27
  28 class SessionManager;
  29
  30 /**
  31  * std::less-like functor for C-style strings.
  32  */
  33 struct strcmpless : public std::binary_function< char const*, char const*, bool >
  34 {
  35         bool operator()(char const* _x, char const* _y) const
  36         {
  37                 return (strcmp(_x, _y) < 0);
  38         }
  39 };
  40
  41
  42 // TODO: This is a pretty heinous mess of methods that accept
  43 // both pointers and references -- a lot of it has to do with
  44 // XML::Node& in the node observer and XML::Node* elsewhere,
  45 // although some of it (like Glib::ustring const& vs.
  46 // Glib::ustring const*) is completely mea culpa. When possible
  47 // it'd be good to thin this class out.
  48
  49 /**
  50  * XMLNodeTracker generates and watches unique IDs for XML::Nodes for use in
  51  * document event serialization and deserialization.
  52  *
  53  * More specifically, it has three tasks:
  54  * <ol>
  55  *      <li>Association XML::Nodes with string IDs, and vice versa.</li>
  56  *  <li>Facilitation of lookup of a string ID or XML::Node given the other key.</li>
  57  *      <li>Generation of new string IDs for XML::Nodes.</li>
  58  * </ol>
  59  *
  60  * XML::Nodes are assigned an ID that follows one of two forms:
  61  * <ol>
  62  *      <li>unsigned integer;user JID</li>
  63  *      <li>unsigned integer;chatroom@conference server/handle</li>
  64  * </ol>
  65  *
  66  * Form 1 is used in user-to-user sessions; form 2 is used in chatroom sessions.
  67  */
  68 class XMLNodeTracker  {
  69 public:
  70         /**
  71          * Constructor.
  72          *
  73          * \param sm The SessionManager with which an XMLNodeTracker instance is to be associated with.
  74          */
  75         XMLNodeTracker(SessionManager* sm);
  76         ~XMLNodeTracker();
  77
  78         /**
  79          * Insert a (key,node) pair into the tracker.
  80          *
  81          * \param key The key to associate with the node.
  82          * \param node The node to associate with the key.
  83          */
  84         void put(std::string key, XML::Node& node);
  85
  86         /**
  87          * Insert a (key,node) pair into the tracker.
  88          *
  89          * \param key The key to associate with the node.
  90          * \param node The node to associate with the key.
  91          */
  92         void put(std::string key, XML::Node const& node);
  93
  94         /**
  95          * Insert a range of (key,node) pairs into the tracker.
  96          *
  97          * The size of the two maps must be the same.
  98          * \param newids The keys to associate with the nodes.
  99          * \param newnodes The nodes to associate with the keys.
 100          */
 101         void put(KeyToNodeMap& newids, NodeToKeyMap& newnodes);
 102
 103         /**
 104          * Process a list of node actions to add and remove nodes from the tracker.
 105          *
 106          * \param actions The action list to process.
 107          */
 108         void process(KeyToNodeActionList& actions);
 109
 110         /**
 111          * Retrieve an XML::Node given a key.
 112          *
 113          * \param key Reference to a string key.
 114          * \return Pointer to an XML::Node, or NULL if no associated node could be found.
 115          */
 116         XML::Node* get(std::string& key);
 117
 118         /**
 119          * Retrieve an XML::Node given a key.
 120          *
 121          * \param key Reference to a const string key.
 122          * \return Pointer to an XML::Node, or NULL if no associated node could be found.
 123          */
 124         XML::Node* get(std::string const& key);
 125
 126         /**
 127          * Retrieve a string key given a reference to an XML::Node.
 128          *
 129          * \param node Reference to an XML::Node.
 130          * \return The associated string key, or an empty string if no associated key could be found.
 131          */
 132         std::string const get(XML::Node& node);
 133
 134         /**
 135          * Retrieve a string key given a reference to an XML::Node.
 136          *
 137          * \param node Reference to a const XML::Node.
 138          * \return The associated string key, or an empty string if no associated key could be found.
 139          */
 140         std::string const get(XML::Node const& node);
 141
 142         /**
 143          * Remove an entry from the tracker based on key.
 144          *
 145          * \param The key of the entry to remove.
 146          */
 147         void remove(std::string& key);
 148
 149         /**
 150          * Remove an entry from the tracker based on XML::Node.
 151          *
 152          * \param A reference to the XML::Node associated with the entry to remove.
 153          */
 154         void remove(XML::Node& node);
 155
 156         /**
 157          * Return whether or not a (key,node) pair is being tracked, given a string key.
 158          *
 159          * \param The key associated with the pair to check.
 160          * \return Whether or not the pair is being tracked.
 161          */
 162         bool isTracking(std::string& key);
 163
 164         /**
 165          * Return whether or not a (key,node) pair is being tracked, given a string key.
 166          *
 167          * \param The key associated with the pair to check.
 168          * \return Whether or not the pair is being tracked.
 169          */
 170         bool isTracking(std::string const& key);
 171
 172         /**
 173          * Return whether or not a (key,node) pair is being tracked, given a node.
 174          *
 175          * \param The node associated with the pair to check.
 176          * \return Whether or not the pair is being tracked.
 177          */
 178         bool isTracking(XML::Node& node);
 179
 180         /**
 181          * Return whether or not a (key,node) pair is being tracked, given a node.
 182          *
 183          * \param The node associated with the pair to check.
 184          * \return Whether or not the pair is being tracked.
 185          */
 186         bool isTracking(XML::Node const& node);
 187
 188         /**
 189          * Return whether or not a node identified by a given name is a special node.
 190          *
 191          * \see Inkscape::Whiteboard::specialnodekeys
 192          * \see Inkscape::Whiteboard::specialnodenames
 193          *
 194          * \param The name associated with the node.
 195          * \return Whether or not the node is a special node.
 196          */
 197         bool isSpecialNode(char const* name);
 198
 199         /**
 200          * Return whether or not a node identified by a given name is a special node.
 201          *
 202          * \see Inkscape::Whiteboard::specialnodekeys
 203          * \see Inkscape::Whiteboard::specialnodenames
 204          *
 205          * \param The name associated with the node.
 206          * \return Whether or not the node is a special node.
 207          */
 208         bool isSpecialNode(std::string const& name);
 209
 210         /**
 211          * Retrieve the key of a special node given the name of a special node.
 212          *
 213          * \see Inkscape::Whiteboard::specialnodekeys
 214          * \see Inkscape::Whiteboard::specialnodenames
 215          *
 216          * \param The name associated with the node.
 217          * \return The key of the special node.
 218          */
 219         std::string const getSpecialNodeKeyFromName(Glib::ustring const& name);
 220
 221         /**
 222          * Retrieve the key of a special node given the name of a special node.
 223          *
 224          * \see Inkscape::Whiteboard::specialnodekeys
 225          * \see Inkscape::Whiteboard::specialnodenames
 226          *
 227          * \param The name associated with the node.
 228          * \return The key of the special node.
 229          */
 230         std::string const getSpecialNodeKeyFromName(Glib::ustring const* name);
 231
 232         /**
 233          * Returns whether or not the given node is the root node of the SPDocument associated
 234          * with an XMLNodeTracker's SessionManager.
 235          *
 236          * \param Reference to an XML::Node to test.
 237          * \return Whether or not the given node is the document root node.
 238          */
 239         bool isRootNode(XML::Node& node);
 240
 241         /**
 242          * Generate a node key given a JID.
 243          *
 244          * \param The JID to use in the key.
 245          * \return A node string key.
 246          */
 247         std::string generateKey(gchar const* JID);
 248
 249         /**
 250          * Generate a node key given the JID specified in the SessionData structure associated
 251          * with an XMLNodeTracker's SessionManager.
 252          *
 253          * \return A node string key.
 254          */
 255         std::string generateKey();
 256
 257         // TODO: remove debugging function
 258         void dump();
 259         void reset();
 260
 261 private:
 262         void createSpecialNodeTables();
 263         void _clear();
 264
 265         unsigned int _counter;
 266         SessionManager* _sm;
 267
 268         // defined in typedefs.h
 269         KeyToTrackerNodeMap _keyToNode;
 270         TrackerNodeToKeyMap _nodeToKey;
 271
 272         std::map< char const*, char const*, strcmpless > _specialnodes;
 273
 274         // Keys for special nodes
 275         std::string _rootKey;
 276         std::string _defsKey;
 277         std::string _namedviewKey;
 278         std::string _metadataKey;
 279
 280         // noncopyable, nonassignable
 281         XMLNodeTracker(XMLNodeTracker const&);
 282         XMLNodeTracker& operator=(XMLNodeTracker const&);
 283 };
 284
 285 }
 286
 287 }
 288
 289
 290 #endif
 291 /*
 292   Local Variables:
 293   mode:c++
 294   c-file-style:"stroustrup"
 295   c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
 296   indent-tabs-mode:nil
 297   fill-column:99
 298   End:
 299 */
 300 // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=99 :