Package org.eclipse.dawnsci.nexus.builder

Class AbstractNexusObjectProvider<N extends NXobject>

java.lang.Object
org.eclipse.dawnsci.nexus.builder.AbstractNexusObjectProvider<N>
Type Parameters:
N - nexus base class type, a subinterface of NXobject
All Implemented Interfaces:
NexusEntryModification, NexusObjectProvider<N>
Direct Known Subclasses:
NexusObjectWrapper, NexusUser
public abstract class AbstractNexusObjectProvider<N extends NXobject> extends Object implements NexusObjectProvider<N>
Abstract implementation of NexusObjectProvider.
Use this class to help implementing NexusObjectProvider, for example: 
   

        class Detector implements IRunnableDevice, INexusDevice {

                private NexusObjectProvider prov;

                public Detector() {
                        prov = new AbstractNexusObjectProvider(NexusBaseClass.NX_DETECTOR) {

                                protected NXdetector doCreateNexusObject(NexusNodeFactory nodeFactory) {
                                        final NXdetectorImpl detector = nodeFactory.createNXdetector();
                                        final int rank = 4;
                                        detector.initializeLazyDataset(NXdetectorImpl.NX_DATA, rank, Double.class);
                                        return detector;
                                }       
                        };
                }

                public NexusObjectProvider getNexusProvider() {
                        return prov;
                }

                public void write(...) {
                        // Use prov to help write the required datasets.
                }
        }

  • Field Details

  • Constructor Details

    • AbstractNexusObjectProvider

      protected AbstractNexusObjectProvider(String name, NexusBaseClass nexusBaseClass)
      Creates a new AbstractNexusObjectProvider for given name, base class type and data node name.
      Parameters:
      name - name
      nexusBaseClass - base class type

    • AbstractNexusObjectProvider

      public AbstractNexusObjectProvider(String name, NexusBaseClass nexusBaseClass, String defaultDataFieldName, String... additionalDataFieldNames)
      Creates a new AbstractNexusObjectProvider for given name, base class type and data node name. The default data field will be used as the @signal for an NexusBaseClass.NX_DETECTOR when building an NXdata for this object, otherwise if this device is the default axis for a particular dimension of the @signal field of the device, this is the field that will be added to the @axes attribute of the NXdata group for that dimension.
      Parameters:
      name - name
      nexusBaseClass - base class type
      defaultDataFieldName - default data field, the default signal field for a detector, the default axis field for any other type of nexus object
      additionalDataFieldNames - the names of any additional data fields

  • Method Details

    • getDefaultName

      public static String getDefaultName(NexusBaseClass nexusBaseClass)

    • getNexusObject

      public final N getNexusObject()
      Description copied from interface: NexusObjectProvider
      Returns the NeXus object for this provider, creating it if necessary The same NeXus object must be returned each time this method is invoked
      Specified by:
      getNexusObject in interface NexusObjectProvider<N extends NXobject>
      Returns:
      NeXus object or null

    • createNexusObject

      protected abstract N createNexusObject()

    • getName

      public String getName()
      Description copied from interface: NexusObjectProvider
      Get the name of the provider. This is used as the name of the NeXus object (i.e. group) in the parent group to which it is added.
      Specified by:
      getName in interface NexusObjectProvider<N extends NXobject>
      Returns:
      name of base

    • setName

      public void setName(String name)

    • getNexusBaseClass

      public NexusBaseClass getNexusBaseClass()
      Description copied from interface: NexusObjectProvider
      Return the NeXus base class enum value for the type NeXus object this provider creates.
      Specified by:
      getNexusBaseClass in interface NexusObjectProvider<N extends NXobject>
      Returns:
      the NexusBaseClass for this object provider

    • getScanRole

      public NexusScanInfo.ScanRole getScanRole()
      Description copied from interface: NexusObjectProvider
      Returns a NexusScanInfo.ScanRole defining the role of the device for this nexus object provider performs in the scan. This affects how the fields within the nexus object returned by NexusObjectProvider.getNexusObject() are added to the NXdata group, if any. For example and NXdata group will be created for each primary field of each detector, and axis fields The nexus writing framework already knows the NexusScanInfo.ScanRole of the INexusDevice whose invalid input: 'method returned this NexusObjectProvider, as the INexusDevices are grouped by ScanRole in the NexusScanModel. However, some INexusDevices may correspond to multiple devices with different roles in the scan - a malcolm device is an example of this. Where this is the case, this method can returns a non-null value to override the scan ro @return the role of this device in the scan, where <code>null</code> tells the nexus writing framework to use the scan role of the {@link INexusDevice} in the NexusScanModel which produced this provider'
      Specified by:
      getScanRole in interface NexusObjectProvider<N extends NXobject>

    • setScanRole

      public void setScanRole(NexusScanInfo.ScanRole scanRole)

    • getExternalFileNames

      public Set<String> getExternalFileNames()
      Description copied from interface: NexusObjectProvider
      Returns the names of the external HDF5 file(s) that this device writes its data to, or null if none.
      Specified by:
      getExternalFileNames in interface NexusObjectProvider<N extends NXobject>
      Returns:
      name of external file, or null

    • setDefaultExternalFileName

      public void setDefaultExternalFileName(String externalFileName)
      Set the name of the external file that this device writes its data to.
      Parameters:
      externalFileName - external file name

    • addExternalFileName

      public void addExternalFileName(String externalFileName)
      Adds an external filename to this AbstractNexusObjectProvider.
      Parameters:
      externalFileName -

    • addExternalLink

      public void addExternalLink(NXobject groupNode, String fieldName, String pathToNode, int rank)
      A convenience method to add an external link to the given group node with the given name, while also setting the rank of the external dataset within this AbstractNexusObjectProvider. This is required to be set when adding a NexusObjectProvider with external links to a NexusDataBuilder in order for the axes and <axisname>_indices to be created.

      An external file must have been set by calling setDefaultExternalFileName(String) prior to calling this method.

      Parameters:
      groupNode - group node to add external link to
      fieldName - name of external dataset within the group
      pathToNode - path of node to link to within the external file
      rank - the rank of the

    • addExternalLink

      public void addExternalLink(NXobject groupNode, String fieldName, String externalFileName, String pathToNode, int rank)

    • getExternalDatasetRank

      public int getExternalDatasetRank(String fieldName)
      Description copied from interface: NexusObjectProvider
      Returns the rank of the external dataset with the given field name.
      Specified by:
      getExternalDatasetRank in interface NexusObjectProvider<N extends NXobject>
      Parameters:
      fieldName - field name
      Returns:
      rank of external dataset with given field name

    • setExternalDatasetRank

      public void setExternalDatasetRank(String fieldName, int rank)
      Set the rank of an external dataset within the nexus object returned by getNexusObject(). The method setDefaultExternalFileName(String) must have been invoked before calling this method.
      Parameters:
      fieldName - the name of the external dataset within the nexus object
      rank - the rank of the external dataset

    • getPrimaryDataFieldName

      public String getPrimaryDataFieldName()
      Description copied from interface: NexusObjectProvider
      Returns the name of the default data field to write to within the nexus object. If this object is added as the primary device to an NXdata group, then this is the field name of the default field, i.e. the field referred to by the @signal attribute.

      If additional NXdata groups should be created for other fields in this scan, then the names of these fields should be returned by NexusObjectProvider.getAdditionalPrimaryDataFieldNames().

      Specified by:
      getPrimaryDataFieldName in interface NexusObjectProvider<N extends NXobject>
      Returns:
      default data field name, this cannot be null

    • setPrimaryDataFieldName

      public void setPrimaryDataFieldName(String primaryDataFieldName)
      Sets the name of the field to use as the primary data field. If this device is the primary device for a scan then this field is used as the @signal field for the NXdata group.
      Parameters:
      primaryDataFieldName - name of the primary data field

    • getDefaultAxisDataFieldName

      public String getDefaultAxisDataFieldName()
      Description copied from interface: NexusObjectProvider
      Returns the name of the default axis field for this nexus object, if any. If this object is added as a device to an NXdata then this is the field that will be added as a default axis of the @signal field, for example for a positioner this may be the demand field.
      Specified by:
      getDefaultAxisDataFieldName in interface NexusObjectProvider<N extends NXobject>
      Returns:
      name of demand field, or null if none.

    • setDefaultAxisDataFieldName

      public void setDefaultAxisDataFieldName(String defaultAxisDataFieldName)
      Sets the name of the data field for this device that acts as an axis. This field should only be set if this device is a scannable, i.e. a device that is set to a position at a particular point in the scan.
      Parameters:
      defaultAxisDataFieldName -

    • getAxisDataFieldNames

      public List<String> getAxisDataFieldNames()
      Description copied from interface: NexusObjectProvider
      Returns the axis data field names for this object. These are the fields that will be linked to when this this object is added to an NexusDataBuilder to construct an NXdata group. This method should not return the names of primary data fields, nor should it return the names of data fields which should only be added to the NXdata groups for a particular primary data field (an NXdata group is added to the scan for each primary data field, as returned by NexusObjectProvider.getPrimaryDataFieldName() and NexusObjectProvider.getAdditionalPrimaryDataFieldNames()). The primary data field will also be linked to in an NXdata group, except where this device is the primary device for the scan where it is not linked to in the NXdata groups for additional primary data fields.
      Specified by:
      getAxisDataFieldNames in interface NexusObjectProvider<N extends NXobject>
      Returns:
      name of data fields for this object

    • setAxisDataFieldNames

      public void setAxisDataFieldNames(String... axisDataFieldNames)
      Sets the names of the data fields for this device. Each data field will be added to any NXdata group created for this scan.
      Parameters:
      axisDataFieldNames - names of data fields

    • addAxisDataFieldName

      public void addAxisDataFieldName(String dataFieldName)
      Adds the given name to the names of the axis data fields for this device. Each data field will be added to any NXdata group created for this scan (an NXdata group is created for each primary data field). In order to add a data field that should only be added to the NXdata group for a specific primary data field use addAxisDataFieldForPrimaryDataField(String, String, Integer, int...)
      Parameters:
      dataFieldName - names of data fields

    • addAxisDataFieldNames

      public void addAxisDataFieldNames(String... axisDataFieldNames)
      Adds the given names to the names of the data fields for this device. Each data field will be added to any NXdata group created for this scan (an NXdata group is created for each primary data field). In order to add a data field that should only be added to the NXdata group for a specific primary data field use addAxisDataFieldForPrimaryDataField(String, String, Integer, int...)
      Parameters:
      axisDataFieldNames - names of data fields

    • addAxisDataField

      public void addAxisDataField(String dataFieldName, Integer defaultAxisDimension, int... dimensionMappings)
      Adds the given axis data field for the primary data field of this device. It will be added as an axis field to the NXdata group where the primary data field of this device is the @signal field.
      Parameters:
      dataFieldName - name of data field
      defaultAxisDimension - the dimension of the primary data field for which this field is a default axis
      dimensionMappings - mappings between the dimensions of the axis data field and the primary data field for this device, can be omitted if the mapping is one-to-one as is usually the case

    • getAxisDataFieldsForPrimaryDataField

      public List<String> getAxisDataFieldsForPrimaryDataField(String primaryDataFieldName)
      Returns the names of the data fields that are axes for the given primary data field within this device.
      Specified by:
      getAxisDataFieldsForPrimaryDataField in interface NexusObjectProvider<N extends NXobject>
      Parameters:
      primaryDataFieldName - primary data field name
      Returns:
      names of data fields

    • addAxisDataFieldForPrimaryDataField

      public void addAxisDataFieldForPrimaryDataField(String dataFieldName, String primaryDataFieldName, Integer defaultAxisDimension, int... dimensionMappings)
      Adds a data field as an axis to a given primary data field. This field is only added to the NXdata group for the given primary data field (i.e. where it is the @signal field).
      Parameters:
      dataFieldName - name of data field to add
      primaryDataFieldName - name of primary data field that the new data field is an axis for
      defaultAxisDimension -
      dimensionMappings - (optional) dimension mappings between the new data field and the primary data. If this argument is not specified then the dimension mappings will be assumed to be {0, 1, 2, etc} if the data field is multidimensional, or { defaultAxisDimension } if the data field has a single dimension

    • addAdditionalPrimaryDataFieldName

      public void addAdditionalPrimaryDataFieldName(String dataFieldName)
      Add an additional primary data field. This is a data field for which, when this device is the primary device in a scan, an additional NXdata group should be created with this field as the @signal field.
      Parameters:
      dataFieldName - the name of the additional primary data field

    • getAdditionalPrimaryDataFieldNames

      public List<String> getAdditionalPrimaryDataFieldNames()
      Description copied from interface: NexusObjectProvider
      Returns the names of any additional primary data fields for this device. This method indicates that if this device is to be used to create an NXdata with the field NexusObjectProvider.getPrimaryDataFieldName() as the default (signal field), then additional NXdata groups should be created for each of these fields.
      Specified by:
      getAdditionalPrimaryDataFieldNames in interface NexusObjectProvider<N extends NXobject>
      Returns:
      additional primary data field names

    • getCategory

      public NexusBaseClass getCategory()
      Description copied from interface: NexusObjectProvider
      Returns the category for this NexusObjectProvider. When adding a nexus object to a NexusEntryBuilder, the nexus object will be added to a group of this type, if one exists in the skeleton tree. For example a NexusObjectProvider that provides an NXpositioner would normally be added to the NXinstrument group, but if this method returns NexusBaseClass.NX_SAMPLE, then it will instead be added to the NXsample group.
      Specified by:
      getCategory in interface NexusObjectProvider<N extends NXobject>
      Returns:
      category for this object

    • setCategory

      public void setCategory(NexusBaseClass category)

    • getCollectionName

      public String getCollectionName()
      Description copied from interface: NexusObjectProvider
      Returns the name of the collection for this NexusObjectProvider. When adding a nexus object to a NexusEntryBuilder, if this method does not return null, then the nexus object will be added to the NXcollection with this name within the group that it would have been added to otherwise. The collection will be created if it does not already exist.
      Specified by:
      getCollectionName in interface NexusObjectProvider<N extends NXobject>
      Returns:
      collection name or null

    • setCollectionName

      public void setCollectionName(String collectionName)

    • getDefaultAxisDimension

      public Integer getDefaultAxisDimension(String primaryDataFieldName, String axisDataFieldName)
      Description copied from interface: NexusObjectProvider
      Returns the dimension of the given primary data field for which the data field with the given name is a default axis, or null if this field does not provide a default axis to the default data field. This method is required only when this device provides the default data field of an NXdata group (i.e. that referred to by the @signal attribute), and additional data fields within this device provide default axis for that data field
      Specified by:
      getDefaultAxisDimension in interface NexusObjectProvider<N extends NXobject>
      Parameters:
      primaryDataFieldName - name of primary data field
      axisDataFieldName - axis data field name
      Returns:
      dimension of the default data field for which the field with the given name provides a default axis, or null if none

    • getDimensionMappings

      public int[] getDimensionMappings(String primaryDataFieldName, String axisDataFieldName)
      Description copied from interface: NexusObjectProvider
      Returns the dimension mappings between the data field and the primary data field with the given names. This method is required only when this device provides the default data field of an NXdata group (i.e. that referred to by the signal attribute), and additional data fields within that and the default data field of this device.
      Specified by:
      getDimensionMappings in interface NexusObjectProvider<N extends NXobject>
      Parameters:
      primaryDataFieldName - field name
      axisDataFieldName - axis data field name
      Returns:
      dimension mappings between the field with the given name and the default data field

    • getWriteableDataset

      public org.eclipse.january.dataset.ILazyWriteableDataset getWriteableDataset(String fieldName)

    • addAuxilaryDataGroup

      public void addAuxilaryDataGroup(String dataGroupName, List<String> dataFieldNames)

    • setAuxiliaryDataGroups

      public void setAuxiliaryDataGroups(Map<String,List<String>> auxiliaryDataFieldNames)

    • addAuxiliaryDataField

      public void addAuxiliaryDataField(String dataGroupName, String dataFieldName)

    • getAuxiliaryDataGroupNames

      public Set<String> getAuxiliaryDataGroupNames()
      Description copied from interface: NexusObjectProvider
      Returns the names of any auxiliary data groups to create. An auxiliary data group is one that groups a number of data group with the same rank together. A typical use case would be for statistics about the main data field for the device, such as min, max, mean, sum, etc.
      Specified by:
      getAuxiliaryDataGroupNames in interface NexusObjectProvider<N extends NXobject>
      Returns:
      names of auxiliary data groups

    • getAuxiliaryDataFieldNames

      public List<String> getAuxiliaryDataFieldNames(String primaryFieldName)
      Description copied from interface: NexusObjectProvider
      Returns the names of the data fields for the given auxiliary data group as a List. These are the plottable fields for that data group. In the typical use case of an auxiliary data group for statistics.
      Specified by:
      getAuxiliaryDataFieldNames in interface NexusObjectProvider<N extends NXobject>
      Parameters:
      primaryFieldName - name of the auxiliary data group
      Returns:
      list of names of data fields for the auxiliary data group with the given name, or null if there is no such auxiliary data group

    • isUseDeviceNameInNXdata

      public Optional<Boolean> isUseDeviceNameInNXdata()
      Description copied from interface: NexusObjectProvider
      Returns whether the name of this device name (as returned by NexusObjectProvider.getName() should be used in the names of the links created within NXdata groups to the fields within the nexus object for this instance. If this is not the case, the links to the fields created in the NXdata group will have the same name as they do in the nexus object for this instance (i.e. that returned by NexusObjectProvider.getNexusObject().

      If this method returns an empty Optional then the default behaviour is to use the device name in the names of the links in the NXdata for this device for the axes device for the NXdata group (often these are the devices being scanned, whose nexus object is an NXpositioner), but not for the primary data device

      If the device name is to be used in the name of the links created then:

      • If a single field from this device is added to the NXdata group then that link will simply have the same name as this device.
      • If multiple fields from this devices are added to an NXdata group then name of the link created within the NXdata group will be the name of the device, followed by an underscore, followed by the name of the field within the nexus object for this instance.
      Specified by:
      isUseDeviceNameInNXdata in interface NexusObjectProvider<N extends NXobject>
      Returns:
      an Optional containing Boolean.TRUE to use the device name when linking fields in an NXdata group, Boolean.FALSE to not use the device name, and an empty optional to use the default behaviour, i.e. use the device name for axis devices only

    • setUseDeviceNameInNXdata

      public void setUseDeviceNameInNXdata(boolean useDeviceNameInNXdata)

    • getPropertyValue

      public Object getPropertyValue(String propertyName)
      Description copied from interface: NexusObjectProvider
      Returns the value of the application defined property of this object with the given name. This allows arbitrary application or implementation specific information to be associated with this object.

      Note that these properties should not be confused with the fields of the NeXus object returned by NexusObjectProvider.getNexusObject().

      Specified by:
      getPropertyValue in interface NexusObjectProvider<N extends NXobject>
      Parameters:
      propertyName - name of property
      Returns:
      the value of the property with the given name, or null if no property with the given name is set

    • setPropertyValue

      public void setPropertyValue(String propertyName, Object value)