Table

FRAMES NO FRAMES

Overview

Package

Deprecated

Help

API Reference for EPL (ApamaDoc) 10.11.3.3

SUMMARY: IMPORT | CONSTANT | MEMBER | ACTION

DETAIL: IMPORT | CONSTANT | MEMBER | ACTION

com.apama.memorystore
Event Table

Represents a collection of rows in a store, with a defined schema.

A table consists of a series of rows, each identified by a key and containing other values with names and types according to the table's Schema.

A table typically resides in memory, you can also store it on disk if you want to, or a table can be stored on a distributed cache.

See Also:: com.apama.memorystore.Store#open() - Tables exist within a named Store, which is used to create and open tables.

Action summary
`com.apama.memorystore.Row`	`add(string key)` Add the table Row with the specified key.
`com.apama.memorystore.Iterator`	`begin()` Return an iterator to the beginning of the Table.
`void`	`clear()` Remove all rows from the table.
`integer`	`enqueueColumn(string fieldName)` Send an event for each row in the table, taken by parsing the string data in the specified table field/column as an event string.
`com.apama.memorystore.Row`	`get(string key)` Get the table Row with the specified key.
`integer`	`getFieldIndex(string fieldName)` Return the index of a field.
`sequence<string>`	`getKeys()` Returns a sequence that contains the keys for all the rows in this table.
`string`	`getStoreName()` Get the name of the Store that contains this table.
`string`	`getTableName()` Get the name of this Table.
`boolean`	`hasKey(string key)` Indicate whether or not a row with the specified key is present in the table.
`void`	`mutate(string key, action<com.apama.memorystore.Row> a)` Change the row with the specified key by applying an action to it.
`void`	`mutateAll(action<com.apama.memorystore.Row> a)` Mutate all rows in the Table by applying the specified action.
`integer`	`persist()` Persist this table's committed changes back to stable storage, asynchronously.
`void`	`remove(string key)` Remove the specified row from the table.
`integer`	`subscribeRowChanged()` Subscribe to be notified of all successful commits in this table.
`void`	`unsubscribe(integer subscriptionId)` Cancel a previous subscription.

Action detail

add

            com.apama.memorystore.Row add(string key)

Add the table Row with the specified key.

On distributed stores, for performance reasons this action doesn't check if there is a Row already present in the the table with the specified key. To check if the Row is present in the store, use the Table.get() action.

Parameters:: key - The name/key uniquely identifying the row.

Returns:: An empty Row event.

begin

            com.apama.memorystore.Iterator begin()

Return an iterator to the beginning of the Table.

clear

            void clear()

Remove all rows from the table.

enqueueColumn

            integer enqueueColumn(string fieldName)

Send an event for each row in the table, taken by parsing the string data in the specified table field/column as an event string.

The field must be of string type, and its value for every row should be an Apama event string, in the same form that you would send to the Correlator (e.g. "mypackage.MyEvent(123, [false,true])")

This action is most likely to be useful when you are migrating from the StateStore Correlator plug-in to the MemoryStore. In the StateStore plug-in, persistent data re-entered the Correlator as sent events.

This is only supported for non-distributed stores.

Parameters:: fieldName - The name of the table field whose values are event strings that should be sent.

Returns:: The unique identifier for this operation, which will be included in the Finished event sent after the column data for the last row has been sent.

See Also:: com.apama.memorystore.Finished - A Finished event will be sent when this asynchronous operation has completed.

get

            com.apama.memorystore.Row get(string key)

Get the table Row with the specified key.

If there is no row with the specified key, this action returns without error, with a Row event that contains default values for the fields in the row. A call to the Row.inTable() action returns false.

Parameters:: key - The name/key uniquely identifying the row.

Returns:: A Row event representing an atomic snapshot of the committed data in the table when the action was called.

getFieldIndex

            integer getFieldIndex(string fieldName)

Return the index of a field.

Returns what position in the Schema the specified field appears at. If a name that is not in Schema fieldName is passed in, the monitor instance will be terminated with an error.

Using this action is more efficient that getting the same information by using indexOf on the Schema.fields sequence.

Parameters:: fieldName - A field name that exists in this table's Schema.

getKeys

            sequence<string> getKeys()

Returns a sequence that contains the keys for all the rows in this table.

The keys are in an arbitrary order.

getStoreName

            string getStoreName()

Get the name of the Store that contains this table.

getTableName

            string getTableName()

Get the name of this Table.

hasKey

            boolean hasKey(string key)

Indicate whether or not a row with the specified key is present in the table.

t.hasKey("foo") is a more efficient alternative to t.get("foo").inTable()

Parameters:: key - The name/key uniquely identifying the row.

mutate

            void mutate(string key, action<com.apama.memorystore.Row> a)

Change the row with the specified key by applying an action to it.

It is possible for another context to commit changes to this row between the time mutate() obtains a Row event to represent the row and the time mutate() tries to commit the changes that result from executing the specified action. In this situation, the MemoryStore automatically calls the specified action again on the most recently committed row content; therefore mutation actions must be designed to cope with being called repeatedly without causing unwanted side effects.

Parameters:: key; a - An action that (idempotently) performs the desired change to the row.

mutateAll

            void mutateAll(action<com.apama.memorystore.Row> a)

Mutate all rows in the Table by applying the specified action.

This can temporarily consume a lot of memory when called on a relatively large table because the Correlator does no garbage collection until action execution is complete. A few thousand rows are unlikely to present a problem. Beyond that, it depends on how many fields are in each row, how many rows are in the table, and how much RAM is available.

Parameters:: a - An action that performs the desired change to each row in the table.

persist

            integer persist()

Persist this table's committed changes back to stable storage, asynchronously.

Note that any local changes to a Row that were not committed will not be written to disk (see Row#commit()).

Only on-disk persistent stores can be persisted using this action. It is not possible to call this method on Correlator-persistent tables since all changes committed to such tables will be written to disk automatically in the same transaction as changes to the state of persistent EPL monitors.

Returns:: The unique identifier for this operation, which will be included in the Finished event sent after the operation is complete.

See Also:: com.apama.memorystore.Finished - A Finished event will be sent when this asynchronous operation has completed.

remove

            void remove(string key)

Remove the specified row from the table.

If the row does not exist, this action does nothing.

Parameters:: key - The name/key uniquely identifying the row.

subscribeRowChanged

            integer subscribeRowChanged()

Subscribe to be notified of all successful commits in this table.

This is only supported for tables in a distributed store, and only if the underlying provider supports this feature.

The monitor instance will be terminated with an error if this action is called on a store that does not support it.

It is important to note that (due to the nature of distributed store technology) there is no way to atomically subscribe to notifications and get an initial snapshot of the table's contents, so applications that perform an initial iteration over the table's contents to initialize some state before subscribing are at risk of double-counting any keys that are mutated after the subscription and during the iteration/initialization process.

For tables that are relatively small (and fit entirely inside the memory of a single Correlator), a common pattern for addressing the need for a table snapshot to initialize state before subscribing is to maintain a per-key dictionary of last-seen values, updated by both the initial iteration and the RowChanged notification events; any RowChanged event whose old value does not match the last-seen dictionary must be ignored, to avoid double-counting changes. To save memory, entries from the last-seen dictionary can be removed after the first RowChanged event for that key.

For distributed stores and drivers that support it, the application may also receive MissedRowChanges events to signify that some unknown number of updates have been missed (typically due to a network disconnection between the client and the store)

Returns:: A unique subscriptionId that can be passed to any instance of this Table to unsubscribe.

See Also:: com.apama.memorystore.RowChanged - The event sent whenever a row is modified.; com.apama.memorystore.MissedRowChanges - The event sent whenever a row is modified.; com.apama.memorystore.Table#unsubscribe() - Unsubscribe using this action.

unsubscribe

            void unsubscribe(integer subscriptionId)

Cancel a previous subscription.

This is only supported for tables in a distributed store.

If other monitors in this context have also subscribed, events will still be delivered until they have all unsubscribed. subscriptionId must be a value returned from a subscribeRowChanged() on this table.

Parameters:: subscriptionId - Identifier for the subscription to remove, returned by subscribeRowChanged().