Programming Reference: ONMjs.AddressToken Class
I'm keeping this page in the Wiki for reference but ONMjs.AddressToken class has been relegated to the implementation of ONMjs and is not to be used by client developers. Thus, this page is not linked in the master table of contents.
It is however commonplace that your application logic will need to construct a new address based on an address passed to you by the library. And, there are situations where you'll want to create ONMjs.Address instances explicitly in your application code. For example, if you want to create a new data component, you may need to create an an address to pass to ONMjs.Store.createComponent if you've got no other address in context you can easily modify.
To lesson the burden on application developers, ONMjs provides a number of helper functions that automate the creation and manipulation of ONMjs.Address instances for many common scenarios. Using these helper functions in your application logic significantly reduces the amount of code you have to write. However, in order to learn how to apply these functions correctly requires that you gain a basic understanding of the ONMjs.AddressToken class, and ONMjs.Address' token array.
As explained above, an ONMjs.Address class instance represents an address using an ordered array of ONMjs.AddressToken class instances.
The constructor signature for ONMjs.AddressToken is as follows:
function AddressToken(model, idExtensionPoint, key, idNamespace) { /* ... */ };
The first parameter, model, should be pretty much self-explanatory. Address tokens, like addresses are intrinsically bound to your data model and you must supply a reference to a ONMjs.Model class instance in order to construct an ONMjs.AddressToken class instance.
The remaining three parameters are not as obvious and require careful explanation.
idExtensionPoint and idNamespace are path ID's (i.e. numerical aliases for a path string). key is a key string as explained above and discussed in detail in the Data Model article.
idNamespace is required and must always be specified along with model. Its ID value can indicate any path in the model's address space. However, the specific path indicated by the ID impacts the specification of value(s) for the idExtensionPoint and key parameters as follows:
idNamespace |
idExtensionPoint |
key |
Notes |
|---|---|---|---|
| ID of namespace in the root component | void 0 | void 0 | Token indicates a namespace in the root component. |
| ID of the root namespace of a sub-component | required | void 0 | Token indicates a new component to be created via a call to ONMjs.Store.createComponent |
| ID of the root namespace of a sub-component | required | specified | Token indicates an existing component to be accessed via ONMjs.Store.openNamespace, or removed via ONMjs.Store.removeComponent |
| ID of non-root namespace in a sub-component | required | required | Token indicates a sub-namespace in an existing component to be accessed via ONMjs.Store.openNamespace |
To demystify ONMjs.AddressToken, we'll work through some low-level examples that construct and initialize several ONMjs.Address instances step-by-step. This material is presented to provide context for later discussion of the higher-level functions provided by ONMjs for creating and manipulating ONMjs.Address instances. It's atypical that you will need to write code like this in practice.
To start with, let's create an ONMjs.Address that addresses the root addressBook component.
/* You would never actually write this code but for illustrative purposes... */
var model = new ONMjs.Model(addressBookDataModelDeclaration);
var idNamespace = model.getPathIdFromPath("addressBook"); /* We know this will always be zero (0). */
var token = new ONMjs.AddressToken(model, void 0, void 0, idNamespace);
var address = new ONMjs.Address(model);
address.pushToken(token);
Now suppose that we wanted to create an ONMjs.Address that addresses the contacts extension point. Look carefully - this a one-line change from above.
/* Note the change to the request for idNamespace... */
var model = new ONMjs.Model(addressBookDataModelDeclaration);
var idNamespace = model.getPathIdFromPath("addressBook.contacts"); /* We don't know or care what ID is returned. */
var token = new ONMjs.AddressToken(model, void 0, void 0, idNamespace);
var address = new ONMjs.Address(model);
address.pushToken(token);
Okay. Now let's level-up and create an ONMjs.Address that addresses a new contact component. Recall that contact is a sub-component. This means we require not one, but two tokens.
var model = new ONMjs.Model(addressBookDataModelDeclaration);
var idExtensionPoint = model.getPathIdFromPath("addressBook.contacts"); /* We don't know or care what ID is returned. */
var tokenExtensionPoint = new ONMjs.AddressToken(model, void 0, void 0, idExtensionPoint);
var address = new ONMjs.Address(model);
addressNewContact.pushToken(tokenExtensionPoint);
/* At this point there's one token in the address' internal token array. */
var idComponent = model.getPathIdFromPath("addressBook.contacts.contact");
tokenComponent = new ONMjs.AddressToken(model, idExtensionPoint, void 0, idComponent);
addressNewContact.pushToken(tokenComponent);
Notice that we did not specify a key when constructing tokenComponent because we're creating an address for a component that does not yet exist.
Let's create an address book store, and create some contacts.
var store = new ONMjs.Store(model);
var contactNamespace1 = store.createComponent(addressNewContact);
var contactNamespace2 = store.createComponent(addressNewContact);
var contactNamespace3 = store.createComponent(addressNewContact);
Here we have re-used addressNewContact in three successive calls to ONMjs.createComponent to create three new contact data components in our object store.
Now let's remove the last contact component we just created.
store.removeComponent(addressNewContact); /* THROWS AND EXCEPTION! */
/* Obtain the the address of the last contact we created. */
addressContact3 = contactNamespace3.getResolvedAddress()
/* Now we can remove the contact. */
store.removeComponent(addressContact3); /* OKAY. */
See: Address Helper Functions (programming reference documentation)
Copyright (C) 2013 Christopher D. Russell