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
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
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
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}