Lightweight Bartering Grid

lbg.searchengine
Class SearchEngineClient

java.lang.Object
  extended by java.util.TimerTask
      extended by lbg.searchengine.SearchEngineClient
All Implemented Interfaces:
java.lang.Iterable, java.lang.Runnable
Direct Known Subclasses:
LiveSearchEngineClient, SimulatedSearchEngineClient

public abstract class SearchEngineClient
extends java.util.TimerTask
implements java.lang.Iterable

A local database of peer handles, automatically updating from a server.

Handle removal is not automatic and should be done when encountering a problem with a handle.

The local database may hold handles that the server doesn't know of: they might be locally added or currently not expired. The server may hold handles that are not locally known: they will be downloaded at next update.

The local database may hold the handle of the peer owning this client, as he is not required to identify himself before contacting the server.

This object is Thread-safe.

Since:
2007-03-21
Author:
Xavier Dalem, Cyril Briquet

Field Summary
static int DEFAULT_SEARCH_COUNT
          Default handle count that should be returned by a search.
 
Method Summary
 void add(ExternalPeerHandle handle)
          Adds a handle to the local database.
 void add(ExternalPeerHandle[] handles)
          Adds a bunch of handles handle to the local database.
 java.util.Iterator<ExternalPeerHandle> iterator()
          Returns an iterator over the handles known to this client.
static void main(java.lang.String[] argv)
          Stress test.
 void refresh()
          Refreshes the local database by recontacting the reference server.
 void remove(ExternalPeerHandle handle)
          Removes a handle from the local database.
 SearchEngineHandle renewReferenceServer(SearchEngineHandle handle)
          Changes this client's reference server.
 void run()
           
 ExternalPeerHandle[] search()
          Get 40 random handles from the cache.
 ExternalPeerHandle[] search(int k)
          Get k random handles from the cache.
 ExternalPeerHandle search(java.lang.String id)
          Searches for a handle in the local database.
 ExternalPeerHandle[] searchAll()
          Returns a complete snapshot of the local database.
 void setOwnerPeer(ExternalPeerHandle owner_peer)
          Sets this client's owner peer.
 int size()
          Returns the number of entries currently in this cache.
 java.lang.String toString()
          Returns a String representation of this client.
 java.lang.String toStringDetailed()
          Returns a detailed (i.e.
 
Methods inherited from class java.util.TimerTask
cancel, scheduledExecutionTime
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_SEARCH_COUNT

public static final int DEFAULT_SEARCH_COUNT
Default handle count that should be returned by a search.

See Also:
Constant Field Values
Method Detail

setOwnerPeer

public void setOwnerPeer(ExternalPeerHandle owner_peer)
                  throws GridException
Sets this client's owner peer. The owner peer is the peer using the client and wanting to be registered to its search engine server.

Registering an owner is not a requirement to access the server's information, but the owner will then not be listed in the server's database.

Registering an owner can be done only once.

Parameters:
owner_peer - The owner peer
Throws:
GridException - If this client already had an owner

renewReferenceServer

public SearchEngineHandle renewReferenceServer(SearchEngineHandle handle)
                                        throws GridException
Changes this client's reference server.

Parameters:
handle - The new reference server
Returns:
The old reference server
Throws:
GridException - if the new server is invalid

refresh

public void refresh()
             throws GridException
Refreshes the local database by recontacting the reference server.

Throws:
GridException

add

public void add(ExternalPeerHandle handle)
Adds a handle to the local database. If the handle already exists, it is not overwritten.

You can expect log(n) times from this operation.

Parameters:
handle - The peer handle to add

add

public void add(ExternalPeerHandle[] handles)
Adds a bunch of handles handle to the local database. If a handle already exists, it is not overwritten.

You can expect log(n) times from this operation.

Parameters:
handles - The peer handles to add

remove

public void remove(ExternalPeerHandle handle)
            throws GridException
Removes a handle from the local database.

Parameters:
handle - The handle to remove
Throws:
GridException - if the handle is invalid

search

public ExternalPeerHandle search(java.lang.String id)
                          throws GridException
Searches for a handle in the local database.

If the ID is currently known by the reference server, it is garanteed that this method won't return null, regardless of the current state of local database.

Parameters:
id - The ID of the handle to search for
Returns:
The found handle, or null if none matched
Throws:
GridException - if the ID is invalid

searchAll

public ExternalPeerHandle[] searchAll()
Returns a complete snapshot of the local database.

Don't mess with the returned array if you want consistent behaviour as it's always the same one that is returned as long as the database doesn't change

The array is not garanteed to be of the exact size of the database. If the array is larger, the first irrelevant element is set to null.

Returns:
An array of all handles locally known

search

public ExternalPeerHandle[] search(int k)
                            throws GridException
Get k random handles from the cache.

Parameters:
k - The number of random handles
Returns:
An array of k random handles.
Throws:
GridException - if k > size()

search

public ExternalPeerHandle[] search()
                            throws GridException
Get 40 random handles from the cache.

Returns:
An array of 40 random handles.
Throws:
GridException
See Also:
DEFAULT_SEARCH_COUNT

size

public int size()
Returns the number of entries currently in this cache.


toString

public java.lang.String toString()
Returns a String representation of this client.

Overrides:
toString in class java.lang.Object

toStringDetailed

public java.lang.String toStringDetailed()
Returns a detailed (i.e. including known peers) String representation of this client.


iterator

public java.util.Iterator<ExternalPeerHandle> iterator()
Returns an iterator over the handles known to this client. This is fast-fail and most likely to fail fast depending on timeout.
search() is a costy but more reliable alternative.

Specified by:
iterator in interface java.lang.Iterable

run

public void run()
Specified by:
run in interface java.lang.Runnable
Specified by:
run in class java.util.TimerTask

main

public static void main(java.lang.String[] argv)
                 throws java.lang.Exception
Stress test.

Usage: java lbg.searchengine.SearchEngineClient NUM_HANDLES SAMPLES RATIO.

Throws:
java.lang.Exception

Lightweight Bartering Grid

Copyright (c) 2005-2008, Cyril Briquet, parts Xavier Dalem.