Package gda.scan

Class ScanBase

java.lang.Object
gda.scan.ScanBase
All Implemented Interfaces:
NestableScan, Scan, ScanChild, Serializable
Direct Known Subclasses:
AsynchronousTimeScan, CentroidScan, ConcurrentScanChild, GridScan, MultiRegionScan, MultiScan, PseudoDeviceTimeScan, StaticScan, TimeScan
public abstract class ScanBase extends Object implements NestableScan
Base class for objects using the Scan interface.
See Also:

  • Field Details

    • GDA_SCANBASE_FIRST_SCAN_NUMBER_FOR_TEST

      public static final String GDA_SCANBASE_FIRST_SCAN_NUMBER_FOR_TEST
      See Also:

    • GDA_SCANBASE_PRINT_TIMESTAMP_TO_TERMINAL

      public static final String GDA_SCANBASE_PRINT_TIMESTAMP_TO_TERMINAL
      See Also:

    • allDetectors

      protected List<Detector> allDetectors
      all the detectors being operated in this scan. This list is generated from detectors in allScannables and allDetectors. This list is to be used by DataHandlers when writing out the data.

    • allScannables

      protected List<Scannable> allScannables
      all the scannables being operated in this scan, but *not* Detectors. for some scan types this may be a single scannable object.

    • child

      protected Scan child

    • command

      protected String command
      Command line.

    • currentPointCount

      protected int currentPointCount
      Counter to get the current point number. 0 based as for ScanDataPoint

    • instrument

      protected String instrument
      instrument name.

    • isChild

      protected boolean isChild
      to allow nested scans to ignore the baton (as it will have already been taken)

    • name

      protected String name
      unique identifier for this scan

    • numberOfChildScans

      protected int numberOfChildScans

    • parent

      protected NestableScan parent

    • permissionLevel

      protected int permissionLevel

    • scanDataPointPipeline

      protected ScanDataPointPipeline scanDataPointPipeline
      Used to broadcast points and to write them to a DataWriter. Created before a scan is run.

    • stepId

      protected IScanStepId stepId

    • totalNumberOfPoints

      protected int totalNumberOfPoints

    • callCollectDataOnDetectors

      protected boolean callCollectDataOnDetectors

    • parentComponent

      protected ScanBase.ParentScanComponent parentComponent

  • Constructor Details

    • ScanBase

      protected ScanBase()

  • Method Details

    • representThrowable

      public static String representThrowable(Throwable e)
      Return a string representation of an error in the form 'ExceptionTypeName:message'. Useful for e.g. logging. Works for exceptions thrown from Jython code, which would otherwise always contain a null message.

    • getScanNumber

      public int getScanNumber()
      Specified by:
      getScanNumber in interface Scan
      Returns:
      The unique id of the scan. Null if not set

    • setScanNumber

      public void setScanNumber(int scanNumber)

    • requestFinishEarly

      public void requestFinishEarly()
      Description copied from interface: Scan
      Set this scan to complete current scan data point and complete normally without doing any further data points.
      Specified by:
      requestFinishEarly in interface Scan

    • isFinishEarlyRequested

      public boolean isFinishEarlyRequested()
      Specified by:
      isFinishEarlyRequested in interface Scan

    • setStatus

      public void setStatus(Scan.ScanStatus status)

    • getStatus

      public Scan.ScanStatus getStatus()
      Specified by:
      getStatus in interface Scan
      Returns:
      The Scan.ScanStatus

    • waitIfPaused

      protected void waitIfPaused() throws InterruptedException
      Throws:
      InterruptedException

    • scanRunning

      public boolean scanRunning()
      Returns true if the scan baton has been claimed by a scan that has already started.
      Returns:
      boolean

    • sortArguments

      @Deprecated(forRemoval=true, since="9.33") public static Object sortArguments(Object startObj, Object stopObj, Object stepObj)
      Deprecated, for removal: This API element is subject to removal in a future version.
      call checkStartStopStep(Object, Object, Object) instead
      This method is deprecated as it is misnamed, as it does in fact sort its arguments. Instead it returns a step size object with sign(s) corrected, and checks that

    • checkStartStopStep

      public static Object checkStartStopStep(Object startObj, Object stopObj, Object stepObj)
      Makes sure the step has the correct sign and that there are the same number of start, stop and step values. Start, stop and step can be a Number or either a list of array of numbers. It returns the correct step object, i.e. with the sign(s) corrected to be in the same direction as start -> stop.
      Parameters:
      startObj - start object
      stopObj - stop object
      stepObj - step object
      Returns:
      the correct step object, with sign(s) corrected

    • callAtCommandFailureHooks

      protected void callAtCommandFailureHooks()

    • collectData

      protected void collectData() throws Exception
      This should be called at each node of the scan. The collectData method is called for all detectors in the DetectorBase.ActiveDetectors static arraylist. Throws two types of errors as scans may want to handle these differently.

      NOTE: Used only by a few scans, not ScanBase or ConcurrentScan

      Throws:
      Exception

    • setScanIdentifierInScanDataPoint

      protected void setScanIdentifierInScanDataPoint(IScanDataPoint point)

    • readDevicesAndPublishScanDataPoint

      protected void readDevicesAndPublishScanDataPoint() throws Exception
      Samples the position of Scannables (via getPosition()), readouts detectors (via readout) and creates a ScanDataPoint
      Throws:
      Exception

    • createScanDataPoint

      protected ScanDataPoint createScanDataPoint() throws DeviceException
      Throws:
      DeviceException

    • readoutDetectorsAndPublish

      protected void readoutDetectorsAndPublish(ScanDataPoint point) throws Exception
      Readout detectors into ScanDataPoint and add to pipeline for possible completion and publishing.
      Parameters:
      point -
      Throws:
      Exception

    • waitForDetectorReadoutAndPublishCompletion

      public void waitForDetectorReadoutAndPublishCompletion() throws InterruptedException, ExecutionException
      Blocks while detectors are readout and point is added to pipeline (for the previous point).
      Throws:
      ExecutionException
      InterruptedException

    • cancelReadoutAndPublishCompletion

      protected void cancelReadoutAndPublishCompletion()

    • wrappedException

      protected static DeviceException wrappedException(Throwable e)

    • createScanDataPointPipeline

      protected void createScanDataPointPipeline() throws Exception
      Throws:
      Exception

    • createScanDataPointPipeline

      protected void createScanDataPointPipeline(DataWriter dataWriter)

    • doCollection

      public abstract void doCollection() throws Exception
      Description copied from interface: Scan
      The method in which the work of the scan is performed. This method assumes that the data handler has already been created and the baton claimed.
      Specified by:
      doCollection in interface Scan
      Throws:
      Exception

    • endScan

      protected void endScan() throws DeviceException, InterruptedException
      This should be called by all scans when they have finished, including when an exception has been raised.
      Throws:
      DeviceException
      InterruptedException

    • signalScanStarted

      protected void signalScanStarted()

    • signalScanComplete

      protected void signalScanComplete()

    • sendScanEvent

      protected void sendScanEvent(ScanEvent.EventType reason)

    • getScanInformation

      public ScanInformation getScanInformation()
      Specified by:
      getScanInformation in interface Scan

    • shutdownScandataPipeline

      protected void shutdownScandataPipeline(boolean waitForProcessingCompletion) throws DeviceException
      Throws:
      DeviceException

    • callDetectorsEndCollection

      protected void callDetectorsEndCollection() throws DeviceException
      Throws:
      DeviceException

    • callScannablesAtScanEnd

      protected void callScannablesAtScanEnd() throws DeviceException
      Throws:
      DeviceException

    • callScannablesAtScanLineEnd

      protected void callScannablesAtScanLineEnd() throws DeviceException
      Throws:
      DeviceException

    • generateRandomName

      protected String generateRandomName()

    • getChild

      public Scan getChild()
      Specified by:
      getChild in interface Scan
      Returns:
      The child scan if this scan is nested

    • getDataWriter

      public DataWriter getDataWriter()
      Gets the reference to the dataHandler object which this scan uses.
      Specified by:
      getDataWriter in interface Scan
      Returns:
      DataWriter

    • getDetectors

      public List<Detector> getDetectors()
      Description copied from interface: Scan
      Returns the list of Detector objects which form part of the scan.
      Specified by:
      getDetectors in interface Scan
      Returns:
      Vector of Detectors

    • getDimension

      public int getDimension()
      default implementation. Classes that derive from ScanBase which want to support the reporting of scan dimensions -@see getDimensions need to override this method
      Specified by:
      getDimension in interface Scan
      Returns:
      the number of points of this scan object - the whole scan execution can be a hierarchy of parent scan objects and layers of child scan objects
      See Also:

    • getDimensions

      protected int[] getDimensions()
      Returns:
      the dimensions of the hierarchy of scan and child scans that together constitute an individual scan execution For a 1d scan of 10 points the return value is new int[]{10} For a 2d scan of 10 x 20 points the return value is new int[]{10,20}

    • getName

      public String getName()
      Returns the unique identifier for this scan. Nested (child) scans share the same identifier as their parents.
      Specified by:
      getName in interface Scan
      Returns:
      String

    • getNumberOfChildScans

      public int getNumberOfChildScans()

    • getParent

      public NestableScan getParent()
      Specified by:
      getParent in interface ScanChild
      Returns:
      The parent scan if this scan is nested

    • getPositionCallableThreadPoolSize

      public int getPositionCallableThreadPoolSize()

    • getScanDataPointPipeline

      public ScanDataPointPipeline getScanDataPointPipeline()
      Description copied from interface: Scan
      Returns the ScanDataPoint pipeline.
      Specified by:
      getScanDataPointPipeline in interface Scan

    • getScanDataPointQueueLength

      public int getScanDataPointQueueLength()

    • getScannables

      public List<Scannable> getScannables()
      Description copied from interface: Scan
      Returns the list of all the Scannable objects which are part of this scan
      Specified by:
      getScannables in interface Scan
      Returns:
      Vector of Scannables

    • getScanPlotSettings

      public ScanPlotSettings getScanPlotSettings()
      Specified by:
      getScanPlotSettings in interface Scan
      Returns:
      Settings for plotting

    • getStepId

      public IScanStepId getStepId()
      Specified by:
      getStepId in interface Scan
      Returns:
      The identifier of the current step. This is scan dependent and maybe null

    • getStepIds

      protected List<IScanStepId> getStepIds()

    • getTotalNumberOfPoints

      public int getTotalNumberOfPoints()
      Specified by:
      getTotalNumberOfPoints in interface Scan
      Returns:
      the total number of nodes at which data will be collected in this scan. This includes all the dimensions in a multi-dimensional scan.

    • isChild

      public boolean isChild()
      Description copied from interface: Scan
      Returns true if this scan is nested inside another scan.
      Specified by:
      isChild in interface Scan
      Returns:
      if this scan is a child

    • isLineScanNeedsDoing

      public boolean isLineScanNeedsDoing()

    • notifyServer

      @Deprecated(since="at least 2012") public void notifyServer(Object data)
      Deprecated.
      Behaviour now in ScanDataPointPipeline implementations
      Give the command server the latest data object to fan out to its observers.
      Parameters:
      data -

    • notifyServer

      @Deprecated(since="at least 2012") public void notifyServer(Object source, Object data)
      Deprecated.
      Behaviour now in ScanDataPointPipeline implementations
      A better way to notify the observer which allows users to specify source of the data, not like the one above.
      Parameters:
      source -
      data -

    • numberOfScannablesThatCanProvidePositionCallables

      public int numberOfScannablesThatCanProvidePositionCallables()

    • pause

      public void pause()
      Description copied from interface: Scan
      pause the scans progress
      Specified by:
      pause in interface Scan

    • prepareDevicesForCollection

      protected void prepareDevicesForCollection() throws Exception
      Throws:
      Exception

    • callScannablesAtScanStart

      protected void callScannablesAtScanStart() throws DeviceException
      Throws:
      DeviceException

    • callScannablesAtScanLineStart

      protected void callScannablesAtScanLineStart() throws DeviceException
      Throws:
      DeviceException

    • prepareForCollection

      public void prepareForCollection() throws Exception
      This should called by all scans just before they start to collect data. It resets the static variable which the scan classes use and creates a dataHandler if one has not been created yet.
      Specified by:
      prepareForCollection in interface Scan
      Throws:
      Exception

    • prepareScanForCollection

      protected void prepareScanForCollection() throws Exception
      Throws:
      Exception

    • prepareScanNumber

      protected void prepareScanNumber() throws IOException
      Throws:
      IOException

    • prepareStaticVariables

      protected void prepareStaticVariables()

    • reorderScannables

      protected void reorderScannables()
      Order the allScannables vector using the 'level' attribute.

    • resume

      public void resume()
      Description copied from interface: Scan
      resume the scans progress after a pause has been called
      Specified by:
      resume in interface Scan

    • run

      public final void run() throws Exception
      Description copied from interface: Scan
      allows the scan in its own thread. This should NOT be called directly otherwise this may cause thread handling issues and instability in the command server. runScan() should be called instead.
      Specified by:
      run in interface Scan
      Throws:
      Exception

    • runScan

      public void runScan() throws InterruptedException, Exception
      Description copied from interface: Scan
      Does the work of creating a new thread and calling the run() method. Inheriting classes may also declare a runScan method with arguments identical to their constructor. The convention would be to create a new scan object, and then call this runScan method.
      Specified by:
      runScan in interface Scan
      Throws:
      InterruptedException
      Exception

    • setChild

      public void setChild(Scan child)
      Specified by:
      setChild in interface Scan
      Parameters:
      child - The child of this scan if this scan is nested

    • setDataWriter

      public void setDataWriter(DataWriter dataWriter)
      Description copied from interface: Scan
      Gives the scan a reference to the DataWriter it should use to record data. This will create a new ScanDataPointPipeline appropriate for the Scannables to be scanned.
      Specified by:
      setDataWriter in interface Scan
      Parameters:
      dataWriter -

    • setDetectors

      public void setDetectors(List<Detector> allDetectors)
      Description copied from interface: Scan
      Sets the list of Detectors for this scan.
      Specified by:
      setDetectors in interface Scan
      Parameters:
      allDetectors -
      See Also:

    • setIsChild

      public void setIsChild(boolean child)
      Description copied from interface: Scan
      Tells the scan if it is a child.
      Specified by:
      setIsChild in interface Scan
      Parameters:
      child -

    • setLineScanNeedsDoing

      public void setLineScanNeedsDoing(boolean lineScanNeedsDoing)

    • setNumberOfChildScans

      public void setNumberOfChildScans(int numberOfChildScans)

    • setParent

      public void setParent(NestableScan parent)
      Specified by:
      setParent in interface ScanChild
      Parameters:
      parent - The parent of this scan if this scan is nested

    • setPositionCallableThreadPoolSize

      public void setPositionCallableThreadPoolSize(int positionCallableThreadPoolSize)

    • setScanDataPointPipeline

      public void setScanDataPointPipeline(ScanDataPointPipeline scanDataPointPipeline)
      Description copied from interface: Scan
      Sets the scan data point pipeline used to populate, write and broadcast ScanDataPoints. Should not normally be set directly except on a child (or sub) scan.
      Specified by:
      setScanDataPointPipeline in interface Scan
      Parameters:
      scanDataPointPipeline -

    • setScanDataPointQueueLength

      public void setScanDataPointQueueLength(int scanDataPointQueueLength)

    • setScannables

      public void setScannables(List<Scannable> allScannables)
      Description copied from interface: Scan
      Sets the list of all the Scannable objects. This should only be used for a parent scan giving its list to a child scan and not for setting up a scan (that work is done by ScanBase.setUp).
      Specified by:
      setScannables in interface Scan
      Parameters:
      allScannables -

    • setScanPlotSettings

      public void setScanPlotSettings(ScanPlotSettings scanPlotSettings)
      Specified by:
      setScanPlotSettings in interface Scan

    • setStepId

      public void setStepId(IScanStepId stepId)
      Specified by:
      setStepId in interface Scan
      Parameters:
      stepId - The identifier of the current step. This is scan dependent and maybe null

    • setUp

      protected void setUp()
      This should be called by all scans during their constructor. In this method the objects to scan over and the detectors to use are identified, and the data handlers objects are created and setup.

    • wasScanExplicitlyHalted

      public boolean wasScanExplicitlyHalted()
      True if the scan was asked to complete early

    • checkThreadInterrupted

      protected void checkThreadInterrupted() throws InterruptedException
      Throws:
      InterruptedException