/*
 * File   : $Source: /usr/local/cvs/opencms/src/org/opencms/search/documents/I_CmsDocumentFactory.java,v $
 * Date   : $Date: 2008-02-27 12:05:21 $
 * Version: $Revision: 1.27 $
 *
 * This library is part of OpenCms -
 * the Open Source Content Management System
 *
 * Copyright (c) 2002 - 2008 Alkacon Software GmbH (http://www.alkacon.com)
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * For further information about Alkacon Software GmbH, please see the
 * company website: http://www.alkacon.com
 *
 * For further information about OpenCms, please see the
 * project website: http://www.opencms.org
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

package org.opencms.search.documents;

import org.opencms.file.CmsObject;
import org.opencms.file.CmsResource;
import org.opencms.main.CmsException;
import org.opencms.search.CmsSearchIndex;

import java.util.List;

import org.apache.lucene.document.Document;

/**
 * Used to create index Lucene Documents for OpenCms resources,
 * controls the text extraction algorithm used for a specific OpenCms resource type / MIME type combination.<p>
 * 
 * The configuration of the search index is defined in <code>opencms-search.xml</code>.
 * There you can associate a combintion of OpenCms resource types and MIME types to an instance
 * of this factory. This rather complex configuration is required because only the combination of
 * OpenCms resource type and MIME type can decide what to use for search indexing. 
 * For example, if the OpenCms resource type is <code>plain</code>,
 * the extraction algorithm for MIME types <code>.html</code> and <code>.txt</code> must be different.
 * On the other hand, the MIME type <code>.html</code> in OpenCms can be almost any resource type,
 * like <code>xmlpage</code>, <code>xmlcontent</code> or even <code>jsp</code>.<p> 
 * 
 * @author Carsten Weinholz 
 * @author Thomas Weckert 
 * @author Alexander Kandzior
 * 
 * @version $Revision: 1.27 $ 
 * 
 * @since 6.0.0 
 */
public interface I_CmsDocumentFactory extends I_CmsSearchExtractor {

    /**
     * Creates the Lucene Document for the given index resource and the given search index.<p>
     * 
     * This triggers the indexing process for the given index resource accoring to the configuration 
     * of the provided index.<p>
     * 
     * The provided index resource contains the basic contents to index.
     * The provided search index contains the configuration what to index, such as the locale and 
     * possible special field mappings.<p>
     * 
     * @param cms the cms object used to access the OpenCms VFS
     * @param resource the search index resource to create the Lucene document from
     * @param index the search index to create the Document for
     * 
     * @return the Lucene Document for the given index resource and the given search index
     * 
     * @throws CmsException if something goes wrong
     */
    Document createDocument(CmsObject cms, CmsResource resource, CmsSearchIndex index) throws CmsException;

    /**
     * Returns the disk based cache used to store the raw extraction results.<p>
     * 
     * In case <code>null</code> is returned, then result caching is not supported for this factory.<p>
     * 
     * @return the disk based cache used to store the raw extraction results
     */
    CmsExtractionResultCache getCache();

    /**
     * Returns the list of accepted keys for the resource types that can be indexed using this document factory.<p>
     * 
     * The result List contains String objects. 
     * This String is later matched against {@link A_CmsVfsDocument#getDocumentKey(String, String)} to find
     * the corrospondig {@link I_CmsDocumentFactory} for a resource to index.<p> 
     * 
     * The list of accepted resource types may contain a catch-all entry "*";
     * in this case, a list for all possible resource types is returned,
     * calculated by a logic depending on the document handler class.<p>
     * 
     * @param resourceTypes list of accepted resource types
     * @param mimeTypes list of accepted mime types
     * 
     * @return the list of accepted keys for the resource types that can be indexed using this document factory (String objects)
     * 
     * @throws CmsException if something goes wrong
     */
    List getDocumentKeys(List resourceTypes, List mimeTypes) throws CmsException;

    /**
     * Returns the name of this document type factory.<p>
     * 
     * @return the name of this document type factory
     */
    String getName();

    /**
     * Returns <code>true</code> if this document factory is locale depended.<p>
     * 
     * @return <code>true</code> if this document factory is locale depended
     */
    boolean isLocaleDependend();

    /**
     * Returns <code>true</code> if result caching is supported for this factory.<p>
     * 
     * @return <code>true</code> if result caching is supported for this factory
     */
    boolean isUsingCache();

    /**
     * Sets the disk based cache used to store the raw extraction results.<p>
     * 
     * This should only be used for factories where {@link #isUsingCache()} returns <code>true</code>.<p> 
     * 
     * @param cache the disk based cache used to store the raw extraction results
     */
    void setCache(CmsExtractionResultCache cache);
}