16.5 Using the Collection Server

Using the collection server is no more difficult than using a regular Tools.h++ collection class. We'll show this here by presenting code which uses the collection server. Here is the interface that clients use to access the collection server.

#include <rw/toolpro/sockaddr.h>
#include "doc.h"

class DistWebArray {
public:
  DistWebArray(RWSockAddr addr) : addr_(addr)  {}             //1
  void      insertKeyAndValue(const RWCString& s, Document*); //2
  Document* operator[](const RWCString& s);                   //3
private:
  RWSockAddr addr_;                                           //4
};

`//1`	The constructor takes as a parameter the address of the collection server. Whenever an operation needs to be performed, the implementation connects to this address and communicates with the server to get the job done. We'll discuss the details of this communication at length later, but for now, you just have to know that it happens.
`//2`	This member function inserts a string-web pair into the collection.
`//3`	The subscripting operator returns the root document for the web identified with the string `s`. The string must correspond to an entry of the collection which was inserted with `insertKeyAndValue()`.
`//4`	The only data kept by the distributed server interface is the server's address. All other state is kept on the server side.

16.5.1 Inserting Elements

Remember the program adddocs which added entries to the collection? Here is the (slightly edited) code.

#include <rw/toolpro/inetaddr.h>
#include "distdoc.h"

Document* reptileWeb() { ... }                               //1
Document* circleOfLife() { ... }

main()
{
  DistWebArray array( RWSockAddr(SERVER) );                  //2

  Document* rweb = reptileWeb();                             //3
  Document* cweb = circleOfLife();

  array.insertKeyAndValue("ReptileWeb",rweb);                //4
  array.insertKeyAndValue("CircleOfLife",cweb);

  Document::deleteWeb(rweb);                                 //5
  Document::deleteWeb(cweb);

  return 0;
}

`//1`	These are functions which return a pointer to the root of a document web. The details of the functions are omitted. Basically, you just call `Document::newDocument` for each document in the web and you call `Document::addLink` as needed to hook the documents up.
`//2`	Instantiate the interface to the web server. The object `array` is a proxy to the real server. It communicates with the server to accomplish operations. `SERVER` is a preprocessor macro set to the address of the server.
`//3`	Build a couple of hypertext document webs. The documents in the web are allocated on the heap; we get pointers to the root documents.
`//4`	This is where the action is. Stores copies of the document webs in the collection maintained by the server. Notice that, from the point of view of this code, these look just like local operations.
`//5`	Delete the webs allocated in step 3.

16.5.2 Retrieving a Web from the Server

Retrieving a document using the collection server is no more difficult than storing it. Here's a program which requests the "CircleOfLife" web, followed by a description of the key lines.

#include <rw/rstream.h>
#include <rw/toolpro/inetaddr.h>
#include "distdoc.h"

main()
{
  RWWinsockInfo info;

  DistWebArray array( RWSockAddr(SERVER) );

  Document* web = array["CircleOfLife"];                       //1
  cout << web;                                                 //2
  Document::deleteWeb(web);                                    //3

  return 0;
}

`//1`	Retrieving an element is done using the subscripting operator. The proxy collection `array` returns a pointer to the web's root document on the heap. All the documents in the web and their interrelationships are reconstituted.
`//2`	Print the retrieved web. Section 16.3 shows what the output looks like. If the web has not yet been added to the collection you get back a null web.
`//3`	Clean up memory.