cern.cmw.rda.client
Class DeviceHandle

java.lang.Object
  cern.cmw.rda.client.DeviceHandle

All Implemented Interfaces:

IDeviceHandle

public class DeviceHandle
extends Object
implements IDeviceHandle

Allows to set, get and monitor property values in a remote device. An object of this class acts as a proxy which represents a remote device to the local client, and delegates device calls, made by the client, to the device server.

The class provides several groups of the device access methods.

• synchronous calls
  Methods of this group allow to set and get device property values in the synchronous (blocking) mode. When a client makes a synchronous call, it blocks while the call is being executed in the device server. cern.cmw.rda.test.special.GetSync is an example of using the synchronous device calls.
• asynchronous calls
  Methods of this group create a request to set or get a device property value, send it to the device server, and return. Results of the requested operation will be delivered to the ReplyHandler callback object which is specified as an argument in each asynchronous call. cern.cmw.rda.test.special.GetAsync is an example of using the asynchronous device calls.
• subscription
  Using methods of this group, a client can subscribe on a device property value, and receive regular updates of the value via the specified callback object. class is a subscription example.

The class also provides a group of methods that allow to obtain some information on the associated device.

Method Summary

GetRequest	createGetRequest(String propName, String cycleSelector, Data context, ReplyHandler replyHandler)
SetRequest	createSetRequest(String propName, String cycleSelector, Data value, Data context, ReplyHandler replyHandler)
Data	get(String propName) Reads from the device and returns the specified property value.
GetRequest	get(String propName, ReplyHandler replyHandler) Creaters and sends to the device a request to read the speciified property value.
Data	get(String propName, String cycleSelector) Reads from the device and returns the specified property value.
Data	get(String propName, String cycleSelector, Data context) Reads from the device and returns the specified property value.
GetRequest	get(String propName, String cycleSelector, Data context, ReplyHandler replyHandler) Creates and sends to the device a request to read the specified property value.
GetRequest	get(String propName, String cycleSelector, ReplyHandler replyHandler) Creates and sends to the device a request to read the speciified property value.
String	getClassName() Returns the device class name.
String	getDeviceName() Returns the device name.
protected cern.cmw.rda.client.ServerConnection	getServerConnection(RDAService.ListOperationType operation)
static void	main(String[] args) For tests.
void	monitorOff(SubscriptionRequest subscription) Cancels a data subscription initiated by the specified request.
SubscriptionRequest	monitorOn(String propName, boolean onChange, ReplyHandler replyHandler) Starts a subscription on the specified property value.
SubscriptionRequest	monitorOn(String propName, String cycleSelector, boolean onChange, ReplyHandler replyHandler) Starts a subscription on the specified property value.
SubscriptionRequest	monitorOn(String propName, String cycleSelector, boolean onChange, ReplyHandler replyHandler, Data context) Starts a subscription on the specified property value.
void	set(String propName, Data value) Changes the value of the specified property.
SetRequest	set(String propName, Data value, ReplyHandler replyHandler) Creates and sends to the device a request to change the value of the specified property.
void	set(String propName, String cycleSelector, Data value) Changes the value of the specified property.
void	set(String propName, String cycleSelector, Data value, Data context) Changes the value of the specified property.
SetRequest	set(String propName, String cycleSelector, Data value, Data context, ReplyHandler replyHandler) Creates an sends to the device a request to change the value of the specified property.
SetRequest	set(String propName, String cycleSelector, Data value, ReplyHandler replyHandler) Creates and sends to the device a request to change the value of the specified property.

Methods inherited from class java.lang.Object

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

Method Detail

getServerConnection

protected cern.cmw.rda.client.ServerConnection getServerConnection(RDAService.ListOperationType operation)

getDeviceName

public String getDeviceName()

Returns the device name.

Specified by:

getDeviceName in interface IDeviceHandle

getClassName

public String getClassName()
                    throws TimeOut,
                           NoConnection,
                           InternalException

Returns the device class name.

Specified by:

getClassName in interface IDeviceHandle

Throws:

TimeOut

NoConnection

InternalException

get

public Data get(String propName)
         throws BadParameter,
                TimeOut,
                NoConnection,
                InternalException,
                IOError,
                NoPermission

Reads from the device and returns the specified property value.

This method is equivalent to the basic synchronous get(String, String, Data) call with cycleSelector and context arguments equal to null .

Specified by:

get in interface IDeviceHandle

Throws:

BadParameter

TimeOut

NoConnection

InternalException

IOError

NoPermission

get

public Data get(String propName,
                String cycleSelector)
         throws BadParameter,
                TimeOut,
                NoConnection,
                InternalException,
                IOError,
                NoPermission

Reads from the device and returns the specified property value.

This method is equivalent to the basic synchronous get(String, String, Data) call with the null context argument.

Specified by:

get in interface IDeviceHandle

Throws:

BadParameter

TimeOut

NoConnection

InternalException

IOError

NoPermission

get

public Data get(String propName,
                String cycleSelector,
                Data context)
         throws BadParameter,
                TimeOut,
                NoConnection,
                IOError,
                InternalException,
                NoPermission

Reads from the device and returns the specified property value.

Specified by:

get in interface IDeviceHandle

Parameters:

propName - the property name

cycleSelector - the cycle identifier

context - the operation context

Returns:

the property value encapsulated in a Data object

Throws:

BadParameter - thrown if any of the call arguments has an illegal value

TimeOut - thrown if the operation has been timed out

NoConnection - thrown if the device server is currently unreachable

IOError - thrown if an I/O error occured during the call execution in the remote device

InternalException - thrown if the call fails due to some internal RDA error, or if the method implementation in the device server throws an unexpected exception.

NoPermission - Thrown in case of RBAC-related complications. More information can be obtained through downcasting or obtaining the error message of exception. Possible exception types of this kind are: AccessDenied, BadToken and TokenExpired

set

public void set(String propName,
                Data value)
         throws BadParameter,
                TimeOut,
                NoConnection,
                IOError,
                InternalException,
                NoPermission

Changes the value of the specified property.

This method is equivalent to the basic synchronous set(String, String, Data, Data) call with the cycleSelector and context arguments equal to null.

Specified by:

set in interface IDeviceHandle

Throws:

BadParameter

TimeOut

NoConnection

IOError

InternalException

NoPermission

set

public void set(String propName,
                String cycleSelector,
                Data value)
         throws BadParameter,
                TimeOut,
                NoConnection,
                IOError,
                InternalException,
                NoPermission

Changes the value of the specified property.

This method is equivalent to the basic synchronous set(String, String, Data, Data) call with the context argument equal to null.

Specified by:

set in interface IDeviceHandle

Throws:

BadParameter

TimeOut

NoConnection

IOError

InternalException

NoPermission

set

public void set(String propName,
                String cycleSelector,
                Data value,
                Data context)
         throws BadParameter,
                TimeOut,
                NoConnection,
                IOError,
                InternalException,
                NoPermission

Changes the value of the specified property.

Specified by:

set in interface IDeviceHandle

Parameters:

propName - the property name

cycleSelector - the cycle identifier

value - the value to set

context - the operation context

Throws:

BadParameter - thrown if any of the call arguments has an illegal value

TimeOut - thrown if the operation has been timed out

NoConnection - thrown if the device server is currently unreacheable

IOError - thrown if an I/O error occured during the call execution in the remote device

InternalException - thrown if the call fails due to some internal RDA error, or if the method implementation in the device server throws an unexpected exception.

NoPermission - Thrown in case of RBAC-related complications. More information can be obtained through downcasting or obtaining the error message of exception. Possible exception types of this kind are: AccessDenied, BadToken and TokenExpired

get

public GetRequest get(String propName,
                      ReplyHandler replyHandler)
               throws BadParameter,
                      NoConnection,
                      InternalException

Creaters and sends to the device a request to read the speciified property value.

This method is equivalent to the basic asynchronous get(String, String, Data, ReplyHandler) call with cycleSelector and context arguments equal to null .

Specified by:

get in interface IDeviceHandle

Throws:

BadParameter

NoConnection

InternalException

get

public GetRequest get(String propName,
                      String cycleSelector,
                      ReplyHandler replyHandler)
               throws BadParameter,
                      NoConnection,
                      InternalException

Creates and sends to the device a request to read the speciified property value.

This method is equivalent to the basic asynchronous get(String, String, Data, ReplyHandler) call with the null context argument.

Specified by:

get in interface IDeviceHandle

Throws:

BadParameter

NoConnection

InternalException

get

public GetRequest get(String propName,
                      String cycleSelector,
                      Data context,
                      ReplyHandler replyHandler)
               throws BadParameter,
                      NoConnection,
                      InternalException

Creates and sends to the device a request to read the specified property value. The operation results will be delivered to the specified ReplyHandler object, see GetRequest for the detailed description of actions in this phase.

Specified by:

get in interface IDeviceHandle

Parameters:

propName - the property name

cycleSelector - the cycle identifier

context - the operation context

replyHandler - the "callback" object that will be notified on the operation results.

Throws:

BadParameter - thrown if any of the call arguments has an illegal value

NoConnection - thrown if the device server is currently unreachable

InternalException - thrown to indicate an internal RDA error; for example, lack of memory to create the operation request..

set

public SetRequest set(String propName,
                      Data value,
                      ReplyHandler replyHandler)
               throws BadParameter,
                      NoConnection,
                      InternalException,
                      NoPermission

Creates and sends to the device a request to change the value of the specified property.

This method is equivalent to the basic asynchronous set(String, String, Data, Data, ReplyHandler) call with the cycleSelector and context arguments equal to null.

Specified by:

set in interface IDeviceHandle

Throws:

BadParameter

NoConnection

InternalException

NoPermission

set

public SetRequest set(String propName,
                      String cycleSelector,
                      Data value,
                      ReplyHandler replyHandler)
               throws BadParameter,
                      NoConnection,
                      InternalException

Creates and sends to the device a request to change the value of the specified property.

This method is equivalent to the basic synchronous set(String, String, Data, Data) call with the context argument equal to null.

Specified by:

set in interface IDeviceHandle

Throws:

BadParameter

NoConnection

InternalException

set

public SetRequest set(String propName,
                      String cycleSelector,
                      Data value,
                      Data context,
                      ReplyHandler replyHandler)
               throws BadParameter,
                      NoConnection,
                      InternalException

Creates an sends to the device a request to change the value of the specified property. The operation results will be delivered to the specified ReplyHandler object, see SetRequest for the detailed description of actions in this phase.

Specified by:

set in interface IDeviceHandle

Parameters:

propName - the property name

cycleSelector - the cycle identifier

value - the value to set

context - the operation context

replyHandler - the "callback" object that will be notified on the operation results.

Throws:

BadParameter - thrown if any of the call arguments has an illegal value

NoConnection - thrown if the device server is currently unreachable

InternalException - indicates an internal RDA error; for example, lack of memory to create the operation request

monitorOn

public SubscriptionRequest monitorOn(String propName,
                                     boolean onChange,
                                     ReplyHandler replyHandler)
                              throws BadParameter,
                                     NoConnection,
                                     TimeOut,
                                     IOError,
                                     InternalException,
                                     NoPermission

Starts a subscription on the specified property value.

This method is equivalent to the basic monitorOn(String, String, boolean, ReplyHandler, Data) call with the cycleSelector and context arguments equal to null.

Specified by:

monitorOn in interface IDeviceHandle

Throws:

BadParameter

NoConnection

TimeOut

IOError

InternalException

NoPermission

monitorOn

public SubscriptionRequest monitorOn(String propName,
                                     String cycleSelector,
                                     boolean onChange,
                                     ReplyHandler replyHandler)
                              throws BadParameter,
                                     NoConnection,
                                     TimeOut,
                                     IOError,
                                     InternalException,
                                     NoPermission

Starts a subscription on the specified property value.

This method is equivalent to the basic monitorOn(String, String, boolean, ReplyHandler, Data) call with context argument equal to null.

Specified by:

monitorOn in interface IDeviceHandle

Throws:

BadParameter

NoConnection

TimeOut

IOError

InternalException

NoPermission

monitorOn

public SubscriptionRequest monitorOn(String propName,
                                     String cycleSelector,
                                     boolean onChange,
                                     ReplyHandler replyHandler,
                                     Data context)
                              throws BadParameter,
                                     NoConnection,
                                     TimeOut,
                                     IOError,
                                     InternalException,
                                     NoPermission

Starts a subscription on the specified property value.

If a monitorOn call completes successfully then the ReplyHandler object specified as an argument to the call will be notified each time the subscribed value is updated or an attempt to update the value fails due to an I/O error (see SubscriptionRequest for the description of notification methods that can be invoked as a result of this call).

If "on-change" mode has been specified in the call then only the value which is different from the previous one will be reported to the client.

monitorOn is a blocking call that propagates down to the device server. On the server side, it installs a "monitor" on the specified value. Each monitor takes some resources (CPU time, memory, I/O bandwidth) in the server. The call fails if the monitor cannot be installed due to lack of the resources.

On success, the call returns a reference to the SubscriptionRequest object sent to the server. The subscription can be cancelled using the #monitorOff call with this object as an argument.

Specified by:

monitorOn in interface IDeviceHandle

Parameters:

propName - the property name

cycleSelector - the cycle identifier (can be null).

onChange - the subscription mode: "on-change", if true

replyHandler - the "callback" object where to deliver the subscription results

context - the subscription context (can be null).

Throws:

BadParameter - thrown if any of the call arguments has an illegal value

NoConnection - thrown if the device server is currently unreacheable

TimeOut - thrown if the operation has been timed out. You can safely retry a timed out call.

IOError - thrown if an I/O error occured during the call execution in the remote device

InternalException - thrown if the call fails due to some internal RDA error, or if the method implementation in the device server throws an unexpected exception.

NoPermission - Thrown in case of RBAC-related complications. More information can be obtained through downcasting or obtaining the error message of exception. Possible exception types of this kind are: AccessDenied, BadToken and TokenExpired

See Also:

SubscriptionRequest

monitorOff

public void monitorOff(SubscriptionRequest subscription)
                throws BadParameter,
                       TimeOut

Cancels a data subscription initiated by the specified request.

This is a blocking call that propagates down to the device server. In case of timeout, the subscription remains active in the client and may or may not be removed in the server. You can retry the call to definitely remove the server side monitor.

In principle, each monitorOn call should have a matching monitorOff: this allows to optimize resource utilization on the client and server side. However, an uncancelled subscription does not result in an irreversible resource leak: all monitors installed by a client will be automatically removed in connected servers when the client terminates.

Specified by:

monitorOff in interface IDeviceHandle

Throws:

BadParameter - thrown if the specified subscription has already been cancelled

TimeOut - thrown if the operation has been timed out.

See Also:

SubscriptionRequest

createGetRequest

public GetRequest createGetRequest(String propName,
                                   String cycleSelector,
                                   Data context,
                                   ReplyHandler replyHandler)
                            throws BadParameter,
                                   InternalException,
                                   NoPermission

Throws:

BadParameter

InternalException

NoPermission

createSetRequest

public SetRequest createSetRequest(String propName,
                                   String cycleSelector,
                                   Data value,
                                   Data context,
                                   ReplyHandler replyHandler)
                            throws BadParameter,
                                   InternalException,
                                   NoPermission

Throws:

BadParameter

InternalException

NoPermission

main

public static void main(String[] args)

For tests. Locates a device specified by the first command line argument, and prints the device server name and status. For example:

> java cern.cmw.rda.client.DeviceHandle TST.DEV1
Device located on server 'dmcrtest'
The server is up and running
> java cern.cmw.rda.client.DeviceHandle TT40.BIC
Device located on server 'ibsba4'
The server is down or unreachable
> java cern.cmw.rda.client.DeviceHandle abba
Device not found in the system