    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}