001/**
002 * Copyright (C) 2014  Universidade de Aveiro, DETI/IEETA, Bioinformatics Group - http://bioinformatics.ua.pt/
003 *
004 * This file is part of Dicoogle/dicoogle-sdk.
005 *
006 * Dicoogle/dicoogle-sdk is free software: you can redistribute it and/or modify
007 * it under the terms of the GNU General Public License as published by
008 * the Free Software Foundation, either version 3 of the License, or
009 * (at your option) any later version.
010 *
011 * Dicoogle/dicoogle-sdk is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014 * GNU General Public License for more details.
015 *
016 * You should have received a copy of the GNU General Public License
017 * along with Dicoogle.  If not, see <http://www.gnu.org/licenses/>.
018 */
019package pt.ua.dicoogle.sdk;
020
021import java.net.URI;
022import pt.ua.dicoogle.sdk.datastructs.Report;
023import pt.ua.dicoogle.sdk.task.Task;
024
025/**
026 * Index Interface Plugin. Indexers analyze documents for performing queries. They may index
027 * documents by DICOM metadata for instance, but other document processing procedures may be involved.
028 *
029 * @author Luís A. Bastião Silva <bastiao@ua.pt>
030 * @author Frederico Valente <fmvalente@ua.pt>
031 */
032public interface IndexerInterface extends DicooglePlugin {
033
034    /**
035     * Indexes the file path to the database. Indexation procedures are asynchronous, and will return
036     * immediately after the call. The outcome is a report that can be retrieved from the given task
037     * as a future.
038     *
039     * @param file directory or file to index
040     * @return a representation of the asynchronous indexation task
041     */
042    public Task<Report> index(StorageInputStream file, Object ... parameters);
043
044    /**
045     * Indexes multiple file paths to the database. Indexation procedures are asynchronous, and will return
046     * immediately after the call. The outcomes are aggregated into a single report and can be retrieved from
047     * the given task as a future.
048     *
049     * @param files a collection of directories and/or files to index
050     * @return a representation of the asynchronous indexation task
051     */
052    public Task<Report> index(Iterable<StorageInputStream> files, Object ... parameters);
053
054    
055    /**
056     * Checks whether the file in the given path can be indexed by this indexer. The indexer should verify if
057     * the file holds compatible content (e.g. a DICOM file). If this method returns false, the file will not
058     * be indexed.
059     *
060     * @param path a URI to the file to check
061     * @return whether the indexer can handle the file at the given path
062     */
063    public boolean handles(URI path);    
064    
065    /**
066     * Removes the indexed file at the given path from the database.
067     * 
068     * @param path the URI of the document
069     * @return whether it was successfully deleted from the database
070     */
071    public boolean unindex(URI path);
072}