Package
caplin.core

ClassUtility

Constructor Summary

Attributes Name and Description
caplin.core.ClassUtility()

Contains utility functions for working with classes.

Method Summary

Attributes Name and Description
<static> void delegate(Function fMyClass, Function fInterface, String sDelegateFieldName)

This method creates methods on the prototype of a class that delegate to an object that the class contains.

<static> Object getClass(String sClassName)

Converts a string that references a class on the global object to that class.

<static> Object getPackage(String sPackageName)

Converts a string that references a namespace on the global object into that namespace object.

Constructor Detail

caplin.core.ClassUtility()

Contains utility functions for working with classes.

Method Detail

<static> void delegate(Function fMyClass, Function fInterface, String sDelegateFieldName)

This method creates methods on the prototype of a class that delegate to an object that the class contains. It is useful when creating wrappers for classes.

Because this function adds methods to the prototype, if you replace the prototype after calling this method, you will lose all the delegated functions. For this reason, if you intend to call caplin.extends or caplin.implements, you should do so before calling this method.

After you have called this function, all methods from the interface will have been added to your class, but you can then modify any that you wish to have different behaviour.

Example:

// An interface I'm using for this example
function AnInterface() {}
AnInterface.prototype.sayHello = function() {};
AnInterface.prototype.sayGoodbye = function() {};

// The wrapper that uses delegate
function MyWrapper(wrappee) {
	if ( ! caplin.isImplementorOf(wrappee, AnInterface) ) {
		var Error = caplin.core.Error;
		throw new Error(Error.INVALID_PARAMETERS, "MyWrapper: wrappee must implement AnInterface.");
	}
	this.aWrappedClass = wrappee;
}
caplin.implement(MyWrapper, AnInterface);
caplin.core.ClassUtility.delegate(MyWrapper, AnInterface, 'aWrappedClass');
// Now all calls to sayHello or sayGoodbye on instances of MyWrapper are proxied on to this.aWrappedClass.

// If I wish to modify behaviour I can do it now:
MyWrapper.prototype.sayGoodbye = function() {
	this.aWrappedClass.sayGoodbye();
	console.log('or is it.....')
};
Obviously this example uses a simple interface, this method is more useful if there are many methods on the interface that you will wish to pass through to a wrapped object.

Since it's not possible for this function to do it for you, in the interests of failing fast, you may wish to check that the object you are wrapping is an instance of the intended interface before you assign it to the named field. Also, bear in mind that trying to call methods before it is assigned will cause errors. It's usually best practice to ensure that the wrapped object is passed into the constructor and this field is assigned to early.

This method should make it less painful to 'prefer composition over inheritance'.

Parameters
Function fMyClass the constructor of the class you want to delegate methods from. May not be null.
Function fInterface the interface that contains the methods you wish to delegate to. May not be null.
String sDelegateFieldName the name of the instance variable inside your class that contains the object you will delegate to. Must be a nonempty string.

<static> Object getClass(String sClassName)

Converts a string that references a class on the global object to that class.

e.g. to access the class caplin.core.Observable, you could call caplin.core.ClassUtility.getClass("caplin.core.Observable").

Parameters
String sClassName the fully qualified class name to be returned. e.g. caplin.core. May not be null
Returns
{Object} the package corresponding to the passed string. Will usually be a function.

<static> Object getPackage(String sPackageName)

Converts a string that references a namespace on the global object into that namespace object.

e.g. if there is the following global object in a browser: window.caplin = {core:{ test: {}}; then caplin.core.ClassUtility.getPackage("caplin.core.test") will return the innermost object.

Parameters
String sPackageName the fully qualified package name to be returned. e.g. caplin.core. May not be null
Returns
{Object} the package corresponding to the passed string.