Base class for all data objects. More...

#include <Workspace/DataExecution/DataObjects/dataobject.h>

Inheritance diagram for DataObject:

Public Member Functions
template<typename T >
DataObject *	adaptTo (bool copy=false)

template<typename T >
const DataObject *	adaptTo (bool copy=false) const

void	assign (const DataObject &src)

virtual void	clearData ()=0

DataObject *	clone () const

bool	compareData (const DataObject &other) const

bool	compareData (const DataObject &other, int &relationship) const

virtual bool	contains (const void *data) const =0

virtual bool	containsData (const DataObject &object) const =0

void	destroy ()

virtual void	ensureHasData (bool recurse=true)=0

virtual bool	fromQVariant (const QVariant &v)=0

virtual const ObjectGroup *	getAsObjectGroup () const =0

virtual ObjectGroup *	getAsObjectGroup ()=0

template<typename T >
T *	getData ()

template<typename T >
const T *	getData () const

virtual const DataFactory &	getFactory () const =0

template<typename T >
T &	getRawData ()

template<typename T >
const T &	getRawData () const

virtual TypeAdaptor *	getTypeAdaptor (const DataFactory &factory) const

virtual bool	hasData (bool recurse=true) const =0

bool	isObjectGroup () const

template<typename T >
bool	isType () const

bool	isType (const DataFactory &type) const

bool	matchesType (const DataObject &otherObject) const

virtual bool	ownsData () const =0

virtual void	setOwnsData (bool b)=0

bool	sharesData (const DataObject &otherObject) const

virtual QVariant	toQVariant () const =0

virtual void	useData (DataObject &obj, bool transferOwnership=false)=0

bool	useDataClone (const DataObject &obj)

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

Detailed Description

All subclasses of DataObject should act more or less like pointers to a particular type (more accurately, like smart pointers).

Member Function Documentation

◆ adaptTo() [1/2]

DataObject * adaptTo ( bool copy = false )

inline

Precondition: hasData() must be true.

Template Parameters

T	The target datatype to which to adapt.

Parameters

copy	True if the adaptor should be a unique copy of the source (some adaptor can reference existing data)

Returns: A new DataObject of the target datatype. It is the responsibility of the caller to delete the object when they have finished with it.

Adapts this DataObject into a DataObject of the specified type, if possible without copying the underlying data. The adaption occurs only if this particular DataObject is of a type that has a registered TypeAdaptorFactory that knows how to convert it into the specified type (e.g. a registered DerivedToBaseAdaptor or AssignmentAdaptor).

See also: bool CSIRO::DataExecution::adaptDataObject(DataObject& src, TypedObject<DestType>& dest, bool copy); bool CSIRO::DataExecution::adaptDataObject(DataObject& src, DataObject& dest, bool copy);

◆ adaptTo() [2/2]

const DataObject * adaptTo ( bool copy = false ) const

inline

◆ assign()

void assign ( const DataObject & src )

Parameters

src	A data object which must be of the same type as this one. More accurately, the data factory must be able to assign to this object from src.

Precondition: There must already be valid underlying data to assign to. This can be enforced by calling ensureHasData before the call to assign.

◆ clearData()

virtual void clearData ( )

pure virtual

Clear the underlying data being held by this object. Clients should not normally need to call this function.

◆ clone()

DataObject * clone ( ) const

Returns: A copy of this DataObject. If the underlying data object doesn't exist, the clone will also hold no data object (it is not an error to clone a DataObject which does not yet hold any data).

This is merely a convenience function which delegates the clone operation to DataFactory::cloneDataObject.

◆ compareData() [1/2]

bool compareData ( const DataObject & other ) const

Parameters

other The other data object to compare to. The type of the two objects must match.

Returns

◆ compareData() [2/2]

bool compareData	(	const DataObject &	other,
		int &	relationship
	)		const

Parameters

other	The other data object to compare to. The type of the two objects must match.
relationship	(out) The relationship between the two objects: If this < other, relationship will be < 0. If this == other, relationship will == 0. If this > other, relationship will be > 0.

◆ contains()

virtual bool contains ( const void * data ) const

pure virtual

Parameters

data	The data we are comparing the the data objects underyling data.

Returns: True if this object's underlying data matches the address of the specified data. False if the pointers do not match, or the incoming pointer is null.

◆ containsData()

virtual bool containsData ( const DataObject & object ) const

pure virtual

Parameters

object The data object we are comparing the data objects underlying data.

Returns: True if this object's underlying data matches the address of the data in the underlying object. False if the pointers do not match, or the incoming pointer is null.

◆ destroy()

void destroy ( )

Destroy this object, which should have been created by a call to clone or by DataFactory::cloneDataObject from this object's factory. Calling destroy() essentially makes the object self-destruct.

This is merely a convenience function which delegates the destroy operation to DataFactory::destroyDataObject.

◆ ensureHasData()

virtual void ensureHasData ( bool recurse = true )

pure virtual

Parameters

recurse If true, ensure not only this object has valid data, but all child objects if this is an object group. The recursion also continues for all subsequent groups below this one too.

Call this function to ensure that we are holding a valid data object. Any new objects created by this call will be owned by the DataObject associated with that particular data (ie that level in the hierarchy).

◆ fromQVariant()

virtual bool fromQVariant ( const QVariant & v )

pure virtual

Parameters

v	The value to store in this data object.

The subclass implementation should take care to handle the case where the data stored in v cannot be converted to the underlying data type. Ideally, the implementation should also consider performance impacts of the conversion and avoid any unnecessary cloning, copy or memory allocation for temporary objects. In most cases, the TypedObject class template will handle these things sensibly, so there should be little need to manually write code for this.

Returns: True if the value could be set, or false otherwise. Note that it is up to the implementation what "success" means, but as a rule of thumb there should be no data loss as a result of calling setValue(toQVariant()).

◆ getAsObjectGroup() [1/2]

virtual const ObjectGroup * getAsObjectGroup ( ) 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.

◆ getAsObjectGroup() [2/2]

virtual ObjectGroup * getAsObjectGroup ( )

pure virtual

Returns: A pointer to the underlying data as an ObjectGroup, or if the underlying data is not derived from ObjectGroup, return a null pointer. Note that if hasData() returns false, then this function will also return a null pointer even if T is derived from ObjectGroup.

◆ getData() [1/2]

T * getData ( )

inline

This function is templated on the type the user expects the data object to hold. It allows to access the underlying data. The difference with getRawData() is this function does not throw any exceptions in case of an error but rather return a nullptr.

Returns: The pointer to the underlying data, or nullptr if either the underlying data is of a different type than the one expected by the user or the object does not have any data.

◆ getData() [2/2]

const T * getData ( ) const

inline

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

◆ getFactory()

virtual const DataFactory & getFactory ( ) const

pure virtual

Returns: The data factory for this object type.

◆ getRawData() [1/2]

T & getRawData ( )

inline

Precondition: The object must contain data of type T and the result of hasData(false) must be true.

This function is templated on the type you are expecting the data object to hold. It is merely a convenience wrapper around DataFactoryTraits<T>::getData() to make client code more compact and easier to read. This function should be used in preference to explicitly casting to a TypedObject<T>.

Returns: A reference to the underlying data of the object.

◆ getRawData() [2/2]

const T & getRawData ( ) const

inline

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

◆ getTypeAdaptor()

TypeAdaptor * getTypeAdaptor ( const DataFactory & factory ) const

virtual

Returns: The type adaptor factory for the specified data factory, if it exists.

◆ hasData()

virtual bool hasData ( bool recurse = true ) const

pure virtual

Parameters

recurse If true, test not only this object, but all child objects if this is an object group. The recursion also continues for all subsequent groups below this one too.

Returns: True if this object has valid data. If recurse is true, it will only return true if this object and all its descendents have valid data.

◆ isObjectGroup()

bool isObjectGroup ( ) const

Returns: True if this DataObject holds an ObjectGroup subclass.

This function is purely a convenience. It simply calls the same-named function on its data factory.

◆ isType() [1/2]

bool isType ( ) const

inline

Returns: True if the object's type matches the specified type. False otherwise. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Template function for testing the type of the DataObject. Shorthand for:

&object.getFactory() == &DataFactoryTraits<T>::getInstance()

◆ isType() [2/2]

bool isType ( const DataFactory & type ) const

inline

Returns: True if the object's type matches the specified type. False otherwise. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Utility function for testing the type of the object. Shorthand for:

&object.getFactory() == &type

◆ matchesType()

bool matchesType ( const DataObject & otherObject ) const

inline

Returns: True if the object's type matches the type of the other object. False otherwise.

Utility function for testing whether the data types of two DataObjects match. Shorthand for:

&object.getFactory() == &otherObject.getFactory()

◆ ownsData()

virtual bool ownsData ( ) const

pure virtual

The underlying data can be owned by another DataObject, in which case the caller must be very careful to ensure that access to the underlying data is only attempted at times when it can be guaranteed that the owner still exists. When a DataObject is deleted, it will delete its underlying data only if it owns that data. At certain other times, such as during assignment, a DataObject may also delete its underlying data, but again only if it owns that data.

Returns: True if this object owns its data.

See also: setOwnsData(), useData()

◆ setOwnsData()

virtual void setOwnsData ( bool b )

pure virtual

Parameters

b	If this is true, then the data object will own the underlying data it is currently holding until it either deletes that data, has ownership removed with another call to setOwnsData() or some other action is performed which causes the underlying data to be replaced or cleared.

Note: Client code would not normally call this function. It is used by the workspace internally to manage the transfer of ownership from one data object to another.

See also: ownsData(), useData()

◆ sharesData()

bool sharesData ( const DataObject & otherObject ) const

Returns: True if the otherObject is using the same object as this object.

See also: DataFactory::sharesData()

◆ toQVariant()

virtual QVariant toQVariant ( ) const

pure virtual

Returns: This data object converted to a QVariant (it should always be a copy, never the original data, except for when the underlying type is already QVariant).

◆ useData()

virtual void useData	(	DataObject &	obj,
		bool	transferOwnership = `false`
	)

pure virtual

Parameters

obj	The DataObject whose underlying data is to be shared.
transferOwnership	If this parameter is true, then ownership will be transferred from obj to this object. Transfer of ownership must be carried out by calling setOwnsData() on obj at the appropriate point. Note that it is an error to set this parameter to true if obj does not own the data when passed into this function.

This function is not often used outside of core workspace code or code related to polymorphic operations. The caller is responsible for ensuring that obj is exactly the same data type as this one (ie no adaptors can be involved). Failure to obey this rule will almost certainly result in crashes.

If you want to make a DataObject hold an existing data item, such as one that you dynamically create and want to pass ownership to the DataObject, you need to use DataFactoryTraits::setData() instead. The rationale for this is that DataFactoryTraits requires a template type to be specified, so its setData() member function will be able to perform checks that the DataObject is of the correct type to hold the data being passed to it.

See also: ownsData(), setOwnsData(), DataFactoryTraits::setData()

◆ useDataClone()

bool useDataClone ( const DataObject & obj )

Parameters

obj	The DataObject whose underlying data is to be cloned and embedded within this data object. This object will take ownership of the cloned data.

Convenience method similar to useData. Clones obj and assumes ownership of its data. Similar to assign(), but rather than using the assignment operator, clones a completely new object and assumes ownership of it.

Note: The data type must be Clonable.

See also: useData(), ownsData(), setOwnsData(), DataFactoryTraits::setData()

Public Member Functions

Detailed Description

Member Function Documentation

◆ adaptTo() [1/2]

◆ adaptTo() [2/2]

◆ assign()

◆ clearData()

◆ clone()

◆ compareData() [1/2]

◆ compareData() [2/2]

◆ contains()

◆ containsData()

◆ destroy()

◆ ensureHasData()

◆ fromQVariant()

◆ getAsObjectGroup() [1/2]

◆ getAsObjectGroup() [2/2]

◆ getData() [1/2]

◆ getData() [2/2]

◆ getFactory()

◆ getRawData() [1/2]

◆ getRawData() [2/2]

◆ getTypeAdaptor()

◆ hasData()

◆ isObjectGroup()

◆ isType() [1/2]

◆ isType() [2/2]

◆ matchesType()

◆ ownsData()

◆ setOwnsData()

◆ sharesData()

◆ toQVariant()

◆ useData()

◆ useDataClone()