Maintains a map of Zuble Sprockets and creates Sprocket object factories for javascript background threads. Manages Zuble resource plugins. More...

#include <ZblCog.h>

Inheritance diagram for Zbl::ZblCog:

[legend]

Collaboration diagram for Zbl::ZblCog:

[legend]

Public Member Functions
	ZblCog (QObject *parent=0)

virtual	~ZblCog ()

bool	registerSprocket (const char *uri, int versionMajor, int versionMinor)
	Called by Zuble sprocket extension plugins to register themselves with Zuble so their objects can be imported into javascript background threads by calling Zbl.import(uri, version-major, version-minor). More...

bool	registerSprocketObject (const char uri, int versionMajor, int versionMinor, const char qmlName, sprocketObjectConstructor createFunc)
	Called by Zuble sprocket extension plugins to register their object constructors with Zuble so their objects can be created in javascript background threads by calling Zbl.newObject(uri, type-name). More...

ZblFactory *	createFactory (const char sprocketUri, int versionMajor, int versionMinor, QObject parent=NULL)
	Constructs a ZblFactory object and populates it with a set of version-specific Sprocket object constructors based on the QML type name version semantics. More...

bool	mapResource (const char uri, int versionMajor, int versionMinor, const char fileName)
	Binds a resource uri with it's associated binary resource file. The resource can subsequently be referred to by the uri. More...

bool	mapPluginResources (const char *fileName, bool qmlRegister=false)
	Make a plugin's binary resource files known to Zuble so they can be loaded into QML by calling Zbl.registerResource(uri, versionMajor, versionMinor). More...

bool	mapConfigResources (const char *configFilePath)
	Reads specified zblconfig.xml file and maps/loads resources accordingly. More...

bool	isMappedResource (const char *uri, int versionMajor, int versionMinor)
	Determine whether a resource is mapped. More...

QStringList	getMappedResources ()
	Returns the list of mapped resource keys in the form of uri:versionMajor:versionMinor, ie: 'org.zuble.qml:1:0'. More...

bool	registerResource (const char *uri, int versionMajor, int versionMinor)
	Makes a Zuble resource file available to QML and background javascript programs. More...

Static Public Member Functions
static ZblCog &	zInit (QObject *parent)

static ZblCog &	zInstance ()
	zInstance More...

Protected Types
enum	commandFields { cmdAction = 0, cmdResourceType, cmdRecordSize, commandFieldCount }

enum	paramFile { fileUri = 1, fileVersionMajor, fileVersionMinor, fileName }

enum	paramPlugin { pluginName = 1 }

Protected Member Functions
QString	getNodeName (const QXmlItem &item, const QXmlQuery &query)

void	warnInvalidResourceCommand (const QString &label, const QString &command)

void	warnAbortingResourceLoad (const QString &label, const QString &reason)

bool	validateParamCount (int actual, int required)

bool	getPluginResParams (const QJsonValue &resourceValue, QString &uri, QString &fileName, QString &versionMajor, QString &versionMinor)

bool	getPluginStringParam (const QJsonObject &resource, const QString &paramKey, QString &outValue)

Protected Attributes
sprocketPluginMap	m_sprockets
	Maps Sprocket plugin uri's to sprocket objects. More...

resourceMap	m_resources
	Maps Resource plugin uri's to resource objects. More...

QReadWriteLock	m_lock
	ZblCog's multithreaded lock. More...

Static Protected Attributes
static const QString	m_commandSeparator = "::"

static const QString	m_actionMap = "map"

static const QString	m_actionQmlregister = "register"

static const QString	m_actionIgnore = "ignore"

static const QString	m_restypeFile = "file"

static const QString	m_restypePlugin = "plugin"

static const QString	m_restypeInvalid = "invalid"

static const int	m_paramcountFile = 4

static const int	m_paramcountPlugin = 1

Static Private Attributes
static ZblCog *	m_zCog = 0
	The one and only ZblCog object allowed to exist in this process. More...

Detailed Description

Maintains a map of Zuble Sprockets and creates Sprocket object factories for javascript background threads. Manages Zuble resource plugins.

Zuble Sprockets:

A "Sprocket" is a QML extension plugin that conforms to Zuble's sprocket design pattern and links directly to Zuble's core plugin (zblcore). Sprockets provide an extension mechanism for Zuble that allows additional features to be added to the core plugin. This supports such built-in features as PostgreSQL client connections and the Zuble log file viewer application (zlogger) as well as custom user-defined application extensions.

User applications can code their performance critical modules in C++ and enjoy the benefit of Zuble's C++ API by building a custom sprocket to encapsulate their C++ code.

Background Extension Object creation:

The QML engine does not support constructing extension objects in a QML background thread. (TBD: or have I missed something?) The sprocket design pattern overcomes this limitation by providing a custom object factory for each thread that can be accessed through the Zbl object (Zbl::ZblApp class) via the ZblApp::newObject() method. This allows QML code executing in ZScriptThread objects to construct QML objects. (Note that background QML extension objects can't be visual objects. They should derive from QObject, not QQuickItem.)

Each javascript thread creates a separate object factory for each Sprocket plugin that QML code imports into the thread by calling ZblApp::import(). Each object factory maps the plugin's QML type names to the appropriate version-specific Sprocket object constructors in the plugin determined by the version information passed into the ZblApp::import() function call.

This construct supports the version semantics of QML types which allow plugins to contain a separate C++ class for each version of a specific QML type. When a plugin is imported into a Zuble background thread the set of QML type constructors that satisfies verison semantics is coalesced into an object factory that binds the object constructors to a specific object version and is owned by that thread. Different threads may therefore use different QML object versions. TBD: should the version be passed in the Zbl.newObject() call instead to afford the finest granularity of object version mixing?

Once the object factory is constructed the thread can call Sprocket object constructor methods directly without blocking since each thread has it's own factory. The Sprocket plugin's object constructor may or may not block depending on the requirements of the plugin itself. The choice to block the thread on object construction is up to the plugin designer.

Resource Plugins:

Resource plugins allow Zuble programs to load binary resource files created by the Qt resource compiler at specific mount points in the Qt resource system.

See also: Zbl::ZblApp::import

Definition at line 110 of file ZblCog.h.

Member Enumeration Documentation

◆ commandFields

enum Zbl::ZblCog::commandFields

protected

Enumerator
cmdAction
cmdResourceType
cmdRecordSize
commandFieldCount

Definition at line 348 of file ZblCog.h.

◆ paramFile

enum Zbl::ZblCog::paramFile

protected

Enumerator
fileUri
fileVersionMajor
fileVersionMinor
fileName

Definition at line 356 of file ZblCog.h.

◆ paramPlugin

enum Zbl::ZblCog::paramPlugin

protected

Enumerator
pluginName

Definition at line 363 of file ZblCog.h.

Constructor & Destructor Documentation

◆ ZblCog()

Zbl::ZblCog::ZblCog ( QObject * parent = 0 )

explicit

Definition at line 62 of file ZblCog.cpp.

Referenced by zInit().

◆ ~ZblCog()

Zbl::ZblCog::~ZblCog ( )

virtual

Definition at line 75 of file ZblCog.cpp.

Member Function Documentation

◆ createFactory()

ZblFactory * Zbl::ZblCog::createFactory	(	const char *	sprocketUri,
		int	versionMajor,
		int	versionMinor,
		QObject *	parent = `NULL`
	)

Constructs a ZblFactory object and populates it with a set of version-specific Sprocket object constructors based on the QML type name version semantics.

Object versions greater than the specified factory version will be omitted from the factory. A type's highest object constructor version that matches the specified factory version will be included in the factory.

Parameters

sprocketUri	uri of the sprocket plugin with which to populate the factory
versionMajor	QML import major version for objects in the factory
versionMinor	QML import minor version for objects in the factory
parent	parent of the ZblFactory object. Caller is responsible for deleting the returned ZblFactory object is no parent QObject is specified.

Returns: pointer to a ZblFactory object, or NULL if the object could not be created

Definition at line 163 of file ZblCog.cpp.

◆ getMappedResources()

QStringList Zbl::ZblCog::getMappedResources ( )

Returns the list of mapped resource keys in the form of uri:versionMajor:versionMinor, ie: 'org.zuble.qml:1:0'.

Returns: the list of key strings

Definition at line 896 of file ZblCog.cpp.

◆ getNodeName()

QString Zbl::ZblCog::getNodeName	(	const QXmlItem &	item,
		const QXmlQuery &	query
	)

protected

Definition at line 773 of file ZblCog.cpp.

◆ getPluginResParams()

bool Zbl::ZblCog::getPluginResParams	(	const QJsonValue &	resourceValue,
		QString &	uri,
		QString &	fileName,
		QString &	versionMajor,
		QString &	versionMinor
	)

protected

Definition at line 412 of file ZblCog.cpp.

Referenced by mapPluginResources().

◆ getPluginStringParam()

bool Zbl::ZblCog::getPluginStringParam	(	const QJsonObject &	resource,
		const QString &	paramKey,
		QString &	outValue
	)

protected

Definition at line 440 of file ZblCog.cpp.

Referenced by getPluginResParams().

◆ isMappedResource()

bool Zbl::ZblCog::isMappedResource	(	const char *	uri,
		int	versionMajor,
		int	versionMinor
	)

Determine whether a resource is mapped.

Parameters

uri	Resource uri to test
versionMajor	major version number to test, -1 to ignore both version numbers
versionMinor	minor version number to test, -1 to ignore only minor version number

Returns: true if the specified resource uri and version are currently mapped, false otherwise.

Definition at line 849 of file ZblCog.cpp.

◆ mapConfigResources()

bool Zbl::ZblCog::mapConfigResources ( const char * configFilePath )

Reads specified zblconfig.xml file and maps/loads resources accordingly.

Parameters

configFilePath

Returns

Definition at line 457 of file ZblCog.cpp.

◆ mapPluginResources()

bool Zbl::ZblCog::mapPluginResources	(	const char *	fileName,
		bool	qmlRegister = `false`
	)

Make a plugin's binary resource files known to Zuble so they can be loaded into QML by calling Zbl.registerResource(uri, versionMajor, versionMinor).

This method reads metadata from a QML extension plugin to determine which resource files to map for the plugin. This allows plugin resources to be bound to a file at run time.

Zuble searches the plugin path to locate plugin files, and the library path to locate their binary resource files. (TBD: should we look in current dir of plugin first?)

Sprocket plugins may map zero or more binary resource files by uri. Zuble QML programs may also map resource files by calling Zbl.mapPluginResource().

See also: ZblApp::loadResource(); ZblApp::mapPluginResource(); ZblCog::registerSprocket()

Parameters

fileName	plugin file name with no extension (platform-specific extension will be determined by Qt)
qmlRegister	true = register binary resource files after mapping resource bundle, false = map resource bundle but don't register binary resource files; default = false

Returns: true if plugin resources mapped/loaded successfully, false if failed

Definition at line 278 of file ZblCog.cpp.

Referenced by mapConfigResources().

◆ mapResource()

bool Zbl::ZblCog::mapResource	(	const char *	uri,
		int	versionMajor,
		int	versionMinor,
		const char *	fileName
	)

Binds a resource uri with it's associated binary resource file. The resource can subsequently be referred to by the uri.

The resource can be loaded into QML by calling Zbl.registerResource(uri, versionMajor, versionMinor).

Note that versionMajor and versionMinor should be the same as those passed in the sprocket's ZblCog::registerSprocket() function call to ensure the resource bundle/plugin binary pair are compatible.

Zuble searches the library path to locate binary resource files.

Sprocket plugins may map zero or more binary resource files by uri. Zuble QML programs may also map resource files by calling Zbl.mapResource.

See also: ZblApp::loadResource(); ZblApp::mapResource(); ZblCog::registerSprocket()

Parameters

uri	Resource's uri
versionMajor	Resource's major version number
versionMinor	Resource's minor version number
fileName	binary resource file name including extension
register	true = call QML to register the resource immediately; false = don't call QML to register resource

Returns: true if resource file mapped successfully, false if failed

Definition at line 212 of file ZblCog.cpp.

Referenced by mapConfigResources(), and mapPluginResources().

◆ registerResource()

bool Zbl::ZblCog::registerResource	(	const char *	uri,
		int	versionMajor,
		int	versionMinor
	)

Makes a Zuble resource file available to QML and background javascript programs.

This function should be called once for each binary resource file a Zuble program will use. After calling this function use QML import statements, ZFile objects or QFile objects to load objects from the resource file.

Note: You should call ZblCog::mapResource() to bind a filename and version to the resource uri before calling this function.

WARNING: When using sprocket plugin resource files the uri of the plugin's QML module must have previously been imported with a QML import statement. Otherwise the uri of the resource file must be registered with Zbl.registerResource or ZblCog::registerResource.

Parameters

uri	uri of the sprocket
versionMajor	major version of the sprocket
versionMinor	minor version of the sprocket

See also: ZblApp::registerResource; ZblCog::mapResource

Definition at line 794 of file ZblCog.cpp.

Referenced by mapConfigResources(), and mapPluginResources().

◆ registerSprocket()

bool Zbl::ZblCog::registerSprocket	(	const char *	uri,
		int	versionMajor,
		int	versionMinor
	)

Called by Zuble sprocket extension plugins to register themselves with Zuble so their objects can be imported into javascript background threads by calling Zbl.import(uri, version-major, version-minor).

Note that the Zbl.import version numbers specify QML type versions, whereas versionMajor and versionMinor arguments to registerSprocket should specify the plugin library version. Each library can contain mutiple object versions per QML type name, thus library versions and import versions are only loosely coupled.

Parameters

uri	the uri of the plugin to register
versionMajor	major version number of the Sprocket plugin
versionMinor	minor version number of the Sprocket plugin

Returns: true if sprocket registered successfully, false if failed

Definition at line 92 of file ZblCog.cpp.

◆ registerSprocketObject()

bool Zbl::ZblCog::registerSprocketObject	(	const char *	uri,
		int	versionMajor,
		int	versionMinor,
		const char *	qmlName,
		sprocketObjectConstructor	createFunc
	)

Called by Zuble sprocket extension plugins to register their object constructors with Zuble so their objects can be created in javascript background threads by calling Zbl.newObject(uri, type-name).

Note that versionMajor and versionMinor should be the same as those passed in the object's qmlRegisterType() function call to ensure the same object is created in both foreground (objects created by QML) and background (objects created by Zuble) threads.

See also: Zbl::sprocketObjectConstructor

Parameters

uri	Sprocket plugin's uri
versionMajor	object's QML type major version number
versionMinor	object's QML type minor version number
qmlName	object's QML type name
createFunc	object's constructor function

Returns: true if object registered successfully, false if registration failed

Definition at line 139 of file ZblCog.cpp.

◆ validateParamCount()

bool Zbl::ZblCog::validateParamCount	(	int	actual,
		int	required
	)

protected

Definition at line 738 of file ZblCog.cpp.

Referenced by mapConfigResources().

◆ warnAbortingResourceLoad()

void Zbl::ZblCog::warnAbortingResourceLoad	(	const QString &	label,
		const QString &	reason
	)

protected

Definition at line 764 of file ZblCog.cpp.

Referenced by mapConfigResources().

◆ warnInvalidResourceCommand()

void Zbl::ZblCog::warnInvalidResourceCommand	(	const QString &	label,
		const QString &	command
	)

protected

Definition at line 751 of file ZblCog.cpp.

Referenced by mapConfigResources().

◆ zInit()

ZblCog & Zbl::ZblCog::zInit ( QObject * parent )

static

Definition at line 904 of file ZblCog.cpp.

◆ zInstance()

ZblCog & Zbl::ZblCog::zInstance ( )

static

zInstance

Returns: a reference to the one and only instance of ZblCog

Definition at line 919 of file ZblCog.cpp.

Member Data Documentation

◆ m_actionIgnore

const QString Zbl::ZblCog::m_actionIgnore = "ignore"

staticprotected

Definition at line 405 of file ZblCog.h.

Referenced by mapConfigResources().

◆ m_actionMap

const QString Zbl::ZblCog::m_actionMap = "map"

staticprotected

Definition at line 403 of file ZblCog.h.

Referenced by mapConfigResources().

◆ m_actionQmlregister

const QString Zbl::ZblCog::m_actionQmlregister = "register"

staticprotected

Definition at line 404 of file ZblCog.h.

Referenced by mapConfigResources().

◆ m_commandSeparator

const QString Zbl::ZblCog::m_commandSeparator = "::"

staticprotected

Definition at line 402 of file ZblCog.h.

Referenced by mapConfigResources().

◆ m_lock

QReadWriteLock Zbl::ZblCog::m_lock

protected

ZblCog's multithreaded lock.

Definition at line 430 of file ZblCog.h.

Referenced by createFactory(), getMappedResources(), isMappedResource(), mapResource(), registerResource(), registerSprocket(), registerSprocketObject(), and ~ZblCog().

◆ m_paramcountFile

const int Zbl::ZblCog::m_paramcountFile = 4

staticprotected

Definition at line 410 of file ZblCog.h.

Referenced by mapConfigResources().

◆ m_paramcountPlugin

const int Zbl::ZblCog::m_paramcountPlugin = 1

staticprotected

Definition at line 411 of file ZblCog.h.

Referenced by mapConfigResources().

◆ m_resources

resourceMap Zbl::ZblCog::m_resources

protected

Maps Resource plugin uri's to resource objects.

Definition at line 424 of file ZblCog.h.

Referenced by getMappedResources(), isMappedResource(), mapResource(), registerResource(), and ~ZblCog().

◆ m_restypeFile

const QString Zbl::ZblCog::m_restypeFile = "file"

staticprotected

Definition at line 406 of file ZblCog.h.

Referenced by mapConfigResources().

◆ m_restypeInvalid

const QString Zbl::ZblCog::m_restypeInvalid = "invalid"

staticprotected

Definition at line 408 of file ZblCog.h.

◆ m_restypePlugin

const QString Zbl::ZblCog::m_restypePlugin = "plugin"

staticprotected

Definition at line 407 of file ZblCog.h.

Referenced by mapConfigResources().

◆ m_sprockets

sprocketPluginMap Zbl::ZblCog::m_sprockets

protected

Maps Sprocket plugin uri's to sprocket objects.

Definition at line 418 of file ZblCog.h.

Referenced by createFactory(), registerSprocket(), registerSprocketObject(), and ~ZblCog().

◆ m_zCog

ZblCog * Zbl::ZblCog::m_zCog = 0

staticprivate

The one and only ZblCog object allowed to exist in this process.

Definition at line 440 of file ZblCog.h.

Referenced by ZblCog(), zInit(), zInstance(), and ~ZblCog().

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

zblcore/ZblCog.h
zblcore/ZblCog.cpp

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Static Protected Attributes

Static Private Attributes

Detailed Description

Member Enumeration Documentation

◆ commandFields

◆ paramFile

◆ paramPlugin

Constructor & Destructor Documentation

◆ ZblCog()

◆ ~ZblCog()

Member Function Documentation

◆ createFactory()

◆ getMappedResources()

◆ getNodeName()

◆ getPluginResParams()

◆ getPluginStringParam()

◆ isMappedResource()

◆ mapConfigResources()

◆ mapPluginResources()

◆ mapResource()

◆ registerResource()

◆ registerSprocket()

◆ registerSprocketObject()

◆ validateParamCount()

◆ warnAbortingResourceLoad()

◆ warnInvalidResourceCommand()

◆ zInit()

◆ zInstance()

Member Data Documentation

◆ m_actionIgnore

◆ m_actionMap

◆ m_actionQmlregister

◆ m_commandSeparator

◆ m_lock

◆ m_paramcountFile

◆ m_paramcountPlugin

◆ m_resources

◆ m_restypeFile

◆ m_restypeInvalid

◆ m_restypePlugin

◆ m_sprockets

◆ m_zCog