<commit_before>/*
 * Copyright (c) 2012 Diamond Light Source Ltd.
 *
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 */
package org.eclipse.dawnsci.analysis.api.persistence;

import java.util.List;
import java.util.Map;

import org.eclipse.dawnsci.analysis.api.diffraction.IPowderCalibrationInfo;
import org.eclipse.dawnsci.analysis.api.fitting.functions.IFunction;
import org.eclipse.dawnsci.analysis.api.metadata.IDiffractionMetadata;
import org.eclipse.dawnsci.analysis.api.processing.IOperation;
import org.eclipse.dawnsci.analysis.api.processing.OperationData;
import org.eclipse.dawnsci.analysis.api.processing.model.IOperationModel;
import org.eclipse.dawnsci.analysis.api.roi.IROI;
import org.eclipse.january.IMonitor;
import org.eclipse.january.dataset.IDataset;
import org.eclipse.january.dataset.ILazyDataset;
import org.eclipse.january.metadata.OriginMetadata;

/**
 * An IPersistent File is defined by what can be saved in an HDF5 file.<br>
 * In this case ROIs, masks, and images.<br>
 * <br>
 * The resulting tree structure of the HDF5 file saved will be the following:<br>
 * <pre>
 *     Entry name              |   Class        |    Description          
 * -----------------------------------------------------------------
 * entry                       |   Group        |                         
 * entry/data                  |   Group        |                         
 * entry/data/image            |   Dataset      |  64-bit floating-point  
 * entry/data/xaxis            |   Dataset      |  64-bit floating-point  
 * entry/data/yaxis            |   Dataset      |  64-bit floating-point  
 * entry/mask                  |   Group        |                         
 * entry/mask/mask0            |   Dataset      |  8-bit integer          
 * entry/mask/mask0/name       |   Attribute    |  String                 
 * entry/mask/mask1            |   Dataset      |  8-bit integer          
 * entry/mask/mask1/name       |   Attribute    |  String                 
 * entry/mask/...              |   ...          |  ...                    
 * entry/region                |   Dataset      |  8-bit integer          
 * entry/region/JSON           |   Attribute    |  String                 
 * entry/function              |   Dataset      |  64-bit floating-point  
 * entry/function/JSON         |   Attribute    |  String                 
 * entry/instrument/detector   |   Group        |                         
 * entry/process               |   Group        |                         
 * </pre>
 * The image can contain more than one Dataset with its corresponding axes.<br>
 * The region is an JSON serialized dataset. It can therefore contain more than one region.<br>
 * The entry/instrument/detector is an NX_detector group containing many datasets
 * required to build a IDiffractionMetadata object. <br>
 * 
 * Calling a setXXX(...) will write the data into the persistence file and will overwrite it
 * providing the data is repeated. It might add if the data is different, for instance adding
 * more regions with different names.
 * 
 * <br>
 * As IPersistentFile is auto-closeable, its close() method is called when used in a try-with-resources
 * block. Otherwise the close() method needs to be called.
 * <code>
 * // Get file ref
 * try (IPersistentFile fileRef = ...) {
 *    // save some things
 * }
 * </code>
 * <br>
 * 
 * @author <NAME>
 *
 */
public interface IPersistentFile extends AutoCloseable {

	/**
	 * Method to set a map of masks<br>
	 * This will write the data to entry/mask<br>
	 * If the masks already exist, they will be overwritten.<br>
	 * 
	 * @param masks
	 * @throws Exception 
	 */
	public void setMasks(Map<String, ? extends IDataset> masks) throws Exception;

	/**
	 * Method to add a mask to the current map of masks<br>
	 * If the mask already exist, it will be overwritten.<br>
	 * @param mon
	 * @param name
	 *           the name of the mask (must be unique)
	 * @param mask
	 *           the mask value as a BooleanDataset
	 * 
	 * @throws Exception
	 */
	public void addMask(IMonitor mon, String name, IDataset mask) throws Exception;

	/**
	 * Write data and axes in a single call.
	 * 
	 * For 1D data set yAxis as null
	 * 
	 * @param data
	 * @param xAxis
	 * @param yAxis
	 * @throws Exception
	 */
	public void setData(IDataset data, IDataset xAxis, IDataset yAxis) throws Exception;

	/**
	 * Write data and axes in a single call.
	 * <p>
	 * <b>Important:</b> the axes should be in order of the dimensions of the dataset
	 * <p>
	 * Multiple calls to this will expand the entry/data group to a NXcollection of NXdata subgroups.
	 * @param data
	 * @param axes
	 * @throws Exception
	 */
	public void setData(IDataset data, IDataset[] axes) throws Exception;

	/**
	 * Method to set datasets which persist history
	 * 
	 * @param data
	 * @throws Exception 
	 */
	public void setHistory(IDataset... data) throws Exception;

	/**
	 * Method to set datasets which persist history
	 * 
	 * @param mon
	 * @throws Exception 
	 */
	public Map<String, ILazyDataset> getHistory(IMonitor mon) throws Exception;

	/**
	 * Method to set the axes<br>
	 * This will write the data to entry/data<br>
	 * If the axes already exist, they will be overwritten.<br>
	 * <p>
	 * <b>Important:</b> the axes should be in order of the dimensions of the dataset
	 * @param axes
	 * @throws Exception 
	 */
	public void setAxes(IDataset... axes) throws Exception;

	/**<commit_msg>Remove unused and obsolete methods (#686)<commit_after>/*
 * Copyright (c) 2012 Diamond Light Source Ltd.
 *
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 */
package org.eclipse.dawnsci.analysis.api.persistence;

import java.util.List;
import java.util.Map;

import org.eclipse.dawnsci.analysis.api.diffraction.IPowderCalibrationInfo;
import org.eclipse.dawnsci.analysis.api.fitting.functions.IFunction;
import org.eclipse.dawnsci.analysis.api.metadata.IDiffractionMetadata;
import org.eclipse.dawnsci.analysis.api.processing.IOperation;
import org.eclipse.dawnsci.analysis.api.processing.OperationData;
import org.eclipse.dawnsci.analysis.api.processing.model.IOperationModel;
import org.eclipse.dawnsci.analysis.api.roi.IROI;
import org.eclipse.january.IMonitor;
import org.eclipse.january.dataset.IDataset;
import org.eclipse.january.dataset.ILazyDataset;
import org.eclipse.january.metadata.OriginMetadata;

/**
 * An IPersistent File is defined by what can be saved in an HDF5 file.<br>
 * In this case ROIs, masks, and images.<br>
 * <br>
 * The resulting tree structure of the HDF5 file saved will be the following:<br>
 * <pre>
 *     Entry name              |   Class        |    Description          
 * -----------------------------------------------------------------
 * entry                       |   Group        |                         
 * entry/data                  |   Group        |                         
 * entry/data/image            |   Dataset      |  64-bit floating-point  
 * entry/data/xaxis            |   Dataset      |  64-bit floating-point  
 * entry/data/yaxis            |   Dataset      |  64-bit floating-point  
 * entry/mask                  |   Group        |                         
 * entry/mask/mask0            |   Dataset      |  8-bit integer          
 * entry/mask/mask0/name       |   Attribute    |  String                 
 * entry/mask/mask1            |   Dataset      |  8-bit integer          
 * entry/mask/mask1/name       |   Attribute    |  String                 
 * entry/mask/...              |   ...          |  ...                    
 * entry/region                |   Dataset      |  8-bit integer          
 * entry/region/JSON           |   Attribute    |  String                 
 * entry/function              |   Dataset      |  64-bit floating-point  
 * entry/function/JSON         |   Attribute    |  String                 
 * entry/instrument/detector   |   Group        |                         
 * entry/process               |   Group        |                         
 * </pre>
 * The image can contain more than one Dataset with its corresponding axes.<br>
 * The region is an JSON serialized dataset. It can therefore contain more than one region.<br>
 * The entry/instrument/detector is an NX_detector group containing many datasets
 * required to build a IDiffractionMetadata object. <br>
 * 
 * Calling a setXXX(...) will write the data into the persistence file and will overwrite it
 * providing the data is repeated. It might add if the data is different, for instance adding
 * more regions with different names.
 * 
 * <br>
 * As IPersistentFile is auto-closeable, its close() method is called when used in a try-with-resources
 * block. Otherwise the close() method needs to be called.
 * <code>
 * // Get file ref
 * try (IPersistentFile fileRef = ...) {
 *    // save some things
 * }
 * </code>
 * <br>
 * 
 * @author <NAME>
 *
 */
public interface IPersistentFile extends AutoCloseable {

	/**
	 * Method to set a map of masks<br>
	 * This will write the data to entry/mask<br>
	 * If the masks already exist, they will be overwritten.<br>
	 * 
	 * @param masks
	 * @throws Exception 
	 */
	public void setMasks(Map<String, ? extends IDataset> masks) throws Exception;

	/**
	 * Method to add a mask to the current map of masks<br>
	 * If the mask already exist, it will be overwritten.<br>
	 * @param mon
	 * @param name
	 *           the name of the mask (must be unique)
	 * @param mask
	 *           the mask value as a BooleanDataset
	 * 
	 * @throws Exception
	 */
	public void addMask(IMonitor mon, String name, IDataset mask) throws Exception;

	/**
	 * Write data and axes in a single call.
	 * <p>
	 * <b>Important:</b> the axes should be in order of the dimensions of the dataset
	 * <p>
	 * Multiple calls to this will expand the entry/data group to a NXcollection of NXdata subgroups.
	 * @param data
	 * @param axes
	 * @throws Exception
	 */
	public void setData(IDataset data, IDataset... axes) throws Exception;

	/**
	 * Method to set datasets which persist history
	 * 
	 * @param data
	 * @throws Exception 
	 */
	public void setHistory(IDataset... data) throws Exception;

	/**
	 * Method to set datasets which persist history
	 * 
	 * @param mon
	 * @throws Exception 
	 */
	public Map<String, ILazyDataset> getHistory(IMonitor mon) throws Exception;

	/**
{'fraction_non_alphanumeric': 0.10237762237762238, 'fraction_numerical': 0.005034965034965035, 'mean_word_length': 2.103587962962963, 'pattern_counts': {'":': 0, '<': 59, '<?xml version=': 0, '>': 59, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6445629', 'n_tokens_mistral': 3107, 'n_tokens_neox': 2885, 'n_words': 991}