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}