This module provides host-independent functions for swarmlet hosts. A specific host (such as the Node.js host, the browser host, or the Ptolemy II host) can use this module to implement common functionality that is realizable in pure JavaScript.
Instantiating Accessors
Specifically, this module provides a constructor for instantiating accessors, and a convenience function (instantiateAccessor) that takes as an argument the fully qualified accessor class name, such as 'net/REST'.
For these functions to be able to instantiate an accessor given only its class name,
the host needs to provide as an argument to new Accessor() or
instantiateAccessor() a function, here designated getAccessorCode(), that
will retrieve the accessor source code given the class name. This cannot be done
in a host-independent way. For example, getAccessorCode('net/REST')
should return the JavaScript code defining the REST accessor.
This function must also be provided if the host is to support accessor
subclassing (extend()) or interface implementation (implement()).
The constructor and instantiate functions return an object that is an instance of an accessor. A specific host will typically use this by invoking the following instance's functions, perhaps in this order:
- setParameter(name, value): Set a parameter value.
- initialize(): Initialize the accessor.
- provideInput(name, value): Provide an input value.
- react() React to input values and fire the accessor.
- latestOutput(name): Retrieve an output value produced in react().
- wrapup(): Wrap up the accessor.
The react() function first invokes all input handlers that have been registered to handle provided inputs. It then invokes all input handlers that have been registered to handle any input. Finally, it invokes the fire() function of the accessor, if one is defined.
Events Emitted
An instantiated accessor is an event emitter that emits the following events:
- initialize: Emitted when the accessor has been initialized.
- output(name, value): Emitted when an output with the specified name and value are sent.
- reactStart Emitted when a reaction is starting.
- reactEnd: Emitted when the accessor has reacted.
- wrapup: Emitted when the accessor has wrapped up.
Extend and Implement
If a getAccessorCode() function is provided, then this implementation supports the extend() and implement() functions. An accessor A extends an accessor B if it includes in its setup() function a statement like:
this.extend(B);In this case, there will be two accessor instances created, one for A and one for B. Somewhat confusingly, A will be the prototype of B. This may seem backwards, but there is a good reason for it. B omits several key properties, such as its lists of inputs, outputs, and parameters. And thus, when the setup() function of B creates an input, that input becomes an input of A. Accessor A can reference the instance of B as A.ssuper. The exported functions of B are accessible via as A.ssuper.exports or A.exports.ssuper.
Accessor A implements accessor B if its setup function includes:
this.implement(B);This case is similar, in that A becomes the prototype of B, but the instance of B is not available to A. The only interaction between the two is that when the setup() function of B is invoked, it will again create inputs, outputs, and parameters in A rather than in its own instance.
If A extends B, then the exports property of B becomes the prototype of the exports property of A. This is the reverse of the prototype chain for the accessor instance itself. The reason for this is that B may define 'base-class' functions and properties that may or may not be overridden by A. These should be declared as exported properties. For example, if B has a property:
exports.foo = 10; Then A can refer to foo as exports.foo. A can also override the value of
foo by just writing to it.
Composite Accessors
If a getAccessorCode() function is provided, then this implementation supports composite accessors, which can instantiate other accessors (instantiate()) and connect them (connect()). That is, an accessor may be defined as a hierarchical composition of other accessors.
If C is a composite accessor and you invoke C.provideInput(name, value) to provide an input to C, the same input will be automatically provided to any contained accessor that is connected to the input with the specified name.
Moreover, if C does not provide its own fire() function, then a default fire() function will invoke react() on any contained accessors that are provided with an input. If those contained accessors produce outputs, those will be provided as inputs to any connected accessors and then those will react as well. Finally, a contained accessor may send an output to an output of C, in which case the composite accessor will produce an output.
The reactions of contained accessors in a composite will occur in topological sort order (upstream accessors are assured of reacting first). This ensures that reactions of a composite are deterministic. Specifically, suppose that A, B, and D are all accessors contained by a composite C. Suppose that the output of A goes to both B and D, and that the output of B also goes to D. Then B will always react before D, since it is upstream of D.
A composition of accessors can have cycles, but at least one output in any directed cycle must have the option 'spontaneous' set to 'true'. This means that the output is not immediately produced as a reaction to an input, but rather will be produced some time later as a consequence of a callback. If there is no such marked output, then the cycle is a causality loop. There is no way to determine the order in which accessors should react.
Mutable Accessors
Mutable accessors are a particular type of composite accessors. They have the ability to dynamically change their behavior by substituting a contained accessor X by another accessor X'. The Mutable accessor can be used as a placeholder where a designer can plug in a discovered accessor. In this version, the reification mechanism is quite open; very little checking is done for correctness.
When calling the 'reify' function on a particular accessor X, the Mutable Accessor will connect to X, making it equivalent to X itself. This is enabled by the composition mechanism. And this is done on runtime. If there is a previous reified accessor, it is unreified.
The choice of the accessor to be used for reification can be handled by another accessor or actor.
At any time, a previous reification can be removed. This will make the Mutable Accessor equivalent to an interface again. Consequently, another reification may be performed, enabling thus dynamic substitution.
Spontaneous Accessors
An accessor need not have any inputs. In this case, an invocation of react() will not invoke any input handlers (there cannot be any) and will only invoke the fire() function. Even with no fire() function, such an accessor can produce outputs if it sets up callbacks in its initialize() function, for example using setTimeout() or setInterval(). We call such an accessor a spontaneous accessor, because it spontaneously produces outputs without being triggered by any input.
A composite accessor can contain spontaneous accessors. When these produce outputs, the composite accessor will automatically react. Hence, the contained spontaneous accessor can trigger reactions of other contained accessors.
Overriding Function Bindings
A particular accessor host (such as the browser host or Node.js host) can provide an accessor instance with specific implementations of various functions that the accessor invokes. Such custom function bindings will override the defaults in this implementation. The most useful ones to override are probably these:
- require: The host's implementation of the require function. The default implementation throws an exception indicating that the host does not support any external modules.
- get: A function to retrieve the value of an input. The default implementation returns the the value specified by a provideInput() call, or if there has been no provideInput() call, then the value provided in the options argument of the this.input() call, or null if there is no value.
- getParameter: A function to retrieve the value of a parameter. The default implementation returns the the value specified by a this.setParameter() call, or if there has been no this.setParameter() call, then the value provided in the options argument of the this.parameter() call, or null if there is no value.
- send: A function to send an output. The default implementation produces the output using console.log().
- Version:
- $$Id$$
- Source:
- Version:
- $$Id$$
- Source:
Members
(inner) _accessorInstanceTable
Table of accessor instances indexed by their exports property. This allows us to retrieve the full accessor data structure, but to only expose to the user of this module the exports property of the accessor. Note that this host does not support removing accessors, so the instance will be around as long as the process exists.
(inner) _accessorInstanceTable
Table of accessor instances indexed by their exports property. This allows us to retrieve the full accessor data structure, but to only expose to the user of this module the exports property of the accessor. Note that this host does not support removing accessors, so the instance will be around as long as the process exists.
Methods
(inner) _recordEventEnd(event)
Callback to be executed upon listing to the event name end. This function is binded to the accessor's instance, when adding the listener.
Parameters:
| Name | Type | Description |
|---|---|---|
event |
Name of the listened event that ended |
(inner) _recordEventEnd(event)
Callback to be executed upon listing to the event name end. This function is binded to the accessor's instance, when adding the listener.
Parameters:
| Name | Type | Description |
|---|---|---|
event |
Name of the listened event that ended |
(inner) _recordEventStart(event)
Callback to be executed upon listening to the event's name start. This function is binded to the accessor's instance, when adding the listener.
Parameters:
| Name | Type | Description |
|---|---|---|
event |
Name of the listened event that started |
(inner) _recordEventStart(event)
Callback to be executed upon listening to the event's name start. This function is binded to the accessor's instance, when adding the listener.
Parameters:
| Name | Type | Description |
|---|---|---|
event |
Name of the listened event that started |
(inner) Accessor(accessorName, code, getAccessorCode, bindings, extendedBy, implementedBy)
Create (using new) an accessor instance whose interface and functionality is given by the specified code. This will evaluate the specified code, and if it exports a setup() function, invoke that function. The created object includes at least the following properties:
- accessorName: The name of the instance provided to the constructor.
- exports: An object that includes any properties that have have been explicitly added to the exports property in the specified code.
- inputList: An array of input names (see below).
- inputs: An object with one property per input (see below).
- outputList: An array of output names (see below).
- outputs: An object with one property per output (see below).
- parameterList: An array of parameter names (see below).
- parameters: An object with one property per parameter (see below).
- inputHandlers: An object indexed by input name with an array of input handlers, each of which is a function.
- anyInputHandlers: An array of input handlers to be invoked when any input arrives (the name argument of addInputHandler is null).
inputHandlersIndex: An object indexed by handler id (returned by this.addInputHandler()) that contains objects of the form {'name': nameOfInput, 'index': arrayIndexOfHandler}. This is used by this.removeInputHandler(). If the handler is one for any input, then nameOfInput is null and arrayIndexOfHandler specifies the position of the handler in the anyInputHandlers array.
Inputs, outputs, and parameters have a defined order. The
inputListproperty is an array giving the name of each input in the order in which it is defined in the setup() function. For each entry in that array, there is a property by that name in theinputsobject, indexed by the name. The value of that property is the options object given to theinput()function, possibly with additional properties such as 'destination', which is used for composite accessors. Similarly, parameters and outputs are represented in the data structure by an array of names and an object with the options values.The returned instance may also include the following properties:
accessorClass: The class name of the accessor, if not anonymous.
- containedAccessors: A list of contained accessors, if this is a composite accessor or a mutable Accessor.
- container: A reference to the containing accessor, if this instance is instantiated by a composite accessor.
- extendedBy: A reference to the accessor that this is extended by, if there is one.
- extending: A reference to the accessor that this extends, if it extends one.
- implementedInterfaces: An array of interfaces that this accessor implements.
- root: The root of the extend/implement tree. This is the accessor instance being invoked in a swarmlet, and each of the instances it extends or implements will reference it in their root property.
ssuper: If this accessor extends another, this is a reference to the instance of the accessor it extends.
If the returned instance is a mutable accessor, then it will include these additional properties:
- isMutable: set to true if the accessor is a mutable one.
- state: indicates the current state of the mutable accessor. It can be 'reified' or 'unreified'.
- inputsMap: An object that maps the mutable accessor inputs to the reifying accessor inputs.
- outputsMap: An object that maps the mutable accessor outputs to the reifying accessor outputs.
reifyingAccessor: reference to the reifying accessor among all possible contained accessors. Notes: (i) When a mutable accessor is reified, the attribute containedAccessors will contain the selected accessor for reification (ii) A mutable accessor cannot extend another accessor.
The bindings parameter provides function bindings for functions that are used by accessors. Any that are not provided will be provided with defaults. Any that are provided will override the defaults.
Parameters:
| Name | Type | Description |
|---|---|---|
accessorName |
A name to give to the accessor. |
|
code |
The accessor source code. |
|
getAccessorCode |
A function that will retrieve the source code of a specified accessor (used to implement the this.extend() and this.implement() functions), or null if the host does not support accessors that extend other accessors. |
|
bindings |
The functhis.emittion bindings to be used by the accessor. |
|
extendedBy |
An optional argument specifying what accessor is extending this new instance. Pass null or no argument if this accessor is not being extended. If this argument is present, then the getAccessorCode and bindings arguments are ignored (the instance inherits those properties from the extender). |
|
implementedBy |
An optional argument specifying what accessor is implementing this new instance. Pass null or no argument if this accessor is not being implemented. If this argument is present, then the getAccessorCode and bindings arguments are ignored (the instance inherits those properties from the implementer). |
(inner) Accessor(accessorName, code, getAccessorCode, bindings, extendedBy, implementedBy)
Create (using new) an accessor instance whose interface and functionality is given by the specified code. This will evaluate the specified code, and if it exports a setup() function, invoke that function. The created object includes at least the following properties:
- accessorName: The name of the instance provided to the constructor.
- exports: An object that includes any properties that have have been explicitly added to the exports property in the specified code.
- inputList: An array of input names (see below).
- inputs: An object with one property per input (see below).
- outputList: An array of output names (see below).
- outputs: An object with one property per output (see below).
- parameterList: An array of parameter names (see below).
- parameters: An object with one property per parameter (see below).
- inputHandlers: An object indexed by input name with an array of input handlers, each of which is a function.
- anyInputHandlers: An array of input handlers to be invoked when any input arrives (the name argument of addInputHandler is null).
inputHandlersIndex: An object indexed by handler id (returned by this.addInputHandler()) that contains objects of the form {'name': nameOfInput, 'index': arrayIndexOfHandler}. This is used by this.removeInputHandler(). If the handler is one for any input, then nameOfInput is null and arrayIndexOfHandler specifies the position of the handler in the anyInputHandlers array.
Inputs, outputs, and parameters have a defined order. The
inputListproperty is an array giving the name of each input in the order in which it is defined in the setup() function. For each entry in that array, there is a property by that name in theinputsobject, indexed by the name. The value of that property is the options object given to theinput()function, possibly with additional properties such as 'destination', which is used for composite accessors. Similarly, parameters and outputs are represented in the data structure by an array of names and an object with the options values.The returned instance may also include the following properties:
accessorClass: The class name of the accessor, if not anonymous.
- containedAccessors: A list of contained accessors, if this is a composite accessor or a mutable Accessor.
- container: A reference to the containing accessor, if this instance is instantiated by a composite accessor.
- extendedBy: A reference to the accessor that this is extended by, if there is one.
- extending: A reference to the accessor that this extends, if it extends one.
- implementedInterfaces: An array of interfaces that this accessor implements.
- root: The root of the extend/implement tree. This is the accessor instance being invoked in a swarmlet, and each of the instances it extends or implements will reference it in their root property.
ssuper: If this accessor extends another, this is a reference to the instance of the accessor it extends.
If the returned instance is a mutable accessor, then it will include these additional properties:
- isMutable: set to true if the accessor is a mutable one.
- state: indicates the current state of the mutable accessor. It can be 'reified' or 'unreified'.
- inputsMap: An object that maps the mutable accessor inputs to the reifying accessor inputs.
- outputsMap: An object that maps the mutable accessor outputs to the reifying accessor outputs.
reifyingAccessor: reference to the reifying accessor among all possible contained accessors. Notes: (i) When a mutable accessor is reified, the attribute containedAccessors will contain the selected accessor for reification (ii) A mutable accessor cannot extend another accessor.
The bindings parameter provides function bindings for functions that are used by accessors. Any that are not provided will be provided with defaults. Any that are provided will override the defaults.
Parameters:
| Name | Type | Description |
|---|---|---|
accessorName |
A name to give to the accessor. |
|
code |
The accessor source code. |
|
getAccessorCode |
A function that will retrieve the source code of a specified accessor (used to implement the this.extend() and this.implement() functions), or null if the host does not support accessors that extend other accessors. |
|
bindings |
The functhis.emittion bindings to be used by the accessor. |
|
extendedBy |
An optional argument specifying what accessor is extending this new instance. Pass null or no argument if this accessor is not being extended. If this argument is present, then the getAccessorCode and bindings arguments are ignored (the instance inherits those properties from the extender). |
|
implementedBy |
An optional argument specifying what accessor is implementing this new instance. Pass null or no argument if this accessor is not being implemented. If this argument is present, then the getAccessorCode and bindings arguments are ignored (the instance inherits those properties from the implementer). |
(inner) allowTrustedAccessors(allow)
If called with argument true, then accessors that are subsequently instantiated whose class name begins with 'trusted/' and accessors that have no class at all (they are given as custom script in the swarmlet definition) will have a binding for the getTopLevelAccessors() function. Such accessors can see and manipulate peer accessors, so a host that allows such trusted accessors should ensure that all trusted accessors are locally defined rather than downloaded from untrusted sources.
Parameters:
| Name | Type | Description |
|---|---|---|
allow |
True to allow trusted accessors, false otherwise. |
(inner) allowTrustedAccessors(allow)
If called with argument true, then accessors that are subsequently instantiated whose class name begins with 'trusted/' and accessors that have no class at all (they are given as custom script in the swarmlet definition) will have a binding for the getTopLevelAccessors() function. Such accessors can see and manipulate peer accessors, so a host that allows such trusted accessors should ensure that all trusted accessors are locally defined rather than downloaded from untrusted sources.
Parameters:
| Name | Type | Description |
|---|---|---|
allow |
True to allow trusted accessors, false otherwise. |
(inner) convertType(value, destination, name)
Convert the specified type to the type expected by the specified input, or throw an exception if no such conversion is possible.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
The value to convert. |
|
destination |
The destination object, which may have a type property. This is an input, parameter, or output options object. |
|
name |
The name of the input, output, or parameter (for error reporting). |
(inner) convertType(value, destination, name)
Convert the specified type to the type expected by the specified input, or throw an exception if no such conversion is possible.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
The value to convert. |
|
destination |
The destination object, which may have a type property. This is an input, parameter, or output options object. |
|
name |
The name of the input, output, or parameter (for error reporting). |
(inner) getHostName()
Return the name of this host.
Hosts are expected to override this function and return their own name.
Returns:
In commonHost.js, throw error. In other hosts, return the name of the host.
(inner) getHostName()
Return the name of this host.
Hosts are expected to override this function and return their own name.
Returns:
In commonHost.js, throw error. In other hosts, return the name of the host.
(inner) getTopLevelAccessors()
Return the top-level accessors that have been created thus far.
Returns:
an array that names the top level accessors that have been created thus far.
(inner) getTopLevelAccessors()
Return the top-level accessors that have been created thus far.
Returns:
an array that names the top level accessors that have been created thus far.
(inner) getTopLevelAccessorsNotSupported()
Throw an error indicating that getTopLevelAccessors is not supported.
(inner) getTopLevelAccessorsNotSupported()
Throw an error indicating that getTopLevelAccessors is not supported.
(inner) instantiateAccessor(accessorName, accessorClass, getAccessorCode, bindings, extendedBy, implementedBy)
Instantiate an accessor given its fully qualified class name, a function to retrieve the code, and bindings that include at least a require function to retrieve modules. The returned object will have a property accessorClass with the value of the class name parameter passed in here.
Parameters:
| Name | Type | Description |
|---|---|---|
accessorName |
A name to give to the accessor instance. |
|
accessorClass |
Fully qualified accessor class, e.g. 'net/REST'. |
|
getAccessorCode |
A function that will retrieve the source code of a specified accessor (used to implement the this.extend() and this.implement() functions), or null if the host does not support accessors that extend other accessors. |
|
bindings |
The function bindings to be used by the accessor. |
|
extendedBy |
An optional argument specifying what accessor is extending this new instance. Pass null or no argument if this accessor is not being extended. If this argument is present, then the getAccessorCode and bindings arguments are ignored (the instance inherits those properties from the extender). |
|
implementedBy |
An optional argument specifying what accessor is implementing this new instance. Pass null or no argument if this accessor is not being implemented. If this argument is present, then the getAccessorCode and bindings arguments are ignored (the instance inherits those properties from the implementer). |
(inner) instantiateAccessor(accessorName, accessorClass, getAccessorCode, bindings, extendedBy, implementedBy)
Instantiate an accessor given its fully qualified class name, a function to retrieve the code, and bindings that include at least a require function to retrieve modules. The returned object will have a property accessorClass with the value of the class name parameter passed in here.
Parameters:
| Name | Type | Description |
|---|---|---|
accessorName |
A name to give to the accessor instance. |
|
accessorClass |
Fully qualified accessor class, e.g. 'net/REST'. |
|
getAccessorCode |
A function that will retrieve the source code of a specified accessor (used to implement the this.extend() and this.implement() functions), or null if the host does not support accessors that extend other accessors. |
|
bindings |
The function bindings to be used by the accessor. |
|
extendedBy |
An optional argument specifying what accessor is extending this new instance. Pass null or no argument if this accessor is not being extended. If this argument is present, then the getAccessorCode and bindings arguments are ignored (the instance inherits those properties from the extender). |
|
implementedBy |
An optional argument specifying what accessor is implementing this new instance. Pass null or no argument if this accessor is not being implemented. If this argument is present, then the getAccessorCode and bindings arguments are ignored (the instance inherits those properties from the implementer). |
(inner) isReifiableBy(mutable, accessor)
Evaluates whether a mutable is reifiable by the accessor given as parameters. It is reifiable if: the set of accessor inputs are included in the set of mutable accessor' inputs. and the set of outputs of mutable accessor are included in the set of outputs of accessor. For port inclusion to hold, the following conditions are checked: Same port name If the ports contain an attribute called 'type', then they need to be checked for equality. FIXME: augment type checking with subtyping. FIXME: augment the function to accept interface names, urls, ontologies...
Parameters:
| Name | Type | Description |
|---|---|---|
mutable |
An instantiated Accessor that is mutable. |
|
accessor |
An instantiated Accessor object. |
Returns:
false if the mutable is not reifiable by the accessor, otherwise true.
(inner) isReifiableBy(mutable, accessor)
Evaluates whether a mutable is reifiable by the accessor given as parameters. It is reifiable if: the set of accessor inputs are included in the set of mutable accessor' inputs. and the set of outputs of mutable accessor are included in the set of outputs of accessor. For port inclusion to hold, the following conditions are checked: Same port name If the ports contain an attribute called 'type', then they need to be checked for equality. FIXME: augment type checking with subtyping. FIXME: augment the function to accept interface names, urls, ontologies...
Parameters:
| Name | Type | Description |
|---|---|---|
mutable |
An instantiated Accessor that is mutable. |
|
accessor |
An instantiated Accessor object. |
Returns:
false if the mutable is not reifiable by the accessor, otherwise true.
(inner) mergeObjects(first, second)
Merge the specified objects. If the two have common properties, the merged object will have the properties of the second argument. If the first argument is null, then the returned object will equal the second argument, unless it too is null, in which case the returned object will be an empty object.
Parameters:
| Name | Type | Description |
|---|---|---|
first |
The first argument, giving default properties. |
|
second |
The second argument. |
(inner) mergeObjects(first, second)
Merge the specified objects. If the two have common properties, the merged object will have the properties of the second argument. If the first argument is null, then the returned object will equal the second argument, unless it too is null, in which case the returned object will be an empty object.
Parameters:
| Name | Type | Description |
|---|---|---|
first |
The first argument, giving default properties. |
|
second |
The second argument. |
(inner) nullHandlerFunction()
Default empty function to use if the function argument to addInputHandler is null.
(inner) nullHandlerFunction()
Default empty function to use if the function argument to addInputHandler is null.
(inner) processCommandLineArguments(argv, fileReader, instantiateTopLevel, terminator)
Process command line arguments to instantiate and initialize accessors or to evaluate plain JavaScript within the context of an accessor host. This is provided here in commonHost so that all accessor hosts that provide a command-line usage have the same command-line argument structure.
This function takes up to four arguments, where only the first is required.
The first argument is an array of command-line arguments (as detailed below).
The second (optional) argument is a function that given a file name, returns the contents of the file as a string. The second argument is needed only if plain JavaScript files are to be evaluated using the -js command-line argument.
The third (optional) argument is an instantiate function that takes two arguments, an accessor name (an arbitrary string) and an accessor class name. This argument is needed only if accessors class names are given on the command line to instantiate and initialize.
The fourth (optional) argument is a callback function to invoke when either a specified timeout is reached (if a timeout is provided), or all instantiated accessors have wrapped up and all specified JavaScript files have been evaluated. This argument may, for example, cause the calling process to exit.
For example, if a host provides a executable command named 'host', then it might be invoked as follows:
> host -t 1000 -js fileName.js test/TestAccessorThe above command will evaluate the JavaScript in fileName.js, then instantiate the accessor with class name test/TestAccessor and initialize it, then wait one second and then call the terminate callback function. For the above command to work, this function has to be provided a fileReader argument to read fileName.js.
The order in which files and accessors are specified matters. They will be evaluated or instantiated and initialized in the order that they appear in the argument list.
The command-line arguments are file names, accessor class names (such as net/REST), or any of the following options:
-e|--e|-echo|--echo: Echo the command-line arguments. This is helpful for use under Ant apply.
-h|--h|-help|--help: Print a usage message.
-j|--j|-js|--js: Interpret the next argument as the name of a regular JavaScript file to evaluate.
-k|--k|-keepalive|--keepalive: Keep the calling process alive until either a timeout option expires or all instanted accessors have called wrapup.
-t|--t|-timeout|--timeout milliseconds: The maximum amount of time the script can run. When this time is reached, stop() is called on all accessors that have been instantiated, and then
-v|--v|-version|--version: Print out the version number
Parameters:
| Name | Type | Description |
|---|---|---|
argv |
An array of command-line arguments, see above. |
|
fileReader |
A function that, given a file name, returns its contents as a string. |
|
instantiateTopLevel |
A function that, given a name and class, instantiates a top-level accessor and returns it. |
|
terminator |
A callback function to invoke when all work is done. |
Returns:
True if any accessors were intantiated and initialized or if the keepalive option was specified. The caller can use the return value to indicate whether there is still work to be done, for example in active accessors. The caller may exit if the return value is false, since this indicates that all work is done.
(inner) processCommandLineArguments(argv, fileReader, instantiateTopLevel, terminator)
Process command line arguments to instantiate and initialize accessors or to evaluate plain JavaScript within the context of an accessor host. This is provided here in commonHost so that all accessor hosts that provide a command-line usage have the same command-line argument structure.
This function takes up to four arguments, where only the first is required.
The first argument is an array of command-line arguments (as detailed below).
The second (optional) argument is a function that given a file name, returns the contents of the file as a string. The second argument is needed only if plain JavaScript files are to be evaluated using the -js command-line argument.
The third (optional) argument is an instantiate function that takes two arguments, an accessor name (an arbitrary string) and an accessor class name. This argument is needed only if accessors class names are given on the command line to instantiate and initialize.
The fourth (optional) argument is a callback function to invoke when either a specified timeout is reached (if a timeout is provided), or all instantiated accessors have wrapped up and all specified JavaScript files have been evaluated. This argument may, for example, cause the calling process to exit.
For example, if a host provides a executable command named 'host', then it might be invoked as follows:
> host -t 1000 -js fileName.js test/TestAccessorThe above command will evaluate the JavaScript in fileName.js, then instantiate the accessor with class name test/TestAccessor and initialize it, then wait one second and then call the terminate callback function. For the above command to work, this function has to be provided a fileReader argument to read fileName.js.
The order in which files and accessors are specified matters. They will be evaluated or instantiated and initialized in the order that they appear in the argument list.
The command-line arguments are file names, accessor class names (such as net/REST), or any of the following options:
-e|--e|-echo|--echo: Echo the command-line arguments. This is helpful for use under Ant apply.
-h|--h|-help|--help: Print a usage message.
-j|--j|-js|--js: Interpret the next argument as the name of a regular JavaScript file to evaluate.
-k|--k|-keepalive|--keepalive: Keep the calling process alive until either a timeout option expires or all instanted accessors have called wrapup.
-t|--t|-timeout|--timeout milliseconds: The maximum amount of time the script can run. When this time is reached, stop() is called on all accessors that have been instantiated, and then
-v|--v|-version|--version: Print out the version number
Parameters:
| Name | Type | Description |
|---|---|---|
argv |
An array of command-line arguments, see above. |
|
fileReader |
A function that, given a file name, returns its contents as a string. |
|
instantiateTopLevel |
A function that, given a name and class, instantiates a top-level accessor and returns it. |
|
terminator |
A callback function to invoke when all work is done. |
Returns:
True if any accessors were intantiated and initialized or if the keepalive option was specified. The caller can use the return value to indicate whether there is still work to be done, for example in active accessors. The caller may exit if the return value is false, since this indicates that all work is done.
(inner) pushIfNotPresent(item, list)
Push the specified item onto the specified list if it is not already there.
Parameters:
| Name | Type | Description |
|---|---|---|
item |
Item to push.reifying |
|
list |
List onto which to push it. |
(inner) pushIfNotPresent(item, list)
Push the specified item onto the specified list if it is not already there.
Parameters:
| Name | Type | Description |
|---|---|---|
item |
Item to push.reifying |
|
list |
List onto which to push it. |
(inner) stopAllAccessors()
Stop execution by invoking wrapup() on all top-level accessors that have been initialized and not wrapped up.
(inner) stopAllAccessors()
Stop execution by invoking wrapup() on all top-level accessors that have been initialized and not wrapped up.
(inner) uniqueName()
Return a name that is unique in the specified container based on the specified seed. If no container is given, then return a name that is unique among top-level accessors. If the seed contains slashes, as in an accessor class name like net/REST, then everything before the last slash is removed. If the seed ends with an extension .js, then everything after and including the last period is removed. The remaining seed will be used as is if the name is unique. Otherwise, it will have a number, starting with 2, appended so as to ensure that it is unique.
(inner) uniqueName()
Return a name that is unique in the specified container based on the specified seed. If no container is given, then return a name that is unique among top-level accessors. If the seed contains slashes, as in an accessor class name like net/REST, then everything before the last slash is removed. If the seed ends with an extension .js, then everything after and including the last period is removed. The remaining seed will be used as is if the name is unique. Otherwise, it will have a number, starting with 2, appended so as to ensure that it is unique.