cern.cmw.rda.client
Class Subscription

java.lang.Object
  cern.cmw.rda.client.ReplyAdapter
      cern.cmw.rda.client.Subscription

All Implemented Interfaces:

ReplyHandler

public abstract class Subscription
extends ReplyAdapter

Represents a subscription on a device property value. This class, implemented on top of the basic device access facilities (see DeviceHandle), provides a simple and easy to use API for creating and managing subscriptions. For example, all you need to do to subscribe to the CPS supercycle information (SCCHIST property of device CPS.TGM) is the following:

  public static void main(String[] args)
  {
     new Subscription("CPS.TGM","SCCHIST")
     {
        protected void handleValue(Data value)
        {
           System.out.println("\nLAST SUPERCYCLE\n"+value);
        }
        protected void handleError(IOError ex)
        {
           System.out.println(ex);
        }
     };
  }
 

A somewhat more complete example is available in the main(java.lang.String[]) function of this class. The constructor of a Subscription object creates a subscription request and tries to send it to the data provider (device server). If the server confirmes the request, then the object will start to receive periodic subscription updates via callback methods. Users can (and should) cancel() susbscribtions that are not needed anymore. If the server cannot be contacted immediately (e.g., is down or ureachable due to a network failure), then the object will repeat attempts to submit the request until it is confirmed() or rejected(cern.cmw.CmwException) by the server, or cancelled by the user. Subscription is rejected(cern.cmw.CmwException) when BadParameter has been thrown i.e. when there is something fundamentally wrong with it such as invalid device or property name. Therefore subscriptions which are rejected(cern.cmw.CmwException) will be cancelled automatically . Subscription can be started automatically once instantiated (default), or, it can by specified at the instantiation time that #start method will be used. This provides a slightly better performance (by calling Subscription#monitorOn within the caller thread, rather than delegating it) and can also be necessary to assure that derived objects are fully constructed before receiving callbacks. The default retry period for pending subscriptions is 100 seconds but it can be changed by setting the configuration property cmw.rda.subscription.retryFrequency to the preferred value in seconds.

Field Summary

protected DeviceHandle

deviceHandle

Constructor Summary

Subscription(String device, String property)

Subscription(String device, String property, boolean onChange)

Subscription(String device, String property, Data context)

Subscription(String device, String property, String cycle)

Subscription(String device, String property, String cycle, Data context, boolean onChange)

Subscription(String device, String property, String cycle, Data context, boolean onChange, boolean automaticStart)

Method Summary

void	cancel() Cancels the subscription.
protected void	confirmed() Invoked when the subscription request is confirmed by the data provider.
protected void	disconnected() Invoked when a confirmed subscription is suspended because of a lost connection to the data source.
void	disconnected(SubscriptionRequest request) Invoked when a subscription is suspended because of a lost connection to a remote device; for example, because the device server is down.
Data	getContext() Returns the subscription context, or null if context was not specified in the constructor of this object.
String	getCycle() Returns the cycle identifier, or null if cycle was not specified in the constructor of this object.
String	getDevice() Returns the device name.
String	getProperty() Returns the property name.
protected abstract void	handleError(IOError err) Invoked if an error occured when updating the value.
void	handleException(Request request, IOError exception) Invoked on receipt of a reply containing the specified exception.
void	handleReply(Request request, Data val) Invoked when a property value is delivered as a result of a successful get or monitorOn call.
protected abstract void	handleValue(Data value) Invoked when the subscribed value is updated.
boolean	isConfirmed() Returns true if the subscription request has been confirmed by the data provider.
boolean	isOnChange() Returns true is the subscription is on-change.
boolean	isRejected() Returns true if the subscription request has been rejected by the data provider.
static void	main(String[] args) For tests.
static int	nOfPending() returns the number of pending subscriptions
protected void	reconnected() Invoked when a suspended subscription is resumed.
void	reconnected(SubscriptionRequest request) Invoked when a suspended subscription has been resumed.
protected void	rejected(CmwException why) Invoked when the subscription request is rejected.
void	start() Starts the subscription.

Methods inherited from class cern.cmw.rda.client.ReplyAdapter

cancelled, done, handleError, handleException, handleException, handleException, handleException, handleException, handleException

Methods inherited from class java.lang.Object

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

Field Detail

deviceHandle

protected DeviceHandle deviceHandle

Constructor Detail

Subscription

public Subscription(String device,
                    String property)

Parameters:

device - the device name

property - the property name.

Subscription

public Subscription(String device,
                    String property,
                    String cycle)

Parameters:

device - the device name

property - the property name

cycle - the cycle identifier (can be null).

Subscription

public Subscription(String device,
                    String property,
                    boolean onChange)

Parameters:

device - the device name

property - the property name

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

Subscription

public Subscription(String device,
                    String property,
                    Data context)

Parameters:

device - the device name

property - the property name

context - the subscription context (can be null).

Subscription

public Subscription(String device,
                    String property,
                    String cycle,
                    Data context,
                    boolean onChange)

Parameters:

device - the device name

property - the property name

cycle - the cycle identifier (can be null)

context - the subscription context (can be null)

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

Subscription

public Subscription(String device,
                    String property,
                    String cycle,
                    Data context,
                    boolean onChange,
                    boolean automaticStart)

Parameters:

device - the device name

property - the property name

cycle - the cycle identifier (can be null)

context - the subscription context (can be null)

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

automaticStart - to specify if subscription has to be started automatically when constructed: if true then subscription will be started automatically by the subscription management thread; if false then subscription will not be active until start() method has been called. Note that if automatic start == true, the object may not be fully constructed when callback methods are invoked.

Method Detail

getDevice

public String getDevice()

Returns the device name.

getProperty

public String getProperty()

Returns the property name.

getCycle

public String getCycle()

Returns the cycle identifier, or null if cycle was not specified in the constructor of this object.

isOnChange

public boolean isOnChange()

Returns true is the subscription is on-change.

getContext

public Data getContext()

Returns the subscription context, or null if context was not specified in the constructor of this object.

isConfirmed

public boolean isConfirmed()

Returns true if the subscription request has been confirmed by the data provider.

isRejected

public boolean isRejected()

Returns true if the subscription request has been rejected by the data provider.

start

public void start()

Starts the subscription. To be used when subscription has been created with automaticStart = false in the constructor or when it has been cancelled and has to be started again. If the susbscription is confirmed, then this method will do nothing. Although it does not make sense in most cases, start() can be called on a subscription which is rejected to re-attempt to subscribe. If the server cannot be contacted immediately (e.g., is down or ureachable due to a network failure), then the object will repeat attempts to start subscription until it is confirmed() or rejected(cern.cmw.CmwException) by the server, or cancelled by the user.

cancel

public void cancel()

Cancels the subscription. If the susbscription is confirmed , then this method will stop subscription updates and release all related resources, both on the client and on the server side. Otherwise this method will deactivate the object: prevent all further attempts to make contact with the data provider. A Subscription object will be deleted (garbage collected) if it has been cancelled and unreferenced in the user code. After subscription has been cancelled it can be activated again by calling start() Note that cancel() will be called called automatically on behalf of the user when the subscription was rejected(cern.cmw.CmwException).

handleReply

public void handleReply(Request request,
                        Data val)

Description copied from class: ReplyAdapter

Invoked when a property value is delivered as a result of a successful get or monitorOn call. The value Data may change after the call returns: make a copy of the Data object if you need to store it in your application.

Implementation: empty.

Specified by:

handleReply in interface ReplyHandler

Overrides:

handleReply in class ReplyAdapter

disconnected

public void disconnected(SubscriptionRequest request)

Description copied from class: ReplyAdapter

Invoked when a subscription is suspended because of a lost connection to a remote device; for example, because the device server is down. Note that this is not a fatal error: connection will be automatically reestablished when the server is up again.

Implementation: empty.

Specified by:

disconnected in interface ReplyHandler

Overrides:

disconnected in class ReplyAdapter

See Also:

ReplyHandler.reconnected(cern.cmw.rda.client.SubscriptionRequest)

reconnected

public void reconnected(SubscriptionRequest request)

Description copied from class: ReplyAdapter

Invoked when a suspended subscription has been resumed.

Implementation: empty.

Specified by:

reconnected in interface ReplyHandler

Overrides:

reconnected in class ReplyAdapter

See Also:

ReplyHandler.disconnected(cern.cmw.rda.client.SubscriptionRequest)

handleException

public void handleException(Request request,
                            IOError exception)

Description copied from class: ReplyAdapter

Invoked on receipt of a reply containing the specified exception.

Implementation: calls ReplyAdapter.handleError(cern.cmw.rda.client.Request, cern.cmw.CmwException) with the specified parameters.

Specified by:

handleException in interface ReplyHandler

Overrides:

handleException in class ReplyAdapter

handleValue

protected abstract void handleValue(Data value)

Invoked when the subscribed value is updated. The value Data may change after the call returns: make a copy of the Data object if you need to store it in your application.

Parameters:

value - the Data object containing the updated value.

handleError

protected abstract void handleError(IOError err)

Invoked if an error occured when updating the value. This would typically be a data acquisition, timing, or I/O error in the device server.

Parameters:

err - the error description provided by the device server.

rejected

protected void rejected(CmwException why)

Invoked when the subscription request is rejected. A rejected request will be implicitely cancelled on return from this call (no need to cancel() it explicitely), and this object will be deleted (garbage collected) if it is unreferenced in the user code.

Parameters:

why - the exception thrown in response to the subscription request.

confirmed

protected void confirmed()

Invoked when the subscription request is confirmed by the data provider. This happens when the connection has been established for the first time and after a subsequent cancel/start. reconnected(cern.cmw.rda.client.SubscriptionRequest) will be invoked as well.

See Also:

reconnected(cern.cmw.rda.client.SubscriptionRequest)

disconnected

protected void disconnected()

Invoked when a confirmed subscription is suspended because of a lost connection to the data source. This would typically happen when the device server crashes or shuts down. Note that this is not a fatal error: connection will be automatically reestablished when the server is up again. Also invoked initially when connection is not yet established or when an established connection has been cancelled. Note that in case when the subscription object has been created with automatic start, this method may be invoked when the object has not been yet fully constructed.

See Also:

reconnected(cern.cmw.rda.client.SubscriptionRequest)

reconnected

protected void reconnected()

Invoked when a suspended subscription is resumed. Also invoked when connection to the data source has been established for the first time or after start has succeded.

See Also:

disconnected(cern.cmw.rda.client.SubscriptionRequest)

nOfPending

public static int nOfPending()

returns the number of pending subscriptions

main

public static void main(String[] args)

For tests.

java cern.cmw.rda.client.Subscription   
   

This function takes the device name, property name, and the cycle identifier from the command line arguments, and tries to subscribe to the specified property value. It can be used to quickly check if a certain device/property/cycle combination is valid, and to get current values of the property. Here is the source code:

   public static void main(String[] args)
   {
      //
      // What to subscribe to: device name, property name and (optional)
      // cycle selector string.
      //
      String device = null;
      String property = null;
      String cycle = null;
      //
      // Set device/propertyycle from the command line arguments.
      //
      if (args.length > 1)
      {
         device = args[0];
         property = args[1];
         if (args.length > 2) cycle = args[2];
      }
      else
      {
         System.out.println("Missing command line arguments\n"
            +"Expected:   ");
         System.exit(1);
      }
      //
      // Create a subscription
      //
      try
      {
         //
         // An anonymous inner class that extends Subscription with
         // simple implementations of the callback methods.
         //
         new Subscription(device, property, cycle)
         {
            protected void rejected(CmwException why)
            {
               System.out.println("REJECTED ("+why+")");
               System.exit(1);
            }
            protected void confirmed()
            {
               System.out.println("CONFIRMED");
            }
            protected void disconnected()
            {
               System.out.println("DISCONNECTED FROM DATA SOURCE");
            }
            protected void reconnected()
            {
               System.out.println("RECONNECTED TO DATA SOURCE");
            }
            protected void handleValue(Data value)
            {
               System.out.println("\nValue:\n"+value);
            }
            protected void handleError(IOError ex)
            {
               System.out.println("Error: "+ex);
            }
         };
      }
      catch(Throwable ex)
      {
         ex.printStackTrace();
         System.exit(1);
      }
   }