Class jabberwerx.JWBase (MINIMAL)

jabberwerx.JWBase

The base class for objects in the JWApp framework.

Objects derived from jabberwerx.JWBase get the following features:

Object Graph Client-Side Persistence

A graph of JWBase-derived objects can be serialized, stored, and re-loaded via jabberwerx.util.saveGraph and jabberwerx.util.loadGraph. Cycles and uniqueing are handled via an object registry and per-object guids. Note that cycles among non-JWBase objects will result in infinite recursion, as per usual.

FYI, there are two steps to loading a serialized graph: unserializing and "rehydrating". We unserialize the object registry via eval(). Rehydrating involves turning the resulting bare JS objects with keys and values into full JW objects, with appropriate methods and prototype chain in place. For this to work, the serialization must include the objects' class name. For now this is accomplished in the class definition/declaration: jabberwerx.JWBase.extend takes a string parameter that must be the fully-qualified name of the class being defined.

Client-side storage is handled via dojo storage. By default any given JW object in a graph will NOT be saved. Objects that want to be saved must implement jabberwerx.JWBase#shouldBeSavedWithGraph and return true.

Typically only model objects should be saved to a persistent store. See jabberwerx.JWModel, which does return true for `shouldBeSavedWithGraph`.

Object-Method Invocation Objects

A jabberwerx.JWBase object can generate portable function objects that, when invoked, are scoped automatically to their generating instance. The graph storage engine treats these function objects specially, so the observer relationships among stored objects can be serialized and restored automatically.

Class Summary
Constructor Attributes	Constructor Name and Description
	jabberwerx.JWBase() Creates a new jabberwerx.JWBase object.

Method Summary
Method Attributes	Method Name and Description
	destroy() This method is offered as a way to release resources that were acquired by an object during its lifetime.
<static>	jabberwerx.JWBase.extend(prop, className) Provide classical inheritance to Javascript objects.
	getClassName() Get the class name of this object.
	graphUnserialized() A chance for recently-unserialized objects to do something and be assured that every object in the graph has run its custom post-serialization code.
	init() This method is called to initialize the JWBase-derived instance.
<static>	jabberwerx.JWBase.intercept(prop) Provide intercept support to Javascript objects.
	invocation(methodName, boundArguments) Subclasses can call this with one of their method names to get back a storable, portable, and invokable function object.
<static>	jabberwerx.JWBase.mixin(prop) Provide mixin support to Javascript objects.
	shouldBeSavedWithGraph() By default JW objects will not be saved with the object graph.
	shouldBeSerializedInline() By default JW objects will not be serialized inline from their references.
	toString() Returns the objects' classname, in brackets.
	wasUnserialized() A hook for objects to undo any custom serialization work done in #willBeSerialized.
	willBeSerialized() A hook for objects to prepare themselves for serialization.

Class Detail

jabberwerx.JWBase()

Creates a new jabberwerx.JWBase object.

Method Detail

destroy()

This method is offered as a way to release resources that were acquired by an object during its lifetime. However, as Javascript does not have any built-in way to trigger code when an object is about to be garbage-collected, or when a temporary/stack-based object goes out of scope, this method will have to be called by hand.

<static> jabberwerx.JWBase.extend(prop, className)

Provide classical inheritance to Javascript objects. Following John Resig's Class, http://ejohn.org/blog/simple-javascript-inheritance/ Inspired by base2 and Prototype One important addition to Resig's code: we provide a quasi-"copy constructor" that will take a bare javascript object with the data and classname of a JW object, and rehydrate it into a full object with prototype chain and object methods in place. Clients/sub-classes probably won't need to use it; it's used by jabberwerx.util.loadGraph. Within any object method, the superclass's version may be invoked via the variable named `_super`. Ex:

        MyClass = jabberwerx.JWBase.extend({
            init: function() {
                this._super()
            },
            someMethod: function() {
                doSomething();
            }
        }, 'MyClass');

        AnotherClass = MyClass.extend({ ... })

Parameters:
{Object} prop: The "subclass definition", an object with which to extend the parent class.
{String} className: The fully-qualified name of the class.

{String} getClassName()

Get the class name of this object.

Returns:: The fully-qualified name of the object's class.

graphUnserialized()

A chance for recently-unserialized objects to do something and be assured that every object in the graph has run its custom post-serialization code.

init()

This method is called to initialize the JWBase-derived instance.

<static> jabberwerx.JWBase.intercept(prop)

Provide intercept support to Javascript objects. This method applies all of the properties and methods from {prop} to this type. A copy of {prop} is made before it is applied, to ensure changes within this type do not impact the intercept definition.

NOTE: This method should not be called for jabberwerx.JWBase directly. Instead intercept a specific subclasses of jabberwerx.JWBase by adding new or overriding exisiting functions and properties.

Intercept functions are inserted into the top of the super class call stack, that is a intercept function's _super call will invoke the original, overridden method. Other properties are "overridden" by changing the property directly.

MyClass = jabberwerx.JWBase.extend({
       someProperty: "MyClass property"
       init: function() {
           this._super();  //calls JWBase.prototype.init
       },
       doSomething: function() {
           jabberwerx.util.debug.log("something is done");
       }
   }, "MyClass");
   AnIntercept = {
       someProperty: "AnIntercept property",
       doSomething: function() {
           jabberwerx.util.debug.log("preparing to do something");
           this._super(); //call MyClass.doSomething
           jabberwerx.util.debug.log("post something");
       }
   };

MyClass.intercept(AnIntercept);

Parameters:
{Object} prop: The intercept to include

{Function} invocation(methodName, boundArguments)

Subclasses can call this with one of their method names to get back a storable, portable, and invokable function object. The result can be passed to anything expecting a bare callback.

Parameters:
{String} methodName: The name of this object's method to wrap in an invocation object.
{Array} boundArguments Optional: Arguments can be bound to the eventual invocation of your object method here at the invocation creation. These arguments will **preceed** in the argument list any arguments that are passed to your method at the actual call site.

Returns:: A bare callback

See:: jabberwerx.util.generateInvocation

<static> jabberwerx.JWBase.mixin(prop)

Provide mixin support to Javascript objects. This method applies all of the properties and methods from {prop} to this type. A copy of {prop} is made before it is applied, to ensure changes within this type do not impact the mixin definition.

NOTE: This method should not be called for jabberwerx.JWBase directly. Instead, specific subclasses of jabberwerx.JWBase may use it to include new functionality.

Mixin properties are shadowed by the jabberwerx.JWBase class in the same way as super class properties are. In this case, the mixin is considered the super class, and any properties defined in the class override or shadow those with the same name in the mixin.

Mixin methods may be overridden by the jabberwerx.JWBase class in the same manner as super class methods are. In this case, the mixin's method is considered to be the "_super":

        AMixin = {
            someProperty: "property value",
            doSomething: function() {
                jabberwerx.util.debug.log("something is done");
            }
        };
        MyClass = jabberwerx.JWBase.extend({
            init: function() {
                this._super();  //calls JWBase.prototype.init
            },
            doSomething: function() {
                jabberwerx.util.debug.log("preparing to do something");
                this._super();  //calls AMixin.doSomething
                jabberwerx.util.debug.log("finished doing something");
            }
        }, "MyClass");

        MyClass.mixin(AMixin);

Parameters:
{Object} prop: The mixin to include

{Boolean} shouldBeSavedWithGraph()

By default JW objects will not be saved with the object graph. Subclasses can override this behavior by implementing this method and having it return true. The jabberwerx.JWModel class does this for you; in general, model objects are the only objects that should be saved in a persistent store.

Returns:: Whether this object should be saved with the object graph.

{Boolean} shouldBeSerializedInline()

By default JW objects will not be serialized inline from their references. Subclasses can override this behavior by implementing this method and having it return true.

Returns:: Whether this object should be serialized inline with its references.

{String} toString()

Returns the objects' classname, in brackets. Override if desired.

Returns:: A string representation of this object.

wasUnserialized()

A hook for objects to undo any custom serialization work done in #willBeSerialized. As with that method, there's no guarantee of the order in which objects will have this method invoked. When this method is invoked, every object in the graph will have been rehydrated into a fully-fleshed-out JW object, with data and prototype chain in place, but there is no guarantee that any other object will have had its `wasUnserialized` invoked.

willBeSerialized()

A hook for objects to prepare themselves for serialization. Subclasses should use this to do any custom serialization work. Typically this will involve serializing by hand any foreign (eg, non-JWModel-based) object references that will be necessary for the object's functioning when restored from serialization. It's important to note that there is no guarantee of the order in which objects will have this method invoked, relative to other objects in the graph. Basically, you can't depend on other object's `willBeSerialized` having been called or not called when you're in this method.

See:

Classes

Class jabberwerx.JWBase (MINIMAL)

Object Graph Client-Side Persistence

Object-Method Invocation Objects