Preparing and opening tables
After you have an open store, you can add one or more tables to that store. You call actions on Store events to create tables. Store events define actions that do the following:
Prepare a table. You specify a table name and a schema. This call is asynchronous. The MemoryStore enqueues a
Finished event that indicates success or failure. If the table does not exist, the MemoryStore creates an empty table.
Open a table that has been prepared
Store on disk the in-memory changes to tables.
If the store that contains the table is persistent and the table exists on disk then the on-disk schema must match the schema that you specify when you call the action to prepare the table. The schemas must also match if the table is a distributed table that already exists in a distributed store. If the schemas do not match, the Finished event that the MemoryStore enqueues includes an error message.
Note: A persistent table can be an on-disk table or a table in a correlator-persistent store.
If a monitor instance calls Store.prepare() with the same table name and schema as those of a previously successful Store.prepare() call, the call does nothing and indicates success immediately. If a monitor instance calls Store.prepare() and specifies the same table name but the schema does not exactly match, that call fails immediately. If a monitor makes a call to Store.prepare() that matches a preparation that is in progress, the result is the same as the result of the preparation that is in progress.
If the table you want to prepare is persistent and it has not yet been loaded into memory then the MemoryStore loads the table’s on-disk data into memory in its entirety. The MemoryStore enqueues the Finished event when loading the table is complete.
To use a table that is in memory, you must retrieve a handle to it from the store that contains it. Obtaining a handle to a prepared (loaded) table is a synchronous action that completes immediately and does not block. The calling monitor instance dies if you try to obtain a handle to a table that is not prepared or that is in the process of being prepared.
For example:
integer id := store.prepare("tablename", schema);
on Finished(id,*,*):f onTablePrepared(f);
action onTablePrepared(Finished f) {
if not f.success then { log "Whoops"; die; }
Table tbl := store.open("tablename");
Note: The term "table" is a reserved keyword. Consequently, you should not use "table" as a variable name.
Preparation of a table can fail for a number of reasons including, but not limited to, the following:
You call
prepare() on an existing table and the schema of that table and the schema specified in the
prepare() call do not match.
You call
prepare() on an existing in-memory table and the
exposePersistentView setting is true for the schema you specify in the
prepare() call.
You call
prepare() on a table that does not exist and the store has been opened read-only.
You call
prepare() on a table that does not exist in a persistent store and the attempt to create a new table in the persistent store fails, perhaps because the disk is full.
The on-disk version of the table is corrupt in some way.
You set
exposePersistentView on a table in a correlator-persistent store.
You set
exposeMemoryView or
exposePersistentView to true for a distributed store .
The third-party distributed store implementation throws an exception for some reason such as unrecoverable network failure.
Copyright © 2013
Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or Terracotta Inc., San Francisco, CA, USA, and/or Software AG (Canada) Inc., Cambridge, Ontario, Canada, and/or, Software AG (UK) Ltd., Derby, United Kingdom, and/or Software A.G. (Israel) Ltd., Or-Yehuda, Israel and/or their licensors.