[Wasabi Proposal] Live search API

[Mikkel Kamstrup Erlandsen]

Here's an actual proposal for unifying the simple and live apis. I'm not
saying that we really really should do this, just that it is doable, and it
still allows for quite simple use cases (see below). It is actually very
much in spirit with Magnus' very first proposal a while back. Praise late
insight :-)

== Unified API Proposal ==

NewSession (out s session)
 *

SetProperty (in s session, in s prop, in s val)
 * Set a property on the session. Prominent ones are
   - live : whether or not to be in live mode. Default false.
   - hit.properties : semi colon separated list of field names. Default
"uri".

GetProperty (in s session, in s prop)
 *

CloseSession (in s session)
 * Close the session and all child searches

Search (in s session, in s query_xml, out s search)
 * Start a new search from a query

CountHits (in s search, out i count)
 * Returns the current number of found hits. If live=false this call blocks
until the index has been fully searched.

GetHits (in s search, in i num, out aav hits)
 * Return num hits. If live=false this call blocks until there is num hits
available or the index has been fully searched.
   The client should keep track of each hit's serial number if it want to
use GetHitData later.

GetHitData (in s search, in ai hit_ids, in as properties, out aav hit_data)
 * Get hit metadata. Intended for snippets or modified hits. hit_ids are
serial numbers as obtained from GetHits.

CloseSearch (in s search)
 * Close and free a search.

SIGNAL HitsAdded (in i count)
SIGNAL HitsRemoved (in ai hit_ids)
SIGNAL HitsModified (in ai hit_ids)

== Session Properties ==
 * live : Default false.
 * hit.properties : the properties to return in GetHits. Default "uri".

== Use Cases ==
Retrieve a list of URIs matching a query:

session = NewSession()
search = Search (session, query)
hits = GetHits (search, 1000)
CloseSession (session)

A live search:

session = NewSession()
SetProperty (session, "live", "true")
SetProperty (session, "hit.properties", "uri ; dc:title")
search = Search (session, query)
<loop and wait for signals>
if HitsAdded(count):
    GetHits(session, count)
    <update ui>
    GetHitData (search, hit_ids, "snippet")
    <update ui with snippets>
else if HitsRemoved (hit_ids):
    <remove all affected hits>
else if HitsModified (hit_ids):
    new_data = GetHitData(search, hit_ids, "uri ; dc:title; snippet")
    <update ui with new data>
...
CloseSearch (search)
...


Cheers,
Mikkel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.freedesktop.org/archives/xdg/attachments/20070121/c04adfaa/attachment.htm