From 04ce2f985ab3a29ed90d39a5d3783b2cec34615c Mon Sep 17 00:00:00 2001 From: Victor Woeltjen Date: Tue, 10 Nov 2015 14:16:07 -0800 Subject: [PATCH] [Persistence] Add JSDoc Add JSDoc to classes added/modified to support multiple persistence spaces, nasa/openmctweb#245. --- .../capabilities/InstantiationCapability.js | 2 ++ platform/core/src/identifiers/Identifier.js | 27 +++++++++++++++++-- .../src/identifiers/IdentifierProvider.js | 16 +++++++++++ .../src/actions/AbstractComposeAction.js | 2 ++ .../src/policies/CrossSpacePolicy.js | 8 ++++++ .../aggregator/src/PersistenceAggregator.js | 5 +++- 6 files changed, 57 insertions(+), 3 deletions(-) diff --git a/platform/core/src/capabilities/InstantiationCapability.js b/platform/core/src/capabilities/InstantiationCapability.js index ba2fa982a2..82187a49bd 100644 --- a/platform/core/src/capabilities/InstantiationCapability.js +++ b/platform/core/src/capabilities/InstantiationCapability.js @@ -33,6 +33,7 @@ define( * @constructor * @memberof platform/core * @param $injector Angular's `$injector` + * @implements {Capability} */ function InstantiationCapability($injector, identifierService, domainObject) { this.$injector = $injector; @@ -47,6 +48,7 @@ define( * have been persisted, nor will it have been added to the * composition of the object which exposed this capability. * + * @param {object} the model for the new domain object * @returns {DomainObject} the new domain object */ InstantiationCapability.prototype.instantiate = function (model) { diff --git a/platform/core/src/identifiers/Identifier.js b/platform/core/src/identifiers/Identifier.js index 6f4e12ce86..e587ee006b 100644 --- a/platform/core/src/identifiers/Identifier.js +++ b/platform/core/src/identifiers/Identifier.js @@ -29,8 +29,15 @@ define( var SEPARATOR = ":"; /** - * Provides an interface for interpreting domain object - * identifiers. + * Provides an interface for interpreting domain object identifiers; + * in particular, parses out persistence space/key pairs associated + * with the domain object. + * + * @memberof platform/core + * @constructor + * @param {string} id the domain object identifier + * @param {string} defaultSpace the persistence space to use if + * one is not encoded in the identifier */ function Identifier(id, defaultSpace) { var separatorIndex = id.indexOf(SEPARATOR); @@ -46,14 +53,30 @@ define( } } + /** + * Get the key under which the identified domain object's model + * should be persisted, within its persistence space. + * @returns {string} the key within its persistence space + */ Identifier.prototype.getKey = function () { return this.key; }; + /** + * Get the space in which the identified domain object's model should + * be persisted. + * @returns {string} the persistence space + */ Identifier.prototype.getSpace = function () { return this.space; }; + /** + * Get the persistence space, if any, which has been explicitly + * encoded in this domain object's identifier. Returns undefined + * if no such space has been specified. + * @returns {string} the persistence space, or undefined + */ Identifier.prototype.getDefinedSpace = function () { return this.definedSpace; }; diff --git a/platform/core/src/identifiers/IdentifierProvider.js b/platform/core/src/identifiers/IdentifierProvider.js index a922807cc3..c6b2a136cb 100644 --- a/platform/core/src/identifiers/IdentifierProvider.js +++ b/platform/core/src/identifiers/IdentifierProvider.js @@ -28,11 +28,22 @@ define( /** * Parses and generates domain object identifiers. + * @param {string} defaultSpace the default persistence space + * @constructor + * @memberof {platform/core} */ function IdentifierProvider(defaultSpace) { this.defaultSpace = defaultSpace; } + /** + * Generate a new domain object identifier. A persistence space + * may optionally be included; if not specified, no space will + * be encoded into the identifier. + * @param {string} [space] the persistence space to encode + * in this identifier + * @returns {string} a new domain object identifier + */ IdentifierProvider.prototype.generate = function (space) { var id = uuid(); if (space !== undefined) { @@ -41,6 +52,11 @@ define( return id; }; + /** + * Parse a domain object identifier to examine its component + * parts (e.g. its persistence space.) + * @returns {platform/core.Identifier} the parsed identifier + */ IdentifierProvider.prototype.parse = function (id) { return new Identifier(id, this.defaultSpace); }; diff --git a/platform/entanglement/src/actions/AbstractComposeAction.js b/platform/entanglement/src/actions/AbstractComposeAction.js index a9fbbf282c..1e7b356b8d 100644 --- a/platform/entanglement/src/actions/AbstractComposeAction.js +++ b/platform/entanglement/src/actions/AbstractComposeAction.js @@ -62,6 +62,8 @@ define( * @constructor * @private * @memberof platform/entanglement + * @param {PolicyService} policyService the policy service to use to + * verify that variants of this action are allowed * @param {platform/entanglement.LocationService} locationService a * service to request destinations from the user * @param {platform/entanglement.AbstractComposeService} composeService diff --git a/platform/entanglement/src/policies/CrossSpacePolicy.js b/platform/entanglement/src/policies/CrossSpacePolicy.js index ad28e0e66b..a113972815 100644 --- a/platform/entanglement/src/policies/CrossSpacePolicy.js +++ b/platform/entanglement/src/policies/CrossSpacePolicy.js @@ -33,6 +33,14 @@ define( "compose" ]; + /** + * This policy prevents performing move/copy/link actions across + * different persistence spaces (e.g. linking to an object in + * a private space from an object in a public space.) + * @memberof {platform/entanglement} + * @constructor + * @implements {Policy} + */ function CrossSpacePolicy() { } diff --git a/platform/persistence/aggregator/src/PersistenceAggregator.js b/platform/persistence/aggregator/src/PersistenceAggregator.js index f46ddfbe68..a195cd3fd5 100644 --- a/platform/persistence/aggregator/src/PersistenceAggregator.js +++ b/platform/persistence/aggregator/src/PersistenceAggregator.js @@ -36,10 +36,13 @@ define( }; /** + * Aggregates multiple persistence providers, such that they can be + * utilized as if they were a single object. * @memberof platform/persistence/aggregator * @constructor * @implements {PersistenceService} - * @param q Angular's $q, for promises + * @param $q Angular's $q, for promises + * @param {PersistenceService[]} providers the providers to aggregate */ function PersistenceAggregator($q, providers) { var providerMap = {};