Programming Reference: ONMjs.Namespace Class
See also: onm Data Storage & Access
See also: onm.Store Class
Class onm.Namespace represents a namespace within an existing data component stored in an onm.Store instance.
Given an onm.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 onm.Namespace instances is wholly encapsulated in factory methods provided by the core onm.Store class. Specifically, onm.Namespace instances are created by the onm.Store.createComponent and onm.Store.openNamespace methods.
onm.Address instances are not constructed with the JavaScript new operator.
A reference to the onm.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 onm.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 onm.Store instance is a semantically ambiguous operation with respect to registered observers of an onm.Store. This is because injecting raw data into a Namespace via either the onm.Namespace.fromData or onm.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, onm 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 onm.Namespace.fromData remarks.
namespace.update();
Return:
- Returns no semantically useful information on success.
- Throws on exception on error.
Remarks:
onm does not track namespace data modifications. Instead, onm relies on your application logic to indicate via a call to onm.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 onm.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 onm.Store requires to construct an onm.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 onm.Model(addressBookDataModelDeclaration);
var store = new onm.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 */
var key = namespace.getComponentKey();
Return:
- Returns the data object key of the data component containing this namespace.
- Throws an exception on error.
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:
onm.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 onm.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 onm.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:
onm.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.
var count = namespace.getExtensionPointSubcomponentCount();
Return:
- Returns an integer count (possibly zero) of the components contained in an extension point namespace.
- Throws an exception if an error occurs.
Remarks:
It is often useful to determine if an extension point namespace contains components without actually visiting them (or performing low-level operations on the data).
Copyright (C) 2013 Christopher D. Russell