VFS_creator is a static class used to instantiate nodes. More...

#include <VFS_creator.h>

Static Public Member Functions
static VFS_request *	code (VFS_request *r)
	Resolve a request for code. More...

static QJsonObject	codeDirectory (QString &error)
	Gather and return a directory of code namespaces served by this VFS instance. More...

static QString	configAttribute (QVariantMap env, QDomElement e, QString attr, bool req=true, QString def="")
	Fetch an XML node attribute value and resolve it against an environment. More...

static bool	configBoolAttribute (QVariantMap env, QDomElement e, QString attr, bool req=true, bool def=false)
	Fetch an XML node attribute value and resolve it against an environment, returning it as a bool. More...

static double	configDoubleAttribute (QVariantMap env, QDomElement e, QString attr, bool req=true, double def=0.0)
	Fetch an XML node attribute value and resolve it against an environment, returning it as a double value. More...

static int	configIntAttribute (QVariantMap env, QDomElement e, QString attr, bool req=true, int def=0)
	Fetch an XML node attribute value and resolve it against an environment, returning it as an int. More...

static QString	configPathAttribute (QVariantMap env, QDomElement e, QString attr, bool req=true, QString def="")
	Fetch an XML node attribute value and resolve it against an environment, ensuring it is a cleaned path. More...

static bool	registerPlugin (QString name, VFS_node_interface *node)
	Register a plugin. More...

static QString	resolveEnvValue (QString value, QVariantMap env)
	Resolve an incoming value against the system environment and the provided environment. More...

static bool	unregisterPlugin (QString name)
	Unregister a plugin. More...

Static Public Attributes
static QMutex	_pluginsLock
	A mutex for protecting the _plugins object. More...

Static Private Member Functions
static void	build (QString configFile, VFS_node *root, bool printConfig=false)
	Build an environment for creating nodes. More...

static void	constructConfig (QString configFile, QVariantMap env, VFS_node *mount, bool printConfig, QDomNamedNodeMap attrs=QDomNamedNodeMap())
	Build nodes from a config file using the provided environment values. More...

static QVariantMap	constructEnvironment (QVariantMap env, QDomElement c)
	Construct an environment from an <env> node. More...

static VFS_node *	constructNode (QDomElement child, QVariantMap &env, bool printConfig=false)
	VFS_creator::constructNode. More...

static void	constructNodes (QDomElement nodeConfig, QVariantMap env, VFS_node *mount, bool printConfig=false)
	Now that the file is open and an environment exists, do the work. More...

static void	init (QStringList plugins=QStringList(), bool describe=false)
	Initialize plugins recursively. More...

static void	setParameters (QVariantMap env, QDomElement c)
	Set parameters on the VFS::root() instance, for future query. More...

Static Private Attributes
static QSemaphore	_outstanding
	A semaphore used to sync creation during startup. More...

static QMap< QString, VFS_node_interface * >	_plugins
	The plugin registry. More...

static QProcessEnvironment	_systemEnvironment
	The system environment inherited during startup. More...

Friends
class	VFS

class	VFS_thread

class	VFS_threadthread

Detailed Description

VFS_creator is a static class used to instantiate nodes.

All functions and members are static; this class cannot be instantiated.

During initialization, VFS_creator will parse xml config files, assign threads, manage plugins, and create the virtual filesystem. When VFS_creator::build() is complete, VFS will emit an initialized() signal.

When creating multiple threads, VFS_creator will consume semaphores from the VFS_creator::outstanding pool. The harcoded maximum number of concurrent build threads is set to 100.

When parsing config files, VFS_creator will create shell-like environments for each level of the filesystem. Environment variables present when the executable is run, plus any environment variables provided to the executable commmand, plus any variables defined in the head of the config file itself will comprise that environment. When entering a deeper level, new variable values will be set, however when that context is left, previous values will persist, like a shell.

See also: XML Config File(s)

Definition at line 17 of file VFS_creator.h.

Member Function Documentation

◆ build()

void VFS_creator::build	(	QString	configFile,
		VFS_node *	root,
		bool	printConfig = `false`
	)

staticprivate

Build an environment for creating nodes.

Parameters

configFile	The file to pass to constructConfig()
root	The node to pass to constructConfig() to mount new nodes to
printConfig	A debug setting, used to make sure contexts are correct

This function will instantiate a new environment, claim semaphore resources, and then call constructConfig() with the new environment.

Warning: This private function should only be called from VFS, which is a friend class.

Definition at line 148 of file VFS_creator.cpp.

◆ code()

VFS_request * VFS_creator::code ( VFS_request * r )

static

Resolve a request for code.

Parameters

r	The VFS_request object.

Returns: The VFS_request with _data containing the requested code, or a VFS_request with _success=false.

Reference the plugin repository for an entry matching nodename, and if so, request code from the libname of the plugin.

The _path of the incoming VFS_request should be in "nodename:libname" format.

If an error happens, r._reason will be set to the error, and r._success will be set to false.

The plugin must be licensed for this to succeed.

If the requested resource ends in .js, it will be uglified (http://www.crockford.com/javascript/jsmin.html) on output, which will make the source code smaller, remove all comments, and will obfusticate it to the end user.

See also: VFS_node_interface::code(); VFS_node::code()

Definition at line 905 of file VFS_creator.cpp.

◆ codeDirectory()

QJsonObject VFS_creator::codeDirectory ( QString & error )

static

Gather and return a directory of code namespaces served by this VFS instance.

Parameters

error An error string to write back to if there's a problem.

Returns: The code directory as a QJsonObject

The code directory will allow a VFS to register any code being served by another mounted VFS.

This will not include VFS_stdlib entries, as those should already be global to all instances of the VFS.

Definition at line 999 of file VFS_creator.cpp.

◆ configAttribute()

QString VFS_creator::configAttribute	(	QVariantMap	env,
		QDomElement	e,
		QString	attr,
		bool	req = `true`,
		QString	def = `""`
	)

static

Fetch an XML node attribute value and resolve it against an environment.

Parameters

env	The environment
e	The XML node
attr	The attribute to fetch and resolve
req	Is this attribute required?
def	If not required and not present, this is a default value.

Returns: The resolved attribute value

When creating nodes from a config file, attributes may refer to environment variables using @variable@ syntax.

This function will resolve those tokens.

See also: XML Config File(s); VFS_node_interface::create()

Definition at line 609 of file VFS_creator.cpp.

◆ configBoolAttribute()

bool VFS_creator::configBoolAttribute	(	QVariantMap	env,
		QDomElement	e,
		QString	attr,
		bool	req = `true`,
		bool	def = `false`
	)

static

Fetch an XML node attribute value and resolve it against an environment, returning it as a bool.

Parameters

env	The environment
e	The XML node
attr	The attribute to fetch and resolve
req	Is this attribute required?
def	If not required and not present, this is a default value.

Returns: The resolved attribute value as a boolean

When creating nodes from a config file, attributes may refer to environment variables using @variable@ syntax.

This function will resolve those tokens, and then compare against "1", "true", or "yes" to determine if the boolean value is true; otherwise it is false. The comparison is not case sensitive.

See also: XML Config File(s); VFS_node_interface::create()

Definition at line 671 of file VFS_creator.cpp.

◆ configDoubleAttribute()

double VFS_creator::configDoubleAttribute	(	QVariantMap	env,
		QDomElement	e,
		QString	attr,
		bool	req = `true`,
		double	def = `0.0`
	)

static

Fetch an XML node attribute value and resolve it against an environment, returning it as a double value.

Parameters

env	The environment
e	The XML node
attr	The attribute to fetch and resolve
req	Is this attribute required?
def	If not required and not present, this is a default value.

Returns: The resolved attribute value as a double

When creating nodes from a config file, attributes may refer to environment variables using @variable@ syntax.

This function will resolve those tokens, and then parse the string value as an double.

[0-9], '-', and '.' are the only characters accepted.

See also: XML Config File(s); VFS_node_interface::create()

Definition at line 761 of file VFS_creator.cpp.

◆ configIntAttribute()

int VFS_creator::configIntAttribute	(	QVariantMap	env,
		QDomElement	e,
		QString	attr,
		bool	req = `true`,
		int	def = `0`
	)

static

Fetch an XML node attribute value and resolve it against an environment, returning it as an int.

Parameters

env	The environment
e	The XML node
attr	The attribute to fetch and resolve
req	Is this attribute required?
def	If not required and not present, this is a default value.

Returns: The resolved attribute value as an int

When creating nodes from a config file, attributes may refer to environment variables using @variable@ syntax.

This function will resolve those tokens, and then parse the string value as an integer.

[0-9] and '-' are the only characters accepted.

See also: XML Config File(s); VFS_node_interface::create()

Definition at line 712 of file VFS_creator.cpp.

◆ configPathAttribute()

QString VFS_creator::configPathAttribute	(	QVariantMap	env,
		QDomElement	e,
		QString	attr,
		bool	req = `true`,
		QString	def = `""`
	)

static

Fetch an XML node attribute value and resolve it against an environment, ensuring it is a cleaned path.

Parameters

env	The environment
e	The XML node
attr	The attribute to fetch and resolve
req	Is this attribute required?
def	If not required and not present, this is a default value.

Returns: The resolved attribute value as a clean path

When creating nodes from a config file, attributes may refer to environment variables using @variable@ syntax.

This function will resolve those tokens, taking care to remove duplicate and leading '/' path separators, effectively performing an rutils::cleanPath();

See also: XML Config File(s); VFS_node_interface::create(); VFS_creator::configAttribute()

Definition at line 640 of file VFS_creator.cpp.

◆ constructConfig()

void VFS_creator::constructConfig	(	QString	configFile,
		QVariantMap	env,
		VFS_node *	mount,
		bool	printConfig,
		QDomNamedNodeMap	attrs = `QDomNamedNodeMap()`
	)

staticprivate

Build nodes from a config file using the provided environment values.

Parameters

configFile	The file to parse and instantiate
env	The build environment
mount	The node to mount new nodes to
printConfig	A debug setting, used to make sure contexts are correct
attrs	Additional environment variables to pass on, probably from an <include> tag

If mount == VFS::root(), this method will set the VFS::_logLevel and VFS::_logTime. If the environment variables VFS_LOG_LEVEL or VFS_LOG_TIME are set, they will override the values in the config file.

If a root config file has a monitor="true" entry in its <VFS> xml node, the path to that config file will be added to VFS::_monitoredFiles and monitored for changes. Alternatively, a full path to any other file can be provided for monitoring: ‘monitor=’/path/to/some/file'`. The file must exist when the server starts to be monitored.

Note: This private function is used internally by VFS_creator, and should not be called directly.

Definition at line 187 of file VFS_creator.cpp.

◆ constructEnvironment()

QVariantMap VFS_creator::constructEnvironment	(	QVariantMap	env,
		QDomElement	c
	)

staticprivate

Construct an environment from an <env> node.

Parameters

env	The current environment
c	The <env> node itself

Returns: The new environment

This will iterate over the children of an <env> node to augment an environment.

Definition at line 499 of file VFS_creator.cpp.

◆ constructNode()

VFS_node * VFS_creator::constructNode	(	QDomElement	child,
		QVariantMap &	env,
		bool	printConfig = `false`
	)

staticprivate

VFS_creator::constructNode.

Parameters

child	The XML node containing initialization parameters for a VFS_node
env	The build environment
printConfig	A debug setting, used to make sure contexts are correct

Returns: The new VFS_node, or 0 if creation was not possible.

This is where plugins are accessed and nodes are actually created. If the node specifies a new thread is to be created, a VFS_thread is instantiated with the current environemnt, and the XML node is passed to it. This will spawn a new constructNode() thread and a concurrent build will start.

A created node will be checked for if an initialized plugin has registered an feature with VFS_acl::registerACLFeature(), and if so, that feature will be added to all VFS_acl entries.

If a node is flagged with isContainer() == true, constructNodes() will be called on the XML node's children.

Definition at line 437 of file VFS_creator.cpp.

◆ constructNodes()

void VFS_creator::constructNodes	(	QDomElement	nodeConfig,
		QVariantMap	env,
		VFS_node *	mount,
		bool	printConfig = `false`
	)

staticprivate

Now that the file is open and an environment exists, do the work.

Parameters

nodeConfig	The XML tag node being parsed for node creation
env	The build environment
mount	The mount point for new nodes
printConfig	A debug setting, used to make sure contexts are correct

This is the recursive function used to actually iterate over the children of an XML node.

Certain control tags are used:

<env> - set environment variables
<include> - include another config file for parsing. The current environment will be sent to the included file
<parameters> - parameters set on the executable... this will probably become deprecated.

Warning: This private function is used internally by VFS_creator, and should not be called directly.

Definition at line 322 of file VFS_creator.cpp.

◆ init()

void VFS_creator::init	(	QStringList	pluginsDirs = `QStringList()`,
		bool	describe = `false`
	)

staticprivate

Initialize plugins recursively.

Parameters

pluginsDirs	The list of directories to search for plugins.
describe	Boolean value indicating whether or not to describe each plugin as it's loaded.

Warning: This private function should only be called from VFS, which is a friend class.

Definition at line 60 of file VFS_creator.cpp.

◆ registerPlugin()

bool VFS_creator::registerPlugin	(	QString	name,
		VFS_node_interface *	node
	)

static

Register a plugin.

Parameters

name	The plugin name
node	The node to handle the plugin

Returns: Success or failure of registering the plugin

This is used by VFS_tcp_mount to associate a mount point with the location of remote code resources.

Definition at line 1035 of file VFS_creator.cpp.

◆ resolveEnvValue()

QString VFS_creator::resolveEnvValue	(	QString	value,
		QVariantMap	env
	)

static

Resolve an incoming value against the system environment and the provided environment.

Parameters

value	The incoming value
env	A provided environment

Returns: The resolved value

Tokens in the form of @variable@ will be resolved against the environment.

This will first query the VFS_creator::systemEnvironment to resolve values, then the provided environment, doing a string replacement on each match. Environment variables can contain references to other @variables@, and they will be resolved to a maximum depth of 20 replacements.

It can be useful to perform rudimentary calculations to resolve the value of an attribute. Currently the only operators supported are '+', '-' and '*', but more may be added later.

Given a config file:

<VFS logLevel='9'>
    <env>
        <portstart default='1234'/>
    </env>
 
    <remotoserver name='remotoserver' port='@portstart@+5' auth='/services/auth/passwd,/services/auth/nopasswd' thread='1' />
</VFS>

This will cause the VFS_remotoserver node to start on port 1239. This is useful because a base port can be provided from which other ports will offset, so a whole VFS can be moved to a different port block by changing one value.

Note: More script functions may be introduced in the future. The evaluation environment uses QJSEngine, but will only activate if '+' or '-' are present.

Exceptions

QString If a variable can't be resolved, a QString exception is thrown. Not sure where it goes, because in practice you will learn of a bug like this quickly and correct the problem early on, rather than the system employing a more complex handler for this case.

Definition at line 830 of file VFS_creator.cpp.

◆ setParameters()

void VFS_creator::setParameters	(	QVariantMap	env,
		QDomElement	c
	)

staticprivate

Set parameters on the VFS::root() instance, for future query.

Parameters

env	The current environment
c	The <parameters> node itself

When running in a cloud environment with many containers, it can be useful for an instance of VFS to have some introspection data to identify itself to other instances.

A <parameters> tag can be placed in a config file to provide this data to an instance of VFS.

Warning: This feature may be deprecated in favor of other introspection techniques.

Definition at line 548 of file VFS_creator.cpp.

◆ unregisterPlugin()

bool VFS_creator::unregisterPlugin ( QString name )

static

Unregister a plugin.

Parameters

name	The plugin name

Returns: Success or failure of unregistering the plugin

This is used by VFS_tcp_mount to un-associate a mount point with the location of remote code resources. Technically, the node is not needed, but it's included here

Definition at line 1057 of file VFS_creator.cpp.

Friends And Related Function Documentation

◆ VFS

friend class VFS

friend

Definition at line 19 of file VFS_creator.h.

◆ VFS_thread

friend class VFS_thread

friend

Definition at line 20 of file VFS_creator.h.

◆ VFS_threadthread

friend class VFS_threadthread

friend

Definition at line 21 of file VFS_creator.h.

Member Data Documentation

◆ _outstanding

QSemaphore VFS_creator::_outstanding

staticprivate

A semaphore used to sync creation during startup.

Definition at line 56 of file VFS_creator.h.

◆ _plugins

QMap< QString, VFS_node_interface * > VFS_creator::_plugins

staticprivate

The plugin registry.

Definition at line 54 of file VFS_creator.h.

◆ _pluginsLock

QMutex VFS_creator::_pluginsLock

static

A mutex for protecting the _plugins object.

Definition at line 41 of file VFS_creator.h.

◆ _systemEnvironment

QProcessEnvironment VFS_creator::_systemEnvironment

staticprivate

The system environment inherited during startup.

Definition at line 57 of file VFS_creator.h.

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

Static Public Member Functions

Static Public Attributes

Static Private Member Functions

Static Private Attributes

Friends

Detailed Description

Member Function Documentation

◆ build()

◆ code()

◆ codeDirectory()

◆ configAttribute()

◆ configBoolAttribute()

◆ configDoubleAttribute()

◆ configIntAttribute()

◆ configPathAttribute()

◆ constructConfig()

◆ constructEnvironment()

◆ constructNode()

◆ constructNodes()

◆ init()

◆ registerPlugin()

◆ resolveEnvValue()

◆ setParameters()

◆ unregisterPlugin()

Friends And Related Function Documentation

◆ VFS

◆ VFS_thread

◆ VFS_threadthread

Member Data Documentation

◆ _outstanding

◆ _plugins

◆ _pluginsLock

◆ _systemEnvironment