Inheritance diagram for alma.acs.nc.Consumer:

Public Member Functions
	Consumer (String channelName, ContainerServicesBase services) throws AcsJException
	Consumer (String channelName, String channelNotifyServiceDomainName, ContainerServicesBase services) throws AcsJException
void	consumerReady () throws AcsJException
void	addSubscription (Class<?extends IDLEntity > structClass) throws AcsJEventSubscriptionFailureEx
void	addSubscription (Class<?extends IDLEntity > structClass, Object receiver) throws AcsJException
void	removeSubscription (Class structClass) throws AcsJException
int	addFilter (Class<?extends IDLEntity > structClassName, String filter) throws AcsJException
boolean	removeFilter (int filter) throws AcsJException
void	disconnect_structured_push_consumer ()
void	push_structured_event (StructuredEvent structuredEvent) throws org.omg.CosEventComm.Disconnected
void	offer_change (EventType[] eventType, EventType[] eventType1) throws org.omg.CosNotifyComm.InvalidEventType
void	disconnect ()
void	suspend ()
void	resume ()
alma.acs.nc.Helper	getHelper ()
void	reconnect (EventChannelFactory ecf)
Static Public Attributes
static final int	EVENT_QUEUE_CAPACITY = 50
Protected Member Functions
String	getChannelKind ()
String	getChannelDomain ()
String	getNotificationFactoryName ()
void	configSubscriptions () throws AcsJEventSubscriptionFailureEx
void	configFilters ()
String	getFilterLanguage ()
void	processEvent (IDLEntity corbaData, EventDescription eventDescrip)
void	processEvent (Object corbaData)
Protected Attributes
final ChannelInfo	m_channelInfo
final Logger	m_logger
final Helper	m_helper
final String	m_notifyServiceName
final String	m_channelName
EventChannel	m_channel
final String	m_channelNotifyServiceDomainName
final HashMap< String, Object >	m_handlerFunctions = new HashMap<String, Object>()
final HashMap< String, Double >	m_handlerTimeoutMap
ConsumerAdmin	m_consumerAdmin
StructuredProxyPushSupplier	m_proxySupplier
OSPushConsumer	m_corbaRef
AnyAide	m_anyAide
Static Protected Attributes
static final String	RECEIVE_METHOD_NAME = "receive"

Detailed Description

Consumer is the Java implementation of a structured push consumer notification channel class. In short, this class is used to receive events asynchronously from notification channel suppliers. It can either be used as-is (assuming receivers/handlerFunctions are being utilized) or subclassed. Developers must remember to use the disconnect method after they are done receiving events.

Author:: dfugate

Constructor & Destructor Documentation

alma.acs.nc.Consumer.Consumer	(	String	channelName,
		ContainerServicesBase	services
	)			throws AcsJException

Creates a new instance of Consumer

Parameters:

	channelName	Subscribe to events on this channel registered in the CORBA Naming Service.
	services	This is used to access ACS logging system.

Exceptions:

AcsJException

Thrown on any really bad error conditions encountered.

alma.acs.nc.Consumer.Consumer	(	String	channelName,
		String	channelNotifyServiceDomainName,
		ContainerServicesBase	services
	)			throws AcsJException

Creates a new instance of Consumer

Parameters:

	channelName	Subscribe to events on this channel registered in the CORBA Naming Service.
	channelNotifyServiceDomainName	Channel domain name, which is being used to determine notification service. May be `null`.
	services	This is used to access ACS logging system.

Exceptions:

AcsJException

Thrown on any really bad error conditions encountered.

Member Function Documentation

int alma.acs.nc.Consumer.addFilter	(	Class<?extends IDLEntity >	structClassName,
		String	filter
	)			throws AcsJException

Adds a single filter to this consumer. With ALMA's use of IDL structs for ICD events, this method is no longer useful. May become deprecated in future ACS releases.

Returns:: The filter ID of the newly created filter. This is only useful for removing filters. Returns -1 on failure.

Parameters:

	structClassName	IDL struct Java class filter is to be applied to.
	filter	The filter string in extended trader constraint language.

Exceptions:

AcsJException

Thrown if there is some CORBA problem (like the filter is not using the correct grammar).

References alma.acs.nc.Consumer.getChannelDomain(), alma.acs.nc.Consumer.getFilterLanguage(), alma.acs.nc.Consumer.m_channel, alma.acs.nc.Consumer.m_channelName, and alma.acs.nc.Consumer.m_proxySupplier.

void alma.acs.nc.Consumer.addSubscription ( Class<?extends IDLEntity > structClass ) throws AcsJEventSubscriptionFailureEx

Add a subscription to a given (IDL struct) Java class. Use this method only when Consumer has been subclassed and processEvent overridden.

Parameters:

structClass Type of event to subscribe to (i.e., alma.CORR.DataStruct.class). If null then all events are subscribed.

Exceptions:

AcsJEventSubscriptionFailureEx

Thrown if the subscription failed.

References alma.acs.nc.Consumer.getChannelDomain(), alma.acs.nc.Consumer.m_channelName, and alma.acs.nc.Consumer.m_consumerAdmin.

Referenced by com.cosylab.acs.jms.ACSJMSMessageEntityConsumer.ACSJMSMessageEntityConsumer(), alma.acs.nc.Consumer.addSubscription(), alma.acs.nc.CorbaReceiver.attach(), alma.acs.nc.ArchiveConsumer.configSubscriptions(), alma.alarmsystem.clients.SourceClient.connect(), alma.acs.nc.CorbaReceiver.connect(), alma.acs.nc.ExecutiveConsumer.ExecutiveConsumer(), alma.COUNTER.CounterConsumerImpl.CounterConsumerImpl.getBlocks(), alma.demo.EventConsumerImpl.EventConsumerImpl.initialize(), alma.ACSCOURSE_MOUNT.MountConsumer.MountConsumer(), cl.utfsm.samplingSystemUI.core.NotificationChannelSuscription.NotificationChannelSuscription(), and alma.alarmsystemdemo.listener.SourcesListener.SourcesListener().

void alma.acs.nc.Consumer.addSubscription	(	Class<?extends IDLEntity >	structClass,
		Object	receiver
	)			throws AcsJException

Add a subscription to a given (IDL struct) Java class and also register a method capable of processing that event (IDL struct). Each time an event of the (IDL struct) type is received, the Consumer will automatically invoke the receiver object's "receive" method using the (IDL struct) data extracted from the CORBA event.

Parameters:

	structClass	Type of event to subscribe to (i.e., alma.CORR.DataStruct.class).
	receiver	An object which implements a method called "receive". The "receive" method must accept an instance of a structClass object as its sole parameter.

Exceptions:

AcsJException

Thrown if there is some CORBA problem.

References alma.acs.nc.Consumer.addSubscription(), alma.acs.nc.Consumer.m_channelName, alma.acs.nc.Consumer.m_handlerFunctions, alma.acs.nc.Consumer.m_logger, and alma.acs.nc.Consumer.RECEIVE_METHOD_NAME.

void alma.acs.nc.Consumer.configFilters ( ) [protected]

Override this method in subclasses to specify all filters this Consumer will use. The method would then just make a lot of calls to addFilter(...). Important to note this is the last method invoked by consumer's constructor.

Referenced by alma.acs.nc.Consumer.Consumer().

void alma.acs.nc.Consumer.configSubscriptions ( ) throws AcsJEventSubscriptionFailureEx [protected]

Override this method to setup any number of event subscriptions. That is, this method is invoked by consumer's constructor after everything else has been initialized.

Reimplemented in alma.acs.nc.ArchiveConsumer.

Referenced by alma.acs.nc.Consumer.Consumer().

void alma.acs.nc.Consumer.consumerReady ( ) throws AcsJException

After invoking this method, the user has no control over when push_structured_event is invoked by the notification channel. User may still add and remove subscriptions at any given time though. Also, the connection can be suspended and resumed.

Finally, consumerReady may spawn a thread to search for the channel if it does not already exist. Once the channel becomes available, all saved subscription are subscribed to and consumerReady is automatically invoked again.

Exceptions:

AcsJException

Thrown if the consumer cannot begin receiving events for some CORBA reason.

References alma.acs.nc.Consumer.getHelper(), alma.acs.nc.Consumer.m_corbaRef, and alma.acs.nc.Consumer.m_proxySupplier.

Referenced by com.cosylab.acs.jms.ACSJMSTopicSubscriber.ACSJMSTopicSubscriber(), alma.alarmsystem.clients.SourceClient.connect(), alma.acs.nc.CorbaReceiver.connect(), alma.COUNTER.CounterConsumerImpl.CounterConsumerImpl.getBlocks(), alma.demo.EventConsumerImpl.EventConsumerImpl.initialize(), alma.ACSCOURSE_MOUNT.MountConsumer.main(), cl.utfsm.samplingSystemUI.core.PropertySamp.run(), and alma.alarmsystemdemo.listener.SourcesListener.SourcesListener().

void alma.acs.nc.Consumer.disconnect ( )

This method must be invoked before a component or client is destroyed. Failure to do so can cause remote memory leaks. Make sure it is not invoked multiple times. Once it has been called, events will no longer be received.

References alma.acs.nc.AcsNcReconnectionCallback.disconnect(), alma.acs.nc.Consumer.getHelper(), alma.acs.nc.Consumer.m_channelName, alma.acs.nc.Consumer.m_consumerAdmin, alma.acs.nc.Consumer.m_corbaRef, alma.acs.nc.Consumer.m_logger, alma.acs.nc.Consumer.m_proxySupplier, alma.acs.nc.Consumer.removeSubscription(), and alma.acs.nc.Consumer.suspend().

Referenced by alma.demo.EventConsumerImpl.EventConsumerImpl.cleanUp(), alma.COUNTER.CounterConsumerImpl.CounterConsumerImpl.cleanUp(), alma.alarmsystem.clients.SourceClient.close(), com.cosylab.acs.jms.ACSJMSTopicSubscriber.close(), alma.acs.eventbrowser.model.EventModel.closeSelectedConsumer(), alma.acs.nc.Consumer.Consumer(), alma.COUNTER.CounterConsumerImpl.CounterConsumerImpl.getBlocks(), alma.demo.EventConsumerImpl.EventConsumerImpl.initialize(), alma.ACSCOURSE_MOUNT.MountConsumer.main(), and cl.utfsm.samplingSystemUI.core.PropertySamp.stop().

void alma.acs.nc.Consumer.disconnect_structured_push_consumer ( )

Override this method to do some "housekeeping". Invoked by the CORBA Notification Service itself each time a Supplier subclass is destroyed. Do not call it from your code!

String alma.acs.nc.Consumer.getChannelDomain ( ) [protected]

This method returns a constant character pointer to the notification channel domain which is normally equivalent to acscommon.ALMADOMAIN. The sole reason this method is provided is to accomodate 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.Consumer.addFilter(), alma.acs.nc.Consumer.addSubscription(), and alma.acs.nc.Consumer.removeSubscription().

String alma.acs.nc.Consumer.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 accomodate subclasses which subscribe/publish non-ICD style events (ACS archiving channel for example).In that case, the developer would override this method.

Returns:: string

Reimplemented in alma.acs.nc.ArchiveConsumer.

Referenced by alma.acs.nc.Consumer.Consumer().

String alma.acs.nc.Consumer.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. Override to change this behavior.

Returns:: pointer to a constant string.

Referenced by alma.acs.nc.Consumer.addFilter().

alma.acs.nc.Helper alma.acs.nc.Consumer.getHelper ( )

Returns a reference to this instance's helper. Not too useful outside this class.

Returns:: A valid reference to this instances helper.

References alma.acs.nc.Consumer.m_helper.

Referenced by alma.acs.nc.Consumer.Consumer(), alma.acs.nc.Consumer.consumerReady(), and alma.acs.nc.Consumer.disconnect().

String alma.acs.nc.Consumer.getNotificationFactoryName ( ) [protected]

This method returns the notify service name as registered with the CORBA Naming Service. This is normally equivalent to acscommon.ALMADOMAIN. 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 (e.g. to return or logging channel with alma.acscommon.LOGGING_NOTIFICATION_FACTORY_NAME.value)

Returns:: string

Reimplemented in alma.acs.eventbrowser.model.AdminConsumer, and alma.acs.nc.ArchiveConsumer.

References alma.acs.nc.Consumer.m_channelName, alma.acs.nc.Consumer.m_channelNotifyServiceDomainName, and alma.acs.nc.Consumer.m_helper.

Referenced by alma.acs.nc.Consumer.Consumer(), alma.acs.nc.Consumer.processEvent(), alma.acs.nc.CorbaReceiver.push_structured_event(), and alma.acs.nc.Consumer.push_structured_event().

void alma.acs.nc.Consumer.offer_change	(	EventType[]	eventType,
		EventType[]	eventType1
	)			throws org.omg.CosNotifyComm.InvalidEventType

A "smart" consumer will override this method to subscribe to new domain/type events as suppliers offer them. A fairly advanced feature. Do not call it from your code!

Parameters:

	eventType	Domain/type pairs of events that have been added to this channel.
	eventType1	Domain/type pairs of events that have been removed from this channel.

Exceptions:

org.omg.CosNotifyComm.InvalidEventType

...

void alma.acs.nc.Consumer.processEvent ( Object corbaData ) [protected]

The method invoked each time an ICD-style event is received. Consumer subclasses must override this method. If receiver object(s) have been registered using the addSubscription method, this method does not need to be overriden.

Parameters:

corbaData

Generally an IDL struct. It has already been extracted from the CORBA Any (when it was packed into the CORBA structured event) and a simple typecast on it to the correct type should be enough to make it usable.

References alma.acs.nc.Consumer.m_channelName, and alma.acs.nc.Consumer.m_logger.

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

The method invoked each time an ICD-style event is received. Consumer subclasses must override this method or the other signature of processEvent (if they do not care about the EventDescription parameter). If receiver object(s) have been registered using the addSubscription method, this method does not need to be overriden.

Parameters:

	corbaData	Generally an IDL struct. It has already been extracted from the CORBA Any (when it was packed into the CORBA structured event) and a simple typecast on it to the correct type should be enough to make it usable.
	eventDescrip	An instance of an IDL struct which describes the event. See acsnc.idl for the defintion.

References alma.acs.util.StopWatch.getLapTimeMillis(), alma.acs.nc.Consumer.getNotificationFactoryName(), alma.acs.nc.Consumer.m_channelName, alma.acs.nc.Consumer.m_handlerFunctions, alma.acs.nc.Consumer.m_handlerTimeoutMap, alma.acs.nc.Consumer.m_logger, alma.acs.nc.Consumer.RECEIVE_METHOD_NAME, and alma.acs.util.StopWatch.reset().

Referenced by alma.acs.nc.Consumer.push_structured_event().

void alma.acs.nc.Consumer.push_structured_event ( StructuredEvent structuredEvent ) throws org.omg.CosEventComm.Disconnected

As of ACS 3.0, override processEvent(Object) instead of this CORBA method. push_structured_event is what is called each time an event is received. Do not call it from your code!

Parameters:

structuredEvent

The structured event sent by a supplier subclass.

Exceptions:

org.omg.CosEventComm.Disconnected

Reimplemented in com.cosylab.acs.jms.ACSJMSMessageEntityConsumer, cl.utfsm.samplingSystemUI.core.NotificationChannelSuscription, alma.acs.eventbrowser.model.AdminConsumer, and alma.acs.nc.ArchiveConsumer.

References alma.acs.logging.RepeatGuard.checkAndIncrement(), alma.acs.nc.AnyAide.complexAnyToObject(), alma.acs.nc.Consumer.EVENT_QUEUE_CAPACITY, alma.acs.nc.Consumer.getNotificationFactoryName(), alma.acs.nc.Consumer.m_anyAide, alma.acs.nc.Consumer.m_channelName, alma.acs.nc.Consumer.m_logger, and alma.acs.nc.Consumer.processEvent().

void alma.acs.nc.Consumer.reconnect ( EventChannelFactory ecf )

Implements alma.acs.nc.ReconnectableSubscriber.

References alma.acs.nc.Consumer.m_channel, alma.acs.nc.Consumer.m_channelName, alma.acs.nc.Consumer.m_helper, and alma.acs.nc.Consumer.m_logger.

boolean alma.acs.nc.Consumer.removeFilter ( int filter ) throws AcsJException

Removes a single filter from this consumer. See deprecation comments on the addFilter method.

Parameters:

filter

The filter's unique ID. This parameter is the return value of the addFilter method.

Exceptions:

AcsJException

Thrown if CORBA problems are encountered.

Returns:: True if the filter was succesfully removed and false otherwise. TODO: this method should not throw an AcsJException

References alma.acs.nc.Consumer.m_channelName, alma.acs.nc.Consumer.m_logger, and alma.acs.nc.Consumer.m_proxySupplier.

void alma.acs.nc.Consumer.removeSubscription ( Class structClass ) throws AcsJException

Remove a subscription from this consumer. After invoking this, events of the parameter's type will no longer be received.

Parameters:

structClassName

Unsubscribes from this IDL struct (Java class). By passing in null here, no events of any type will be received.

Exceptions:

AcsJException

Thrown if there is some CORBA problem (like this consumer has never subscribed to the IDL struct).

References alma.acs.nc.Consumer.getChannelDomain(), alma.acs.nc.Consumer.m_channelName, alma.acs.nc.Consumer.m_consumerAdmin, and alma.acs.nc.Consumer.m_handlerFunctions.

Referenced by alma.acs.nc.CorbaReceiver.detach(), alma.acs.nc.CorbaReceiver.disconnect(), and alma.acs.nc.Consumer.disconnect().

void alma.acs.nc.Consumer.resume ( )

Used to reenable the Consumer after a call to the suspend() method. Queued events will be received after this call, see suspend().

This call has no effect if the consumer is not connected at all (see consumerReady()), or if it has not been suspended.

References alma.acs.nc.Consumer.m_proxySupplier.

void alma.acs.nc.Consumer.suspend ( )

Used to temporarily halt receiving events of all types.

If the consumer has been connected already (method consumerReady(), 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 design 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.Consumer.m_proxySupplier.

Referenced by alma.acs.nc.Consumer.disconnect().

Member Data Documentation

final int alma.acs.nc.Consumer.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.Consumer.Consumer(), and alma.acs.nc.Consumer.push_structured_event().

AnyAide alma.acs.nc.Consumer.m_anyAide [protected]

Helper class used to manipulate CORBA anys

Referenced by alma.acs.nc.Consumer.Consumer(), alma.acs.nc.Consumer.push_structured_event(), and alma.acs.nc.ArchiveConsumer.push_structured_event().

EventChannel alma.acs.nc.Consumer.m_channel [protected]

There can be only one notification channel for any given consumer.

Referenced by alma.acs.nc.Consumer.addFilter(), alma.acs.nc.Consumer.Consumer(), and alma.acs.nc.Consumer.reconnect().

final ChannelInfo alma.acs.nc.Consumer.m_channelInfo [protected]

helper object contains various info about the notification channel

Referenced by alma.acs.nc.Consumer.Consumer().

final String alma.acs.nc.Consumer.m_channelName [protected]

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

final String alma.acs.nc.Consumer.m_channelNotifyServiceDomainName [protected]

The channel notification service domain name, can be null.

Referenced by alma.acs.nc.Consumer.Consumer(), and alma.acs.nc.Consumer.getNotificationFactoryName().

ConsumerAdmin alma.acs.nc.Consumer.m_consumerAdmin [protected]

The consumer admin object used by consumers to get a reference to the structured supplier proxy.

Referenced by alma.acs.nc.Consumer.addSubscription(), alma.acs.eventbrowser.model.AdminConsumer.AdminConsumer(), alma.acs.nc.Consumer.disconnect(), and alma.acs.nc.Consumer.removeSubscription().

OSPushConsumer alma.acs.nc.Consumer.m_corbaRef [protected]

CORBA reference to ourself

Referenced by alma.acs.nc.Consumer.consumerReady(), and alma.acs.nc.Consumer.disconnect().

final HashMap<String, Object> alma.acs.nc.Consumer.m_handlerFunctions = new HashMap<String, Object>() [protected]

Contains a list of handler/receiver objects whose "receive" method (see RECEIVE_METHOD_NAME) will be invoked when an event of a particular type is received.

Referenced by alma.acs.nc.Consumer.addSubscription(), alma.acs.nc.Consumer.processEvent(), and alma.acs.nc.Consumer.removeSubscription().

final HashMap<String, Double> alma.acs.nc.Consumer.m_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.Consumer.Consumer(), and alma.acs.nc.Consumer.processEvent().

final Helper alma.acs.nc.Consumer.m_helper [protected]

Provides access to the naming service among other things.

Referenced by alma.acs.nc.Consumer.Consumer(), alma.acs.nc.Consumer.getHelper(), alma.acs.nc.Consumer.getNotificationFactoryName(), and alma.acs.nc.Consumer.reconnect().

final Logger alma.acs.nc.Consumer.m_logger [protected]

Provides access to the ACS logging system.

Referenced by alma.acs.nc.Consumer.addSubscription(), alma.acs.nc.ArchiveConsumer.ArchiveConsumer(), alma.acs.nc.ArchiveConsumer.configSubscriptions(), alma.acs.nc.Consumer.Consumer(), alma.acs.nc.Consumer.disconnect(), alma.acs.nc.ExecutiveConsumer.processEvent(), alma.acs.nc.Consumer.processEvent(), cl.utfsm.samplingSystemUI.core.NotificationChannelSuscription.push_structured_event(), alma.acs.nc.ExecutiveConsumer.push_structured_event(), alma.acs.nc.CorbaReceiver.push_structured_event(), alma.acs.nc.Consumer.push_structured_event(), alma.acs.nc.ArchiveConsumer.push_structured_event(), alma.acs.eventbrowser.model.AdminConsumer.push_structured_event(), com.cosylab.acs.jms.ACSJMSMessageEntityConsumer.push_structured_event(), alma.acs.nc.Consumer.reconnect(), and alma.acs.nc.Consumer.removeFilter().