GigaSpaces XAP.NET 8.0.1 introduces a few cool new features such as SpaceDocument (code name: Docu.NET API) as well as dynamic properties. Roughly speaking, a SpaceDocument is a virtual document-like type that can be written and read from the space like any other regular object, however, it provides a more dynamic API by having a key value dictionary in its properties instead of fixed properties that are part of the class code. Even though a document is dynamic, it fully supports indexing and even more powerfully so, since 8.0 now supports dynamic addition of indexes, it also supports indexing defined at runtime using the dynamic indexing capability (indexes can be added via the GigaSpaces management center at runtime).

Lets demonstrate this by evolving our beloved creature Nimbin.

SpaceDocument nimbin = new SpaceDocument("Creature");
// First schema of our creature
nimbin ["Name"] = "Nimbin";
nimbin ["Age"] = 4;
nimbin ["Sex"] = Sex.Male;
nimbin ["DigestableFood"] = new String[]{"Carrot, Apple"};

// Write Nimbin to the space

After a while Nimbin has evolved and grown some new limbs.

// Get Nimbin and "evolve" it. 
SpaceDocument nimbin = spaceProxy.ReadById(new IdQuery<SpaceDocument>("Creature""Nimbin"));
Dictionary<String, Object> tailDetails = new  Dictionary<String, Object>();
tailDetails["Color"] = Colors.Green;
tailDetails["Length"] = 1.5
nimbin["Tail"] =  tailDetails;

// Update Nimbin in the space:

As seen here the document can contain nested properties which are key value dictionaries as well, in this case the newly added tail of Nimbin. A SpaceDocument is also fully interoperable with a regular concrete Object, we can have a corresponding class of the "Creature" that can support dynamic properties in dictionary form (or even without the dynamic properties, by having the object ignore the dynamic properties).

Let's define a class for our Creature:

public class Creature
    public String Name{ getset; } 
    public Int Age{ getset; } 
    public Sex Sex{ getset; }
    public String[] DigestableFood{ getset; } 
    public Dictionary<String, Object> { getset; }

We can read Nimbin as the actual creature class as well:

Creature concreteNimbin = spaceProxy.ReadById<Creature>("Nimbin");
//We can also query for all creatures that have a tail shorter than 1.
SqlQuery<Creature> query = new SqlQuery<Creature>("Tail.Length < ?");
Creature[] shotTailCreatures = spaceProxy.ReadMultiple<Creature>(query); 

The Docu.NET API is vast and contains many more capabilities such as the Document wrapper type that enables the use of dynamic SpaceDocuments while using it as a concrete object look and feel. 

For a more in-depth look at the space document see Document Schema Free API at the GigaSpaces Wiki.


Eitan Yanovsky

Schema evolution in XAP.NET 8.0.1
.Net Team
Tagged on: