Inheritance diagram for alma.acs.nc.refactored.NCSubscriber:

Public Member Functions
	NCSubscriber (String channelName, String channelNotifyServiceDomainName, ContainerServicesBase services, NamingContext namingService, String clientName) throws AcsJException
void	startReceivingEvents () throws CannotStartReceivingEventsException, IllegalStateException
void	addGenericSubscription (GenericCallback receiver) throws CannotAddSubscriptionException
void	removeGenericSubscription () throws SubscriptionNotFoundException
void	addSubscription (AcsEventSubscriber.Callback<?extends IDLEntity > receiver) throws CannotAddSubscriptionException
void	removeSubscription (Class<?extends IDLEntity > structClass) throws SubscriptionNotFoundException
void	disconnect () throws IllegalStateException
boolean	isDisconnected ()
void	suspend () throws IllegalStateException
void	resume () throws IllegalStateException
final void	push_structured_event (StructuredEvent structuredEvent) throws Disconnected
void	disconnect_structured_push_consumer ()
void	offer_change (EventType[] added, EventType[] removed) throws InvalidEventType
void	reconnect (EventChannelFactory ecf)
Static Public Attributes
static final int	EVENT_QUEUE_CAPACITY = 50
Protected Member Functions
void	processEvent (IDLEntity corbaData, EventDescription eventDescrip)
String	getChannelKind ()
String	getChannelDomain ()
String	getNotificationFactoryName ()
String	getFilterLanguage ()
void	push_structured_event_called (StructuredEvent structuredEvent)
Protected Attributes
final Logger	logger
final Helper	helper
EventChannel	channel
final String	channelName
final String	channelNotifyServiceDomainName
ConsumerAdmin	sharedConsumerAdmin
StructuredProxyPushSupplier	proxySupplier
OSPushConsumer	corbaRef = null
AnyAide	anyAide
final HashMap< String, Double >	handlerTimeoutMap
AcsEventSubscriber.GenericCallback	genericReceiver = null
final Map< Class<?extends IDLEntity > , AcsEventSubscriber.Callback <?extends IDLEntity > >	receivers
final Map< String, Integer >	subscriptionsFilters = new HashMap<String, Integer>()
final MultipleRepeatGuard	processTimeLogRepeatGuard
Static Protected Attributes
static final int	PROXIES_PER_ADMIN = 5
Package Functions
private< T extends IDLEntity > void	_process (AcsEventSubscriber.Callback< T > receiver, IDLEntity corbaData, EventDescription eventDescrip)

Detailed Description

NCSubscriber is the Java implementation of the Notification Channel subscriber, while following the more generic AcsEventSubscriber interface.

This class is used to receive events asynchronously from notification channel suppliers. It is the replacement of alma.acs.nc.Consumer, and to keep things simple it no longer supports the inheritance mode, but instead supports type-safe delegation of incoming calls to a user-supplied handler.

The lifecycle steps are:

During creation of an NCSubscriber, the NC and consumer admin objects are either created or reused, and a proxy supplier object is created, all inside the notify service.
The reason for creating the proxy supplier (and the other objects along) already at this stage is to support event filtering on the server side, with Filter objects getting attached to the proxy supplier, see addSubscription(alma.acs.nc.AcsEventSubscriber.Callback).
TODO: This implementation could be changed to create the server-side filters on demand (e.g. in startReceivingEvents), so that addSubscription only stores the event type information without yet creating the filter.
Handlers for specialized events (addSubscription(alma.acs.nc.AcsEventSubscriber.Callback)) and/or for all events (addGenericSubscription(alma.acs.nc.AcsEventSubscriber.GenericCallback)) can be registered.
Once startReceivingEvents() is called, Corba NCs push events to this class, which delegates the events to the registered handlers.
The connection can then be suspended or resumed.

The NCSubscriber will be created (and cleaned up if needed) through the container services, At the moment it is still under development and not used in operational code, see the currently deprecated method alma.acs.container.ContainerServicesImpl#createNotificationChannelSubscriber(String, String).

Author:: jslopez, hsommer, rtobar

Constructor & Destructor Documentation

alma.acs.nc.refactored.NCSubscriber.NCSubscriber	(	String	channelName,
		String	channelNotifyServiceDomainName,
		ContainerServicesBase	services,
		NamingContext	namingService,
		String	clientName
	)			throws AcsJException

Creates a new instance of NCSubscriber. Normally an ACS class such as container services will act as the factory for NCSubscriber objects, but for exceptional cases it is also possible to create one stand-alone, as long as the required parameters can be provided.

Parameters:

	channelName	Subscribe to events on this channel registered in the CORBA Naming Service. If the channel does not exist, it's registered.
	channelNotifyServiceDomainName	Channel domain name, which is being used to determine the notification service that should host the NC. Passing `null` results in the default notify service "NotifyEventChannelFactory" being used.
	services	To get ACS logger, access to the CDB, etc.
	namingService	Must be passed explicitly, instead of the old hidden approach via `ORBInitRef.NameService` property.

Exceptions:

AcsJException

Thrown on any really bad error conditions encountered.

Member Function Documentation

private<T extends IDLEntity> void alma.acs.nc.refactored.NCSubscriber._process	(	AcsEventSubscriber.Callback< T >	receiver,
		IDLEntity	corbaData,
		EventDescription	eventDescrip
	)			`[package]`

"Generic helper method" to enforce type argument inference by the compiler, see http://www.angelikalanger.com/GenericsFAQ/FAQSections/ProgrammingIdioms.html#FAQ207

References alma.acs.nc.refactored.NCSubscriber.logger.

Referenced by alma.acs.nc.refactored.NCSubscriber.processEvent().

void alma.acs.nc.refactored.NCSubscriber.addGenericSubscription ( GenericCallback receiver ) throws CannotAddSubscriptionException

Subscribes to all events. The latest generic receiver displaces the previous one.

If in addition to this generic subscription we also have specific subscriptions via addSubscription(Class, alma.acs.nc.AcsEventSubscriber.Callback), then those more specific subscriptions will take precedence in receiving an event.

Notice though that any server-side filters previously created for the event type specific subscriptions get deleted when calling this method, so that even after removing a generic subscription the network performance gain of server-side filtering is lost. : Couldn't this be fixed by creating the server-side filters on demand (see also javadoc class comment about lifecycle)?

References alma.acs.nc.refactored.NCSubscriber.genericReceiver, and alma.acs.nc.refactored.NCSubscriber.subscriptionsFilters.

void alma.acs.nc.refactored.NCSubscriber.addSubscription ( AcsEventSubscriber.Callback<?extends IDLEntity > receiver ) throws CannotAddSubscriptionException

References alma.acs.nc.refactored.NCSubscriber.receivers, and alma.acs.nc.refactored.NCSubscriber.subscriptionsFilters.

void alma.acs.nc.refactored.NCSubscriber.disconnect ( ) throws IllegalStateException

References alma.acs.nc.refactored.NCSubscriber.channel, alma.acs.nc.refactored.NCSubscriber.channelName, alma.acs.nc.refactored.NCSubscriber.corbaRef, alma.acs.nc.refactored.NCSubscriber.helper, alma.acs.nc.refactored.NCSubscriber.logger, alma.acs.nc.refactored.NCSubscriber.proxySupplier, alma.acs.nc.refactored.NCSubscriber.sharedConsumerAdmin, and alma.acs.nc.refactored.NCSubscriber.suspend().

void alma.acs.nc.refactored.NCSubscriber.disconnect_structured_push_consumer ( )

ACS does not provide an implementation of this method.

See also:: org.omg.CosNotifyComm.StructuredPushConsumerOperations.disconnect_structured_push_consumer()

Exceptions:

NO_IMPLEMENT

String alma.acs.nc.refactored.NCSubscriber.getChannelDomain ( ) [protected]

This method returns a constant character pointer to the notification channel domain which is normally equivalent to acscommon.ALMADOMAIN.

Returns:: string

String alma.acs.nc.refactored.NCSubscriber.getChannelKind ( ) [protected]

This method returns a constant character pointer to the "kind" of notification channel as registered with the naming service (i.e., the kind field of a CosNaming.Name) which is normally equivalent to acscommon.NC_KIND. The sole reason this method is provided is to accommodate subclasses which subscribe/publish non-ICD style events (ACS archiving channel for example).In that case, the developer would override this method.

Returns:: string

Referenced by alma.acs.nc.refactored.NCSubscriber.NCSubscriber().

String alma.acs.nc.refactored.NCSubscriber.getFilterLanguage ( ) [protected]

This method returns a string to the type of filter constraint language to be used for filtering events which is normally equivalent to acsnc.FILTER_LANGUAGE_NAME.

Returns:: pointer to a constant string.

String alma.acs.nc.refactored.NCSubscriber.getNotificationFactoryName ( ) [protected]

This method returns the notify service name as registered with the CORBA Naming Service. This is normally equivalent to NotifyEventChannelFactory.

Returns:: string

References alma.acs.nc.refactored.NCSubscriber.channelName, alma.acs.nc.refactored.NCSubscriber.channelNotifyServiceDomainName, and alma.acs.nc.refactored.NCSubscriber.helper.

Referenced by alma.acs.nc.refactored.NCSubscriber.NCSubscriber(), alma.acs.nc.refactored.NCSubscriber.processEvent(), alma.acs.nc.refactored.NCSubscriber.push_structured_event(), and alma.acs.nc.refactored.NCSubscriber.startReceivingEvents().

boolean alma.acs.nc.refactored.NCSubscriber.isDisconnected ( )

References alma.acs.nc.refactored.NCSubscriber.sharedConsumerAdmin.

Referenced by alma.acs.nc.refactored.NCSubscriber.push_structured_event().

void alma.acs.nc.refactored.NCSubscriber.offer_change	(	EventType[]	added,
		EventType[]	removed
	)			throws InvalidEventType

ACS does not provide an implementation of this method.

See also:: org.omg.CosNotifyComm.NotifyPublishOperations.offer_change(org.omg.CosNotification.EventType[], org.omg.CosNotification.EventType[])

Exceptions:

NO_IMPLEMENT

void alma.acs.nc.refactored.NCSubscriber.processEvent	(	IDLEntity	corbaData,
		EventDescription	eventDescrip
	)			`[protected]`

Called from Corba (via push_structured_event). The implementation cannot assume any particular event type.

No exception is allowed to be thrown by this method, even if the receiver implementation throws a RuntimeExecption

Referenced by alma.acs.nc.refactored.NCSubscriber.push_structured_event().

final void alma.acs.nc.refactored.NCSubscriber.push_structured_event ( StructuredEvent structuredEvent ) throws Disconnected

This method is called by the notification channel (supplier proxy) each time an event is received.

It is declared final because it is crucial for the functioning of the NC library and thus cannot be overwritten by a subclass. If for special purposes a notification of raw event reception is needed, a subclass can implement push_structured_event_called(StructuredEvent), which gets called from this method as the first thing it does.

Parameters:

structuredEvent

The structured event sent by a supplier.

Exceptions:

Disconnected

If this subscriber is disconnected from the NC.

See also:: org.omg.CosNotifyComm.StructuredPushConsumerOperations.push_structured_event(org.omg.CosNotification.StructuredEvent)

void alma.acs.nc.refactored.NCSubscriber.push_structured_event_called ( StructuredEvent structuredEvent ) [protected]

Users can override this method to get notified of raw events, for additional statistics etc. Dealing with events in this method is only in addition to the normal processing of that event, and should generally be avoided by simply not overriding this method.

Parameters:

structuredEvent

Referenced by alma.acs.nc.refactored.NCSubscriber.push_structured_event().

void alma.acs.nc.refactored.NCSubscriber.reconnect ( EventChannelFactory ecf )

Implements alma.acs.nc.ReconnectableSubscriber.

References alma.acs.nc.refactored.NCSubscriber.channel, alma.acs.nc.refactored.NCSubscriber.channelName, alma.acs.nc.refactored.NCSubscriber.helper, and alma.acs.nc.refactored.NCSubscriber.logger.

void alma.acs.nc.refactored.NCSubscriber.removeGenericSubscription ( ) throws SubscriptionNotFoundException

Removes the generic receiver handler.

Exceptions:

AcsJCORBAProblemEx

References alma.acs.nc.refactored.NCSubscriber.genericReceiver, alma.acs.nc.refactored.NCSubscriber.proxySupplier, alma.acs.nc.refactored.NCSubscriber.receivers, and alma.acs.nc.refactored.NCSubscriber.subscriptionsFilters.

void alma.acs.nc.refactored.NCSubscriber.removeSubscription ( Class<?extends IDLEntity > structClass ) throws SubscriptionNotFoundException

References alma.acs.nc.refactored.NCSubscriber.proxySupplier, alma.acs.nc.refactored.NCSubscriber.receivers, and alma.acs.nc.refactored.NCSubscriber.subscriptionsFilters.

void alma.acs.nc.refactored.NCSubscriber.resume ( ) throws IllegalStateException

References alma.acs.nc.refactored.NCSubscriber.proxySupplier.

void alma.acs.nc.refactored.NCSubscriber.startReceivingEvents ( ) throws CannotStartReceivingEventsException, IllegalStateException

After invoking this method, the user has no control over when push_structured_event is invoked by the notification channel.

Try to defer contacting the NC and creating server-side objcts until this method gets called.

References alma.acs.nc.refactored.NCSubscriber.channelName, alma.acs.nc.refactored.NCSubscriber.corbaRef, alma.acs.nc.refactored.NCSubscriber.getNotificationFactoryName(), alma.acs.nc.refactored.NCSubscriber.helper, alma.acs.nc.refactored.NCSubscriber.logger, and alma.acs.nc.refactored.NCSubscriber.proxySupplier.

void alma.acs.nc.refactored.NCSubscriber.suspend ( ) throws IllegalStateException

The design of this implementation follows CORBA NC standard, as described in <it>Notification Service Specification, Version 1.1, formal/04-10-11, 3.4.13 The StructuredProxyPushSupplier Interface.</it>

References alma.acs.nc.refactored.NCSubscriber.proxySupplier.

Referenced by alma.acs.nc.refactored.NCSubscriber.disconnect().

Member Data Documentation

AnyAide alma.acs.nc.refactored.NCSubscriber.anyAide [protected]

Helper class used to manipulate CORBA anys.

Referenced by alma.acs.nc.refactored.NCSubscriber.NCSubscriber(), and alma.acs.nc.refactored.NCSubscriber.push_structured_event().

EventChannel alma.acs.nc.refactored.NCSubscriber.channel [protected]

There can be only one notification channel for any given subscriber. The NC is created on demand. Already in the constructor of this class, the NC's admin object and proxy supplier objects are created or reused.

Referenced by alma.acs.nc.refactored.NCSubscriber.disconnect(), alma.acs.nc.refactored.NCSubscriber.NCSubscriber(), and alma.acs.nc.refactored.NCSubscriber.reconnect().

final String alma.acs.nc.refactored.NCSubscriber.channelName [protected]

The channel has exactly one name registered in the CORBA Naming Service.

Referenced by alma.acs.nc.refactored.NCSubscriber.disconnect(), alma.acs.nc.refactored.NCSubscriber.getNotificationFactoryName(), alma.acs.nc.refactored.NCSubscriber.NCSubscriber(), alma.acs.nc.refactored.NCSubscriber.processEvent(), alma.acs.nc.refactored.NCSubscriber.push_structured_event(), alma.acs.nc.refactored.NCSubscriber.reconnect(), and alma.acs.nc.refactored.NCSubscriber.startReceivingEvents().

final String alma.acs.nc.refactored.NCSubscriber.channelNotifyServiceDomainName [protected]

The channel notification service domain name, can be null.

Referenced by alma.acs.nc.refactored.NCSubscriber.getNotificationFactoryName(), and alma.acs.nc.refactored.NCSubscriber.NCSubscriber().

OSPushConsumer alma.acs.nc.refactored.NCSubscriber.corbaRef = null [protected]

CORBA reference to ourself.

Referenced by alma.acs.nc.refactored.NCSubscriber.disconnect(), and alma.acs.nc.refactored.NCSubscriber.startReceivingEvents().

final int alma.acs.nc.refactored.NCSubscriber.EVENT_QUEUE_CAPACITY = 50 [static]

Event queue should hold at least two events to avoid unnecessary scary logs about slow receivers, but must be short enough to get receivers to actually implement their own queue and discard mechanism instead of relying on this ACS queue which may buffer events for a limited time and thus obscure the problem.

See also:: eventHandlingExecutor

Referenced by alma.acs.nc.refactored.NCSubscriber.NCSubscriber(), and alma.acs.nc.refactored.NCSubscriber.push_structured_event().

AcsEventSubscriber.GenericCallback alma.acs.nc.refactored.NCSubscriber.genericReceiver = null [protected]

Contains a generic receiver to be used by the addGenericSubscription() method.

Referenced by alma.acs.nc.refactored.NCSubscriber.addGenericSubscription(), alma.acs.nc.refactored.NCSubscriber.processEvent(), and alma.acs.nc.refactored.NCSubscriber.removeGenericSubscription().

final HashMap<String, Double> alma.acs.nc.refactored.NCSubscriber.handlerTimeoutMap [protected]

Maps event names to the maximum amount of time allowed for receiver methods to complete. Time is given in floating point seconds.

Referenced by alma.acs.nc.refactored.NCSubscriber.NCSubscriber(), and alma.acs.nc.refactored.NCSubscriber.processEvent().

final Helper alma.acs.nc.refactored.NCSubscriber.helper [protected]

Provides access to the notify service and CDB, creates NCs, etc

Referenced by alma.acs.nc.refactored.NCSubscriber.disconnect(), alma.acs.nc.refactored.NCSubscriber.getNotificationFactoryName(), alma.acs.nc.refactored.NCSubscriber.NCSubscriber(), alma.acs.nc.refactored.NCSubscriber.reconnect(), and alma.acs.nc.refactored.NCSubscriber.startReceivingEvents().

final Logger alma.acs.nc.refactored.NCSubscriber.logger [protected]

Provides access to the ACS logging system.

Referenced by alma.acs.nc.refactored.NCSubscriber._process(), alma.acs.nc.refactored.NCSubscriber.disconnect(), alma.acs.nc.refactored.NCSubscriber.NCSubscriber(), alma.acs.nc.refactored.NCSubscriber.processEvent(), alma.acs.nc.refactored.NCSubscriber.push_structured_event(), alma.acs.nc.refactored.NCSubscriber.reconnect(), and alma.acs.nc.refactored.NCSubscriber.startReceivingEvents().

final MultipleRepeatGuard alma.acs.nc.refactored.NCSubscriber.processTimeLogRepeatGuard [protected]

Contains a list of repeat guards for each different type of event.

Referenced by alma.acs.nc.refactored.NCSubscriber.NCSubscriber(), and alma.acs.nc.refactored.NCSubscriber.processEvent().

final int alma.acs.nc.refactored.NCSubscriber.PROXIES_PER_ADMIN = 5 [static, protected]

Referenced by alma.acs.nc.refactored.NCSubscriber.NCSubscriber().

StructuredProxyPushSupplier alma.acs.nc.refactored.NCSubscriber.proxySupplier [protected]

The supplier proxy we are connected to.

Referenced by alma.acs.nc.refactored.NCSubscriber.disconnect(), alma.acs.nc.refactored.NCSubscriber.NCSubscriber(), alma.acs.nc.refactored.NCSubscriber.removeGenericSubscription(), alma.acs.nc.refactored.NCSubscriber.removeSubscription(), alma.acs.nc.refactored.NCSubscriber.resume(), alma.acs.nc.refactored.NCSubscriber.startReceivingEvents(), and alma.acs.nc.refactored.NCSubscriber.suspend().

final Map<Class<? extends IDLEntity>, AcsEventSubscriber.Callback<? extends IDLEntity> > alma.acs.nc.refactored.NCSubscriber.receivers [protected]

Initial value:

 
                                                        new HashMap<Class<? extends IDLEntity>, AcsEventSubscriber.Callback<? extends IDLEntity>>()

Contains a list of receiver functions to be invoked when an event of a particular type is received.

key = the event type (IDL-defined struct, which is an IDLEntity subclass).
value = the matching event handler.

Referenced by alma.acs.nc.refactored.NCSubscriber.addSubscription(), alma.acs.nc.refactored.NCSubscriber.processEvent(), alma.acs.nc.refactored.NCSubscriber.removeGenericSubscription(), and alma.acs.nc.refactored.NCSubscriber.removeSubscription().

ConsumerAdmin alma.acs.nc.refactored.NCSubscriber.sharedConsumerAdmin [protected]

The consumer admin object attached to the NC, which is used by subscribers to get a reference to the structured supplier proxy. This reference is null when the subscriber is not connected to a NC.

The TAO extensions allow us to set a meaningful name for the admin object, but it probably will not be used as the ID, but as a separate name field. You can get the consumer admin object ID from here, see ConsumerAdmin#MyID(). (In the NC spec, it says "The MyID attribute is a readonly attribute that maintains the unique identifier of the target ConsumerAdmin instance, which is assigned to it upon creation by the Notification Service event channel.) It is an integer type, which makes it necessarily different from the name used with the TAO extensions.

We try to reuse a single admin object, to not allocate a new thread in the notification service for every subscriber.

Referenced by alma.acs.nc.refactored.NCSubscriber.disconnect(), alma.acs.nc.refactored.NCSubscriber.isDisconnected(), and alma.acs.nc.refactored.NCSubscriber.NCSubscriber().

final Map<String, Integer> alma.acs.nc.refactored.NCSubscriber.subscriptionsFilters = new HashMap<String, Integer>() [protected]

Contains a list of the added and removed subscriptions filters applied. Events on this list will be processed to check if the event should be accepted or discarded.

Referenced by alma.acs.nc.refactored.NCSubscriber.addGenericSubscription(), alma.acs.nc.refactored.NCSubscriber.addSubscription(), alma.acs.nc.refactored.NCSubscriber.removeGenericSubscription(), and alma.acs.nc.refactored.NCSubscriber.removeSubscription().

The documentation for this class was generated from the following file:

NCSubscriber.java

All Classes Namespaces Files Functions Variables Enumerations Properties

alma.acs.nc.refactored.NCSubscriber Class Reference

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Static Protected Attributes

Package Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation