NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Some Background

Before we get to the meat here, let’s get some background information out there so we’re all on the same page.

What is Serialization?

Let’s clearly define what we mean by serialization. By Serialization we mean converting an object, or a connected graph of objects, stored within computer memory, and conventionally drawn on paper in two dimensions, into a linear sequence of bytes. That string of bytes contains all of the important information that was held in the objects we started with.

We can go on to use that sequence of bytes in several ways. For example:

What’s an object graph?

An object graph is a set of objects with some set of references to each other. The interesting question here is what problems does this bring for Serialization? The most obvious problem is how to represent the links between the objects in the Serialized stream. After all, the value held in the field of the in-memory object which links to another object is essentially a 32-bit address, which has meaning only in the owner address space (and may even change, ‘beneath our feet’, due to garbage collection). Serialization needs to allocate each object in the stream a number. So, for example, we have assigned arbitrary, small numbers to objects below, and shown the class of each:

Then we can represent this graph of objects with a serialized stream like this:

Dog, 3, ref 4, ref 7, ref 1 || Cat, 4 || Cat 7 || Mouse, 1, ref 9, ref 2 || Horse, 9, ref 4 || Duck, 2

(To simplify the diagram, we’ve not shown the value of each object’s scalar fields, just the object references). It doesn’t matter what order we stream out the objects, nor what numbers we assign to the objects. What does matter is that no two objects are assigned the same number. The object numbers only have significance within a serialized stream. They are simply a way to represent the graph topology, and allow us to reconstruct a copy of that graph, perhaps on another computer. Of course, this is trivial to do when we can see the whole graph on paper. But an algorithm that visits objects one-at-a-time clearly has to keep track of which objects it has already ‘seen’, using an internal list for example. Without due care, we might otherwise serialize two copies of the Cat object on the left, and later Deserialize two copies of that object, one linked from object Dog,3 and the other copy linked from object Horse, 9.

Note that we have chosen to represent one complete object at a t ime in the serialized stream. This corresponds to a breadth-first traversal of the object graph. An alternative, depth-first traversal, would serialize each object, embedded into the stream, at the point the graph walk encountered its object reference in the parent object. So we’d end up with a stream like this, using a slightly different, but obvious syntax:

Dog, 3, < Cat 4>, <Cat 7>, <Mouse, 1, <Horse, 9, ref 4>, Duck, 2>>

In many cases, this technique avoids the need to insert explicit references into the stream (but not always – see the two links to Cat, 4, required to avoid duplicating objects at Deserializationn time).