/*
 * BEGIN FLOCK GPL
 *
 * Copyright Flock Inc. 2005-2008
 * 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"
#include "nsIFile.idl"
#include "flockILuceneListener.idl"


/**
 * flockILucene
 * 
 * This interface maintains and provides asychronous 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 aListener
   *        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 flockILuceneListener aListener);

  /**
   * 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 aListener
   *        a listener to be called when the document has been deleted
   */
  void deleteDocument(in string aURI, in flockILuceneListener aListener);

  /**
   * 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 aListener
   *        a listener to be called when the search is complete
   */
  void search(in AString aQuery, in string aType, in long aMaxResults,
              in flockILuceneListener aListener);
};

