Merge remote-tracking branch 'origin/open987' into open-master

platform/core/src/capabilities/RelationshipCapability.js

@@ -0,0 +1,118 @@
+/*global define*/
+
+define(
+    [],
+    function () {
+        "use strict";
+
+        /**
+         * Relationship capability. Describes a domain objects relationship
+         * to other domain objects within the system, and provides a way to
+         * access related objects.
+         *
+         * For most cases, this is not the capability to use; the
+         * `composition` capability describes the more general relationship
+         * between objects typically seen (e.g. in the tree.) This capability
+         * is instead intended for the more unusual case of relationships
+         * which are not intended to appear in the tree, but are instead
+         * intended only for special, limited usage.
+         *
+         * @constructor
+         */
+        function RelationshipCapability($injector, domainObject) {
+            var objectService,
+                lastPromise = {},
+                lastModified;
+
+            // Get a reference to the object service from $injector
+            function injectObjectService() {
+                objectService = $injector.get("objectService");
+                return objectService;
+            }
+
+            // Get a reference to the object service (either cached or
+            // from the injector)
+            function getObjectService() {
+                return objectService || injectObjectService();
+            }
+
+            // Promise this domain object's composition (an array of domain
+            // object instances corresponding to ids in its model.)
+            function promiseRelationships(key) {
+                var model = domainObject.getModel(),
+                    ids;
+
+                // Package objects as an array
+                function packageObject(objects) {
+                    return ids.map(function (id) {
+                        return objects[id];
+                    }).filter(function (obj) {
+                        return obj;
+                    });
+                }
+
+                // Clear cached promises if modification has occurred
+                if (lastModified !== model.modified) {
+                    lastPromise = {};
+                    lastModified = model.modified;
+                }
+
+                // Make a new request if needed
+                if (!lastPromise[key]) {
+                    ids = (model.relationships || {})[key] || [];
+                    lastModified = model.modified;
+                    // Load from the underlying object service
+                    lastPromise[key] = getObjectService().getObjects(ids)
+                        .then(packageObject);
+                }
+
+                return lastPromise;
+            }
+
+            // List types of relationships which this object has
+            function listRelationships() {
+                var relationships =
+                    (domainObject.getModel() || {}).relationships || {};
+
+                // Check if this key really does expose an array of ids
+                // (to filter out malformed relationships)
+                function isArray(key) {
+                    return Array.isArray(relationships[key]);
+                }
+
+                return Object.keys(relationships).filter(isArray).sort();
+            }
+
+            return {
+                /**
+                 * List all types of relationships exposed by this
+                 * object.
+                 * @returns {string[]} a list of all relationship types
+                 */
+                listRelationships: listRelationships,
+                /**
+                 * Request related objects, with a given relationship type.
+                 * This will typically require asynchronous lookup, so this
+                 * returns a promise.
+                 * @param {string} key the type of relationship
+                 * @returns {Promise.<DomainObject[]>} a promise for related
+                 *          domain objects
+                 */
+                getRelatedObjects: promiseRelationships
+            };
+        }
+
+        /**
+         * Test to determine whether or not this capability should be exposed
+         * by a domain object based on its model. Checks for the presence of
+         * a `relationships` field, that must be an object.
+         * @param model the domain object model
+         * @returns {boolean} true if this object has relationships
+         */
+        RelationshipCapability.appliesTo = function (model) {
+            return !!(model || {}).relationships;
+        };
+
+        return RelationshipCapability;
+    }
+);

platform/core/test/capabilities/RelationshipCapabilitySpec.js

@@ -0,0 +1,125 @@
+/*global define,Promise,describe,it,expect,beforeEach,waitsFor,jasmine*/
+
+/**
+ * CompositionCapabilitySpec. Created by vwoeltje on 11/6/14.
+ */
+define(
+    ["../../src/capabilities/RelationshipCapability"],
+    function (RelationshipCapability) {
+        "use strict";
+
+        var DOMAIN_OBJECT_METHODS = [
+            "getId",
+            "getModel",
+            "getCapability",
+            "hasCapability",
+            "useCapability"
+        ];
+
+        describe("The relationship capability", function () {
+            var mockDomainObject,
+                mockInjector,
+                mockObjectService,
+                relationship;
+
+            // Composition Capability makes use of promise chaining,
+            // so support that, but don't introduce complication of
+            // native promises.
+            function mockPromise(value) {
+                return {
+                    then: function (callback) {
+                        return mockPromise(callback(value));
+                    }
+                };
+            }
+
+            beforeEach(function () {
+                mockDomainObject = jasmine.createSpyObj(
+                    "domainObject",
+                    DOMAIN_OBJECT_METHODS
+                );
+
+                mockObjectService = jasmine.createSpyObj(
+                    "objectService",
+                    [ "getObjects" ]
+                );
+
+                mockInjector = {
+                    get: function (name) {
+                        return (name === "objectService") && mockObjectService;
+                    }
+                };
+
+                mockObjectService.getObjects.andReturn(mockPromise([]));
+
+                relationship = new RelationshipCapability(
+                    mockInjector,
+                    mockDomainObject
+                );
+            });
+
+            it("applies only to models with a 'relationships' field", function () {
+                expect(RelationshipCapability.appliesTo({ relationships: {} }))
+                    .toBeTruthy();
+                expect(RelationshipCapability.appliesTo({}))
+                    .toBeFalsy();
+            });
+
+            it("requests ids found in model's composition from the object service", function () {
+                var ids = [ "a", "b", "c", "xyz" ];
+
+                mockDomainObject.getModel.andReturn({ relationships: { xyz: ids } });
+
+                relationship.getRelatedObjects('xyz');
+
+                expect(mockObjectService.getObjects).toHaveBeenCalledWith(ids);
+            });
+
+            it("provides a list of relationship types", function () {
+                mockDomainObject.getModel.andReturn({ relationships: {
+                    abc: [ 'a', 'b' ],
+                    def: "not an array, should be ignored",
+                    xyz: []
+                } });
+                expect(relationship.listRelationships()).toEqual(['abc', 'xyz']);
+            });
+
+            it("avoids redundant requests", function () {
+                    // Lookups can be expensive, so this capability
+                // should have some self-caching
+                var response;
+
+                mockDomainObject.getModel
+                    .andReturn({ relationships: { xyz: ['a'] } });
+
+                // Call twice; response should be the same object instance
+                expect(relationship.getRelatedObjects('xyz'))
+                    .toBe(relationship.getRelatedObjects('xyz'));
+
+                // Should have only made one call
+                expect(mockObjectService.getObjects.calls.length)
+                    .toEqual(1);
+            });
+
+            it("makes new requests on modification", function () {
+                // Lookups can be expensive, so this capability
+                // should have some self-caching
+                var response, testModel;
+
+                testModel = { relationships: { xyz: ['a'] } };
+
+                mockDomainObject.getModel.andReturn(testModel);
+
+                // Call twice, but as if modification had occurred in between
+                relationship.getRelatedObjects('xyz');
+                testModel.modified = 123;
+                relationship.getRelatedObjects('xyz');
+
+                // Should have only made one call
+                expect(mockObjectService.getObjects.calls.length)
+                    .toEqual(2);
+            });
+
+        });
+    }
+);

platform/core/test/suite.json

@@ -11,6 +11,7 @@
     "capabilities/DelegationCapability",
     "capabilities/MutationCapability",
     "capabilities/PersistenceCapability",
+    "capabilities/RelationshipCapability",
 
     "models/ModelAggregator",
     "models/PersistedModelProvider",