    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}