org.openprivacy.reptile.search
Interface SearchProvider

All Known Subinterfaces:
RemoteSearchProvider
All Known Implementing Classes:
AbstractSearchProvider

public interface SearchProvider

The SearchProvider class provides a plugin mechanism for integrating external search mechanisms within Reptile. Essentially the goals are:

  • Support asynchronous code such as JXTA, Freenet.
  • Support synchronous code like local DB queries via JDBC.
  • Support pageable result sets int a portable manner.
  • Allow us to support future implementations of SearchProviders.

    The design of the SearchProvider was based on the following search frameworks.

  • Conventional DB searching. ( SELECT statements )
  • The Lucene search framework ( http://jakarta.apache.org/lucene )
  • The JXTA search framework ( http://search.jxta.org )

    Note: if you run a search on a SearchProvider you are NOT guaranteed that it will return a result immediately. In fact it might need to run for a while so that we can collect results.

    If you depend on a stable result set, you should synchronize around this search provider. This is important especially when you want to serialize a group of results

    Version:
    $Id: SearchProvider.java,v 1.14 2002/02/07 11:08:13 burton Exp $
    Author:
    Kevin A. Burton

    Field Summary
    static int STATE_NEVER_SEARCHED
              The state of the SearchProvider if there has NEVER been a search run on it.
    static int STATE_SEARCH_COMPLETE
              Should be the state of this SearchProvider if the given search is complete.
    static int STATE_SEARCH_IN_PROGRESS
              The state of this SearchProvider if it is still trying to find results.
     
    Method Summary
     void assertSearchable()
              Throws an Exception if this SearchProvider is not searchable.
     void destroy()
               Called before garbage collection by the SearchProviderGCThread.
     java.lang.String getHandle()
               Get a unique handle for this SearchProvider.
     int getResultCount()
               Get the number of results found for this SearchProvider.
     long getSearchCompletedTime()
              Get the time (UNIX time) that this providers search was completed on.
     SearchRequest getSearchRequest()
              Set the SearchRequest that this provider has results for.
     long getSearchStartTime()
              Get the time (UNIX time) that this providers search was started on.
     int getState()
              Get the state of this SearchProvider
     java.lang.String getState(int state)
              Get the state of this provider as a string.
     long getTimeCreated()
               The time created for this this SearchProvider is the current time in milliseconds when this SearchProvider was instantiated.
     boolean isSearchable()
              Return true if this SearchProvider is searchable.
     void record(SearchRecord record)
               Get the given SearchRecord from this SearchProvider.
     void search(SearchRequest sr)
               Run a search with a given query.
     void setResultCount(int resultCount)
               Set the result count.
     void setSearchCompletedTime(long time)
               
     void setSearchRequest(SearchRequest request)
               
     void setSearchStartTime(long time)
               
     void setState(int state)
              Set the state of this SearchProvider
     

    Field Detail

    STATE_NEVER_SEARCHED

    public static final int STATE_NEVER_SEARCHED
    The state of the SearchProvider if there has NEVER been a search run on it.

    See Also:
    Constant Field Values

    STATE_SEARCH_IN_PROGRESS

    public static final int STATE_SEARCH_IN_PROGRESS
    The state of this SearchProvider if it is still trying to find results.

    See Also:
    Constant Field Values

    STATE_SEARCH_COMPLETE

    public static final int STATE_SEARCH_COMPLETE
    Should be the state of this SearchProvider if the given search is complete.

    See Also:
    Constant Field Values
    Method Detail

    getResultCount

    public int getResultCount()

    Get the number of results found for this SearchProvider. If the search has not been run yet this will return 0.


    setResultCount

    public void setResultCount(int resultCount)

    Set the result count.


    getHandle

    public java.lang.String getHandle()

    Get a unique handle for this SearchProvider. Each SearchProvider has a unique handle that can be used to obtain it from the SearchProviderManager


    getTimeCreated

    public long getTimeCreated()

    The time created for this this SearchProvider is the current time in milliseconds when this SearchProvider was instantiated.

    This is used by the SearchProviderGCThread to determine when it should GC SearchProviders.


    search

    public void search(SearchRequest sr)
                throws java.lang.Exception

    Run a search with a given query. Note that some search providers may NOT finish the search here.. Specifically some search providers may take a few minutes to fill in results as results are collected. A good example of this is code that executes within a P2P network and is waiting or other peers to reply.

    Only one 'search' can be run on any search provder. If you wish to run multiple searches you need to instantiate multiple SearchProviders.

    If you want to develop a mutltithreaded/asynchronous SearchProvider, you should set the state to STATE_SEARCH_IN_PROGRESS, kick off any threads or async queries an then set the state to STATE_SEARCH_COMPLETE (possibly outside of the search method)

    Note that when you are running this method you should synchronize around 'this' object instance. This should only be done int code that could break the search if it is requested to early.

    AKA This IS thread reentrant!

    SearchProviders also need to pay attention to the SearchRequest and implement any settings here. Specifically we need to pay attention to sort order, search fields, criteria, etc.

    java.lang.Exception

    record

    public void record(SearchRecord record)
                throws java.lang.Exception

    Get the given SearchRecord from this SearchProvider.

    It is important that all SearchProviders implement this method correctly.

    The given implementation needs to fill in all necessary information into this SearchRecord, this includes the title, description, etc.

    Note. This is basically a visitor pattern. Callers use a search provider and then fetch a record from the SearchProvider by index.

    Throws:
    java.lang.Exception - When an invalid SearchRecord index is used

    destroy

    public void destroy()
                 throws java.lang.Exception

    Called before garbage collection by the SearchProviderGCThread. If your search provider needs to perform any garbage collection it should do so here.

    If your SearchProvider has executed an asynchronous query, it should abort this before returning.

    java.lang.Exception

    getState

    public int getState()
    Get the state of this SearchProvider


    getState

    public java.lang.String getState(int state)
    Get the state of this provider as a string.


    setState

    public void setState(int state)
    Set the state of this SearchProvider


    isSearchable

    public boolean isSearchable()
    Return true if this SearchProvider is searchable. A SearchProvider is only searchable if it's state is STATE_NEVER_SEARCHED


    assertSearchable

    public void assertSearchable()
                          throws java.lang.Exception
    Throws an Exception if this SearchProvider is not searchable.

    java.lang.Exception

    getSearchRequest

    public SearchRequest getSearchRequest()
    Set the SearchRequest that this provider has results for. This should be called at least once when a SearchProvider has ran a search.


    setSearchRequest

    public void setSearchRequest(SearchRequest request)

    getSearchStartTime

    public long getSearchStartTime()
    Get the time (UNIX time) that this providers search was started on.


    setSearchStartTime

    public void setSearchStartTime(long time)
    See Also:
    getSearchStartTime()

    getSearchCompletedTime

    public long getSearchCompletedTime()
    Get the time (UNIX time) that this providers search was completed on.


    setSearchCompletedTime

    public void setSearchCompletedTime(long time)
    See Also:
    getSearchCompletedTime()