state

Object State Database Access

A Summit application may need to communicate state information to the larger world. The Object State Database is one way this can be accomplished.

Classes

Name Summary
State

Represents a connection to the Object State Database.

Functions

Name Summary
get

Get a state object with a given name

query

Query for states based on property values

Fields

Name Type Summary
me

State

State for the current Summit State.

Classes : state

State

Represents a connection to the Object State Database.

This is not intented to be instantiated directly. Use the me field to access the current Summit state.

Usage
local state = require 'summit.state'
state.me:add('foo', 'bar')
state.me:commit()
print(state.me.properties)  -- prints {foo="bar"}
Fields
Name Type Summary
properties

table

A table representing the channel state.

Functions
Name Returns Summary
add(key, value)

nil

Stage an addition of the given key and its value to the state properties table.

clear_pending_updates()

nil

Clear pending updates.

commit()

1: string

2: string

Commit pending updates.

remove(key)

nil

Stage a removal from the state properties table.

update(key, value)

nil

Stage an update of the given key’s value to the state properties table.

State:add(key, value)

Stage an addition of the given key and its value to the state properties table.

Parameters
Name Type Default Summary

key

string

Key to add to the state properties table.

value

string

Value associated with the key added to the state properties table.

Returns
Type Summary

nil

Usage
local state = require 'summit.state'
state.me:add('foo', 'bar')

State:clear_pending_updates()

Clear pending updates. Useful if after staging a bunch of changes, you decide to not do them. This is something like a rollback in database lingo.

Returns
Type Summary

nil

Usage
local state = require 'summit.state'
state.me:add('foo', 'bar')
state.me:clear_pending_updates()

State:commit()

Commit pending updates.

Returns
Type Summary

string

'OK' if successful or nil on error

string

nil if successful, error_message otherwise

Usage
local state = require 'summit.state'
state.me:add('foo', 'bar')
state.me:commit()

State:remove(key)

Stage a removal from the state properties table.

Parameters
Name Type Default Summary

key

string

Key to be removed along with its value from the state properties able.

Returns
Type Summary

nil

Usage
local state = require 'summit.state'
state.me:remove('foo')

State:update(key, value)

Stage an update of the given key’s value to the state properties table.

Parameters
Name Type Default Summary

key

string

Key whose value will be updated.

value

string

Updated value to be stored in the state properties table.

Returns
Type Summary

nil

Usage
local state = require 'summit.state'
state.me:update('foo', 'zip')

Functions : state

get(name)

Get a state object with a given name If you know the name of the state object you are interested in, you can go retrieve it by name with this function.

Parameters
Name Type Default Summary

name

string

The name of some interesting State object.

Returns
Type Summary

State

if successful, nil otherwise

nil

if successful, Error message otherwise. One possible error message is “Not found”

Usage
local state = require 'summit.state'
result, err = state.get(channel.data.channel_id)
if result then
    if result.properties.channel_id == channel.data.channel_id then
        print("This is expected")
    else
        print("This is not expected")
    end
else
    print("There was an error: "..tostring(err))
end

query(query)

Query for states based on property values Get all object states that match your query. A query is a table, for example, the query {localnumber=“1234”,“remotenumber=4145551212”} will find all channels that have localnumber == 1234 AND remotenumber == 4145551212. The result is an array of State objects that can be manipulated like any other of its kind.

Parameters
Name Type Default Summary

query

table

The Query

Returns
Type Summary

table

array of State objects if successful, nil otherwise

string

nil if successful, error_message otherwise

Usage
local state = require 'summit.state'
results, err = state.query({applictaion_name="myapp"})
if results then
    num_calls_to_myapp = #results
end

Fields : state

me

Type: State

State for the current Summit State.