Package org.eclipse.dawnsci.nexus.builder

Interface NexusObjectProvider<N extends NXobject>

Type Parameters:
N - a subinterface of NXobject that an object
All Superinterfaces:
NexusEntryModification
All Known Implementing Classes:
AbstractNexusObjectProvider, NexusObjectWrapper, NexusUser, NXObjectProvider
public interface NexusObjectProvider<N extends NXobject> extends NexusEntryModification
Defines the interface for a class that can create a a NeXus object of a particular type. (i.e. an instance of a NeXus base class). For example, this interface can be implemented by classes representing devices such as positioners or detectors; alternatively a wrapper class implementing this class could contain objects representing such devices, this allows for greater decoupling.

  • Method Details

    • getName

      String getName()
      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.
      Returns:
      name of base

    • getNexusBaseClass

      NexusBaseClass getNexusBaseClass()
      Return the NeXus base class enum value for the type NeXus object this provider creates.
      Returns:
      the NexusBaseClass for this object provider

    • getNexusObject

      N getNexusObject()
      Returns the NeXus object for this provider, creating it if necessary The same NeXus object must be returned each time this method is invoked
      Returns:
      NeXus object or null

    • getCategory

      NexusBaseClass getCategory()
      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.
      Returns:
      category for this object

    • getCollectionName

      String getCollectionName()
      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.
      Returns:
      collection name or null

    • getScanRole

      NexusScanInfo.ScanRole getScanRole()
      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 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'

    • getExternalFileNames

      Set<String> getExternalFileNames()
      Returns the names of the external HDF5 file(s) that this device writes its data to, or null if none.
      Returns:
      name of external file, or null

    • getExternalDatasetRank

      int getExternalDatasetRank(String fieldName)
      Returns the rank of the external dataset with the given field name.
      Parameters:
      fieldName - field name
      Returns:
      rank of external dataset with given field name
      Throws:
      IllegalArgumentException - if no such field exists

    • getAxisDataFieldNames

      List<String> getAxisDataFieldNames()
      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 getPrimaryDataFieldName() and 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.
      Returns:
      name of data fields for this object

    • getPrimaryDataFieldName

      String getPrimaryDataFieldName()
      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 getAdditionalPrimaryDataFieldNames().

      Returns:
      default data field name, this cannot be null

    • getAdditionalPrimaryDataFieldNames

      List<String> getAdditionalPrimaryDataFieldNames()
      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 getPrimaryDataFieldName() as the default (signal field), then additional NXdata groups should be created for each of these fields.
      Returns:
      additional primary data field names

    • getAxisDataFieldsForPrimaryDataField

      List<String> getAxisDataFieldsForPrimaryDataField(String primaryDataFieldName)
      Returns the names of any data fields that are axes for the primary data field with the given name. These data fields are those that should be added to the NXdata group for the primary data field with the given name (and not those for other primary data fields), in addition to the data fields returned by getAxisDataFieldNames()
      Parameters:
      primaryDataFieldName - primary data field name
      Returns:
      names of data fields

    • getDefaultAxisDataFieldName

      String getDefaultAxisDataFieldName()
      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.
      Returns:
      name of demand field, or null if none.

    • getDefaultAxisDimension

      Integer getDefaultAxisDimension(String primaryDataFieldName, String axisDataFieldName)
      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
      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

      int[] getDimensionMappings(String primaryDataFieldName, String axisDataFieldName)
      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.
      Parameters:
      primaryDataFieldName - field name
      axisDataFieldName - axis data field name
      Returns:
      dimension mappings between the field with the given name and the default data field

    • getAuxiliaryDataGroupNames

      default Set<String> getAuxiliaryDataGroupNames()
      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.
      Returns:
      names of auxiliary data groups

    • getAuxiliaryDataFieldNames

      default List<String> getAuxiliaryDataFieldNames(String dataGroupName)
      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.
      Parameters:
      dataGroupName - 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

      Optional<Boolean> isUseDeviceNameInNXdata()
      Returns whether the name of this device name (as returned by 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 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.
      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

    • getPropertyValue

      Object getPropertyValue(String propertyName)
      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 getNexusObject().

      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