GroupLab.Networking :: How to Use

Here we describe the core GroupLab.Networking components and common steps for any application that uses GroupLab.Networking.

Sections:

  1. What is a Shared Dictionary?
  2. What is a Subscription?
  3. General Steps for Any Application

I. What is a Shared Dictionary?

A shared dictionary is the main component within GroupLab.Networking.  It enables multiple applications to share information over a network.

A shared dictionary can be viewed as a remote hashtable that can store keys and their corresponding values. The values can have any type, from integers and strings to vectors and two dimensional arrays to custom made objects. The shared dictionary uses paths (e.g., "/path1") and subpaths (e.g., "/path1/subpath1") for keys. Thus, at each path or subpath there will be a value. Because the shared dictionary is remote, it can run on remote machines and store data remotely. Clients can connect, send or retrieve values, set new paths or subpaths or delete them.

II. What is a Subscription?

A subscription is a way clients can watch certain entries in the shared dictionary and get notified when those entries get changed, deleted or added.  For example, you set a subscription to monitor a path like this:

subscription1.Pattern = "/some/path";

You can also use wildcard characters when setting a subscription's path:

The * wildcard matches zero or more characters traversing sub-trees.  For example, /countries/*/capital would match /countries/Canada/capital and /countries/USA/capital.

The ? wildcard is similar, but scans only one level in the hierarchy.  For example, /countries/?/population would match /countries/Canada/population but not /countries/USA/California/population.

The + wildcard matches a sub-tree and its root.  For example, /countries/Canada+ matches /countries/Canada  and any keys under it, like /countries/Canada/anthem, /countries/Canada/Alberta/capital.

III. General Steps for Any Application

Appliactions using GroupLab.Networking will typically involve the same six basic steps.

1. Object Creation: Create a SharedDictionary object and a Subscription object by dragging them on to the form.

2. Subscription Setup: Subscribe to dictionary paths in the Form Constructor like this:

this.subscription1.BeginInit();
this.subscription1.Pattern = "/value";

// this next line creates an event handler that will fire when a notification is received
this.subscription1.Notified += new SubscriptionEventHandler(sub_notified);

this.subscription1.EndInit();

3. Connect: Connecting to a Shared Dictionary in the Form Constructor like this:

      this.sharedDictionary1.Url = "tcp://localhost:port";
    this.sharedDictionary1.Open();

4. Set Values: Place integers, strings, vectors, objects into a dictionary path like this:

    this.sharedDictionary1["/value"] = 0;

5. Retrieve Values: When your application receives notifications about changes to the paths you subscribed to, retrieve the data like this:

    private void sub_Notified(object sender, SubscriptionEventArgs e)
    {
         int x = (int) e.Entry.Value;
    }

6. Disconnect: Disconnect from a remote shared dictionary when you're finished:

     this.sharedDictionary1.Close();