Package org.eclipse.scanning.event.remote

Class MalcolmDeviceProxy

java.lang.Object

org.eclipse.scanning.event.remote.MalcolmDeviceProxy

All Implemented Interfaces:

AutoCloseable, IActivatable, IPausableDevice<IMalcolmModel>, IResettableDevice, IRunnableDevice<IMalcolmModel>, IRunnableEventDevice<IMalcolmModel>, IDeviceRoleActor, IConnection, IConfigurable<IMalcolmModel>, ILevel, IModelProvider<IMalcolmModel>, INameable, IValidator<IMalcolmModel>, IMalcolmDevice

public class MalcolmDeviceProxy
extends Object
implements IMalcolmDevice

Field Summary

Fields

Modifier and Type	Field	Description
protected IEventService	eservice
protected DeviceInformation<IMalcolmModel>	info
protected String	name
protected final IRequester<DeviceRequest>	requester
protected URI	uri

Fields inherited from interface org.eclipse.scanning.api.ILevel

MAXIMUM

Method Summary

Modifier and Type	Method	Description
void	abort()	Call to terminate the scan before it has finished.
void	addMalcolmListener(IMalcolmEventListener listener)	Add a listener to malcolm changes.
void	addRunListener(IRunListener l)	A listener which notifies when a run of the device will occur and after it has occurred.
void	configure(IMalcolmModel model)	Call to configure the device.
void	disable()	Call to disable the device, stopping all activity.
void	disconnect()	Call to disconnect any resources which we no longer need.
void	dispose()	Disposes of the malcolm device causing it to disconnect from the underlying malcolm device.
void	fireRunPerformed(IPosition position)	Called during the scanning to notify the device that the run method has been called at a given position.
void	fireRunWillPerform(IPosition position)	Called during the scanning to notify the device that the run method will be called at a given position.
void	fireWritePerformed(IPosition position)	Called during the scanning to notify the device that the write method has been called at a given position, if the device implements one.
void	fireWriteWillPerform(IPosition position)	Called during the scanning to notify the device that the write method will be called at a given position, if the device implements one.
List<String>	getAvailableAxes()	Returns the axes that this malcolm device can move.
List<String>	getConfiguredAxes()	Returns the axes that this malcolm device is currently configured to move.
MalcolmTable	getDatasets()	Returns a MalcolmTable object describing the datasets that this malcolm device is configured to create during a scan.
List<MalcolmDetectorInfo>	getDetectorInfos()	Returns the MalcolmDetectorInfos for the detectors controlled by this malcolm device, describing their current state.
String	getDeviceHealth()
DeviceState	getDeviceState()
protected IEventService	getEventService()
int	getLevel()
IMalcolmModel	getModel()	The model being used for the device.
String	getName()
String	getOutputDir()	Get the directory where malcolm will write its h5 files to.
IPointGenerator<? extends IScanPointGeneratorModel>	getPointGenerator()	Get the point generator that this malcolm device has been configured with
DeviceRole	getRole()	The role of the device.
Set<ScanMode>	getSupportedScanModes()	Returns a set of the scan modes that this device can participate in.
URI	getUri()
MalcolmVersion	getVersion()	Returns the version of this malcolm device.
void	initialize()	Initializes the connection to the actual malcolm device.
boolean	isActivated()
boolean	isAlive()	Gets whether the device is 'alive' or not.
boolean	isConnected()	Returns whether this connection is connected.
boolean	isDeviceBusy()
boolean	isLocked()	Attempts to determine if the device is locked doing something like a configure or a run.
protected void	merge(DeviceInformation<IMalcolmModel> info)
protected void	method(DeviceRequest deviceRequest)
void	pause()	Allowed when the device is in Running state.
void	removeMalcolmListener(IMalcolmEventListener listener)	Remove a listener to malcolm changes.
void	removeRunListener(IRunListener l)	A listener which notifies when a run of the device will occur and after it has occurred.
void	reset()	Allowed from Fault.
void	resume()	Allowed when the device is in Paused state.
void	run(IPosition position)	Blocking call to execute the scan.
void	seek(int stepNumber)	Seek to/from a point number (absolute) in the scan.
boolean	setActivated(boolean activated)
void	setAlive(boolean alive)	Sets whether the device is alive or not
void	setConnected(boolean isConnected)
void	setEventService(IEventService eservice)
void	setLevel(int level)
void	setName(String name)
void	setOutputDir(String fileDir)	Set the directory where malcolm will write its h5 files to.
void	setPointGenerator(IPointGenerator<? extends IScanPointGeneratorModel> pointGenerator)	Set the point generator for the malcolm device.
void	setRole(DeviceRole role)	The role of the device.
void	setUri(URI uri)
protected DeviceRequest	update()
IMalcolmModel	validate(IMalcolmModel model)	If the given model is considered "invalid", this method may either throw a ModelValidationException explaining why it is considered invalid or return a modified version of the model that does pass validation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.eclipse.scanning.api.IConfigurable

configure

Methods inherited from interface org.eclipse.scanning.api.event.core.IConnection

close

Methods inherited from interface org.eclipse.scanning.api.device.models.IDeviceRoleActor

getRole, getSupportedScanModes, setRole

Methods inherited from interface org.eclipse.scanning.api.ILevel

getLevel, setLevel

Methods inherited from interface org.eclipse.scanning.api.IModelProvider

setModel, updateModel

Methods inherited from interface org.eclipse.scanning.api.INameable

getName, setName

Methods inherited from interface org.eclipse.scanning.api.device.IResettableDevice

reset

Methods inherited from interface org.eclipse.scanning.api.device.IRunnableDevice

abort, disable, getDeviceHealth, getDeviceState, getModel, isAlive, isDeviceBusy, latch, latch, run, run, setAlive, start, throwFirstRunException

Methods inherited from interface org.eclipse.scanning.api.IValidator

setService, validate

Field Details

name

protected String name

info

protected DeviceInformation<IMalcolmModel> info

requester

protected final IRequester<DeviceRequest> requester

eservice

protected IEventService eservice

uri

protected URI uri

Method Details

addRunListener

public void addRunListener(IRunListener l)
                    throws ScanningException

Description copied from interface: IRunnableEventDevice

A listener which notifies when a run of the device will occur and after it has occurred. This can be used to modify the model before the next run.

Specified by:

addRunListener in interface IRunnableEventDevice<IMalcolmModel>

Throws:

ScanningException

removeRunListener

public void removeRunListener(IRunListener l)
                       throws ScanningException

Description copied from interface: IRunnableEventDevice

A listener which notifies when a run of the device will occur and after it has occurred. This can be used to modify the model before the next run.

Specified by:

removeRunListener in interface IRunnableEventDevice<IMalcolmModel>

Throws:

ScanningException

fireRunWillPerform

public void fireRunWillPerform(IPosition position)
                        throws ScanningException

Description copied from interface: IRunnableEventDevice

Called during the scanning to notify the device that the run method will be called at a given position. This method is called on the same thread that the run() method is called on, e.g. parallel execution by level in the case of AcquisitionDevice.

Specified by:

fireRunWillPerform in interface IRunnableEventDevice<IMalcolmModel>

Parameters:

position -

Throws:

ScanningException

fireRunPerformed

public void fireRunPerformed(IPosition position)
                      throws ScanningException

Description copied from interface: IRunnableEventDevice

Called during the scanning to notify the device that the run method has been called at a given position. This method is called on the same thread that the run() method is called on, e.g. parallel execution by level in the case of AcquisitionDevice.

Specified by:

fireRunPerformed in interface IRunnableEventDevice<IMalcolmModel>

Parameters:

position -

Throws:

ScanningException

fireWriteWillPerform

public void fireWriteWillPerform(IPosition position)
                          throws ScanningException

Description copied from interface: IRunnableEventDevice

Called during the scanning to notify the device that the write method will be called at a given position, if the device implements one. This method is called on the same thread that the write() method is called on, e.g. parallel execution by level in the case of AcquisitionDevice. NOTE: If the write method returns false, fireWritePerformed is not called. However fireWriteWillPerform will still be called. This is because until the device attempts to write we do not know if is has written.

Specified by:

fireWriteWillPerform in interface IRunnableEventDevice<IMalcolmModel>

Parameters:

position -

Throws:

ScanningException

fireWritePerformed

public void fireWritePerformed(IPosition position)
                        throws ScanningException

Description copied from interface: IRunnableEventDevice

Called during the scanning to notify the device that the write method has been called at a given position, if the device implements one. This method is called on the same thread that the write() method is called on, e.g. parallel execution by level in the case of AcquisitionDevice. NOTE: If the write method returns false, fireWritePerformed is not called. However fireWriteWillPerform will still be called. This is because until the device attempts to write we do not know if is has written.

Specified by:

fireWritePerformed in interface IRunnableEventDevice<IMalcolmModel>

Parameters:

position -

Throws:

ScanningException

pause

public void pause()
           throws ScanningException,
InterruptedException

Description copied from interface: IPausableDevice

Allowed when the device is in Running state. Will block until the device is in a rest state. When paused the same thread must call resume() or abort() which has paused or an IllegalMonitorState Exception will be thrown.

Specified by:

pause in interface IPausableDevice<IMalcolmModel>

Throws:

ScanningException

InterruptedException

seek

public void seek(int stepNumber)
          throws ScanningException,
InterruptedException

Description copied from interface: IPausableDevice

Seek to/from a point number (absolute) in the scan.

Specified by:

seek in interface IPausableDevice<IMalcolmModel>

Throws:

ScanningException

InterruptedException

resume

public void resume()
            throws ScanningException,
InterruptedException

Description copied from interface: IPausableDevice

Allowed when the device is in Paused state. Will block until the device is unpaused. When paused the same thread must call resume() or abort() which has paused or an IllegalMonitorState Exception will be thrown.

Specified by:

resume in interface IPausableDevice<IMalcolmModel>

Throws:

ScanningException

InterruptedException

initialize

public void initialize()
                throws MalcolmDeviceException

Description copied from interface: IMalcolmDevice

Initializes the connection to the actual malcolm device. This methods must be called before the malcolm device can be used.

Specified by:

initialize in interface IMalcolmDevice

Throws:

MalcolmDeviceException - if the malcolm device could not be initialized

isLocked

public boolean isLocked()
                 throws MalcolmDeviceException

Description copied from interface: IMalcolmDevice

Attempts to determine if the device is locked doing something like a configure or a run.

Specified by:

isLocked in interface IMalcolmDevice

Returns:

true if not in locked state, otherwise false.

Throws:

MalcolmDeviceException

getVersion

public MalcolmVersion getVersion()
                          throws MalcolmDeviceException

Description copied from interface: IMalcolmDevice

Returns the version of this malcolm device.

Specified by:

getVersion in interface IMalcolmDevice

Returns:

version

Throws:

MalcolmDeviceException - if the version cannot be returned for any reason

getAvailableAxes

public List<String> getAvailableAxes()
                              throws MalcolmDeviceException

Description copied from interface: IMalcolmDevice

Returns the axes that this malcolm device can move.

Specified by:

getAvailableAxes in interface IMalcolmDevice

Returns:

the axes this malcolm device can move, never null

Throws:

MalcolmDeviceException

getConfiguredAxes

public List<String> getConfiguredAxes()
                               throws ScanningException

Description copied from interface: IMalcolmDevice

Returns the axes that this malcolm device is currently configured to move. Normally, the value returned is the same as IMalcolmDevice.getAvailableAxes(), except if the last time that malcolm was configured by calling

invalid reference

IMalcolmDevice#configure(IMalcolmModel)

, IMalcolmModel.getAxesToMove() was non-null, in which case it is the

Specified by:

getConfiguredAxes in interface IMalcolmDevice

Returns:

the axes that the malcolm device is currently configured to move

Throws:

ScanningException

getDetectorInfos

public List<MalcolmDetectorInfo> getDetectorInfos()
                                           throws MalcolmDeviceException

Description copied from interface: IMalcolmDevice

Returns the MalcolmDetectorInfos for the detectors controlled by this malcolm device, describing their current state.

Specified by:

getDetectorInfos in interface IMalcolmDevice

Returns:

detector infos

Throws:

MalcolmDeviceException

getDatasets

public MalcolmTable getDatasets()
                         throws MalcolmDeviceException

Description copied from interface: IMalcolmDevice

Returns a MalcolmTable object describing the datasets that this malcolm device is configured to create during a scan. This method should only be called after

invalid reference

#configure(IMalcolmModel)

has been called on this malcolm device.

Specified by:

getDatasets in interface IMalcolmDevice

Returns:

a table of the datasets created by this malcolm device

Throws:

MalcolmDeviceException - if the datasets table could not be returned for any reason

setPointGenerator

public void setPointGenerator(IPointGenerator<? extends IScanPointGeneratorModel> pointGenerator)

Description copied from interface: IMalcolmDevice

Set the point generator for the malcolm device.

Specified by:

setPointGenerator in interface IMalcolmDevice

Parameters:

pointGenerator - point generator

getPointGenerator

public IPointGenerator<? extends IScanPointGeneratorModel> getPointGenerator()

Description copied from interface: IMalcolmDevice

Get the point generator that this malcolm device has been configured with

Specified by:

getPointGenerator in interface IMalcolmDevice

Returns:

setOutputDir

public void setOutputDir(String fileDir)

Description copied from interface: IMalcolmDevice

Set the directory where malcolm will write its h5 files to. The directory should exist at the point that the malcolm device is configured, malcolm is not responsible for creating it.

Specified by:

setOutputDir in interface IMalcolmDevice

getOutputDir

public String getOutputDir()

Description copied from interface: IMalcolmDevice

Get the directory where malcolm will write its h5 files to.

Specified by:

getOutputDir in interface IMalcolmDevice

addMalcolmListener

public void addMalcolmListener(IMalcolmEventListener listener)

Description copied from interface: IMalcolmDevice

Add a listener to malcolm changes.

Specified by:

addMalcolmListener in interface IMalcolmDevice

Parameters:

listener -

removeMalcolmListener

public void removeMalcolmListener(IMalcolmEventListener listener)

Description copied from interface: IMalcolmDevice

Remove a listener to malcolm changes.

Specified by:

removeMalcolmListener in interface IMalcolmDevice

Parameters:

listener -

dispose

public void dispose()
             throws MalcolmDeviceException

Description copied from interface: IMalcolmDevice

Disposes of the malcolm device causing it to disconnect from the underlying malcolm device.

Specified by:

dispose in interface IMalcolmDevice

Throws:

MalcolmDeviceException

configure

public void configure(IMalcolmModel model)
               throws ScanningException

Description copied from interface: IConfigurable

Call to configure the device. If the model provided is invalid, a scanning exception will be thrown.

Specified by:

configure in interface IConfigurable<M>

Parameters:

model -

Throws:

ScanningException

getModel

public IMalcolmModel getModel()

Description copied from interface: IRunnableDevice

The model being used for the device.

Specified by:

getModel in interface IModelProvider<M>

Specified by:

getModel in interface IRunnableDevice<M>

Returns:

getDeviceHealth

public String getDeviceHealth()
                       throws ScanningException

Specified by:

getDeviceHealth in interface IRunnableDevice<M>

Returns:

the current device Health.

Throws:

ScanningException

isDeviceBusy

public boolean isDeviceBusy()
                     throws ScanningException

Specified by:

isDeviceBusy in interface IRunnableDevice<M>

Returns:

the current value of the device 'busy' flag.

Throws:

ScanningException

getRole

public DeviceRole getRole()

Description copied from interface: IDeviceRoleActor

The role of the device.

Specified by:

getRole in interface IDeviceRoleActor

Returns:

role of the device

setRole

public void setRole(DeviceRole role)

Description copied from interface: IDeviceRoleActor

The role of the device.

Specified by:

setRole in interface IDeviceRoleActor

Parameters:

role - role of the device

getSupportedScanModes

public Set<ScanMode> getSupportedScanModes()

Description copied from interface: IDeviceRoleActor

Returns a set of the scan modes that this device can participate in.

Specified by:

getSupportedScanModes in interface IDeviceRoleActor

Returns:

possible roles of the device

validate

public IMalcolmModel validate(IMalcolmModel model)
                       throws ValidationException

Description copied from interface: IValidator

If the given model is considered "invalid", this method may either throw a ModelValidationException explaining why it is considered invalid or return a modified version of the model that does pass validation. If the model is valid, it is returned. A model should be considered invalid if its parameters would cause the generator implementation to hang or crash.

Specified by:

validate in interface IValidator<M>

Parameters:

model - - a model of type T to validate

Returns:

a valid model

Throws:

ValidationException

getDeviceState

public DeviceState getDeviceState()
                           throws ScanningException

Specified by:

getDeviceState in interface IRunnableDevice<M>

Returns:

the current device State. This is not the same as the Status of the scan.

Throws:

ScanningException

update

protected DeviceRequest update()

run

public void run(IPosition position)
         throws ScanningException,
InterruptedException

Description copied from interface: IRunnableDevice

Blocking call to execute the scan. The position specified may be null.

Specified by:

run in interface IRunnableDevice<M>

Throws:

ScanningException

InterruptedException

reset

public void reset()
           throws ScanningException

Description copied from interface: IResettableDevice

Allowed from Fault. Will try to reset the device into Idle state. Will block until the device is in a rest state.

Specified by:

reset in interface IResettableDevice

Throws:

ScanningException

abort

public void abort()
           throws ScanningException

Description copied from interface: IRunnableDevice

Call to terminate the scan before it has finished.

Specified by:

abort in interface IRunnableDevice<M>

Throws:

ScanningException

disable

public void disable()
             throws ScanningException

Description copied from interface: IRunnableDevice

Call to disable the device, stopping all activity.

Specified by:

disable in interface IRunnableDevice<M>

Throws:

ScanningException

isActivated

public boolean isActivated()

Specified by:

isActivated in interface IActivatable

Returns:

true if device is activated.

setActivated

public boolean setActivated(boolean activated)
                     throws ScanningException

Specified by:

setActivated in interface IActivatable

Parameters:

activated -

Returns:

the old value of activated

Throws:

ScanningException

isAlive

public boolean isAlive()

Description copied from interface: IRunnableDevice

Gets whether the device is 'alive' or not. 'Alive' is taken to mean that the device is on and responding.

Specified by:

isAlive in interface IRunnableDevice<M>

Returns:

setAlive

public void setAlive(boolean alive)

Description copied from interface: IRunnableDevice

Sets whether the device is alive or not

Specified by:

setAlive in interface IRunnableDevice<M>

Parameters:

alive -

disconnect

public void disconnect()
                throws EventException

Description copied from interface: IConnection

Call to disconnect any resources which we no longer need. The resource may have timed out so it might not be connected, in that case it silently returns. Note, that the method IConnection.close(), inherited from AutoCloseable calls this method, which means that if an object of a class implementing IConnection is used with a try-with-resources block this method will be called automatically when exiting that block.

Throws:

EventException - if resource could not be disconnected.

getName

public String getName()

setName

public void setName(String name)

setLevel

public void setLevel(int level)

getLevel

public int getLevel()

merge

protected void merge(DeviceInformation<IMalcolmModel> info)

method

protected void method(DeviceRequest deviceRequest)
               throws ScanningException

Throws:

ScanningException

getEventService

protected IEventService getEventService()

setEventService

public void setEventService(IEventService eservice)

getUri

public URI getUri()

setUri

public void setUri(URI uri)

isConnected

public boolean isConnected()

Description copied from interface: IConnection

Returns whether this connection is connected. This method returns true until disconnect is called, even if the connection is created lazily.

Specified by:

isConnected in interface IConnection

Returns:

true if connected, false otherwise

setConnected

public void setConnected(boolean isConnected)