[Entanglement] Add LocationCapability

DomainObjects with a context capability also gain a LocationCapability.

This capability allows you to determine the location of the current
instance of a domain object, and also provides methods for determining
if the current instance of a domain object is a link, or if it is an
original.

platform/entanglement/bundle.json

@@ -37,6 +37,12 @@
         "controllers": [
         ],
         "capabilities": [
+            {
+                "key": "location",
+                "name": "Location Capability",
+                "description": "Provides a capability for retrieving the location of an object based upon it's context.",
+                "implementation": "capabilities/LocationCapability"
+            }
         ],
         "services": [
             {

platform/entanglement/src/capabilities/LocationCapability.js

@@ -0,0 +1,66 @@
+/*global define */
+
+define(
+
+    function () {
+
+        function LocationCapability(domainObject) {
+            this.domainObject = domainObject;
+        }
+
+        /**
+         * Return the current location of the current domain object.  Only
+         * valid for domain objects that have a context capability.
+         */
+        LocationCapability.prototype.getLocation = function () {
+            var context = this.domainObject.getCapability("context"),
+                pathObjects,
+                pathIds;
+
+            if (!context) {
+                return this.domainObject.getId();
+            }
+
+            pathObjects = context.getPath();
+            if (!pathObjects) {
+                pathObjects = [];
+            }
+
+            pathIds = pathObjects.map(function (object) {
+                return object.getId();
+            });
+
+            return pathIds.join('/');
+        };
+
+        /**
+         * Returns true if the domainObject is a link, false if it's an
+         * original.
+         */
+        LocationCapability.prototype.isLink = function () {
+            var model = this.domainObject.getModel();
+
+            return model.location !== this.getLocation();
+        };
+
+        /**
+         * Returns true if the domainObject is an original, false if it's a
+         * link.
+         */
+        LocationCapability.prototype.isOriginal = function () {
+            var model = this.domainObject.getModel();
+
+            return model.location === this.getLocation();
+        };
+
+        /**
+         * Return true if the LocationCapability can apply to a given
+         * domainObject, otherwise return false.
+         */
+        LocationCapability.appliesTo = function (domainObject) {
+            return domainObject.hasCapability('context');
+        };
+
+        return LocationCapability;
+    }
+);

platform/entanglement/test/capabilities/LocationCapabilitySpec.js

@@ -0,0 +1,81 @@
+/*global define,describe,it,expect,beforeEach */
+
+define(
+    [
+        '../../src/capabilities/LocationCapability',
+        '../DomainObjectFactory'
+    ],
+    function (LocationCapability, domainObjectFactory) {
+
+        describe("LocationCapability", function () {
+
+
+            it("applies to objects with a context capability", function () {
+                var domainObject = domainObjectFactory({
+                    capabilities: {
+                        context: true
+                    }
+                });
+                expect(LocationCapability.appliesTo(domainObject)).toBe(true);
+            });
+
+            it("does not apply to objects without context capability", function () {
+                var domainObject = domainObjectFactory();
+                expect(LocationCapability.appliesTo(domainObject)).toBe(false);
+            });
+
+            describe("instantiated with domain object", function () {
+                var locationCapability,
+                    domainObject;
+
+                beforeEach(function () {
+                    domainObject = domainObjectFactory({
+                        capabilities: {
+                            context: {
+                                getPath: function() {
+                                    return [
+                                        {
+                                            getId: function () {
+                                                return 'root';
+                                            }
+                                        },
+                                        {
+                                            getId: function () {
+                                                return 'parent';
+                                            }
+                                        },
+                                        {
+                                            getId: function () {
+                                                return 'me';
+                                            }
+                                        }
+                                    ];
+                                }
+                            }
+                        }
+                    });
+
+                    locationCapability = new LocationCapability(domainObject);
+                });
+
+                it("returns location", function () {
+                    expect(locationCapability.getLocation())
+                        .toBe('root/parent/me');
+                });
+
+                it("knows when the object is an original", function () {
+                    domainObject.model.location = 'root/parent/me';
+                    expect(locationCapability.isOriginal()).toBe(true);
+                    expect(locationCapability.isLink()).toBe(false);
+                });
+
+                it("knows when the object is a link.", function () {
+                    domainObject.model.location = 'root/another/location/me';
+                    expect(locationCapability.isLink()).toBe(true);
+                    expect(locationCapability.isOriginal()).toBe(false);
+                });
+
+            });
+        });
+    }
+);

platform/entanglement/test/suite.json

@@ -5,5 +5,6 @@
     "services/CopyService",
     "services/LinkService",
     "services/MoveService",
-    "services/LocationService"
+    "services/LocationService",
+    "capabilities/LocationCapability"
 ]