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.io.IOException;
022import java.net.URI;
023import org.dcm4che2.data.DicomObject;
024import org.dcm4che2.io.DicomInputStream;
025
026/** Storage plugin interface. These types of plugins provide an abstraction to reading and writing from
027 * files or data blobs.
028 * 
029 * @author Luís A. Bastião Silva <bastiao@ua.pt>
030 * @author Frederico Valente
031 */
032public interface StorageInterface extends DicooglePlugin {    
033    
034    /**
035     * Gets the scheme URI of this storage plugin.
036     *
037     * @see URI
038     * @return a string denoting the scheme that this plugin associates to
039     */
040    public String getScheme();
041    
042    /**
043     * Checks whether the file in the given path can be handled by this storage plugin.
044     *
045     * @param location a URI containing a scheme to be verified
046     * @return true if this storage plugin is in charge of URIs in the given form 
047     */
048    public boolean handles(URI location);
049    
050    /**
051     * Provides a means of iteration over existing objects at a specified location.
052     * This method is particularly nice for use in for-each loops.
053     * The provided scheme is not relevant at this point, but the developer must avoid calling this method
054     * with a path of a different schema.
055     * 
056     * <pre>for(StorageInputStream dicomObj : storagePlugin.at("file://dataset/")){
057     *      System.err.println(dicomObj.getURI());
058     * }</pre>
059     * 
060     * @param location the location to read
061     * @param parameters a variable list of extra parameters for the retrieve
062     * @return an iterable of storage input streams
063     * @see StorageInputStream
064     */
065    public Iterable<StorageInputStream> at(URI location, Object ... parameters);
066    
067    /**
068     * Stores a DICOM object into the storage.
069     *
070     * @param dicomObject Object to be Stored
071     * @param parameters a variable list of extra parameters for the retrieve
072     * @return The URI of the previously stored Object.
073     */
074    public URI store(DicomObject dicomObject, Object ... parameters);
075
076    /**
077     * Stores a new element into the storage.
078     *
079     * @param inputStream an input stream with the contents to be stored
080     * @param parameters a variable list of extra parameters for the retrieve
081     * @return the URI of the stored data
082     * @throws IOException if an I/O error occurs
083     */
084    public URI store(DicomInputStream inputStream, Object ... parameters) throws IOException;
085    
086    /** Removes an element at the given URI.
087     * 
088     * @param location the URI of the stored data
089     */
090    public void remove(URI location);
091}