Space Browser Methods

Although you can use a listener to query the data in a space, in practice, you will almost always use space browsers: a browser is used to iterate through the contents of a space.

You create a browser by calling the browse method of a Space or Metaspace object. Parameters of this method include the type of browser and a BrowserDef object, which contains configuration settings for the browser.

A browser has two only methods: next() and stop(). What the next() method does, and what it returns, depends on the type of the browser. There are three types of browser:

GET

A browser of type GET’s next method gets and returns the next unread tuple.

TAKE

A browser of type TAKE’s next method takes and returns the next unread and unlocked tuple.

LOCK

A browser of type LOCK’s next method locks and returns the next unread and unlocked tuple.

To run queries on the space, you can specify a filter string when creating the browser: a filtered browser will only return tuples that match the specified filter. The browser's filtering criteria is expressed as a string in the language described in the section on filters: see Filters. Some of the filtering may be executed in a distributed manner by ActiveSpaces in order to optimize performance.

A tuple browser can have either time scope or distribution scope, defined by setting the values of fields in the browser’s BrowserDef object:

Time scope

The time scope can be used to narrow down the period of time of interest.

snapshot means that the browser starts with all the tuples in the space at the time the browser is created (or initial values), but is not updated with new tuples that are put into the space after that moment. This is the default value of the Time scope.
new means that the browser starts empty, and is updated only with tuples put into the space after the moment of the browser’s creation.
all means that the browser starts with all the tuples in the space, and is continuously updated with new tuples.

Warning: The CURRENT TimeScope may report less or more entries depending on redistribution. To avoid duplicate results, do not use current TimeScope if redistribution is in progress.

Distribution scope

The distribution scope can be used to narrow down the set of tuples or events being browsed.

all is used to browse over all the tuples (or associated events) in the space . This is the default value of the Distribution scope.
seeded is used to browse only over the tuples (or associated events) actually distributed to the member creating the browser

The BrowserDef object for a tuple browser can include a timeout value. The timeout is the amount of time for which a tuple browser's next() method can block while waiting for something new in the space to 'next()' on. If there is still nothing new for the browser to ’next()’ on at the end of the timeout, the next() method will return null. By default, the timeout value is 0 which means the browser's next() method does not wait.

Note: The browser’s timeout value is ignored when the time scope is set to snapshot. In this case any invocation of the next method on the browser once all of the tuples in the snapshot have been iterated through will return null right away.

Browser prefetch

A query in ActiveSpaces consists of two steps:

The space's seeders filter the data according to the criteria of the filter.

The matching tuples must be retrieved from those seeders to the application issuing the query. The default value of the Browser prefetch is 1000.

By default, the matching records will be mostly retrieved on demand, one by one, each time next() is called on the browser. Due to network latency there is a minimum amount of time potentially required by a next() operation, and it is therefore much more efficient in many cases (for example, when the resulting dataset is large) to pre-fetch some of the tuples in parallel with the processing of the result tuples.

The prefetch is expressed in number of records per seeder that are prefetched in parallel with the browser's thread. A special value of ALL (-1) indicates that the whole result set should be pushed at once to the client.

Note: If any form of fault-tolerance is desired, prefetch should not be used on TAKE browsers.