Nov 05

The DataContext component: linking objects

Posted in Javascript MS AJAX      Comments Off on The DataContext component: linking objects

Today we’ll keep going in our study of the DataContext component and we’ll see how we can establish relationships between objects through links. I guess you’re probably asking something like: “Hum…establishing relationships between objects…how about using properties?” For instance, suppose we’re working with person and contact instances from the previous post…We can say that a person has one contact and that is easily expressed through JavaScript which looks like this:

var personWithContact = {
  id: 6,
  name: "dumb",
  contact: { value: 1, contact: "123123123" }

Now, this is perfectly good code…really…so, why would I want to use links then? Glad you asked :,,)

Before going on, I’d like to point out that this is a feature which was added in order to support ADO.NET Data Services. Fortunately, the team wrote it in a generic way so that you could use it even if you’re not using ADO.NET Data Services (I said fortunately because you can reuse this feature if you want). But I’m divagating…why would we use links? For bookkeeping, of course! Whenever you create a link between two objects, you end up setting a property in the source and you’ll also get an entry in the changes array (internal _changelist array).

When working with links, you’ve got several methods which you can use:

  • addLink: you should use this method when you need to add items to a collection. For instance, suppose you’ve got a property which is an array and you want to add an object to that array. The addLink method is the way to go;
  • setLink: also used for adding a new link between two objects. This is the method you should use when you’re thinking of “simple” properties (instead of collections);
  • removeLink: used for deleting an existing link between two objects. You should only use this method when you’re removing an item from a collection

As I’ve said above, you should keep in mind that these methods end up changing the internal changes list maintained by the DataContext control. Establishing and cancelling links produces different results when you’re working with single properties and collections. For instance, take a look at the following code (based in code presented in the previous post):

var newPerson = { name: "joseph", address: "fx", 
contacts: [] };
var ct1 = { value: 1, contact: "123123123" }; var ct2 = { value: 2, contact: "222333444" }; ctx.addLink(newPerson, "contacts", ct1);//collection ctx.setLink(newPerson, "contact", ct2);//single prop ctx.setLink(newPerson, "contact", null);//removing single ctx.removeLink(newPerson, "contacts", ct1);//removing coll.

In the previous snippet, we’ve introduced a new person instance and several contacts in order to show you how to establish links between the objects. If you stop the code in the addLink method, you’ll see something like this:


As you can see, establishing the link through the add method ended up adding the contact to the contacts array of the person object and inserting a new entry in the changes list. If you stop the code’s execution after the setLink line, you’ll see something similar (depending on what changes were made to the DataContext):


As you can see, the main difference is that setLink ends up setting an item instead of adding it to a collection. Canceling a relationship established through the setLink method involves using that method again, but passing null instead of a valid value. On the other hand, removing an item from the collection should always be done with the removeLink method. Interestingly, these methods produce different results in this scenario (don’t forget that we still haven’t committed the changes, ie, we still haven’t committed our setLink and addLink changes). Take a look at the following picture to see what I mean:


As you can see, the removeLink call ended up deleting the previous addLink entry (while also removing the entry from the contacts array). However, the setLink method doesn’t affect the changes array in the same way; instead, it will simply update the existing entry so that it points to the new target that has been passed to it. Notice that this means that you’ll have to pay attention to this if you’re writing custom code in the server side which is responsible for persisting the changes.

And I guess this sums it up quite nicely. but there’s still more to discuss…so stay tuned for more on MS AJAX.