DataFS Code - Linking Objects

Working with DataFS Links

Links are the core principle of DataFS to structure and store our data. Objects that are not sustainingly linked are not saved and hence will be deleted. Though there might be a lot of situations where you would like to "link" an object to another, but you don't want this particular link to sustain the Object you linked.

Example Sustaining Links VS Lazy-Links

Let's say we have a team of people stored as Objects in a co-worker list, and we've made a task-app where we would like to link a respective team-mate into the task he should work on. Imagine one team-mate leaves the team but has not quite finished all tasks, now if we'd sever the link from our co-worker list trying to delete the entry, the Team-mate-object would still exist because the links from the tasks sustain it. In this case we would use unecessary memory and we would'nt notice that one task is actually linked to an invalid team-mate.
To circumvent this we have lazy-links. Lazy-links do simply not sustain the object that is linked but otherwise act the same like the sustaining link when we want to brachiate from object to object.

with Sustaining Links:

trying to delete Team Member Bob

but Bob is still linked from one task

with Lazy-Links:

deleting Team Member Bob

now the Task just points to an invalid adress, which is good

Functions

Linking can be done in several ways, in this section we look at the differences between linking Objects that are intended to be linked from the start, and linking Objects that we didnt actually intend to link from the start but have proven viable to be linked.

We may have encountered these functions already:

create a sustaining link

with dadl-generated link function

pSomeObject->LinkSomeChildObject(pSomeChildObject);

with BuildLink(true)

pSomeObject->SetUnspecifiedObject(&pSomeChildObject->BuildLink(true));

create a lazy-link

with dadl-generated set function

pSomeObject->SetSomeChildObject(pSomeChildObject);

with BuildLink(false)

pSomeObject->SetUnspecifiedObject(&pSomeChildObject->BuildLink(false));

create an Entry-Point-Link

pDomain->InsertNamedObject(&pSomeObject->BuildLink(true), &guidEntryPoint, L"someEntryPoint");

The blue dadl-generated functions are the ones we would commonly use when we know what Objects we want to link. The red basic functions are actually "baked" into the blue ones by dadl, so the blue functions are a little easyer to use but do the same thing. The main difference is, that in dadl we declaire specific object-classes to link beforehand with blue, and with red we have the freedom to link any object we want and even decide if it's a sustaining link or a lazy-link.
To use either possibilities we need to declaire it in DADL and DTDL:

In DADL we would use "link" for sustaining link and "set" for lazy-link with brackets for the blue functions:

link(WSomeChildObject), set(WSomeChildObject)

and for the red functions we would use a simple "set" for both sustaining and lazy-link:

set

Here are the DTDL- and DADL-files for this example:

DataDefinition.dtdl

class SomeObject [id({1F919316-F8F1-4087-8067-8CC606DB9941})]
{
    object SomeChildObject;		
    object UnspecifiedObject;
};
class SomeChildObject [id({C4D3E0B6-D4E2-4b18-AD97-37F1EADC2579})]
{
wstring SomeAttribute;
};

AccessDefinition.dadl

#import <DataDefinition.bdtd>
object WSomeObject{
	SomeObject{
		SomeChildObject [link(WSomeChildObject), set(WSomeChildObject), remove];
		UnspecifiedObject [set, remove];
        }  
    };
object WSomeChildObject{
	    SomeChildObject{	SomeAttribute[get, set, remove];
        }
    };

Conclusion Example for blue and red

Imagine we have programmed a Dossier for a client where we initially only intended to link certain objects - let's say text-objects. But we as programmers had a hunch that our client later wants to link other objects as well - for example an picture-object or a contacts-object or maybe even something else completely.
For the intended links we use the blue functions, because it's clear that we will have a lot of text-objects. For the things we may not know yet we just use the red ones, and maybe in a leter itteration of the projects development - if we have seen, that our client almost always want's to link for example contacts, we might change from red to blue and write new classes. Just note that we should think about these things early and thoroughly, because if we have to restructure the classes and objects when they were already in use we would have to write conversions from the old version to the new one ourselves.