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 012/** 013 * This interface is intended for data sources that change shape dynamically. 014 * Examples: 015 * 1. An image stream from a camera encoded which entire image, changes periodically. 016 * 2. An HDF5 dataset which entire shape changes as data is added. 017 * 018 */ 019public interface IDynamicShape { 020 021 /** 022 * Denotes an unlimited dimension in maximum shape 023 */ 024 public static final int UNLIMITED = -1; 025 026 027 /** 028 * @return dataset associated with shape 029 */ 030 public ILazyDataset getDataset(); 031 032 /** 033 * Change shape 034 * @param newShape new shape 035 * @throws IllegalArgumentException if new shape exceeds maximum shape or is of different rank 036 * @throws UnsupportedOperationException if used on a view 037 * @return true if shape has changed 038 */ 039 public boolean resize(int... newShape); 040 041 /** 042 * @return maximum shape (can be null) 043 */ 044 public int[] getMaxShape(); 045 046 /** 047 * Set maximum shape 048 * @param maxShape maximum shape 049 */ 050 public void setMaxShape(int... maxShape); 051 052 /** 053 * Starts a periodic checker to see if dataset has changed in some manner. If any potential changes 054 * are detected after the period has finished then registered listeners are alerted. 055 * A period of 0 or less will stop any existing checker. 056 * 057 * @param milliseconds period between checks in milliseconds 058 * @param checker can be null for default implementation of alerting listeners unconditionally 059 */ 060 public void startUpdateChecker(int milliseconds, IDatasetChangeChecker checker); 061 062 /** 063 * Force the shape to be re-read from file, if possible 064 * @return true if shape has changed 065 */ 066 public boolean refreshShape(); 067 068 /** 069 * Add a listener which will be fired when aspects of the data change for 070 * instance shape or content. 071 * @param l listener 072 */ 073 public void addDataListener(IDataListener l); 074 075 /** 076 * Remove a listener which will be fired when aspects of the data change for 077 * instance shape or content. 078 * @param l listener 079 */ 080 public void removeDataListener(IDataListener l); 081 082 /** 083 * Alert any registered listeners 084 */ 085 public void fireDataListeners(); 086 087 /** 088 * Add a listener which will be fired when aspects of the meta data change for 089 * instance origin of data 090 * @param l 091 */ 092 // TODO Add this when required. 093 //public void addMetadataListener(IMetadataListener l); 094 095 096 /** 097 * Remove a listener which will be fired when aspects of the meta data change for 098 * instance origin of data 099 * @param l 100 */ 101 // TODO Add this when required. 102 //public void removeDataListener(IMetadataListener l); 103}