Row

com.apama.memorystore
Event Row

Represents an ordered and typed set of named fields in a table, with a key that uniquely identifies the row within the table.

A Row is an atomic snapshot of the data in the table and once returned, a Row's contents are guaranteed to be consistent and unchanging.

Any changes the user makes to a Row are local until commit is called.

See Also:: com.apama.memorystore.Table - A table holds a collection of rows.

Action summary
`void`	`commit()` Try to commit changes from this Row back to the table, which could result in an exception being thrown if the Row is not up to date.
`void`	`copy(com.apama.memorystore.Row other)` Copy the contents of the specified other Row into this one.
`void`	`forceCommit()` Commit this Row back to the table even if the Row is not up to date.
`any`	`get(string name)` Get the value of the specified field in this row (can be used on all types). This will return a string for types that cannot be stored. Use getParsed() to parse to a type.
`any`	`getAll(any prototype)` Fill in value of all keys in the supplied 'any' with values from the row.
`boolean`	`getBoolean(string name)` Get the value of the specified field in this row (must only be used on boolean fields).
`decimal`	`getDecimal(string name)` Get the value of the specified field in this row (must only be used on decimal fields).
`float`	`getFloat(string name)` Get the value of the specified field in this row (must only be used on float fields).
`integer`	`getInteger(string name)` Get the value of the specified field in this row (must only be used on integer fields).
`string`	`getKey()` Get the key for this Row.
`sequence<string>`	`getKeys()` Get all of the field names held in this Row. These are all of the valid values that can be passed to get(). Will include all Schema field names followed by any extra fields if the driver supports them.
`any`	`getParsed(string name, string typeName)` Get the value of the specified field in this row parsed to the specified typeName.
`string`	`getStoreName()` Get the name of the Store that contains this Row's Table.
`string`	`getString(string name)` Get the value of the specified field in this row (must only be used on string fields).
`string`	`getTableName()` Get the name of the Table that contains this Row.
`boolean`	`inTable()` Indicate whether this row was in the table when the Row was created or updated.
`void`	`remove()` Mark the row for deletion when the table is committed.
`void`	`removeNonSchema(string name)` Remove a non-schema field from the row.
`void`	`set(string name, any value)` Set the value of the specified field in this row (can be used with all types). Will use the string form if needed.
`void`	`setAll(any value)` Set all values in this row from all available fields in the supplied any type.
`void`	`setBoolean(string name, boolean b)` Set the value of the specified field in this row (must only be used on boolean fields).
`void`	`setDecimal(string name, decimal d)` Set the value of the specified field in this row (must only be used on decimal fields).
`void`	`setFloat(string name, float f)` Set the value of the specified field in this row (must only be used on float fields).
`void`	`setInteger(string name, integer i)` Set the value of the specified field in this row (must only be used on integer fields).
`void`	`setString(string name, string s)` Set the value of the specified field in this row (must only be used on string fields).
`any`	`toAny()` Get the row as an any using the type the Store was created with (using prepareFromAny() or prepareFromTypeName()).
`dictionary<string, any>`	`toDictionary()` Get a dictionary copy of the Row.
`boolean`	`tryCommit()` Try to commit changes from this Row back to the table, returning false if the Row is not up to date.
`boolean`	`tryCommitOrUpdate()` Try to commit, or update (losing local modifications) if not.
`void`	`update()` Update the local Row event to reflect the current state of the shared MemoryStore table, losing any local modifications.

Action detail

commit

void commit()

Try to commit changes from this Row back to the table, which could result in an exception being thrown if the Row is not up to date.

If nothing else has modified the row in the table since this Row was created, the changes are committed so other users can see them.

Otherwise, an exception is thrown and the table is left unchanged.

If there is any chance that the same row may be written to concurrently - for example by multiple correlator contexts, and/or if using a distributed MemoryStore - use Row.tryCommit() instead of Row.commit() so that it is possible to recover from this situation when it occurs or use Row.forceCommit() to commit the changes forcefully.

Note that a MemoryStore commit operation synchronously writes changes made to the local Row instance back to the table which is shared by all monitors inside the Correlator (or the distributed store), but does not cause a persistent write to disk (see Table#persist).

See Also:: com.apama.memorystore.Row.tryCommit(); com.apama.memorystore.Row.tryCommitOrUpdate()

copy

void copy(com.apama.memorystore.Row other)

Copy the contents of the specified other Row into this one.

The two rows that these Row events represent must have the same schema but they need not be in the same table.

r1.copy(r2) is a more efficient equivalent to r1.setX("a", r2.getX("a")) for every field.

You cannot copy a row between a correlator-persistent store and an in-memory, on-disk or distributed store.

Parameters:: other

forceCommit

void forceCommit()

Commit this Row back to the table even if the Row is not up to date.

If this Row is marked for deletion using Row.remove() then forceCommit will unconditionally remove the Row from the table.

Note that a MemoryStore commit operation synchronously writes changes made to the local Row instance back to the table which is shared by all monitors inside the Correlator (or the distributed store), but does not cause a persistent write to disk (see Table#persist).

get

any get(string name)

Get the value of the specified field in this row (can be used on all types). This will return a string for types that cannot be stored. Use getParsed() to parse to a type.

An exception will be thrown if the specified field name is not present in this row.

If it is not known whether the field name exists or not, use getKeys().indexOf(...) to find out, or use toDictionary.getOr(...).

Parameters:: name

Since:: 10.1

See Also:: com.apama.memorystore.Row.getParsed()

getAll

any getAll(any prototype)

Fill in value of all keys in the supplied 'any' with values from the row.

Parameters:: prototype - Any type value (an event or non-empty dictionary) which will be modified in-place with the current values from this row.

Returns:: The same instance passed in as prototype, filled in with values from this row.

Since:: 10.1

getBoolean

boolean getBoolean(string name)

Get the value of the specified field in this row (must only be used on boolean fields).

Parameters:: name

getDecimal

decimal getDecimal(string name)

Get the value of the specified field in this row (must only be used on decimal fields).

Parameters:: name

getFloat

float getFloat(string name)

Get the value of the specified field in this row (must only be used on float fields).

Parameters:: name

getInteger

integer getInteger(string name)

Get the value of the specified field in this row (must only be used on integer fields).

Parameters:: name

getKey

string getKey()

Get the key for this Row.

It cannot be changed.

getKeys

sequence<string> getKeys()

Get all of the field names held in this Row. These are all of the valid values that can be passed to get(). Will include all Schema field names followed by any extra fields if the driver supports them.

Since:: 10.1

getParsed

any getParsed(string name, string typeName)

Get the value of the specified field in this row parsed to the specified typeName.

Parameters:: name; typeName

Since:: 10.1

getStoreName

string getStoreName()

Get the name of the Store that contains this Row's Table.

getString

string getString(string name)

Get the value of the specified field in this row (must only be used on string fields).

Parameters:: name

getTableName

string getTableName()

Get the name of the Table that contains this Row.

inTable

boolean inTable()

Indicate whether this row was in the table when the Row was created or updated.

It is possible to construct a Row that has no corresponding entry in the table, in which case all fields have default values.

Calling commit on a Row for which inTable()=false will create the row.

remove

void remove()

Mark the row for deletion when the table is committed.

Fields cannot be accessed after this call, until the removal is successfully committed (or reverted using update).

removeNonSchema

void removeNonSchema(string name)

Remove a non-schema field from the row.

Only functions on non-schema fields with a supported distributed store.

Parameters:: name

Since:: 10.3

set

void set(string name, any value)

Set the value of the specified field in this row (can be used with all types). Will use the string form if needed.

If name is a non-schema field and the store is a distributed store which supports them, a new field will be added. If any is empty and the above is true, then the field will be removed from the row. Otherwise this method will throw.

Parameters:: name; value

Since:: 10.1

setAll

void setAll(any value)

Set all values in this row from all available fields in the supplied any type.

Parameters:: value - Any type value (event or dictionary) to take the field values from

Since:: 10.1

setBoolean

void setBoolean(string name, boolean b)

Set the value of the specified field in this row (must only be used on boolean fields).

Parameters:: name; b

setDecimal

void setDecimal(string name, decimal d)

Set the value of the specified field in this row (must only be used on decimal fields).

Parameters:: name; d

setFloat

void setFloat(string name, float f)

Set the value of the specified field in this row (must only be used on float fields).

Parameters:: name; f

setInteger

void setInteger(string name, integer i)

Set the value of the specified field in this row (must only be used on integer fields).

Parameters:: name; i

setString

void setString(string name, string s)

Set the value of the specified field in this row (must only be used on string fields).

Parameters:: name; s

toAny

any toAny()

Get the row as an any using the type the Store was created with (using prepareFromAny() or prepareFromTypeName()).

This is equivalent to calling getAll(any.newInstance(getTableName())). This action can be used only if the table name is a valid Apama type. Use getAll() instead if the store was not created from an Apama type.

See Also:: com.apama.memorystore.Store.prepareFromAny(); com.apama.memorystore.Store.prepareFromTypeName(); com.apama.memorystore.Row.getAll()

toDictionary

dictionary<string, any> toDictionary()

Get a dictionary copy of the Row.

Since:: 10.1

tryCommit

boolean tryCommit()

Try to commit changes from this Row back to the table, returning false if the Row is not up to date.

If nothing else has modified the row in the table since this Row was created, the changes are committed so other users can see them and true is returned.

Otherwise, false is returned and the table is left unchanged. Do not repeatedly call tryCommit() without also calling update(), or use the more efficient Row.tryCommitOrUpdate().

Note that a MemoryStore commit operation synchronously writes changes made to the local Row instance back to the table which is shared by all monitors inside the Correlator (or the distributed store), but does not cause a persistent write to disk (see Table#persist).

Returns:: true if the table was modified; false if an error occurred and the table was not changed.

See Also:: com.apama.memorystore.Row.tryCommitOrUpdate()

tryCommitOrUpdate

boolean tryCommitOrUpdate()

Try to commit, or update (losing local modifications) if not.

This is a more efficient equivalent to calling tryCommit then calling update if the commit fails. Typical usage would be to have a loop that makes some modifications to a row, calls tryCommitOrUpdate, and continues to loop (re-instating the local modifications and calling tryCommitOrUpdate again) until it returns true.

Note that a MemoryStore commit operation synchronously writes changes made to the local Row instance back to the table which is shared by all monitors inside the Correlator (or the distributed store), but does not cause a persistent write to disk (see Table#persist).

Returns:: true if the commit succeeded, false if the commit failed but the row has been updated ready for a retry attempt.

update

void update()

Update the local Row event to reflect the current state of the shared MemoryStore table, losing any local modifications.

row.update() has a very similar effect to r := t.get(r.getKey()), but is more efficient and doesn't require access to the table.

com.apama.memorystoreEvent Row