Programming API
- Functions
- this.genModule(moduleObject, callback)
- this.genModules(moduleObject, callback)
- this.genEntity(entityDefinition, callback)
- this.deleteEntity(apex, pid, callback)
- this.genPid()
- this.send(command, pid, callback)
- this.save(callback)
- this.getFile(module, filename, callback)
- this.require(module)
- this.exit(code)
- Logs
Functions
The xGraph platform offers a number of features to support the development of these fractal graph
architectures. In addition to the self-similar architecture defined by entities and modules, xGraph’s Nexus
provides programmers with a few special functions. These functions provide programmers with the ability to
communicate between entities and modules (or build relations), generate xGraph structures dynamically, and
save the current state of a system. All these functions exist in the this
context of every entity.
this.genModule(moduleObject, callback);
-and-
this.genModules(moduleObject, callback);
The genModule
function takes a module object and a callback function, starts the modules found in the
module object, and then calls the callback function.
The module object can be: Either a single module definition object
{
Module: "xGraph.Proxy",
Source: "Core",
Par: {
Role: "Client",
Host: "127.0.0.1",
Port: 25005,
Poll: true
}
}
Or an object of module definitions with descriptive keys
{
"Plexus": {
"Module": "xGraph.Plexus",
"Source": "xGraph",
"Par": {}
},
"Proxy": {
"Module": "xGraph.Proxy",
"Source": "xGraph",
"Par": {
"Link": "$Plexus",
"Role": "Server"
}
}
}
this.addModule(moduleName, moduleZip, callback);
The addModule
function allows you to add a module to the system by adding the module’s zip to the system’s
cache. To use this function, the --allow-add-module
flag must be set when running the system from the CLI.
addModule
takes the Zipped module file and inserts it into the system’s cache under the name of the module.
this.genEntity(entityDefinition, callback);
The genEntity
command takes an entity definition object and generates the entity in the module. An entity
can only be generated in the module that is making the call. When the function is complete, the callback is
returned with the pid of the generated entity in object.Pid.
The entity definition must have an "Entity"
key valued with the name of the entity being generated. The
entity must exists in the same module as the entity that is calling genEntity. For more information on
defining entities, see our Entity Guide.
Here is an example of an entity being generated. The Suite.js
entity is generated with a Setup and Start
command and no parameters.
let entity = {
"Entity": "Suite.js",
"$Setup": "SetupCommand",
"$Start": "StartCommand"
};
let callback = ((err, apx) => {
this.Vlt.gennedEntity = com.Pid = apx;
fun(null, com);
});
this.genEntity(entity, callback);
this.deleteEntity(apex, pid, callback);
The deleteEntity
function takes a module apex, an entity pid and a callback function and deletes the entity
from the module’s memory. If the entity pid is the module’s apex, then all the module’s entities are deleted.
this.genPid();
The genPid function does not accept any parameters and returns a 32 character hexadecimal pid.
this.send(command, pid, callback);
The special function that you will use most is the send
function. send
requires three parameters: a
command object, a destination pid, and a callback function. Send then sends the command object and the
callback function to the xGraph part (entity or module, depending on the fractal layer) specified in the Pid.
The command object must have a Cmd
key valued as the command that is being sent. The simplest commands look
like this:
{
"Cmd": "Ping"
}
Additionally, the command object is used to pass information from one node to another. Any number of key-value pairs can be added to the command object to handle information exchange. Here is a command with multiple parameters:
{
Cmd: "Subscribe",
Pid: this.Par.Pid,
Link: "2DView"
}
Pids are generated by Genesis when and xGraph system is compiled, and saved in references, typically in the
this.Par
object. These references are defined in a system’s structure object, typically a config.json file,
or a module’s structure object, a schema.json file.
Here is an example of a command being sent to a Pid
referenced in the entities parameter object,
this.Par
, and then calling a callback function.
var commandObject = {
Cmd: "OtherFunction",
someValue: 1
};
that.send(commandObject, that.Par.Friend, callback);
function callback(err,com){
log.i("----Recieved callback from Other, someValue is now: ", com.someValue);
commandObject.someValue = com.someValue;
log.i("--xGraph Repeats: [" + message.toString().trim() + "]");
log.i("HelloWorld is Listening... Type Something!");
}
this.save(callback);
The save
function takes only a callback function. The function saves the state of this entity, the entity
that called the function, including its current Par
and Vlt
, to the cache. If this entity is not an Apex,
the save message is sent to the Apex of this entity’s module. If it is an Apex, save the entity’s
information, as well as all other relevant information. When this is complete, the callback function is
called.
You can use this.send()
anytime to save an entity by simply using this.send(callback);
Here is an
example of an entity that saves itself on the Start
command:
function Start(com, fun) {
console.log('--Model/Start');
this.save();
if(fun)
fun();
}
this.getFile(module, filename, callback);
Get a file from the module.json module definition.
this.require(‘module’);
The require
function handles external dependencies in xGraph. Given a module name, require
loads the
given module, returning the module object. Often, you will want to save the module object in the entity’s
Vault, this.Vlt
.
Here, we load the sqlite3
dependency, check to see that it loaded properly, and then save sqlite3 module to
this.Vlt
with the key Sqlite3
.
let sqlite3 = this.require('sqlite3');
if (sqlite3 == null || sqlite3 == undefined) {
errors = "Unable to load sqlite3.";
}
Vlt.Sqlite3 = sqlite3;
this.exit(code);
The exit
function instructs nexus to exit with the code provided. Nexus will then stop all running xGraph
processes related to the system.
Logs
xGraph offers a suit of logging functions that enable logs to be printed or saved without losing information on the structure of your xGraph system. There are a variety of functions available to print logs, each with its own special functionality. Next we will look at the different log functions and how they might be used.
Info - log.i(string);
log.i
takes a string and prints it. It is meant for printing general statements and logs. These will be
printed and will be printed in turquoise.
Warning - log.w(string);
log.w
takes a string and prints it. It is meant for printing warning statements and logs. These will
typically be printed in white.
Error - log.e(string);
log.e
takes a string and prints it. It is meant for printing error statements and logs. These will
typically be printed in red.
Debug - log.d(string);
log.d
takes a string and prints it. It is meant for printing debug statements and logs. These will
typically be printed in fuchsia.
Verbose - log.v(string);
log.v
takes a string and prints it. It is meant for printing verbose statements, or statements that give
specific or detailed information. These will typically be printed in gray.