C H A P T E R 1 1
Data Storage and Retrieval
About Data Storage on Newton Devices
11-5
the query specification or query spec. The query spec describes the kind of
information the query returns. The order in which soups return data items is
imposed by an index you define for a specified soup.
information the query returns. The order in which soups return data items is
imposed by an index you define for a specified soup.
If you've ever used an array, you are already familiar with the concept of an index.
Each element of the array is associated with a unique numeric value called a key.
These key values can be sorted, thus imposing order on their associated data items
(the elements of the array). In the case of a common array, a single numeric index
sorts the array elements in ascending key order.
Each element of the array is associated with a unique numeric value called a key.
These key values can be sorted, thus imposing order on their associated data items
(the elements of the array). In the case of a common array, a single numeric index
sorts the array elements in ascending key order.
Key values can also be used to reference or retrieve an indexed item. For example,
arrays allow you to reference or retrieve the data at a particular position in the array
without regard to the actual content stored at that position. Soup indexes provide
similar capabilities for soup data: they allow you to find and sort soup entries
associated with specified key values without specific knowledge of the data associated
with a particular key value.
arrays allow you to reference or retrieve the data at a particular position in the array
without regard to the actual content stored at that position. Soup indexes provide
similar capabilities for soup data: they allow you to find and sort soup entries
associated with specified key values without specific knowledge of the data associated
with a particular key value.
You can index soup entries on any slot value you need to use as a key for extracting
them from the soup. For example, you could retrieve entries having a certain
creation date, or entries in which a particular string is present, and so on. Soups can
be created with a set of default indexes you specify and you can also add new
indexes to existing soups. Indexes are discussed in more detail in "Indexes"
beginning on page 11-8.
them from the soup. For example, you could retrieve entries having a certain
creation date, or entries in which a particular string is present, and so on. Soups can
be created with a set of default indexes you specify and you can also add new
indexes to existing soups. Indexes are discussed in more detail in "Indexes"
beginning on page 11-8.
A soup responds to a query by returning a cursor object that iterates over the set of
entries meeting the criteria defined by the query spec. Cursors are updated
dynamically: if soup entries meeting the search criteria are added or deleted after
the original query is made, these changes are reflected automatically in the set of
entries that the cursor returns.
entries meeting the criteria defined by the query spec. Cursors are updated
dynamically: if soup entries meeting the search criteria are added or deleted after
the original query is made, these changes are reflected automatically in the set of
entries that the cursor returns.
The cursor responds to messages that position it within the set of entries it
references and extract individual entries from this set. Until an entry is extracted
from the cursor, its data resides in the soup that was queried to generate the cursor.
references and extract individual entries from this set. Until an entry is extracted
from the cursor, its data resides in the soup that was queried to generate the cursor.
The first time a slot in the entry is referenced--whether to read its value, set its
value, or to print its value in the Inspector--the system creates a normal frame
from it that is referenced by a special area of the NewtonScript heap known as the
entry cache. Changes to the entry's soup data are actually made in the cached
frame, not the permanent store; hence, changes to a soup entry are not persistent
until the cached frame is written back to a soup. This scheme makes it simple to
undo the changes to a soup entry--the system simply throws away the cached
frame and restores references to the original, unmodified soup entry.
value, or to print its value in the Inspector--the system creates a normal frame
from it that is referenced by a special area of the NewtonScript heap known as the
entry cache. Changes to the entry's soup data are actually made in the cached
frame, not the permanent store; hence, changes to a soup entry are not persistent
until the cached frame is written back to a soup. This scheme makes it simple to
undo the changes to a soup entry--the system simply throws away the cached
frame and restores references to the original, unmodified soup entry.
Because the frame-based storage model facilitates the sharing of data, the system
provides a soup change notification mechanism that you can use to advise other
objects of changes to soups or soup data. All the methods that add, modify, or
delete soups or soup entries provide the option to execute registered callback
functions in response to changes in specified soups. Soup changes for which
provides a soup change notification mechanism that you can use to advise other
objects of changes to soups or soup data. All the methods that add, modify, or
delete soups or soup entries provide the option to execute registered callback
functions in response to changes in specified soups. Soup changes for which