Kanzi Engine Lua API
Previous
Next
Contents
Manual
Classes
Modules

Class DataObject

Class Hierarchy

DataObject is a node in a tree of data.

All data within the data context is described as a tree of data objects. The class provides access and look-up functionality of the contained data objects.

The interface for navigating and modifying the tree of data objects mirrors the same interface as in Node2D and Node3D.

Creating data objects

To create a data object call a create function that returns one of the data objects. Those functions are DataObject:create, DataObjectInt:create, DataObjectBool:create, etc.

Example
-- Create a DataObjectString. Note that an owning reference is created.
local dataObjectStringRef = DataObjectString:create("Name", "Value")
-- It can be used in the same way non-owning references are used.
assertEq(dataObjectStringRef:getName(), "Name")

Data object tree

Kanzi arranges data objects in a tree that you can think of as a directed acyclic graph with no loops. Each data object can have multiple children but only one parent.

Constructing the data object tree

You can construct a data object tree by providing a definition schema to DataObject:create:

Example
local root = DataObject:create("root", {
    gauges = {
        speed = 91.45,
        unit = "km/h",
        fuel = 75,
        battery = 20,
    },
    turnindicator = {
        left = false,
        right = true,
    },
    navigation = {
        visualdirections = 1,
        distance = "5 mi",
        instructions = 1,
    },
    contacts = {
        { firstname = "Rob",    lastname = "Krar",  phone = "+1 (503) 123 4567", },
        { firstname = "Anna",   lastname = "Frost", phone = "+64 3-483 2081",    },
        { firstname = "Kwamie", lastname = "Liv",   phone = "+45 20 32 73 29",   },
        { firstname = "Ricky",  lastname = "Gates", phone = "+1 (303) 786 9255", },
    },
})

The types of data objects will be inferred based on the values provided. If an unknown type is provided, the function will raise an error.

Consider the following important details:

  • The order of insertion is not stable. Calling dataObject:getChild(0) can return any of the three subobjects.
  • Children can be specified only for objects with Object data type.
  • Lua arrays are converted to DataObjectListInMemory data object class. They are intended to be used in simulation scripts with all data being stored in-memory. The list can be modified with the following API:
Example
-- For the definition schema above.
root:findChild("contacts"):addItem(DataObject:create("ListItem", { firstname = "Mike", lastname = "Bron", phone = "+375 22 444 43 44" }))
root:findChild("contacts"):removeItem(1) -- removes `Anna`
assertEq(root:findChild("contacts"):getItem(2):findChild("firstname"):getValue(), "Ricky")
  • To access items, the custom Lua DataObjectListInMemory class uses the getItem function, instead of using the generic acquireItem function, even though both share the same implementation for the in-memory list. This is because acquireItem has additional semantics and requires managing resources, associated with getting said item. When writing generic code over lists, use the acquireItem and releaseItem functions.
See also DataObjectList

You can manipulate the data object tree by adding children:

Example
-- Add the `dataObjectSpeed` data object to the `root` data object, which is a root of some data source:
local dataObjectSpeed = DataObjectInt:create("Speed", 80)
root:addChild(dataObjectSpeed)

You can remove child data objects from a parent data object.

Example
-- Remove the previously added child data objects from the `root` data object.
root:removeChild(dataObjectSpeed)

Parents take ownership, and hold a reference to the children.

See also ObjectRef
Example
-- Release a Lua reference. Note that data objects take ownership of their children.
-- But since previously `removeChild` was executed, this will release the reference.
dataObjectSpeed = nil

-- The reference is kept alive by Lua Runtime until garbage collected. You can optionally force Lua garbage collection.
collectgarbage() -- Marks `dataObjectSpeed` for GC.
collectgarbage() -- Deletes `dataObjectSpeed`.

Iterating the data object tree

You can iterate over the data object children by using iterators.

Example
for child in root:iterateChildren() do
    print(child:getName())
end

While you are iterating over a collection, modifying it is not safe.

Example
for child in root:iterateChildren() do
    root:removeAllChildren() -- Bad. Will crash Kanzi Engine.
end

Finding data objects

Usually you should search for data objects from DataSource through DataContext interface:

Example
local speedObject = dataSource:lookupDataContext("vehicle.cluster.speed")

If lookup fails, Kanzi returns nil.

Inherits properties and message types from DataObjectMetadata.

Synopsis

Methods
create()

Creates an instance of DataObject
getName()

Retrieves the name of the object
setName()

Sets the name of the data object
getType()

Allows to retrieve the type of the object
setParent()

Assigns a parent data object to this object
getParent()

Retrieves the parent data object of this object
getChildCount()

Retrieves the count of child objects in this data object
getChild()

Retrieves a child object at the given index
getChildIndex()

Retrieves the index of a child data object
findChild()

Tries to find a child with the given name
hasChild()

Checks whether or not the child data object exists
addChild()

Adds the data object as a child of this object
insertChild()

Inserts the data object as a child of this object, allows to specify index of the object
removeChildAtIndex()

Removes a child object at the given index
removeChild()

Removes a child object from the list of children
removeAllChildren()

Removes all children
iterateChildren()

Returns an iterator used to iterate over children of the data object
DataObject.DataObject:create(objectName, schema)

Creates an instance of DataObject.

Parameters
objectName (string)

The name of the object.
schema (table or nil)

Optional table definining data object tree.
DataObject.DataObject:getName()

Retrieves the name of the object.

Return Values
(string)

The name of the object.
DataObject.DataObject:setName(name)

Sets the name of the data object.

Parameters
name (string)

The name.
DataObject.DataObject:getType(objectName)

Allows to retrieve the type of the object.

Return Values
(DataObjectType)

Returns the type of the object.
DataObject.DataObject:setParent(parent)

Assigns a parent data object to this object.

Parameters
parent (DataObject)

Parent DataObject to assign.
DataObject.DataObject:getParent()

Retrieves the parent data object of this object.

Return Values
(DataObject)

The parent DataObject of this DataObject.
DataObject.DataObject:getChildCount()

Retrieves the count of child objects in this data object.

Return Values
(number)

Child object count.
DataObject.DataObject:getChild(index)

Retrieves a child object at the given index.

Parameters
index (number)

Index of the child.
Return Values
(DataObject)

Child data object at the given index.
DataObject.DataObject:getChildIndex(child)

Retrieves the index of a child data object.

Parameters
child (DataObject)

Child DataObject which index to get.
Return Values
(number)

Index of the item in question.
DataObject.DataObject:findChild(childName)

Tries to find a child with the given name.

Return Values
(DataObject or nil)

Child object that was found, or nil if there is no such child.
DataObject.DataObject:hasChild(child)

Checks whether or not the child data object exists.

Parameters
child (DataObject)

Child to check.
Return Values
(boolean)

true if there is such child, otherwise false.
DataObject.DataObject:addChild(child)

Adds the data object as a child of this object.

Parameters
child (DataObject)

Child object to add.
DataObject.DataObject:insertChild(index, child)

Inserts the data object as a child of this object, allows to specify index of the object.

Parameters
index (number)

Index where to add the given object.
child (DataObject)

Child object to add.
DataObject.DataObject:removeChildAtIndex(index)

Removes a child object at the given index.

Parameters
index (number)

Index of the child object to remove.
DataObject.DataObject:removeChild(child)

Removes a child object from the list of children.

Parameters
child (DataObject)

Child object to remove.
DataObject.DataObject:removeAllChildren()

Removes all children.

DataObject.DataObject:iterateChildren()

Returns an iterator used to iterate over children of the data object.