Programming Reference: ONMjs.Namespace Class
See also: ONMjs Data Storage & Access
See also: ONMjs.Store Class
Class ONMjs.Namespace represents a namespace within an existing data component stored in an ONMjs.Store instance.
Given an ONMjs.Namespace instance, you can obtain a JavaScript reference to the namespace's actual data, obtain its resolved address, serialize the namespace and its subnamespaces to JSON, and visit components contained in an extension point namespace.
The construction and initialization of ONMjs.Namespace instances is wholly encapsulated in factory methods provided by the core ONMjs.Store class. Specifically, ONMjs.Namespace instances are created by the ONMjs.Store.createComponent and ONMjs.Store.openNamespace methods.
ONMjs.Address instances are not constructed with the JavaScript new operator.
A reference to the ONMjs.Store instance that contains the actual data represented by this namespace instance.
var data = namespace.data();
Return:
- Returns a reference to the actual namespace data.
- Throws an exception on error.
Remarks:
Client application code gains access to the actual namespace data by calling the ONMjs.Namespace.data method. The returned reference can be handled just like any other reference to a JavaScript object. In other words you can read and write it's properties and leverage all your normal JavaScript just as you would any other JavaScript data object.
var jsonString = namespace.toJSON(replacer, space);
Parameters:
- Both replacer and space parameters are optional. See Using Native JSON (MDN).
Return:
- Returns a JSON string created by serializing the data the namespace represents.
- Throws an exception on error.
var address = namespace.fromData(data);
Parameters:
- data - (required) raw data to write into the namespace object's associated data reference.
Return:
- Returns the address of the updated namespace object if successful.
- Throws an exception on error.
Remarks:
The fromData method is valid only for component namespaces.
Wholesale replacement of data in an ONMjs.Store instance is a semantically ambiguous operation with respect to registered observers of an ONMjs.Store. This is because injecting raw data into a Namespace via either the ONMjs.Namespace.fromData or ONMjs.Namespace.fromJSON methods replaces an entire data branch in the store.
In order to ensure that all observers continue to track the current data in the store, ONMjs dispatches component/namespace removed signals prior to applying the data, and concludes by dispatching component/namespace added signals.
var address = namespace.fromData(jsonString);
Parameters:
-
jsonString - (required) JSON string obtained from
Namespace.toJSON().
Return:
- Returns the address of the updated namespace object if successful.
- Throws an exception on error.
Remarks:
The fromJSON method is valid only for component namespaces.
_See ONMjs.Namespace.fromData remarks.
namespace.update();
Return:
- Returns no semantically useful information on success.
- Throws on exception on error.
Remarks:
ONMjs does not track namespace data modifications. Instead, ONMjs relies on your application logic to indicate via a call to ONMjs.Namespace.update that an update data change signal should be broadcast to observer routines registered with the namespace's owning store instance.
This protocol allows you to determine the granularity and frequency of observer callbacks based on data semantics and performance considerations.
var address = namespace.getResolvedAddress();
Return:
- Returns an ONMjs.Address instance representing this namespace's address in the backing data model's address space.
- Throws an exception on error.
Remarks:
Resolved vs. unresolved addresses are a little tricky so here's the deal: a resolved address encapsulates all the information that class ONMjs.Store requires to construct an ONMjs.Namespace instance provided that the addressed namespace actually exists in the store. An unresolved address does not; unresolved addresses are used to create new data components within a store but cannot be used to actually create a namespace instance.
This is best illustrated with a simple example:
var model = new ONMjs.Model(addressBookDataModelDeclaration);
var store = new ONMjs.Store(model);
/* Create an unresolved address for creating a new data component in the store. */
var unresolvedContactAddress = model.createPathAddress("addressBook.contacts.contact");
/* Create the new contact component. */
var contactNamespace = store.createComponent(newContactAddress);
/* Obtain the resolved address of the newly-created contact component. */
var resolvedContactAddress = contactNamespace.getResolvedAddress();
/* You cannot use unresolved addresses to open a namespace, or remove a component... */
contactNamespace = store.openNamespace(unresolvedContactAddress); /* THROWS */
store.removeComponent(unresolvedContactAddress); /* THROWS */
/* ... instead you must use the resolved address: */
contactNamespace = store.openNamespace(resolvedContactAddress); /* OKAY */
store.removeComponent(resolvedContactAddress); /* OKAY */
label = namespace.getResolvedLabel();
Return:
- Returns a human readable string label for the namespace (see remarks).
- Returns void 0 if a label cannot be resolved for the namespace.
- Throws an exception on error.
Remarks:
ONMjs.Namespace.getResolvedLabel is a convenience method that encapsulates the common operation of obtaining a human readable label for a namespace. The method will search for the function semanticBindings.getLabel in your data model declaration and all it passing a raw data reference to the namespace's data as the first parameter, and the namespace's resolved address as the second parameter providing all the context you require to implement some application-specific protocol for labelling namespaces.
If your data model declaration does not define semanticBindings.getLabel, then ONMjs.Namespace.getResolvedLabel looks at the namespace's model and uses the value specified for optional ____label meta-property. If this is not defined either, then ONMjs.NamespaceResolvedLabel returns void 0.
var subcomponentAddresses = [];
namespace.visitExtensionPointSubcomponents( function (address) { subcomponentAddress.push(address); } );
Return:
- Returns true when the visitation completes.
- Returns false if no callback function is specified.
- Throws an exception on error.
Remarks:
ONMjs.Namespace.visitExtensionPointSubcomponents is used to enumerate the contents of an extension point namespace. Calling this method on any other type of namespace is an error.
Copyright (C) 2013 Christopher D. Russell