001/*
002 * Copyright 2010-2015 Institut Pasteur.
003 * 
004 * This file is part of Icy.
005 * 
006 * Icy 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 * Icy 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 Icy. If not, see <http://www.gnu.org/licenses/>.
018 */
019package icy.sequence;
020
021import java.io.Closeable;
022import java.io.IOException;
023
024import icy.common.exception.UnsupportedFormatException;
025import icy.file.SequenceFileImporter;
026import icy.image.AbstractImageProvider;
027import icy.image.ImageProvider;
028
029/**
030 * Sequence importer interface.<br>
031 * Used to define a specific {@link Sequence} importer.<br>
032 * Can take any resource type identified by an ID and should be able to give multiple level access
033 * to the image data.<br>
034 * See details about the image data access implementation with the {@link ImageProvider} interface
035 * and {@link AbstractImageProvider} abstract class helper.
036 * Note that you have {@link SequenceFileImporter} interface which allow to import {@link Sequence}
037 * from file(s).
038 * 
039 * @author Stephane
040 */
041public interface SequenceIdImporter extends ImageProvider, Closeable
042{
043    public static final int FLAG_METADATA_MASK = 0x0003;
044    /**
045     * Flag to indicate we want to load only mandatory metadata informations (faster metadata loading)
046     */
047    public static final int FLAG_METADATA_MINIMUM = 0x0001;
048    /**
049     * Flag to indicate we want to load all possible metadata
050     */
051    public static final int FLAG_METADATA_ALL = 0x0002;
052
053    /**
054     * @return The <code>id</code> of the image currently opened or <code>null</code> otherwise.
055     * @see #open(String, int)
056     * @see #close()
057     */
058    public String getOpened();
059
060    /**
061     * Open the image designed by the specified <code>id</code> to allow image data / metadata
062     * access.<br>
063     * Calling this method will automatically close the previous opened image.<br>
064     * Don't forget to call {@link #close()} to close the image when you're done.<br>
065     * 
066     * @param id
067     *        Image id, it can be a file path or URL or whatever depending the internal
068     *        import method.
069     * @param flags
070     *        operation flag:<br>
071     *        <li>{@link #FLAG_METADATA_MINIMUM} = load minimum metadata informations</li>
072     *        <li>{@link #FLAG_METADATA_ALL} = load all metadata informations</li>
073     * @return <code>true</code> if the operation has succeeded and <code>false</code> otherwise.
074     */
075    public boolean open(String id, int flags) throws UnsupportedFormatException, IOException;
076
077    /**
078     * Close the image which has been previously opened with {@link #open(String, int)} method.<br>
079     */
080    @Override
081    public void close() throws IOException;
082}