Base class for all objects that are executable within a workspace. More...

#include <Workspace/DataExecution/Execution/updatable.h>

Inheritance diagram for Updatable:

Public Member Functions
	~Updatable () override

virtual bool	comesFromExternal () const

QString	getEnclosingScope () const

virtual Updatable *	getFromPath (const QString &path, Workspace &relativeTo, QStringList &errors) const =0

const QString &	getGlobalName () const

virtual QString	getIdPath (bool scoped=true) const =0

virtual Workspace *	getRootWorkspace ()

virtual const Workspace *	getRootWorkspace () const

QString	getScopedGlobalName () const

virtual bool	getUpToDate () const =0

virtual const Workspace *	getWorkspace () const =0

virtual Workspace *	getWorkspace ()=0

virtual void	idPathChanged ()

virtual bool	isConnectedToAsynchronous () const =0

virtual bool	isWaitingForAsynchronousUpdate () const =0

void	setGlobalName (const QString &name)

virtual void	setUpToDate (bool b)=0

virtual bool	update (Updater *updater=nullptr)=0

Public Member Functions inherited from Observable
virtual	~Observable ()

void	attachObserver (Observer &observer)

void	destroy ()

void	detachObserver (Observer &observer)

void	notifyEvent (const ObservableEvent &event)

Public Member Functions inherited from Serialize
virtual	~Serialize ()=default

virtual bool	canSerialize () const =0

virtual bool	load (const SerializedItem &item)=0

virtual bool	save (SerializedItem &item) const =0

Static Public Member Functions
static InputScalar *	findInputScalarGlobalName (const QString &scopedGlobalName, Workspace &relativeTo)

static IOBase *	findIOBaseGlobalName (const QString &scopedGlobalName, Workspace &relativeTo)

static Operation *	findOperationGlobalName (const QString &scopedGlobalName, Workspace &relativeTo)

Protected Member Functions
	Updatable ()

	Updatable (const Updatable &up)

void	notifyUpdated ()

Updatable &	operator= (const Updatable &up)

Protected Member Functions inherited from Observable
	Observable ()

	Observable (const Observable &)

Detailed Description

Updatable implies that an object has an up to date status which can be queried or set, and that clients can request that the object be brought up to date. Subclasses generally call notifyUpdated() when their setUpToDate() function is called with a true parameter. This allows clients to be notified when an object is brought up to data and to then update their own internal state to reflect the change.

See also: UpdateEvent

Constructor & Destructor Documentation

◆ Updatable() [1/2]

Updatable ( )

protected

◆ Updatable() [2/2]

Updatable ( const Updatable & up )

protected

◆ ~Updatable()

~Updatable ( )

overridedefault

Member Function Documentation

◆ comesFromExternal()

bool comesFromExternal ( ) const

virtual

Returns: True if this object is from a workspace that was loaded from an external reference. This is normally used to determine if the item should be saved along with its parent workspace or if the object can be modified interactively by the user (workspace execution is always allowed to modify objects regardless of where they came from).

Reimplemented in Workspace.

◆ findInputScalarGlobalName()

InputScalar * findInputScalarGlobalName	(	const QString &	scopedGlobalName,
		Workspace &	relativeTo
	)

static

◆ findIOBaseGlobalName()

IOBase * findIOBaseGlobalName	(	const QString &	scopedGlobalName,
		Workspace &	relativeTo
	)

static

◆ findOperationGlobalName()

Operation * findOperationGlobalName	(	const QString &	scopedGlobalName,
		Workspace &	relativeTo
	)

static

◆ getEnclosingScope()

QString getEnclosingScope ( ) const

◆ getFromPath()

virtual Updatable * getFromPath	(	const QString &	path,
		Workspace &	relativeTo,
		QStringList &	errors
	)		const

pure virtual

Parameters

path	The global path for which an updatable object should be found.
relativeTo	The workspace where the search for path should begin. If path is relative, then it will be treated as relative to relativeTo.
errors	Upon exit, this will hold any errors encountered when trying to find an updatable object that matches path.

Returns: A pointer to the updatable object that matches path, or a null pointer if no such object could be found.

Implemented in Connection, IOBase, and Operation.

◆ getGlobalName()

const QString & getGlobalName ( ) const

Returns: The global name assigned to this object.

See also: setGlobalName()

◆ getIdPath()

virtual QString getIdPath ( bool scoped = true ) const

pure virtual

Parameters

scoped If true then return full scope of the item. If false, only return identifier local to its workflow.

Returns: The string that represents the global path to this object using the numeric ID notation. Note that the global name can always be obtained from getGlobalName() so this function is only needed when the ID path is required, typically because the caller cannot handle situations where a global name could potentially be used more than once across the whole workspace hierarchy (in which case the path/global name would not be sufficient to uniquely identify the object). If this string is passed as the first parameter to getFromPath(), we should get this object back again unless it is an empty string. An empty string would normally indicate that this type of updatable object does not have path global support.

Implemented in Connection, IOBase, and Operation.

◆ getRootWorkspace() [1/2]

Workspace * getRootWorkspace ( )

virtual

Returns: The root workspace this updatable object resides in or a null pointer if it is not part of a workspace.

Reimplemented in IOBase, and Workspace.

◆ getRootWorkspace() [2/2]

const Workspace * getRootWorkspace ( ) const

virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Reimplemented in IOBase, and Workspace.

◆ getScopedGlobalName()

QString getScopedGlobalName ( ) const

◆ getUpToDate()

virtual bool getUpToDate ( ) const

pure virtual

Returns: True if this object is up to date. For container-type objects, such as array inputs, it must return true only if all items in the container are themselves up to date.

See also: setUpToDate(), update()

Implemented in Connection, InputArray, InputScalar, Output, Operation, and IOBase.

◆ getWorkspace() [1/2]

virtual const Workspace * getWorkspace ( ) const

pure virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Implemented in IOBase, and WorkspaceElement.

◆ getWorkspace() [2/2]

virtual Workspace * getWorkspace ( )

pure virtual

Returns: The workspace this Updatable object belongs to, or a null pointer if it is not currently part of a workspace.

Implemented in IOBase, and WorkspaceElement.

◆ idPathChanged()

virtual void idPathChanged ( )

inlinevirtual

Sub-classes should override this if they want to control notifications in response to ancestry changes.

Reimplemented in Operation, and Workspace.

◆ isConnectedToAsynchronous()

virtual bool isConnectedToAsynchronous ( ) const

pure virtual

Returns: True if the updatable object is connected to an asynchronous updatable.

See also: isWaitingForAsynchronousUpdate(), update()

Implemented in Connection, InputArray, InputScalar, Output, Operation, and Workspace.

◆ isWaitingForAsynchronousUpdate()

virtual bool isWaitingForAsynchronousUpdate ( ) const

pure virtual

Returns: True if the updatable object is waiting for an asynchronous update.

See also: update()

Implemented in Connection, InputArray, InputScalar, Output, Operation, and Workspace.

◆ notifyUpdated()

void notifyUpdated ( )

protected

Called by subclasses when they can confirm that the underlying data for this object has been brought up to date. This is usually done within setUpToDate() and only when the parameter passed to that function is true.

◆ operator=()

Updatable & operator= ( const Updatable & up )

protected

◆ setGlobalName()

void setGlobalName ( const QString & name )

Parameters

name	The global name to assign to this object.

The global name of a particular type of object is meant to be unique across the entire workspace hierarchy for the particular type, or set of types. For instance, global names for inputs and outputs must be unique across all inputs and outputs because they are treated at the IOBase level. Operations must be unique among all types of operations from the top level workspace down because they are treated at the Operation level.

The main use of global names is to provide an easy identifier for workspace widgets and in particular for .ui files to use when associating widgets with updatable objects. By using a global name, the actual structure of the workspace hierarchy and their associated operations is unimportant. The user is free to move things around and organize their workspaces however they like. The next time they load the .ui file, the widgets will be connected up to the updatable objects even if they were shifted as long as the global name is still defined for the relevant type of updatable object.

A global name may only contain letters (upper and lower case), numbers, spaces, underscores, hyphens and plus symbols. All other characters are forbidden. An attempt to set a name containining any forbidden characters will result in the global name being left unmodified.

Note that having more than one object of a certain type with the same global name is not an error, but it is something that should generally be avoided. If more than one object uses a given name, then widgets can no longer reliably find them by their global name. They will find an object, but not necessarily the one you want. Hence, clients should do their own processing to ensure global name uniqueness in their workspace hierarchy.

The default value for the global name is an empty string. The data path returned from getDataPath() will rely on the operation id path instead of a global name in such instances.

See also: getDataPath()

◆ setUpToDate()

virtual void setUpToDate ( bool b )

pure virtual

Parameters

b	Boolean value specifying the new up-to-date status of the object.

Precondition: If this object belongs to a workspace and that workspace's execution thread is running, setUpToDate() must only be called from that execution thread. If the execution thread is not running or there is no execution thread (or perhaps not even a workspace), then setUpToDate() may be called from any thread with appropriate thread protection being the responsibility of the caller.

If b is false, the call must also try to propagate forward the not up-to-date status through the workspace. The forward propagation must continue until it reaches something already not up to date. Note that for container-type objects (eg array inputs), the up-to-date status is controlled by all items in the container, so calling setUpToDate() doesn't actually change the status for a container as a whole. In that case, all it does is propagate forward the status as necessary.

Note that when is true, some subclasses may choose to raise some kind of event notification to let clients know that they have been brought up to date. Since this will have an impact on performance even if nothing is observing the event, subclasses should avoid making such notifications if it is not necessary.

See also: update(), getUpToDate()

Implemented in Connection, InputArray, InputScalar, Output, WorkspaceInput, WorkspaceOutput, Operation, Workspace, IOBase, and QuerySqlDatabase.

◆ update()

virtual bool update ( Updater * updater = nullptr )

pure virtual

Parameters

updater The execution thread that is calling the function. When the object is being updated from within a workspace, this parameter will normally hold the execution thread that is calling this function. If the object is not part of a workspace or is being updated from client code directly in some other way, this parameter should be a null pointer to indicate that execution is not under the control of an Updater object. This is crucial for robust handling of things like logging messages.

Calling this function attempts to bring the object up to date. For objects connected in a workspace, this must first bring all upstream dependencies up to date as required. Some updatables can update themselves asynchronously. In such instances update() will return false if an updatable is still being updated (asynchronously). In order to determine if an update() returned false because of a genuine failure or because the update is asynchronous (and still in progress) the isWaitingForAsynchronousUpdate() method should be queried to help determine the cause of the update failure.

Returns: True if the update was successful.

Postcondition: Exactly what "up to date" means is up to the subclass, but if update() returns true, then getUpToDate() must also return true immediately after update() returns.

See also: setUpToDate(), getUpToDate(), isWaitingForAsynchronousUpdate()

Implemented in Connection, InputArray, InputScalar, Output, PlaceHolder, Operation, Workspace, and IOBase.

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Updatable() [1/2]

◆ Updatable() [2/2]

◆ ~Updatable()

Member Function Documentation

◆ comesFromExternal()

◆ findInputScalarGlobalName()

◆ findIOBaseGlobalName()

◆ findOperationGlobalName()

◆ getEnclosingScope()

◆ getFromPath()

◆ getGlobalName()

◆ getIdPath()

◆ getRootWorkspace() [1/2]

◆ getRootWorkspace() [2/2]

◆ getScopedGlobalName()

◆ getUpToDate()

◆ getWorkspace() [1/2]

◆ getWorkspace() [2/2]

◆ idPathChanged()

◆ isConnectedToAsynchronous()

◆ isWaitingForAsynchronousUpdate()

◆ notifyUpdated()

◆ operator=()

◆ setGlobalName()

◆ setUpToDate()

◆ update()