alma.acs.nc

Interface AcsEventSubscriber<T>

Type Parameters:

T - The event (base) type. If all events are of the same type then that type should be used; otherwise a common base type for all applicable events should be used, such as Object or IDLEntity.

All Known Implementing Classes:

AcsEventSubscriberImplBase, AdminConsumer, NCSubscriber

public interface AcsEventSubscriber<T>

This interface provides an event subscriber that can be implemented on top of Corba NC or DDS, in-memory for local testing, or hopefully also on top of other technologies such as ZeroMQ.

Subscriber lifecycle:

• Creation of the subscriber object may already allocate remote resources. Therefore you must always call disconnect() when done using the subscriber, even if startReceivingEvents() was never called.
• Subscriptions by event type or for all types of events can be set up using addSubscription(Callback) and addGenericSubscription(GenericCallback).
  Subscriptions can optionally be removed again using removeSubscription(Class) and removeGenericSubscription(). TODO: Verify that these can be called both before and after startReceivingEvents.
  
• Call startReceivingEvents() to actually subscribe.
• Call suspend() and resume() to temporarily suspend and later resume the subscription. Depending on the underlying framework, suspending will typically cause events to be queued somewhere.
• Call disconnect() to destroy all resources. The subscriber cannot be used afterwards.

The lifecycle is internally implemented using a state machine, see getLifecycleState().

Discussion:

• One AcsEventSubscriber object may subscribe to different types of events, which for a Corba NC is normal, but for DDS requires tricks with topics and partitions. We might change this API to allow only one event type per NC.
• TODO: We need to check if this API actually works for DDS, by integrating Rodrigo's RTI prototype.
• For historical reasons the API is asymmetric with respect to creation and destruction of resources, because resources are allocated both in the ctor and in startReceivingEvents(), whereas they are released only in the single method disconnect(). However, the underlying state machine knows two 'connect' and two 'disconnect' transitions and artificially maps them to the asymmetric API. If we want to make the API symmetric, we could break up 'disconnect' into 'stopReceivingEvents' and 'destroy'.

Author:

jslopez, hsommer

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	AcsEventSubscriber.Callback<U> User callback for received events.
static interface	AcsEventSubscriber.GenericCallback Generic event callback, for use with addGenericSubscription(GenericCallback).

Method Summary

Modifier and Type	Method and Description
void	addGenericSubscription(AcsEventSubscriber.GenericCallback receiver) Adds a generic handler for all types of events.
<U extends T> void	addSubscription(AcsEventSubscriber.Callback<U> receiver) Adds a handler that will receive events of a specific type.
void	disconnect() Disconnects this subscriber from the Notification Channel, and releases all the resources associated with it.
java.lang.String	getLifecycleState() Returns the lifecycle state as obtained from an internal state machine.
boolean	isSuspended() Returns true if this subscriber has been suspended.
void	removeGenericSubscription() Removes the generic event handler, so that it will no longer receive events.
<U extends T> void	removeSubscription(java.lang.Class<U> structClass) Removes the subscription for a specified event type or for all events types, so that the handler previously registered for that event type will no longer receive events.
void	resume() Used to reenable the Subscriber after a call to the suspend() method.
void	startReceivingEvents() This method must be called to actually start receiving events.
void	suspend() Used to temporarily halt receiving events of all types.

Method Detail

addSubscription

<U extends T> void addSubscription(AcsEventSubscriber.Callback<U> receiver)
                            throws AcsJEventSubscriptionEx

Adds a handler that will receive events of a specific type. The event type is determined by the value returned by calling AcsEventSubscriber.Callback.getEventType() on the receiver parameter.

Note that the same event type can only be subscribed to with one handler, which means that another handler added for the same type will replace the previous handler.

The event type must be that of actual events, not of base classes. For example, the AcsEventSubscriber could be parameterized with base type IDLEntity and we could then add two subscriptions for events defined as IDL structs, say AntennaStatus and TemperatureData. If you want to subscribe to events without knowing their exact type, use addGenericSubscription(GenericCallback) instead.

Parameters:

receiver - The callback to use when receiving events for the specified type.

Throws:

AcsJEventSubscriptionEx - If there is a problem and the receiver cannot be added

removeSubscription

<U extends T> void removeSubscription(java.lang.Class<U> structClass)
                               throws AcsJEventSubscriptionEx

Removes the subscription for a specified event type or for all events types, so that the handler previously registered for that event type will no longer receive events.

Parameters:

structClass - the event type to be unsubscribed. If null, then all subscriptions but the generic subscription are removed.

Throws:

AcsJEventSubscriptionEx - if the specified event type has not been previously subscribed or if the removal fails with a technical problem.

addGenericSubscription

void addGenericSubscription(AcsEventSubscriber.GenericCallback receiver)
                     throws AcsJEventSubscriptionEx

Adds a generic handler for all types of events. This should only be used by monitoring tools and other special applications. For normal applications, use one or many calls to addSubscription(Callback), each with a Callback object that matches exactly the subscribed event type.

It is possible to add a generic handler in addition to event type-specific handlers (where the latter will get precedence). Adding another generic handler will replace the previous generic handler.

Parameters:

receiver - The callback to use when receiving events

Throws:

AcsJEventSubscriptionEx - If there is a problem and the generic receiver cannot be added

removeGenericSubscription

void removeGenericSubscription()
                        throws AcsJEventSubscriptionEx

Removes the generic event handler, so that it will no longer receive events. Event specific handlers may still receive events.

Throws:

SubscriptionNotFoundException - If a generic receiver has not been previously subscribed

AcsJEventSubscriptionEx - If there is any problem while unsubscribing the generic receiver

getLifecycleState

java.lang.String getLifecycleState()

Returns the lifecycle state as obtained from an internal state machine.

This state can be used only for debug output. The state names may change over time and should not be used to control execution.

startReceivingEvents

void startReceivingEvents()
                   throws AcsJIllegalStateEventEx,
                          AcsJCouldntPerformActionEx

This method must be called to actually start receiving events. Typically it is called after the subscriptions are set up. User may still add and remove subscriptions at any given time, though. Also, the connection can be suspended and resumed.

No further invocations should be attempted on this method after one has been already successful. Otherwise, an AcsJIllegalStateEventEx will be thrown.

If this method is not called, no event will ever be received

Throws:

AcsJIllegalStateEventEx - If the user calls this method on an object that is already receiving events

AcsJCouldntPerformActionEx - If any error happens while trying to start receiving events

disconnect

void disconnect()
         throws AcsJIllegalStateEventEx,
                AcsJCouldntPerformActionEx

Disconnects this subscriber from the Notification Channel, and releases all the resources associated with it. After this call, all registered handlers will stop receiving events, and this subscriber becomes unusable.

Calling this method over a subscriber object that has been already disconnected will throw an AcsJIllegalStateEventEx.

Throws:

AcsJIllegalStateEventEx - If this method is called on an AcsEventSubscriber object that has been already disconnected

AcsJCouldntPerformActionEx

suspend

void suspend()
      throws AcsJIllegalStateEventEx,
             AcsJCouldntPerformActionEx

Used to temporarily halt receiving events of all types.

If the Subscriber has been connected already (method startReceivingEvents(), then after calling this method, incoming events will be buffered instead of being discarded; unexpired events will be received later, after a call to resume().

// * This call has no effect if the Subscriber is not connected, or if it is // * connected but already suspended.

Throws:

AcsJIllegalStateEventEx - if the subscriber is not connected to an NC.

AcsJCouldntPerformActionEx

isSuspended

boolean isSuspended()

Returns true if this subscriber has been suspended.

resume

void resume()
     throws AcsJIllegalStateEventEx,
            AcsJCouldntPerformActionEx

Used to reenable the Subscriber after a call to the suspend() method. Queued events will be received after this call, see suspend(). This call has no effect if the Subscriber is not connected, or if it is connected and already processing events.

Throws:

AcsJIllegalStateEventEx

AcsJCouldntPerformActionEx