16.4 The Hypertext Document Class

For this tutorial, we care only about the names of hypertext documents, and the documents to which they are linked. We ignore document details, such as when the document was created, what form it is in, who created it, and the content. A document object in this example consists simply of a name, and a list of pointers to linked documents.

A document web is represented as a pointer to the root document. There is no separate web abstraction. Adding one would improve the overall design of the code and automate the memory management, but since this is a tutorial and not production code we chose the simplest approach.

Here is the Document header file, doc.h (with the comments stripped out), followed by some explanation of the key lines.

#include <rw/tvslist.h>                                     //1
#include <rw/slistcol.h>
#include <rw/cstring.h>

class Document : public RWCollectable {                     //2

  RWDECLARE_COLLECTABLE(Document)                           //3

public:
  static Document* newDocument(const RWCString& name);      //4
  static void      deleteWeb(Document *root);

  virtual RWTValSlist<Document*> directLinks() const;       //5
  virtual RWTValSlist<Document*> allLinks();
  virtual RWCString              name() const  {return name_;}

  virtual void addLink(Document* p);

  virtual void restoreGuts(RWvistream&);                    //6
  virtual void saveGuts(RWvostream&) const;

protected:
  Document(const RWCString& name)         : name_(name) {}
  ~Document()                             {}

  RWCString name_;
  RWSlistCollectables links_;                              //7
};

ostream& operator<<(ostream&,const Document*);

`//1`	Include the declarations for the template based list class (`tvslist.h`) and the *RWCollectable*-based list class (`slistcol.h`). As we'll see, both types of collections are used, so that we can leverage the strengths of each.
`//2`	*Document* inherits from *RWCollectable* so that it can directly make use of the Tools.h++ persistence machinery. The *RWCollectable* base class provides the interface for storing and extracting a document on a virtual stream.
`//3`	This macro creates some boilerplate declarations that every *RWCollectable* subclass needs. There is a corresponding `RWDEFINE_COLLECTABLE` macro in the implementation file which fills in these boilerplate functions. See your Tools.h++ manual if you are interested in the details.
`//4`	There is no publicly accessible constructor or destructor for *Document*. Instead, you create documents using the `Document::newDocument()` function. When you are done with a web of documents, you delete the entire web at once using `Document::deleteWeb()`.
`//5`	Access components of the abstraction. `directLinks()` returns a list of documents directly referenced by this document; `allLinks()` returns a list of all documents in the web for which this object is the root. The template based collection, **RWTValSlist<Document>* is used in the interface, rather than the RWCollectable based RWSlistCollectables**, because the template based class provides type safety.
`//6`	These members are inherited from *RWCollectable*. They are used to implement the persistence machinery specific to this class.
`//7`	The list of documents is stored as a *RWSlistCollectables* collection. This collection class is not as type safe as the template based collections, but it is designed to work with the persistence machinery. The lack of type-safety is kept internal to this class since the public interfaces for *Document* are type safe.

16.4.1 Implementation of Document

The implementation of Document is in doc.cpp.

NOTE: This file is located in the examples directory created for your installation of Tools.h++ Professional. The "Examples" chapter in Part V, "Resources," describes the location of that directory, or you can check the online build guide for your installation media.

Since we are concentrating on creating a collection server, and not on the details of working with the hypertext document structure, we'll just show the part of the implementation geared specifically for persistence.

The saveGuts() function is responsible for storing a document to persistent store. The persistence machinery calls saveGuts() only if self has not already been stored, so we don't have to worry about the apparent potential for infinite recursion implied by shifting out links_ even though this list may contain (indirectly or directly) pointers back to self.

void Document::saveGuts(RWvostream& strm) const
{
  strm << name_;
  strm << links_;
}

Restoring a document is just as easy as saving one.

void Document::restoreGuts(RWvistream& strm)
{
  strm >> name_;
  strm >> links_;
}