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 name, 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> metadata); 119}