Granada  1.54.0
Structured layer on top of C++ REST SDK for building server applications in C++. Granada implements sessions, server side plug-in framework, C++ OAuth 2.0 server, data storage access, server script running, server browsing.
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes | List of all members
granada::plugin::PluginHandler Class Reference

#include <plugin.h>

Inheritance diagram for granada::plugin::PluginHandler:
granada::plugin::SpidermonkeyPluginHandler granada::plugin::MapSpidermonkeyPluginHandler granada::plugin::RedisSpidermonkeyPluginHandler

Public Member Functions

 PluginHandler ()
 
 PluginHandler (const std::string id)
 
virtual ~PluginHandler ()
 
virtual const std::string & GetId ()
 
virtual bool Exists ()
 
virtual web::json::value Init (const std::vector< std::string > &paths)
 
virtual void Stop ()
 
virtual void Reset ()
 
virtual bool AddPluginLoader (web::json::value &header, const std::string &configuration, const std::string &script)
 
virtual void RemovePluginLoader (const std::string &plugin_id)
 
virtual void AddLoadEvent (const std::string &event_name, const std::string &plugin_id, const web::json::value &plugin_loader)
 
virtual void AddLoadEvent (const std::string &plugin_id, const web::json::value &header)
 
virtual void RemoveLoadEvent (const std::string &event_name)
 
virtual bool Add (const std::string &header, const std::string &configuration, const std::string &script)
 
virtual bool Add (web::json::value &header, const web::json::value &configuration, const std::string &script)
 
virtual bool Add (granada::plugin::Plugin *plugin)
 
virtual bool Add (granada::plugin::Plugin *plugin, web::json::value &parameters)
 
virtual void Extend (granada::plugin::Plugin *plugin)
 
virtual void Extend (granada::plugin::Plugin *extended_plugin, granada::plugin::Plugin *plugin)
 
virtual void Extend (const web::json::array &extended_plugins_ids, granada::plugin::Plugin *plugin)
 
virtual void AddExtension (const std::string &extended_plugin_id, const std::string &plugin_id)
 
virtual bool ApplyExtensions (granada::plugin::Plugin *plugin)
 
virtual void RemoveExtension (const std::string &extended_plugin_id, const std::string &plugin_id)
 
virtual void RemoveExtensions (const std::string &plugin_id)
 
virtual void AddEventListener (const std::string &event_name, const std::string &plugin_id)
 
virtual void RemoveEventListener (const std::string &event_name, const std::string &plugin_id)
 
virtual void RemoveEventListeners (const std::string &plugin_id)
 
virtual void RemoveEventListeners (granada::plugin::Plugin *plugin)
 
virtual web::json::value RemoveEventListeners (const web::json::value &parameters)
 
virtual std::unique_ptr
< granada::plugin::Plugin
GetPluginById (const std::string &plugin_id)
 
virtual void Run (const std::string &plugin_id, web::json::value &parameters, function_void_json success, function_void_json failure)
 
virtual void Run (const std::string &plugin_id, web::json::value &parameters, const std::string &event_name, function_void_json success, function_void_json failure)
 
virtual void Run (granada::plugin::Plugin *plugin, web::json::value &parameters, const std::string &event_name, function_void_json success, function_void_json failure)
 
virtual web::json::value Run (const std::vector< std::string > &plugin_ids, const std::string &event_name, web::json::value &parameters)
 
virtual web::json::value Run (const web::json::value &parameters)
 
virtual void Remove (const std::string &plugin_id)
 
virtual web::json::value Remove (const web::json::value &parameters)
 
virtual void Fire (const std::string &event_name)
 
virtual void Fire (const std::string &event_name, web::json::value &parameters)
 
virtual void Fire (const std::string &event_name, web::json::value &parameters, function_void_json success, function_void_json failure)
 
virtual web::json::value Fire (const web::json::value &parameters)
 
virtual web::json::value SendMessage (const std::string &from, const web::json::value &to_ids, const web::json::value &message)
 
virtual web::json::value SendMessage (const std::string &from, const std::vector< std::string > &to_ids, const web::json::value &message)
 
virtual web::json::value SendMessage (const web::json::value &parameters)
 
virtual web::json::value SetValue (const web::json::value &parameters)
 
virtual web::json::value GetValue (const web::json::value &parameters)
 
virtual web::json::value DestroyValue (const web::json::value &parameters)
 
virtual web::json::value ClearValues (const web::json::value &parameters)
 
virtual void RunnerLock ()
 
virtual
granada::cache::CacheHandler
cache ()
 
virtual
granada::plugin::PluginFactory
plugin_factory ()
 
virtual granada::runner::Runnerrunner ()
 
virtual std::string plugin_handler_value_hash ()
 
virtual std::string plugin_loader_value_hash (const std::string &plugin_id)
 
virtual std::string plugin_value_hash (const std::string &plugin_id)
 
virtual std::string plugin_store_hash (const std::string &plugin_handler_id, const std::string &plugin_id)
 
virtual std::string plugin_event_value_hash (const std::string &event_name)
 

Protected Member Functions

virtual void LoadProperties ()
 
virtual std::string GetUID ()
 
virtual int PreloadRepositories ()
 
virtual int PreloadPackages (const std::string &repository_path)
 
virtual int PreloadPackagedPlugins (const std::string &package_directory_path)
 
virtual void FireLoadEvent (const std::string &event_name)
 
virtual bool Load (granada::plugin::Plugin *plugin, const web::json::value &loader)
 
virtual std::string TransformPluginScriptPath (const std::string &plugin_script_path)
 
virtual std::string TransformPluginConfigurationPath (const std::string &plugin_configuration_path)
 
virtual void AddFunctionsToRunner ()
 

Protected Attributes

std::string id_
 
std::vector< std::string > paths_
 

Static Protected Attributes

static int PLUGIN_BYTES_LIMIT_
 
static int SEND_MESSAGE_PLUGIN_GROUP_SIZE_
 
static int RUNNER_USE_FREQUENCY_LIMIT_
 
static std::once_flag properties_flag_
 
static std::once_flag functions_to_runner_flag_
 
static unsigned long long uid_
 
static std::mutex uid_mtx_
 

Detailed Description

Plugin Handler: Handles the lifecycle and communication of server side plugins. Manages plug-ins lifecycle: Loads and adds plug-ins, runs plug-ins and removes them. This is an abstract class that can't work on its own. Cache and Plug-in Factory need to be overridden.

Use example:

// creating a plug-in that multiplies a number by a pre-configured factor.
// create header
// {"id":"product.tax","events":["calculate-tax","save-product-before"],"extends":["math.multiplication"]}
web::json::value header = web::json::value::parse("{\"id\":\"product.tax\",\"events\":[\"calculate-tax\",\"save-product-before\"],\"extends\":[\"math.multiplication\"]}");
// create configuration
// {"USTaxFactor":{"value":0.07,"editor":"number-2-decimal"},"FRTaxFactor":{"value":0.18,"editor":"number-2-decimal"}}
web::json::value header = web::json::value::parse("{\"USTaxFactor\":{\"value\":0.07,\"editor\":\"number-2-decimal\"},\"FRTaxFactor\":{\"value\":0.20,\"editor\":\"number-2-decimal\"}}");
// script -----------------------
std::string script = "{
run : function(parameters){
var me = this;
var result = -1;
var configuration = getConfiguration();
// default tax factor
var taxFactor = null;
if (parameters["currency"] && configuration["taxFactor"] && configuration["USTaxFactor"]["value"]){
if (parameters["currency"] == "EUR"){
taxFactor = configuration["FRTaxFactor"]["value"];
}else{
taxFactor = configuration["USTaxFactor"]["value"];
}
}else{
taxFactor = 0.07;
}
if (parameters["price"] && taxFactor){
parameters["price"] = me.multiplication(parameters["price"],taxFactor);
}
return parameters;
}
}";
// end script --------------------------
// Adding the plug-in
plugin_handler->Add(header,configuration,script);
// Running the plug-in, 2 options
// 1) Firing an event:
web::json::value parameters = web::json::value::parse("{\"price\":24,\"currency\":\"USD\"}");
plugin_handler->Fire("save-product-before",parameters,[=](const web::json::value& data){
// success callback.
},[=](const web::json::value& data){
// error callback
});
// 2) Retrieving the plug-in by its id:
std::shared_ptr<granada::plugin::Plugin> plugin = plugin_handler->GetPluginById("product.tax");
web::json::value parameters = web::json::value::parse("{\"price\":24,\"currency\":\"USD\"}");
plugin->Run(parameters,[=](const web::json::value& data){
// success callback.
},[=](const web::json::value& data){
// error callback
});

Constructor & Destructor Documentation

granada::plugin::PluginHandler::PluginHandler ( )
inline

Constructor. Plug-in handler without an id. Load Plug-in Handler properties.

granada::plugin::PluginHandler::PluginHandler ( const std::string  id)
inline

Constructor. Assigns an id to the plug-in handler. Load Plug-in Handler properties.

Parameters
idUnique Identifier of the PluginHandler.
virtual granada::plugin::PluginHandler::~PluginHandler ( )
inlinevirtual

Destructor.

Member Function Documentation

virtual bool granada::plugin::PluginHandler::Add ( const std::string &  header,
const std::string &  configuration,
const std::string &  script 
)
virtual

Adds a plug-in.

Parameters
headerStringified JSON containing the information about when the plug-in's events, id, inheritance. Example:
{
"id" : "math.multiplication",
"events" : ["calculate"],
"extends" : ["math.calculus"]
}
configurationStringified JSON containing the values for configuring of the plug-in. Example:
{
"mainContainerId" : {
"value" : "demo-container",
"editor" : "text"
}
}
scriptScript/Executable to be run (or the path to the script/executable).
Returns
True if plug-in has been added correctly, false if it has not.
virtual bool granada::plugin::PluginHandler::Add ( web::json::value &  header,
const web::json::value &  configuration,
const std::string &  script 
)
virtual

Adds a plug-in.

Parameters
headerJSON containing the information about when the plug-in's events, id, inheritance. Example:
{
"id" : "math.multiplication",
"events" : ["calculate"],
"extends" : ["math.calculus"]
}
configurationJSON containing the values for configuring of the plug-in. Example:
{
"mainContainerId" : {
"value" : "demo-container",
"editor" : "text"
}
}
scriptScript/Executable to be run (or the path to the script/executable).
Returns
True if plug-in has been added correctly, false if it has not.
virtual bool granada::plugin::PluginHandler::Add ( granada::plugin::Plugin plugin)
virtual

Adds a plug-in.

Parameters
pluginPlug-in to add.
Returns
True if plug-in has been added correctly, false if it has not.
virtual bool granada::plugin::PluginHandler::Add ( granada::plugin::Plugin plugin,
web::json::value &  parameters 
)
virtual

Adds a plug-in with parameters to pass to the plug-in in case it is executed just after adding it, this happens for example if the plug-in header does not have an "events" field. This is done specifying if the plug-in can be run immediately or not.

Parameters
pluginPlug-in to add.
parametersParameters, useful in case we add a plug-in and it is executed just after adding it.
Returns
True if plug-in has been added correctly, false if it has not.
virtual void granada::plugin::PluginHandler::AddEventListener ( const std::string &  event_name,
const std::string &  plugin_id 
)
virtual

Makes a plug-in listen to an event so it runs when the event is fired.

Parameters
event_nameName of the event.
plugin_idId of the plug-in.
virtual void granada::plugin::PluginHandler::AddExtension ( const std::string &  extended_plugin_id,
const std::string &  plugin_id 
)
virtual

Adds an extension to a plug-in, so when the plug-in is added it is extended. Notice that after extending a plug-in, the extended plug-in is no more active.

Parameters
extended_plugin_idId of the plug-in to extend.
plugin_idId of the extension.
virtual void granada::plugin::PluginHandler::AddFunctionsToRunner ( )
protectedvirtual

Adds the functions that can be called from the plug-ins when they are running. Call it once as runner is static.

virtual void granada::plugin::PluginHandler::AddLoadEvent ( const std::string &  event_name,
const std::string &  plugin_id,
const web::json::value &  plugin_loader 
)
virtual

Associates a plug-in loader to one event, the plug-in will be loaded when the event is fired.

Parameters
event_nameEvent name
plugin_idId of the plug-in.
plugin_loaderPlug-in loader, preferences for plug-in load. Loader Examples:
{}
=> plug-in will be loaded when the event is fired.
{"load":"eager"}
=> plug-in will be loaded now.
{"events":["calculate-square","calculate"]}
=> plug-in will be loaded the first time "calculate-square"
or "calculate" event is fired.
virtual void granada::plugin::PluginHandler::AddLoadEvent ( const std::string &  plugin_id,
const web::json::value &  header 
)
virtual

Associates a plug-in loader contained in the header "loader" field to one or more events contained in the loader "events" field. If the loader "events" field does not exists, header "events" field will be taken instead, if none of them exist, plug-in will be loader on "ph-init-after" (After Plug-in Handler initialization) event.

Parameters
plugin_idId of the plug-in.
headerPlug-in header containing the loader. Header Examples:
{}
=> plug-in will be loaded when the event "ph-init-after" is fired.
{"loader":{"load":"eager"}}
=> plug-in will be loaded now.
{"loader":{"events":["calculate-square","calculate"]}}
=> plug-in will be loaded the first time "calculate-square"
or "calculate" event is fired.
{"events":["calculate-square","calculate"],"loader":{}}
=> plug-in will be loaded the first time "calculate-square"
or "calculate" event is fired.
virtual bool granada::plugin::PluginHandler::AddPluginLoader ( web::json::value &  header,
const std::string &  configuration,
const std::string &  script 
)
virtual

Caches the plug-in loading information so it is faster to load it when needed. Caches information as the paths of the scripts/executable, the path of the plug-ins configurations files, the plug-in header and the plug-in loading options. We can also cache the script and the configuration directly, not only their paths, but it can harm performance, and we might be caching more data than needed if the plug-in finally is never needed. For doing so override TransformPluginScriptPath and TransformPluginConfigurationPath functions so they return the script and the configuration JSON, not the paths of the files.

Parameters
headerJSON containing the information about when the plug-in's events, id, inheritance, loader. Header Example:
{
"id" : "math.multiplication",
"events" : ["calculate"],
"extends" : ["math.calculus"],
"loader" : {"events":["calculate-square","calculate"]}
}
=> Looking at this example, plug-in will be loaded the first
time "calculate-square" or "calculate" events are fired. If
the events are never fired, the plug-in will never load.
configurationJSON containing the values for configuring of the plug-in. Configuration Example:
{
"mainContainerId" : {
"value" : "demo-container",
"editor" : "text"
}
}
scriptScript/Executable to be run (or the path to the script/executable).
Returns
True if plug-in successfully preloaded, false if not.
virtual bool granada::plugin::PluginHandler::ApplyExtensions ( granada::plugin::Plugin plugin)
virtual

If a plug-in is extended by other already added plug-ins extends it and returns true. Otherwise returns false.

Returns
bool True if plug-in has been extended, false if not.
virtual granada::cache::CacheHandler* granada::plugin::PluginHandler::cache ( )
inlinevirtual

Returns a pointer to the Cache Handler. Used to cache plug-ins headers, loaders, configuration and script paths as well as plug-ins global values. Needs to be overridden.

Returns
Pointer to the Cache Handler.

Reimplemented in granada::plugin::MapSpidermonkeyPluginHandler, and granada::plugin::RedisSpidermonkeyPluginHandler.

virtual web::json::value granada::plugin::PluginHandler::ClearValues ( const web::json::value &  parameters)
virtual

Plug-in function: This function can be called from the plug-in script. It destroys all values previously stored by the plug-in. Recommended wrap function in a script: clearValues();

Parameters
parametersJSON with the plug-in id and the Plug-in Handler id. Example:
{
"__PLUGIN_ID" : "math.multiplication",
"__PLUGIN_HANDLER_ID" : "WjdTAXePkQH7UtAWqwdy4v0qtOhFZwLn73tXHsiBn0i9BDAoH0A6WIz9ovtF3AqY"
}
Returns
An empty JSON object {} is returned if the key-value pairs are destroyed correctly, and a JSON object with an error code and an error_description if there was a problem when destroying the key-value pairs. Example of returned JSON when there is an error:
{
"error" : "missing_parameter",
"error_description" : "One or more of the given parameters is missing."
}
virtual web::json::value granada::plugin::PluginHandler::DestroyValue ( const web::json::value &  parameters)
virtual

Plug-in function: This function can be called from the plug-in script. It destroys a value previously stored by the plug-in. Recommended wrap function in a script: destroyValue("number");

Parameters
parametersJSON with the plug-in id, the Plug-in Handler id and the key of the value to destroy. Example:
{
"key" : "number",
"__PLUGIN_ID" : "math.multiplication",
"__PLUGIN_HANDLER_ID" : "WjdTAXePkQH7UtAWqwdy4v0qtOhFZwLn73tXHsiBn0i9BDAoH0A6WIz9ovtF3AqY"
}
Returns
An empty JSON object {} is returned if the key-value pair is destroyed correctly, and a JSON object with an error code and an error_description if there was a problem when destroying the key-value pair. Example of returned JSON when there is an error:
{
"error" : "missing_parameter",
"error_description" : "One or more of the given parameters is missing."
}
virtual bool granada::plugin::PluginHandler::Exists ( )
virtual

Returns true if the PluginHandler exists, stored in the cache. Used to know if the Plug-in Handler has been initialized or not.

Returns
True if the PluginHandler is stored in the cache. False if it is not stored in the cache.
virtual void granada::plugin::PluginHandler::Extend ( granada::plugin::Plugin plugin)
virtual

Extends other plug-ins indicated in the "extends" field contained in the plug-in header. Example of header extends field:

"extends":["math.calculus"]

If this method is called, the plug-in will extend "math.calculus" plug-in, this means that plug-in will integrate the extended plug-in members that it does not override. Both plug-in "extends" members are concatenated.

Parameters
pluginPointer to the plug-in that is going to extend other plug-ins.
virtual void granada::plugin::PluginHandler::Extend ( granada::plugin::Plugin extended_plugin,
granada::plugin::Plugin plugin 
)
virtual

Extends only one plug-in. If this method is called, the "plugin" will extend "extended_plugin", this means that "plugin" will integrate the "extended_plugin" members that it does not override. Both plug-in "extends" members are concatenated.

Parameters
extended_pluginPointer to the plug-in that is going to be extended.
pluginPointer to the plug-in that is going to extend other plug-ins.
virtual void granada::plugin::PluginHandler::Extend ( const web::json::array &  extended_plugins_ids,
granada::plugin::Plugin plugin 
)
inlinevirtual

Cross Extends plug-ins. If this method is called, the "plugin" will extend "extended_plugins", this means that "plugin" will integrate the "extended_plugins" members that it does not override. Both plug-in "extends" members are concatenated.

Parameters
extended_plugins_idsJSON array with the ids of the plug-ins that are going to be extended.
pluginPointer to the plug-in that is going to extend other plug-ins.

Reimplemented in granada::plugin::SpidermonkeyPluginHandler.

virtual void granada::plugin::PluginHandler::Fire ( const std::string &  event_name)
virtual

Called to fire an event. All plug-ins listening to that event will be run.

Parameters
event_nameName of the event. Example: "entry-created-before".
virtual void granada::plugin::PluginHandler::Fire ( const std::string &  event_name,
web::json::value &  parameters 
)
virtual

Called to fire an event. All plug-ins listening to that event will run.

Parameters
event_nameName of the event.
parametersParameters in form of JSON object that are passed to the plug-ins. that listen to the event. Example:
{"number":"9285","factor1":"9285","factor2":"4",addend1":"9285","addend2":"25"}
virtual void granada::plugin::PluginHandler::Fire ( const std::string &  event_name,
web::json::value &  parameters,
function_void_json  success,
function_void_json  failure 
)
virtual

Called to fire an event. All plug-ins listening to that event will run.

Parameters
event_nameName of the event.
parametersParameters in form of JSON object that are passed to the plug-ins. that listen to the event. Example: {"number":"9285","factor1":"9285","factor2":"4",addend1":"9285","addend2":"25"}
successCallback function called when the plug-ins successfully run passing the plug-ins responses in form of a JSON object:
{
"data" :
{
"math.sum" : {"data":{"response":9310}},
"math.multiplication" : {"data":{"response":37140}}
}
}
If there was an error in one of the plug-ins:
{
"data" :
{
"math.sum" : {"data":{"response":9310}},
"math.multiplication" : {"error":"undefined_plugin", "error_description":"Plug-in could not be found with given plug-in id."}
}
}
failureCallback function called when there is a problem running plug-ins with the error code and error description.

Reimplemented in granada::plugin::SpidermonkeyPluginHandler.

virtual web::json::value granada::plugin::PluginHandler::Fire ( const web::json::value &  parameters)
virtual

Plug-in function: This function can be called from the plug-in script. It fires an event. All the plug-ins listening to the event will be run. Recommended wrap function in a script:

fire("math.multiplication-before",
{"number":"9285","factor1":"9285","factor2":"4"},
function(successResponseData){
// success
},dunction(failureResposeData){
// failure
});
Parameters
parametersJSON with the Plug-in Handler id, the event to fire and the parameters to pass to the plug-ins listening to the fired event. Example:
{
"event_name" : "math.multiplication-before",
"data" : {"number":"9285","factor1":"9285","factor2":"4"},
"__PLUGIN_ID" : "math.multiplication",
"__PLUGIN_HANDLER_ID" : "WjdTAXePkQH7UtAWqwdy4v0qtOhFZwLn73tXHsiBn0i9BDAoH0A6WIz9ovtF3AqY"
}
Returns
A JSON object with the plug-ins responses. Examples:
{
"data" :
{
"math.multiplication.check.range" : {"data":{"valid":true,"number":"9285","factor1":"9285","factor2":"4"}},
}
}
If there was an error in one of the plug-ins:
{
"data" :
{
"math.multiplication.check.range" : {"error":"undefined_plugin", "error_description":"Plug-in could not be found with given plug-in id."}
}
}
virtual void granada::plugin::PluginHandler::FireLoadEvent ( const std::string &  event_name)
protectedvirtual

Executes all plug-in loaders listening to an event if there are, loading the plug-ins.

Parameters
event_nameName of the event.
virtual const std::string& granada::plugin::PluginHandler::GetId ( )
inlinevirtual

Returns the plug-in hanler id.

Returns
Plug-in Handler id.
virtual std::unique_ptr<granada::plugin::Plugin> granada::plugin::PluginHandler::GetPluginById ( const std::string &  plugin_id)
virtual

Returns a pointer of a server plug-in managed by the plug-in handler with the given plug-in id.

Parameters
plugin_idPlugin id.
Returns
Plugin pointer.
virtual std::string granada::plugin::PluginHandler::GetUID ( )
protectedvirtual

Get a unique id string, used to give ids to plug-ins that don't have an id.

Returns
Unique id string
virtual web::json::value granada::plugin::PluginHandler::GetValue ( const web::json::value &  parameters)
virtual

Plug-in function: This function can be called from the plug-in script. It retrieves a value previously stored by the plug-in. Used to retrieve plug-in global variables. If value does not exists returns an empty value. Recommended wrap function in script: var number = getValue("number");

Parameters
parametersJSON with the plug-in id, the Plug-in Handler id and the key of the value to retrieve. Example:
{
"key" : "number",
"__PLUGIN_ID" : "math.multiplication",
"__PLUGIN_HANDLER_ID" : "WjdTAXePkQH7UtAWqwdy4v0qtOhFZwLn73tXHsiBn0i9BDAoH0A6WIz9ovtF3AqY"
}
Returns
A JSON object with the requested value or a JSON object with an error message, in case the value couldn't be retrieved successfully. Example:
{"value":"8"} => value successfully retrieved.
{
"error" : "missing_parameter",
"error_description" : "One or more of the given parameters is missing."
} => error retrieving value.
{"value": ""} => value does not exists, but no error.
virtual web::json::value granada::plugin::PluginHandler::Init ( const std::vector< std::string > &  paths)
virtual

Initializes the Plug-in Handler, loads all plug-ins so they are ready to be run.

Parameters
pathsPaths of the repositories where the packaged plug-ins are.
Returns
JSON object with the response to the "ph-init-after" event firing, may contain an error, for example in case of exceeding byte limit. Examples:
{}
=> everyting went OK.
{
"error" : "bytes_limit_exceeded".
"error_description" : "Plug-in Handler could not preload all plug-ins, because they exceed the byte limit. This limit is set for server security reasons. Contact the administrator if you need to increase the limit."
}
virtual bool granada::plugin::PluginHandler::Load ( granada::plugin::Plugin plugin,
const web::json::value &  loader 
)
inlineprotectedvirtual

Loads a plug-in, and returns true if plug-in loaded successfully, false if not. This function is normally called by the Plug-in Handler when the event loader of the plug-in is fired. Can be also called to force the plug-in load

Parameters
pluginPointer to the plug-in to load.
loaderPlug-in loader. JSON object containing the information about how to load a plug-in. Example:
{
"events" : ["init-ph-after"]
}
Returns
True if plug-in loaded successfully, false if not.

Reimplemented in granada::plugin::SpidermonkeyPluginHandler.

virtual void granada::plugin::PluginHandler::LoadProperties ( )
protectedvirtual

Load Plug-in Handler properties.

virtual std::string granada::plugin::PluginHandler::plugin_event_value_hash ( const std::string &  event_name)
inlinevirtual

Return the hash used to store the events in the cache.

Returns
Hash used to store the events in the cache.
virtual granada::plugin::PluginFactory* granada::plugin::PluginHandler::plugin_factory ( )
inlinevirtual

Returns a pointer to a Plug-in Factory. Used to create PluginHandlers and Plugins.

Returns
Pointer to a plug-in Factory.

Reimplemented in granada::plugin::MapSpidermonkeyPluginHandler, and granada::plugin::RedisSpidermonkeyPluginHandler.

virtual std::string granada::plugin::PluginHandler::plugin_handler_value_hash ( )
inlinevirtual

Return the hash used to store the Plug-in Handler values in the cache.

Returns
Hash used to store the Plug-in Handler values in the cache.
virtual std::string granada::plugin::PluginHandler::plugin_loader_value_hash ( const std::string &  plugin_id)
inlinevirtual

Return the hash used to store the Plug-in loaders in the cache.

Returns
Hash used to store the Plug-in loaders in the cache.
virtual std::string granada::plugin::PluginHandler::plugin_store_hash ( const std::string &  plugin_handler_id,
const std::string &  plugin_id 
)
inlinevirtual

Return the hash used to store the Plug-in variables values in the cache.

Returns
Hash used to store the Plug-in variables values in the cache.
virtual std::string granada::plugin::PluginHandler::plugin_value_hash ( const std::string &  plugin_id)
inlinevirtual

Return the hash used to store the Plug-in values in the cache.

Returns
Hash used to store the Plug-in values in the cache.
virtual int granada::plugin::PluginHandler::PreloadPackagedPlugins ( const std::string &  package_directory_path)
protectedvirtual

Preload the packaged plug-ins of one given package, so it is faster to load them when needed. Caches information as the paths of the scripts/executable, the path of the plug-ins configurations files, the plug-in header and the plug-in loading options. We can also cache the script and the configuration directly, not only their paths, but it will be heavier to load. For doing so override TransformPluginScriptPath and TransformPluginConfigurationPath functions so they return the script and the configuration JSON, not the paths of the files.

Parameters
package_directory_pathPackage directory path. path/to/repository/path/to/package
virtual int granada::plugin::PluginHandler::PreloadPackages ( const std::string &  repository_path)
protectedvirtual

Preload the packaged plug-ins of one given repository, so it is faster to load them when needed. Caches information as the paths of the scripts/executable, the path of the plug-ins configurations files, the plug-in header and the plug-in loading options. We can also cache the script and the configuration directly, not only their paths, but it will be heavier to load. For doing so override TransformPluginScriptPath and TransformPluginConfigurationPath functions so they return the script and the configuration JSON, not the paths of the files.

Parameters
repository_pathRepository path, it can be complete or relative path. /path/to/repository => complete path path/to/repository => relative path The path will be relative to where the application is executed.
virtual int granada::plugin::PluginHandler::PreloadRepositories ( )
protectedvirtual

Preload the plug-ins of the given repositories, so it is faster to load them when needed. Caches information as the paths of the scripts/executable, the path of the plug-ins configurations files, the plug-in header and the plug-in loading options. We can also cache the script and the configuration directly, not only their paths, but it will be heavier to load. For doing so override TransformPluginScriptPath and TransformPluginConfigurationPath functions so they return the script and the configuration JSON, not the paths of the files. The repositories paths are in the global paths_ variable.

virtual void granada::plugin::PluginHandler::Remove ( const std::string &  plugin_id)
virtual

Remove plug-in with given id.

Parameters
plugin_idPlug-in id.
virtual web::json::value granada::plugin::PluginHandler::Remove ( const web::json::value &  parameters)
virtual

Plug-in function: This function can be called from the plug-in script. It removes a plug-in with a given id. Recommended wrap function in a script: remove("math.multiplication.check.range");

Parameters
parametersJSON object with the plug-in Handler id and the id of the plug-in to remove. Example:
{
"id" : "math.multiplication.check.range",
"__PLUGIN_HANDLER_ID" : "WjdTAXePkQH7UtAWqwdy4v0qtOhFZwLn73tXHsiBn0i9BDAoH0A6WIz9ovtF3AqY"
}
Returns
An empty JSON object {} when the plug-in has been removed, and a JSON object with an error code and an error description when the plug-in couldn't be removed. Example of returned JSON when there is an error:
{
"error" : "missing_parameter",
"error_description" : "One or more of the given parameters is missing."
}
virtual void granada::plugin::PluginHandler::RemoveEventListener ( const std::string &  event_name,
const std::string &  plugin_id 
)
virtual

The plug-in with given id will no more listen to the given event.

Parameters
event_nameName of the event.
plugin_idId of the plug-in.
virtual void granada::plugin::PluginHandler::RemoveEventListeners ( const std::string &  plugin_id)
virtual

The plug-in with given id will no more listen to any event.

Parameters
plugin_idId of the plug-in.
virtual void granada::plugin::PluginHandler::RemoveEventListeners ( granada::plugin::Plugin plugin)
virtual

The plug-in pointed by the given pointer will no more listen to any event.

Parameters
plugin_idPointer pointing to a plug-in.
virtual web::json::value granada::plugin::PluginHandler::RemoveEventListeners ( const web::json::value &  parameters)
virtual

Plug-in function: This function can be called from the plug-in script. It stops a plug-in from listening to the events it was listening. Recommended wrap function in a script: removeEvents();

Parameters
parametersJSON object with the plug-in Handler id and the id of the plug-in listening to events. Example:
{
"__PLUGIN_ID" : "math.multiplication",
"__PLUGIN_HANDLER_ID" : "WjdTAXePkQH7UtAWqwdy4v0qtOhFZwLn73tXHsiBn0i9BDAoH0A6WIz9ovtF3AqY"
}
Returns
An empty JSON object {} when the plug-in has been stopped from listening to the events, and a JSON object with an error code and an error description when the plug-in couldn't be stopped. Example of returned JSON when there is an error:
{
"error" : "missing_parameter",
"error_description" : "One or more of the given parameters is missing."
}
virtual void granada::plugin::PluginHandler::RemoveExtension ( const std::string &  extended_plugin_id,
const std::string &  plugin_id 
)
virtual

Removes a plug-in extension, so when the plug-in is added, the extension is no more applied. Notice that after extending a plug-in, the extended plug-in is no more active.

Parameters
extended_plugin_idId of the extended plug-in.
plugin_idId of the extension.
virtual void granada::plugin::PluginHandler::RemoveExtensions ( const std::string &  plugin_id)
virtual

Removes all extensions to a plug-in, so when the plug-in is added, the extensions are no more applied. Notice that when extending a plug-in, the extended plug-in is no more active.

Parameters
plugin_idId of the extended plug-in.
virtual void granada::plugin::PluginHandler::RemoveLoadEvent ( const std::string &  event_name)
virtual

Removes loader event.

Parameters
event_nameName of the event.
virtual void granada::plugin::PluginHandler::RemovePluginLoader ( const std::string &  plugin_id)
virtual

Removes a plug-in loader from the cache.

Parameters
plugin_idId of the plug-in owner of the loader.
virtual void granada::plugin::PluginHandler::Reset ( )
virtual

Resets the Plug-in Handler: Stops the Plug-in Handler and Initializes it again.

virtual void granada::plugin::PluginHandler::Run ( const std::string &  plugin_id,
web::json::value &  parameters,
function_void_json  success,
function_void_json  failure 
)
inlinevirtual

Runs a plug-in. Call a success or failure callback, depending if the plug-in was successfully run or not.

Parameters
parametersJSON with the parameters to pass to the plug-in. Example: {"addend1":"4","addend2":"6"}
successCallback function called after the plug-in has been run with a response in form of JSON. Example:
{
"data" :
{
"math.sum" : {"data":{"response":10}},
}
}
failureCallback function called if the plug-in is not run successfully with a response in form of a JSON, in such case normally containing an error code and an error description. Example:
{
"error" : "script_error"
}
virtual void granada::plugin::PluginHandler::Run ( const std::string &  plugin_id,
web::json::value &  parameters,
const std::string &  event_name,
function_void_json  success,
function_void_json  failure 
)
virtual

Runs a plug-in. Call a success or failure callback, depending if the plug-in was successfully run or not.

Parameters
parametersJSON with the parameters to pass to the plug-in. Example: {"addend1":"4","addend2":"6"}
event_nameName of the event that has triggered the plug-in, empty if the plug-in was not triggered firing an event.
successCallback function called after the plug-in has been run with a response in form of JSON. Example:
{
"data" :
{
"math.sum" : {"data":{"response":10}},
}
}
failureCallback function called if the plug-in is not run successfully with a response in form of a JSON, in such case normally containing an error code and an error description. Example:
{
"error" : "script_error"
}
virtual void granada::plugin::PluginHandler::Run ( granada::plugin::Plugin plugin,
web::json::value &  parameters,
const std::string &  event_name,
function_void_json  success,
function_void_json  failure 
)
virtual

Runs a plug-in. Call a success or failure callback, depending if the plug-in was successfully run or not.

Parameters
pluginPointer to the plug-in that has to be run.
parametersJSON with the parameters to pass to the plug-in. Example: {"addend1":"4","addend2":"6"}
event_nameName of the event that has triggered the plug-in, empty if the plug-in was not triggered firing an event.
successCallback function called after the plug-in has been run with a response in form of JSON. Example:
{
"data" :
{
"math.sum" : {"data":{"response":10}},
}
}
failureCallback function called if the plug-in is not run successfully with a response in form of a JSON, in such case normally containing an error code and an error description. Example:
{
"error" : "script_error"
}

Reimplemented in granada::plugin::SpidermonkeyPluginHandler.

virtual web::json::value granada::plugin::PluginHandler::Run ( const std::vector< std::string > &  plugin_ids,
const std::string &  event_name,
web::json::value &  parameters 
)
inlinevirtual

Runs multiple plug-ins at a time. Used by the Fire function to run the plug-ins listening to a certain event.

Parameters
plugin_idsVector of strings containing the ids of the plug-ins to run.
event_nameName of the event, or empty string if there is no event, to pass to the plug-ins.
parametersJSON with the Params to pass to the plug-ins. Example: {"number":"9285","factor1":"9285","factor2":"4",addend1":"9285","addend2":"25"}
Returns
JSON object with the response of the plug-in. Example:
{
"data" :
{
"math.sum" : {"data":{"response":9310}},
"math.multiplication" : {"data":{"response":37140}}
}
}
If there was an error in one of the plug-ins:
{
"data" :
{
"math.sum" : {"data":{"response":9310}},
"math.multiplication" : {"error":"undefined_plugin", "error_description":"Plug-in could not be found with given plug-in id."}
}
}

Reimplemented in granada::plugin::SpidermonkeyPluginHandler.

virtual web::json::value granada::plugin::PluginHandler::Run ( const web::json::value &  parameters)
virtual

Plug-in function: This function can be called from the plug-in script. It runs a plug-in with a given id. Recommended wrap in a script:

runPlugin("math.multiplication.check.range",
{"number":"9285","factor1":"9285","factor2":"4"},
function(successResponseData){
// success
},dunction(failureResposeData){
// failure
});
Parameters
parametersJSON object with the plug-in Handler id, the id of the plug-in to run and the parameters to pass to the plug-in. Example:
{
"id" : "math.multiplication.check.range",
"data" : {"number":"9285","factor1":"9285","factor2":"4"},
"__PLUGIN_ID" : "math.multiplication",
"__PLUGIN_HANDLER_ID" : "WjdTAXePkQH7UtAWqwdy4v0qtOhFZwLn73tXHsiBn0i9BDAoH0A6WIz9ovtF3AqY"
}
Returns
A JSON object with the plug-in response. Example:
{
"data" :
{
"math.multiplication.check.range" : {"data":{"valid":true,"number":"9285","factor1":"9285","factor2":"4"}},
}
}
Example of returned JSON when there is an error:
{
"error" : "missing_parameter",
"error_description" : "One or more of the given parameters is missing."
}
virtual granada::runner::Runner* granada::plugin::PluginHandler::runner ( )
inlinevirtual

Returns a pointer to the responsible of running or executing the plug-in scripts/executables.

Returns
Pointer to the scripts/executables runner.

Reimplemented in granada::plugin::MapSpidermonkeyPluginHandler, and granada::plugin::RedisSpidermonkeyPluginHandler.

virtual void granada::plugin::PluginHandler::RunnerLock ( )
virtual

For increasing server performance the use of the runner is limited. This function returns true if runner is usable or false if it is not, normally if false is returned it is because it has been used very frequently.

Returns
True is runner is usable, false if not.
virtual web::json::value granada::plugin::PluginHandler::SendMessage ( const std::string &  from,
const web::json::value &  to_ids,
const web::json::value &  message 
)
virtual

Send message to plug-ins, and returns the responses to the message in form of JSON value.

Parameters
fromId of the Entity that sends the message. Normally a plug-in Id.
to_idsIds of the Plug-ins that recieve the message. Empty JSON array if we want to send the message to all plug-ins (be-careful, doing this can seriously harm performance).
messageMessage in JSON format. Example: {"message":"square calculated! Somebody wants to tell me something?"}
Returns
JSON object with the response to the message or JSON with an error code and an error_description if the message couldn't be delivered correctly. Response Examples:
{"data":{"math.multiplication":{"data":{"response":"8795"}}}}
{"math.multiplication":
{
"error" : "undefined_plugin",
"error_description" : "Plug-in could not be found with given plug-in id."
}
}
virtual web::json::value granada::plugin::PluginHandler::SendMessage ( const std::string &  from,
const std::vector< std::string > &  to_ids,
const web::json::value &  message 
)
inlinevirtual

Send messag to more than one plug-in, and returns the responses to the message in form of JSON value.

Parameters
fromId of the sender of the message. Normally a plug-in Id.
to_idsIds of the Plug-ins that recieve the message. Empty JSON array if we want to send the message to all plug-ins (be-careful, doing this can seriously harm performance).
messageMessage in JSON format. Example: {"message":"square calculated! Somebody wants to tell me something?"}
Returns
JSON object with the response to the message or JSON with an error code and an error_description if the message couldn't be delivered correctly. Response Examples:
{"data":{"math.multiplication":{"data":{"response":"8795"}}}}
{"math.multiplication":
{
"error" : "undefined_plugin",
"error_description" : "Plug-in could not be found with given plug-in id."
}
}

Reimplemented in granada::plugin::SpidermonkeyPluginHandler.

virtual web::json::value granada::plugin::PluginHandler::SendMessage ( const web::json::value &  parameters)
virtual

Plug-in function: Send message from a plug-in or other entity to a plug-in or to plug-ins. Recommended wrap function in a script:

sendMessage({"message":"square calculated! Somebody wants to tell me something?"},
["math.sum","math.multiplication"],
function(messageResponse){
//...
});
Parameters
parametersJSON containing the sender information an Example:
{
"__PLUGIN_HANDLER_ID" : "GkydJC7abem4pVEdzSP13kxpjS37wHqzvKtt3phLYr5n3XYhZH2CWPNYOugVvHg5",
"__PLUGIN_ID" : "math.square",
"to_ids" : ["math.sum","math.multiplication"],
"data" : {"message":"square calculated! Somebody wants to tell me something?","result":"1759"}
}
=> in this example message is sent to "math.sum" and "math.multiplication" plug-ins,
If "to_ids" parameter is an empty array "[]" the message will be sent to all plug-ins
except to the sender.
Returns
Response to the message in form of JSON object with a JSON array with the message or a JSON object with an error code and an error_description in case there was a problem. Example:
{
"data" :
{
"math.sum" : {"data":{"response":"Do nothing"}},
"math.multiplication" : {"data":{"response":"8795"}}
}
} => everything is fine
{
"error" : "missing_parameter",
"error_description" : "One or more of the given parameters is missing."
} => error sending messages
virtual web::json::value granada::plugin::PluginHandler::SetValue ( const web::json::value &  parameters)
virtual

Plug-in function: This function can be called from the plug-in script. It caches a key-value pair that can be used by the plug-in during the plug-in life. Used to store plug-in global variables. Recommended wrap function in script: setValue("number",8); => stores the value "8" identified by the name "number" until the plug-in is removed or the Plug-in Handler is stoped.

Parameters
parametersJSON with the plug-in id, the Plug-in Handler id and the key-value pair to store. Example:
{
"key" : "number",
"value" : "3",
"__PLUGIN_ID" : "math.multiplication",
"__PLUGIN_HANDLER_ID" : "WjdTAXePkQH7UtAWqwdy4v0qtOhFZwLn73tXHsiBn0i9BDAoH0A6WIz9ovtF3AqY"
}
Returns
An empty JSON object {} is returned if the key-value pair is stored correctly, and a JSON with an error code and an error_description if there was a problem when storing the key-value pair. Example of returned JSON when there is an error:
{
"error" : "missing_parameter",
"error_description" : "One or more of the given parameters is missing."
}
virtual void granada::plugin::PluginHandler::Stop ( )
virtual

Stops the Plug-in Handler removing the cached plug-ins and events.

virtual std::string granada::plugin::PluginHandler::TransformPluginConfigurationPath ( const std::string &  plugin_configuration_path)
protectedvirtual

Transformation function, used to transform a configuration file path or not. This function is called when preloading a plug-in, by default it returns the same file path that is given, but this function can be overriden so it returns the content of the file: the plug-in configuration JSON itself, so the configuration JSON is cached when preloading (and not when loading the plug-in). Notice that by doing so, the preloading may be slower, and we may cache configurations that are never going to be used.

Parameters
plugin_script_pathPath of the plug-in configuration.
Returns
Path of the plug-in configuration, configuration JSON, or a tranformed path.
virtual std::string granada::plugin::PluginHandler::TransformPluginScriptPath ( const std::string &  plugin_script_path)
protectedvirtual

Transformation function, used to transform a script file path or not. This function is called when preloading a plug-in, by default it returns the same file path that is given, but this function can be overriden so it returns the content of the file: the script itself, so script is cached when preloading (and not when loading the plug-in). Notice that by doing so, the preloading may be slower, and we may cache scripts that are never going to be used.

Parameters
plugin_script_pathPath of the script/executable.
Returns
Path of the script/executable, the script itself or a tranformed path.

Member Data Documentation

std::once_flag granada::plugin::PluginHandler::functions_to_runner_flag_
staticprotected

Once flag used to set the functions that can be called from the plug-ins when they are running only once.

std::string granada::plugin::PluginHandler::id_
protected

Id of the Plug-in Handler. It has to be unique. It can be a unique nonce that we pass to the user. Or if we chose to link the Plug-in Handler to a session, it can be the id of a session. Or the username if we link the Plug-in Handler to a user, be aware, that if a Plug-in Handler is linked to a user, the plug-ins of two users connected with the same username will be shared, so they will share for example plug-ins global variables.

std::vector<std::string> granada::plugin::PluginHandler::paths_
protected

Path of the repositories where the packaged plug-ins are.

int granada::plugin::PluginHandler::PLUGIN_BYTES_LIMIT_
staticprotected

Maximum bytes a Plug-in Handler can load.

std::once_flag granada::plugin::PluginHandler::properties_flag_
staticprotected

Once flag for properties loading.

int granada::plugin::PluginHandler::RUNNER_USE_FREQUENCY_LIMIT_
staticprotected

The minimum time Plug-ins have to wait between two runs in milliseconds. Value is taken from the "plugin_runner_use_frequency_limit" property from the server.conf file. If the value is not indicated in the server.conf file a default value is taken from defaults values, default value is: 50ms.

int granada::plugin::PluginHandler::SEND_MESSAGE_PLUGIN_GROUP_SIZE_
staticprotected

Messages to plug-ins are not sent to each plug-in separately, to increase performance, we group the plug-ins so groups of them recieve the messages at the same time.

unsigned long long granada::plugin::PluginHandler::uid_
staticprotected

Used to give an id to plug-ins without id.

std::mutex granada::plugin::PluginHandler::uid_mtx_
staticprotected

Mutex for multi-thread safety when increaing unique ids.


The documentation for this class was generated from the following file: