cern.cmw.rda.client
Class RDAService

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

All Implemented Interfaces:

IRDAService

public class RDAService
extends Object
implements IRDAService

Manages communications with remote devices and serves as a factory for DeviceHandle objects.

The RDAService class is a Singleton class, in that only one instance of the class is allowed per client. It is created when a client invokes the static init method of the class for the first time. If the initialization fails for some reason then a CmwInternalError will be thrown.

See Also:

DeviceHandle

Nested Class Summary

protected static class

RDAService.ListOperationType

Nested classes/interfaces inherited from interface cern.cmw.rda.client.IRDAService

IRDAService.GetElement, IRDAService.SubscriptionResult

Field Summary

static boolean	DEBUG
static boolean	DEBUG_ARRAY_CALLS
static String	RBAC_TOKEN_TAG

Method Summary

static Data	addTokenToCtx(Data ctx, byte[] fullToken) Method allows insertion of RBAToken to the Data object that can be later used as a credential context to the specific operation.
static Data	addTokenToCtx(Data ctx, byte[] token, byte[] signature) Method allows insertion of RBAToken to the Data object that can be later used as a credential context to the specific operation.
DeviceHandle	getDeviceHandle(String deviceName) Returns a handle for the device identified by the specified name.
static Data	getServiceContext() Returns a copy of the RDA service context.
static RDAService	init() Returns a reference to the RDAService singleton.
static boolean	initialized() Returns true if the RDA service has been initialized.
List<IRDAService.GetElement>	listGet(List<String> parameters, String cycleSelector) Performs an optimized (bulk) call for multiple get operation.
List<IRDAService.GetElement>	listGet(List<String> parameters, String cycleSelector, Data context) Performs an optimized (bulk) call for multiple get operation.
List<String>	listSet(List<String> parameters, List<Data> values, String cycleSelector) Performs an optimized (bulk) call for multiple set operation.
List<String>	listSet(List<String> parameters, List<Data> values, String cycleSelector, Data context) Performs an optimized (bulk) call for multiple set operation.
List<IRDAService.SubscriptionResult>	listSubscribe(List<String> parameters, String cycleSelector, Data context, ReplyHandler replyHandler) Performs an optimized (bulk) call for multiple subscriptions, possibly with context.
List<IRDAService.SubscriptionResult>	listSubscribe(List<String> parameters, String cycleSelector, ReplyHandler replyHandler) Performs an optimized (bulk) call for multiple subscriptions.
void	listUnsubscribe(List<ISubscriptionRequest> requests) Performs an optimized (bulk) cancellation for multiple subscriptions.
static void	main(String[] args) For tests.
void	send(GetRequest[] requests) Submits for execution a group of requests to read property values.
void	send(SetRequest[] requests) Submits for execution a group of requests to set property values.
void	setRBACToken(byte[] token) Allows to set the RBAC token on all connections (it will be also sent when establishing a connection to the new server)
static void	setServiceContext(Data ctx) Fills in the RDA service context with contents of the specified Data.

Methods inherited from class java.lang.Object

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

Field Detail

RBAC_TOKEN_TAG

public static final String RBAC_TOKEN_TAG

See Also:

Constant Field Values

DEBUG

public static boolean DEBUG

DEBUG_ARRAY_CALLS

public static boolean DEBUG_ARRAY_CALLS

Method Detail

init

public static RDAService init()

Returns a reference to the RDAService singleton. The first call to this method initializes the RDA and creates an instance of RDAService. Subsequent calls just return a reference to the previously created object.

setRBACToken

public void setRBACToken(byte[] token)
                  throws BadToken,
                         TokenExpired

Allows to set the RBAC token on all connections (it will be also sent when establishing a connection to the new server)

Specified by:

setRBACToken in interface IRDAService

Parameters:

token - The encoded RBAC token (together with its signature), or null

Throws:

BadToken - Token is malformed

TokenExpired - Token is expired

initialized

public static boolean initialized()

Returns true if the RDA service has been initialized.

addTokenToCtx

public static Data addTokenToCtx(Data ctx,
                                 byte[] fullToken)

Method allows insertion of RBAToken to the Data object that can be later used as a credential context to the specific operation. An overloaded version passing the serialized RBAC token and signature in one array.

Parameters:

fullToken - Serialized RBAC token, fields together with signature

ctx - Data object to insert serialized token to

Returns:

ctx with serialized token object

addTokenToCtx

public static Data addTokenToCtx(Data ctx,
                                 byte[] token,
                                 byte[] signature)

Method allows insertion of RBAToken to the Data object that can be later used as a credential context to the specific operation. An overloaded version passing the serialized RBAC token and signature separately.

Parameters:

token - Serialized RBAC token

signature - Serialized RBAC token signature

ctx - Data object to insert serialized token to

Returns:

ctx with serialized token object

setServiceContext

public static void setServiceContext(Data ctx)
                              throws InternalException

Fills in the RDA service context with contents of the specified Data. This method should only be called when the RDA service is not yet initialized (before the first init call). The service context cannot be changed after the service has been initialized.

Throws:

InternalException - indicates an attempt to change context of the initialized service \todo Real documentation: what is the service context and how it can be accessed on the server side (rdaClientInfo).

getServiceContext

public static Data getServiceContext()

Returns a copy of the RDA service context.

See Also:

setServiceContext

getDeviceHandle

public DeviceHandle getDeviceHandle(String deviceName)
                             throws BadParameter,
                                    InternalException

Returns a handle for the device identified by the specified name.

Specified by:

getDeviceHandle in interface IRDAService

Throws:

BadParameter - thrown to indicate that the device name is unknown in the system

InternalException - thrown if the device could not be located due to an internal RDA error

listSubscribe

public List<IRDAService.SubscriptionResult> listSubscribe(List<String> parameters,
                                                          String cycleSelector,
                                                          ReplyHandler replyHandler)
                                                   throws BadParameter,
                                                          InternalException

Performs an optimized (bulk) call for multiple subscriptions. Returns a sequence of subscription requests matching the given list of parameters. Those requests that failed have null entries at relevant positions in the returned sequence.

Specified by:

listSubscribe in interface IRDAService

Throws:

BadParameter - thrown to indicate that some parameter is malformed or does not describe a valid device/property pair

InternalException - thrown if the device could not be located due to an internal RDA error

listSubscribe

public List<IRDAService.SubscriptionResult> listSubscribe(List<String> parameters,
                                                          String cycleSelector,
                                                          Data context,
                                                          ReplyHandler replyHandler)
                                                   throws BadParameter,
                                                          InternalException

Performs an optimized (bulk) call for multiple subscriptions, possibly with context. Returns a sequence of subscription requests matching the given list of parameters. Those requests that failed have null entries at relevant positions in the returned sequence.

Specified by:

listSubscribe in interface IRDAService

Throws:

BadParameter - thrown to indicate that some parameter is malformed or does not describe a valid device/property pair

InternalException - thrown if the device could not be located due to an internal RDA error

listUnsubscribe

public void listUnsubscribe(List<ISubscriptionRequest> requests)
                     throws BadParameter

Performs an optimized (bulk) cancellation for multiple subscriptions.

Specified by:

listUnsubscribe in interface IRDAService

Throws:

BadParameter

listGet

public List<IRDAService.GetElement> listGet(List<String> parameters,
                                            String cycleSelector)
                                     throws BadParameter

Description copied from interface: IRDAService

Performs an optimized (bulk) call for multiple get operation. Returns a sequence of pairs matching the given list of parameters. Each pair contains either the Data object or a String error description. This method does not throw any exceptions (see exception below) - all problems are reported in the String component of returned elements, separately for each requested parameter. The only exception that is thrown reports the duplicated entries in the given parameter list (there would be no way to match results to requests properly).

Specified by:

listGet in interface IRDAService

Throws:

BadParameter

listGet

public List<IRDAService.GetElement> listGet(List<String> parameters,
                                            String cycleSelector,
                                            Data context)
                                     throws BadParameter

Performs an optimized (bulk) call for multiple get operation. Returns a sequence of pairs matching the given list of parameters. Each pair contains either the Data object or a String error description. This method does not throw any exceptions (see exception below) - all problems are reported in the String component of returned elements, separately for each requested parameter. The only exception that is thrown reports the duplicated entries in the given parameter list (there would be no way to match results to requests properly).

Specified by:

listGet in interface IRDAService

Throws:

BadParameter

listSet

public List<String> listSet(List<String> parameters,
                            List<Data> values,
                            String cycleSelector)
                     throws BadParameter

Description copied from interface: IRDAService

Performs an optimized (bulk) call for multiple set operation. Returns a sequence of string matching the given list of parameters. Each string is either empty (null) in case of success or contains an error description. This method does not throw any exceptions (see exception below) - all problems are reported in the String values of returned elements, separately for each requested parameter. The only exception that is thrown reports the duplicated entries in the given parameter list (there would be no way to match results to requests properly).

Specified by:

listSet in interface IRDAService

Throws:

BadParameter

listSet

public List<String> listSet(List<String> parameters,
                            List<Data> values,
                            String cycleSelector,
                            Data context)
                     throws BadParameter

Performs an optimized (bulk) call for multiple set operation. Returns a sequence of string matching the given list of parameters. Each string is either empty (null) in case of success or contains an error description. This method does not throw any exceptions (see exception below) - all problems are reported in the String values of returned elements, separately for each requested parameter. The only exception that is thrown reports the duplicated entries in the given parameter list (there would be no way to match results to requests properly).

Specified by:

listSet in interface IRDAService

Throws:

BadParameter

send

public void send(GetRequest[] requests)
          throws BadParameter,
                 InternalException

Submits for execution a group of requests to read property values.

Parameters:

requests - the array of request objects to be sent to devices

Throws:

BadParameter - if the requests array contains a null value

InternalException - if the method fails due to some internal RDA error; for example, due to lack of memory.

See Also:

createGetRequest

send

public void send(SetRequest[] requests)
          throws BadParameter,
                 InternalException

Submits for execution a group of requests to set property values.

Parameters:

requests - the array of request objects to be sent to devices

Throws:

BadParameter - if the requests array contains a null value

InternalException - if the method fails due to some internal RDA error; for example, due to lack of memory.

See Also:

createSetRequest

main

public static void main(String[] args)

For tests. This function measures and prints out the RDA initialization time: the execution time for the first init call.

   public static void main(String[] args)
   {
      System.out.print("Initializing RDAService...");
      try
      {
         long start = System.currentTimeMillis();
         RDAService.init();
         long stop = System.currentTimeMillis();
         System.out.println(" done in "+(stop - start)+" ms");
      }
      catch(Throwable ex)
      {
         System.out.println(" error");
         ex.printStackTrace();
      }
      System.exit(0);
   }
   

Strictly speaking, the real execution time (the time needed to execute bytecode) is only a small fraction of the measured time (typically, less than 10%). Most of the time is spent loading RDA and CORBA classes. This, depending on your environment and the JVM, may take up to several seconds.