Browsers

ActiveSpaces provides another method of interacting with spaces—space browsers.

You can use space browsers when working with groups of tuples, rather than with the single tuple key lookup of the space’s get method. Space browsers allow you to iterate through a series of tuples by invoking the space browser’s next method. However, unlike a traditional iterator that works only on a snapshot of the data to be iterated through, the space browser is continuously updated according to the changes in the data contained in the space being browsed.

Changes happening to the data in the space are automatically reflected on the list of entries about to be browsed as they happen: a space browser never gives the user outdated information. For example, if an entry existed at the time the space browser was created, but it gets taken from the space before the space browser’s user gets to it, then this entry will not be returned by the space browser.

Note: Do not forget to invoke the stop method on the browser once you are done using it in order to free the resources associated with the browser.

There are two main types of browsers:

  • Space Browsers - Allow your application to not only retrieve the next tuple in a series of tuples, but also to operate directly on the tuple. You can implement three types of space browser:
    • Get Browser - Retrieves the next tuple in a series of tuples.
    • Take Browser - Retrieves the next tuple in a series of tuples and consumes it.
    • Lock Browser - Retrieves the next tuple in a series of tuples and locks it.

For information on coding a space browser, see Space Browser Methods

  • Event Browsers - Allow you to iterate through the stream of events (changes) occurring in the space.

For information on coding an event browser, see ASEventBrowser

Here are some additional differences between space browsers and event browsers:

  • Space browsers and event browsers both have two methods, next() and stop(). However, a space browser's next() method returns a SpaceEntry, while the event browser's next() method returns a SpaceEvent.
  • A space browser also has a getType() method, which the event browser does not have.
  • A space browser's next method will do a get, take, or lock, according to the browser's type: GetBrowser, TakeBrowser, or LockBrowser.
    • The Get Browser’s next() method does a get on the next tuple to browse (very much like a regular iterator).
    • The Take Browser’s next() method atomically retrieves and removes the next tuple currently available to take from the space.
    • The Lock Browser’s next() method atomically retrieves and locks the next tuple currently available to lock in the space).
  • The Event Browser’s next method returns a SpaceEvent rather than a tuple.
  • The SpaceEvent objects returned by the event browser’s next method optionally include the initial values, that is, what was in the space at the time the event browser was created.
  • The initial values are presented as a continuously updated string of PUT events preceding the stream of events that happen after the creation of the event browser. Event browsers allow you to see deletions and expirations of tuples they have already iterated through.

Space browsers deliver the tuples (and initial PUT events) for the initial values in no particular order, and the order might change from one instance of a space browser to another.

Since a space browser is continuously updated, it does not have a next() method; instead, it has a timeout: the amount of time the user is willing for the next call to block in the event that there is nothing to get, take, or lock at the time it is invoked (but there may be in the future).

Continuously updating tuples means that if multiple TAKE browsers created on the same space are used to take tuples from the space using next(), a particular tuple is only taken by one of the space browsers, effectively allowing the use of a space as a tuple queue.
Attention: You get a warning on large query if the query from a client scans more than 500,000 tuples on that seeder. For example, if a client scans 300,000 tuples on seeder1 and 600,000 tuples on seeder2, seeder 2 will print a warning. You get a warning on long query if the query from a client takes more than 5 seconds to complete on that seeder.
Related concepts
Related reference