001/*-
002 * Copyright 2015, 2016 Diamond Light Source Ltd.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the Eclipse Public License v1.0
006 * which accompanies this distribution, and is available at
007 * http://www.eclipse.org/legal/epl-v10.html
008 */
009
010package org.eclipse.january.dataset;
011
012import java.util.concurrent.TimeUnit;
013
014import org.eclipse.january.DatasetException;
015
016/**
017 * A dataset connector contains a lazy dataset which exists in a remote
018 * location. It uses a connection to the DataServer to provide the
019 * implementation of the slicing required remotely.
020 * 
021 * You may also listen to data changing in the dataset
022 */
023public interface IDatasetConnector extends IFileConnection, IDynamicShape {
024
025        /**
026         * The dataset location/name in the file
027         * @return Dataset name
028         */
029        public String getDatasetName();
030
031        /**
032         * The dataset location/name in the file
033         * @param datasetName name
034         */
035        public void setDatasetName(String datasetName);
036
037        /**
038         * If set to true the DataServer will not cache the dataset. 
039         * If left as false: if the data server can figure out that the 
040         * file is writing, it will reshape. However it cannot always 
041         * determine this depending on the file and what is writing to 
042         * it (SWMR can write without changing date stamp for instance)
043         * 
044         * Setting this boolean ensures that a given path, never will
045         * cache on the data server.
046         * 
047         * Default value is false for MJPEG streams and true for standard
048         * remote datasets.
049         *  
050         * @param expectWrite true if server should expect more data
051         */
052        public void setWritingExpected(boolean expectWrite);
053
054        /**
055         * @return true if the remote dataset has been warned that writing is expected.
056         */
057        public boolean isWritingExpected();
058        
059
060        /**
061         * Same as calling connect(500, TimeUnit.MILLISECOND)
062         * 
063         * This will connect with the DataServer to start listening
064         * to any updates to the file should it be written in the remote file system.
065         * When connect is called, the remote file must exist and the dataset properties
066         * are read. These properties must not change in the file while you are connected.
067         * For instance if the file is ints when you connect, it must not change data class.
068         * 
069         * @return the name of the thread started to run the connection or null if each event
070         * is driven from the event thread of the service (for instance web sockets provide the
071         * thread and this runs the connection)
072         * @throws DatasetException when cannot connect
073         */
074        public String connect() throws DatasetException;
075
076        /**
077         * This will connect with the DataServer to start listening
078         * to any updates to the file should it be written in the remote file system.
079         * When connect is called, the remote file must exist and the dataset properties
080         * are read. These properties must not change in the file while you are connected.
081         * For instance if the file is ints when you connect, it must not change data class.
082         * 
083         * @param time amount to wait
084         * @param unit of time
085         * @return the name of the thread started to run the connection or null if each event
086         * is driven from the event thread of the service (for instance web sockets provide the
087         * thread and this runs the connection)
088         * @throws DatasetException when cannot connect
089         */
090        public String connect(long time, TimeUnit unit) throws DatasetException;
091
092        /**
093         * Stops listening to the dataset changing and disconnects from the server.
094         * A remote dataset may be connected and disconnected multiple times.
095         * @throws DatasetException when cannot disconnect
096         */
097        public void disconnect() throws DatasetException;
098}