org.eclipse.dawnsci.nexus.INexusDevice Maven / Gradle / Ivy

/*-
 *******************************************************************************
 * Copyright (c) 2011, 2016 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
 *
 * Contributors:
 *    Matthew Gerring - initial API and implementation and/or initial documentation
 *******************************************************************************/
package org.eclipse.dawnsci.nexus;

import org.eclipse.dawnsci.nexus.builder.AbstractNexusObjectProvider;
import org.eclipse.dawnsci.nexus.builder.CustomNexusEntryModification;
import org.eclipse.dawnsci.nexus.builder.NexusObjectProvider;
import org.eclipse.january.dataset.LazyDataset;

/**
 * Any device which can write NeXus should implement this interface.
 * 
 * This can be done easily by extending {@link AbstractNexusObjectProvider}
 * 
 * @param  the type of nexus object to be created, a sub-interface of {@link NXobject},
 *   e.g. {@link NXdetector}
 *  
 * @author Matthew Gerring, Matthew Dickie
 *
 */
public interface INexusDevice {

	/**
	 * Returns the object provider required for writing correct NeXus files.
	 * 
	 * 
	 * In this method you should prepare the {@link LazyDataset}s the device
	 * will fill during the scan. You can also write out static device metadata,
	 * which will not change during the scan.
	 * 
	 * 
	 * Use the methods on {@link NexusNodeFactory} to create a NeXus object which
	 * matches the device e.g. a {@link NXdetector}.
	 * final NXdetector detector = NexusNodeFactory.createNXdetector();
	 * 
	 * 
	 * On the detector object you can create {@link LazyDataset}s and keep
	 * references which you can later use during the scan to write data. e.g.
	 * imageData = detector.initializeLazyDataset(NXdetector.NX_DATA, info.getRank() + 2, Dataset.FLOAT64);
	 * You should also set chunking on the {@link LazyDataset}s you create e.g. imageData.setChunking(info.createChunk(detectorXSize, detectorYSize));.
	 * 
	 * In this method you can also write static metadata such as the detector
	 * exposure e.g.
	 * detector.setField("exposure_time", model.getExposure());. Or
	 * static datasets such as the image axis data
	 * detector.setDataset("image_x_axis", DatasetFactory.createLinearSpace(minX, maxX, xPoints, Dataset.FLOAT64));
	 * For fields that are defined in the NXDL base class definition for the
	 * returned nexus object, a setXXX or setXXXScalar method may be used as
	 * appropriate, e.g. detector.setLocalName(DatasetFactory.createFromObject("my detector"));
	 * or detector.setLocalNameScalar("my detector");
	 * 
	 * If this device is a 'metadata scannable', then the device should write
	 * its data at this point directly into the returned nexus object. This can be
	 * done with the {@link NXobject#setField(String, Object)} method, or the
	 * setXXXScalar methods for fields defined in the appropriate 
	 * NXDL base class definition.
	 * 
	 * @param info
	 *            Information about the scan which can be useful when creating
	 *            dataset e.g. info.getRank()
	 * @return The {@link NXobject} created using the nodeFactory
	 *         to represent this device
	 * @throws NexusException if the nexus object could not be created for any reason
	 */
	NexusObjectProvider getNexusProvider(NexusScanInfo info) throws NexusException;
	
	/**
	 * Returns an object that performs a custom modification to
	 * an {@link NXentry}.
	 * 

	 * NOTE: Use this method with caution as it can be used to break the central
	 * design concept of the new Nexus writing framework, namely that the nexus framework itself
	 * knows where to put the nexus groups for devices and build any required {@link NXdata} groups.
	 *  It is currently used by the new Nexus framework to partially support legacy GDA8 spring
	 * configurations, in particular the 'locationmap'.
	 * 

	 * The nexus framework will call this method after {@link #createNexusObject(NexusNodeFactory, NexusScanInfo)},
	 * so this method create links to nodes created in that method if appropriate.
	 * 
	 * The easiest way to implement this method is to make this object itself also implement
	 * {@link CustomNexusEntryModification}. This method can then be overridden to simply
	 * return this.
	 * 
	 * @return a {@link CustomNexusEntryModification} that makes a custom modification,
	 *    or null if this device should not make custom modifications
	 */
	default CustomNexusEntryModification getCustomNexusModification() {
		return null;
	}
	
}