    001/*-
    002 *******************************************************************************
    003 * Copyright (c) 2011, 2016 Diamond Light Source Ltd.
    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 * Contributors:
    010 *    Peter Chang - initial API and implementation and/or initial documentation
    011 *******************************************************************************/
    012
    013package org.eclipse.january.metadata;
    014
    015import java.io.Serializable;
    016import java.util.Collection;
    017import java.util.Map;
    018
    019import org.eclipse.january.MetadataException;
    020import org.eclipse.january.io.IDataAnalysisObject;
    021
    022/**
    023 * This interface describes the minimal metadata information that should be
    024 * associated with a Dataset or DataHolder. It is intended that
    025 * this interface will be implemented in an object that will then be
    026 * associated with a DataHolder or dataset using setMetadata(IMetadata).
    027 * <p>
    028 * All returned collections and maps are <b>unmodifiable</b>.
    029 */
    030public interface IMetadata extends IDataAnalysisObject, MetadataType, Serializable {
    031        /**
    032         * Update this when there are any serious changes to API
    033         */
    034        static final long serialVersionUID = 8640458661665962384L;
    035
    036        /**
    037         * Initialize metadata
    038         * @param metadata map
    039         */
    040        public void initialize(Map<String, ? extends Serializable> metadata);
    041
    042        /**
    043         *
    044         * @return the path to the original file, or null if there was not a file.
    045         */
    046        public String getFilePath();
    047
    048        /**
    049         * Returns a collection of dataset names or null if not implemented
    050         *
    051         * @return collection
    052         */
    053        public Collection<String> getDataNames();
    054
    055        /**
    056         * Can be implemented to return sizes of datasets
    057         * (size can be null if it is not known)
    058         * @return map of sizes
    059         */
    060        public Map<String, Integer> getDataSizes();
    061
    062        /**
    063         * Can be implemented to return shapes of dataset
    064         * (shape can be null if it is not known)
    065         * @return map of shapes
    066         */
    067        public Map<String, int[]> getDataShapes();
    068
    069        /**
    070         * Returns string value or null if not implemented
    071         *
    072         * @param key to find value
    073         * @return value
    074         * @throws MetadataException when failing to fetch metadata
    075         */
    076        public Serializable getMetaValue(String key) throws MetadataException;
    077
    078        /**
    079         * Returns a collection of metadata names
    080         * @return collection
    081         * @throws MetadataException when failing to fetch metadata
    082         */
    083        public Collection<String> getMetaNames() throws MetadataException;
    084
    085        /**
    086         * May be implemented to provide custom metadata in the form of a collection of serializable objects
    087         *
    088         * @return collection
    089         */
    090        public Collection<Serializable> getUserObjects();
    091
    092        /**
    093         * Copy of metadata
    094         * @return deep copy
    095         */
    096        @Override
    097        public IMetadata clone();
    098
    099        public void setFilePath(String filename);
    100
    101        /**
    102         * Add name and shape of a dataset to metadata
    103         *
    104         * @param name of dataset
    105         * @param shape (can be null or zero-length)
    106         *
    107         * (NOTE method should be public, people can define loaders outside this
    108         * package like the DESY FIO loader for instance.)
    109         */
    110        public void addDataInfo(String name, int... shape);
    111
    112        public void addNames(Collection<String> names);
    113
    114        /**
    115         * Set metadata map
    116         * @param metadata map
    117         */
    118        public void setMetadata(Map<String, ? extends Serializable> metadata);
    119}