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
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
073         * @return value
074         * @throws MetadataException
075         */
076        public Serializable getMetaValue(String key) throws MetadataException;
077
078        /**
079         * Returns a collection of metadata names
080         * @return collection
081         * @throws MetadataException
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
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 n, int... shape);
111
112        public void addNames(Collection<String> names);
113
114        /**
115         * Set metadata map
116         * @param metadata
117         */
118        public void setMetadata(Map<String, ? extends Serializable> map);
119}