/*
 * BEGIN FLOCK GPL
 *
 * Copyright Flock Inc. 2005-2009
 * http://flock.com
 *
 * This file may be used under the terms of the
 * GNU General Public License Version 2 or later (the "GPL"),
 * http://www.gnu.org/licenses/gpl.html
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * END FLOCK GPL
 */

#include "nsISupports.idl"

interface nsIFile;
interface nsISimpleEnumerator;

/**
 * flockILuceneResult
 *
 * This is an interface that describes a result from a Lucene query.
 */
[scriptable, uuid(625248a0-9d3f-4060-9585-a765b8242df3)]
interface flockILuceneResult : nsISupports {
  readonly attribute string URI;
  readonly attribute string type;
  readonly attribute wstring URL;
  readonly attribute wstring title;
  readonly attribute double score;
};
 
/**
 * flockILuceneSearchCallback
 * 
 * This is a callback interface that gets called when a search query completes.
 */
[function, scriptable, uuid(288ac5a5-4671-4ddf-8dff-e3a98a5385ba)]
interface flockILuceneSearchCallback : nsISupports {
  /**
   * Called on completion of an associated flockILucene search call.
   *
   * @param aNumResults
   *        the number of search results being returned
   * @param aResultsEnumerator
   *        an enumerator of flockILuceneResults
   */
  void handleResults(in unsigned long aNumResults,
                     in nsISimpleEnumerator aResultsEnumerator);
};

/**
 * flockILuceneIndexListener
 * 
 * This is a listener interface that is called when an asynchronous index
 * modification operation completes.
 */
[scriptable, uuid(69694cf8-ff73-4c00-9fe5-aefc6f458704)]
interface flockILuceneIndexListener : nsISupports {
  /**
   * Called on completion of an associated flockILucene addDocument call.
   *
   * @param aURI
   *        the URI of the document that has been added
   */
  void onAddDocumentComplete(in string aURI);

  /**
   * Called on completion of an associated flockILucene deleteDocument call.
   *
   * @param aURI
   *        the URI of the document that has been deleted
   */
  void onDeleteDocumentComplete(in string aURI);
};

/**
 * flockILucene
 * 
 * This interface maintains and provides access to a Lucene indexer thread.
 */
[scriptable, uuid(5d8477b5-3ce0-4bbd-a7f2-6405aeee436e)]
interface flockILucene : nsISupports {
  /**
   * Initialize the Lucene thread using the directory aIndexDir
   *
   * @param aIndexDir
   *        a Lucene index directory containing Lucene index files
   */
  void init(in nsIFile aIndexDir);

  /**
   * Adds a document to the Lucene index.  The request to do this will
   * be dispatched to the worker thread for the actual indexing.
   *
   * @param aURI
   *        the URI of the document to be indexed
   * @param aType
   *        the Flock Type of the document
   * @param aURL
   *        the URL of the document, if one exists
   * @param aTitle
   *        the title of the document
   * @param aTags
   *        comma delimited string of tags for the document, if any exist
   * @param aDescription
   *        notes or other out-of-band text attached to the document
   * @param aText
   *        the text of the document
   * @param aLuceneListener
   *        a listener to be called when the document has been added
   */
  void addDocument(in string aURI, in string aType, in AString aURL,
                   in AString aTitle, in AString aTags,
                   in AString aDescription, in AString aText,
                   in flockILuceneIndexListener aLuceneIndexListener);

  /**
   * Adds a document to the Lucene index synchronously.  The request to
   * do this will be dispatched to the worker thread for the actual
   * indexing.
   *
   * @param aURI
   *        the URI of the document to be indexed
   * @param aType
   *        the Flock Type of the document
   * @param aURL
   *        the URL of the document, if one exists
   * @param aTitle
   *        the title of the document
   * @param aTags
   *        comma delimited string of tags for the document, if any exist
   * @param aDescription
   *        notes or other out-of-band text attached to the document
   * @param aText
   *        the text of the document
   */
  void addDocumentSync(in string aURI, in string aType, in AString aURL,
                       in AString aTitle, in AString aTags,
                       in AString aDescription, in AString aText);

  /**
   * Removes a document from the Lucene index.
   *
   * @param aURI
   *        the URI of the document to be removed
   * @param aLuceneListener
   *        a listener to be called when the document has been deleted
   */
  void deleteDocument(in string aURI,
                      in flockILuceneIndexListener aLuceneIndexListener);

  /**
   * Removes a document from the Lucene index synchronously.
   *
   * @param aURI
   *        the URI of the document to be removed
   */
  void deleteDocumentSync(in string aURI);

  /**
   * Searches the Lucene index.
   *
   * @param aQuery
   *        a Lucene query string
   * @param aType
   *        a Flock Type to restrict the search to.  NULL searches all types.
   * @param aMaxResults
   *        the maximum number of results to return
   * @param aLuceneSearchCallback
   *        flockILuceneSearchCallback interface to be called when the search
   *        is complete
   */
  void search(in AString aQuery, in string aType, in long aMaxResults,
              in flockILuceneSearchCallback aLuceneSearchCallback);
};

%{C++

// b8e91518-135b-4128-8b79-ca489924f102
#define FLOCK_LUCENE_CID \
{ 0xb8e91518, 0x135b, 0x4128, { 0x8b, 0x79, 0xca, 0x48, 0x99, 0x24, 0xf1, 0x02 } }
#define FLOCK_LUCENE_CLASSNAME "Flock Lucene Search Engine"
#define FLOCK_LUCENE_CONTRACTID "@flock.com/lucene;1"

%}
