/*
 * $Id: Classifier.java,v 1.3 2006/10/04 11:31:49 lawern Exp $
 *
 * Copyright (c) Siemens AG 2008 
 *           (c) Universität Paderborn 2008 
 * Licensed under EUPL 1.1. 
 *
 * $Log: Classifier.java,v $
 * Revision 1.3  2006/10/04 11:31:49  lawern
 * Keine Indexoptimierung während der Optimierung der Klassifikationsparameter.
 *
 * Revision 1.2  2006/07/17 13:04:02  lawern
 * Neuer typografiegewichteter Index und k-NN-Klassifikation aus meiner Diss.
 *
 * Revision 1.1  2004/06/22 13:20:20  lawern
 * Classify auf das Interface Classifier umgestellt.
 *
 */
package vkc.search;

import vkc.analyse.SummaryEntry;

import vkc.db.entities.VKCCategory;
import vkc.db.entities.VKCUser;

import java.io.IOException;

import java.util.Collection;


/**
 * Klasse für den Aufbau und Pflege des Klassifikationsindex von Lucene
 *
 * @author lawern
 */
public interface Classifier {
    // Konstanten für die Datumsbegrenzung bei der Suche
    public static final int RANGE_NO_LIMIT = -1;
    public static final int RANGE_MONTH_0 = 0; // nur diesen Monat
    public static final int RANGE_MONTH_1 = 1;
    public static final int RANGE_MONTH_2 = 2;
    public static final int RANGE_MONTH_3 = 3;
    public static final int RANGE_MONTH_4 = 4;
    public static final int RANGE_MONTH_5 = 5;
    public static final int RANGE_MONTH_6 = 6;
    public static final int RANGE_CURRENT_YEAR = 7;
    
    public static final Integer TDF_FORMAT = new Integer(10);

    /**
     * Initialisiert das Classify-Modul
     *
     * @param classifyIndexDir - Wurzelverzeichnis der VKC-Struktur
     * @param create - falls true, wird der Index neu aufgebaut
     */
    public void init(String classifyIndexDir, boolean create);

    /**
     * Methode baut den Klassifikationsindex von Lucene neu auf
     */
    public void rebuildIndex() throws IOException;
    
    /**
     * Liefert true, wenn die Optimierung der Klassifikationsparameter läuft.
     * @return True, wenn die Optimierung der Klassifikationsparameter läuft.
     */
    public boolean optimizationIsRunning();

    /**
     * Einfügemethode für einzelne VKCCategory-Objekte. Nach dem Aufruf muss
     * das übergebene Objekt in der Datenbank aktualisiert werden, da die
     * Keywords ergänzt werden.
     *
     * @param data VKCCategory-Objekt, welches dem Index hinzugefügt werden
     *        soll
     */
    public void addCategory(VKCCategory data) throws IOException;

    /**
     * Sollte immer dann aufgerufen werden, wenn einer Kategorie ein neues
     * Dokument hinzugefügt wird. Nach dem Aufruf muss das übergebene Objekt
     * in der Datenbank aktualisiert werden, da die Keywords ergänzt werden.
     *
     * @param data VKCCategory-Objekt, welches im Index aktualisiert werden
     *        soll
     */
    public void updateCategory(VKCCategory data) throws IOException;

    /**
     * Methode zur Entfernung eines Dokuments aus dem Suchindex
     *
     * @param documentId Eindeutiger Bezeichner für einen Eintrag
     */
    public void removeCategory(Integer categoryId) throws IOException;

    /**
     * Diese Methode liefert zu dem übergebenen Schlagwörtern eines Dokuments
     * einer Liste aller ähnlichen Kategorien.
     *
     * @param keywords Keywords die von der Methode
     *        vkc.analyse.Analyser.getKeywords(...) erzeugt wurden
     * @param dateRangeMode gibt das Alter an das die Dokumente haben dürfen,
     *        die gesucht werden sollen
     * @param user
     * @param category falls !=null, dann soll ab dieser Kategorie
     *        klassifiziert werden
     *
     * @return Liste mit Objekten vom Typ ClassifyResultEntry der ähnlichen
     *         Kategorien oder <code>null</code> falls etwas schief gegangen
     *         ist
     */
    public Collection classify(SummaryEntry[] keywords, int currDocLangId, int dateRangeMode,
        VKCUser user, VKCCategory category, int maxHits);
    
    /**
     * Index mit Platte synchronisieren.
     */
    public void saveCatBase();
}
