Skip to main content
Pentaho Documentation

ISpecifiable

pentaho.lang.ISpecifiable

The ISpecifiable interface represents the class of objects that can be described by a specification.

A specification is a minimal representation of the information required to build a typed object and all of its "owned" contents.

It can be used to create a copy of a typed object.

In most cases, a specification is a plain JavaScript object (plain, i.e., think "it was built with an object literal"). However, it can also be a non-object value, when a typed object can be wholly expressed as a number, boolean, string or function value.

To be clear, depending on a specification's contents, it may or may qualify as a JSON object.

The pentaho.lang.ISpecifiable#toSpec method creates a specification of a specifiable object.

Construction

Given a specification, a specifiable class must provide a way to construct instances from it.

A specification object (or any of its "owned" contents) can be used destructively, partially or totally, to construct a specifiable object.

This supports the memory-effective, one-time cast-construction pattern, where the prototype of existing objects is changed, by using Object.setPrototypeOf.

This also means that, without further knowledge, a specification can only be used to create a single copy of an object.

"Newable" constructors

By convention, in classes that have a constructor function that should be used with the new operator — has a "newable" constructor — the specification object is the first, optional or required, constructor argument.

The following example illustrates this type of constructor function.

function Foo(spec) {
   this.bar = (spec && spec.bar) || "bar";
   this.qux = (spec && spec.qux) || "qux";
}

Foo.prototype.toSpec = function() {
    return {
        bar: this.bar,
        qux: this.qux
    };
};

// Create a Foo instance
var foo1 = new Foo({bar: "a", qux: "b"});

// Obtain a specification of 

"Initialization" constructors

In classes whose constructor is an initialization function that should not, however, be called using new (not "newable"), a plain object's prototype should be set using Object.setPrototypeOf and the constructor called on the "morphed" object, afterwards. In these cases, it is also conventional for the constructor function to provide a static to method that performs the class "conversion".

The following example illustrates this type of constructor function.

function Foo() {
   if(!this.bar) this.bar = "bar";
   if(!this.qux) this.qux = "qux";
}

Foo.prototype.toSpec = function() {
    return {
        bar: this.bar,
        qux: this.qux
    };
};

Foo.to = function(spec) {
    if(spec instanceof Foo) return spec;

    Object.setPrototypeOf(spec, Foo);
    Foo.call(spec);
    return spec;
};

// Convert to a Foo instance
var foo1 = Foo.to({bar: "a", qux: "b"});

Source: doc-js/pentaho/lang/ISpecifiable.jsdoc, line 17

Methods

Name Description
toSpec(keyArgs) : *

Creates a specification of this object.

Methods Details

toSpec(keyArgs) : *

Creates a specification of this object.

Specific classes can support optional keyword arguments.

Source: doc-js/pentaho/lang/ISpecifiable.jsdoc, line 133

Parameters:
Name Default Value Summary
keyArgs : Object
 
Optional

The keyword arguments.

Returns:
Name Description
*

A new specification of the object.