alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity > Class Reference

Inheritance diagram for alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >:

Collaboration diagram for alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >:

Public Member Functions
	NCSubscriber (String channelName, ContainerServicesBase services) throws AcsJException
	NCSubscriber (String channelName, String channelNotifyServiceDomainName, ContainerServicesBase services) throws AcsJException
void	startReceivingEvents () throws AcsJException
void	addGenericSubscription (GenericCallback receiver)
void	removeGenericSubscription () throws AcsJCORBAProblemEx
void	addSubscription (Class< T > structClass, AcsEventSubscriber.Callback< T > receiver) throws AcsJException
void	removeSubscription (Class< T > structClass) throws AcsJException, FilterNotFound, InvalidEventType
void	disconnect ()
void	suspend ()
void	resume ()
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)
Protected Member Functions
void	processEvent (T corbaData, EventDescription eventDescrip)
String	getChannelKind ()
String	getChannelDomain ()
String	getNotificationFactoryName ()
String	getFilterLanguage ()
Protected Attributes
final Logger	logger
final Helper	helper
EventChannel	channel
final String	channelName
final String	channelNotifyServiceDomainName
ConsumerAdmin	consumerAdmin
StructuredProxyPushSupplier	proxySupplier
OSPushConsumer	corbaRef = null
AnyAide	anyAide
final HashMap< String, Double >	handlerTimeoutMap
AcsEventSubscriber.GenericCallback	genericReceiver = null
Map< String, AcsEventSubscriber.Callback< T > >	receivers = new HashMap<String, AcsEventSubscriber.Callback<T>>()
Map< String, Integer >	subscriptionsFilters = new HashMap<String, Integer>()
MultipleRepeatGuard	multiRepeatGuard
Private Member Functions
void	getAdmin () throws AcsJException
void	createProxySupplier () throws AcsJCORBAProblemEx
int	addFilter (String eventType) throws AcsJCORBAProblemEx
void	discardAllEvents () throws AcsJCORBAProblemEx
Private Attributes
final StopWatch	profiler
final boolean	isTraceNCEventsEnabled
AcsNcReconnectionCallback	m_callback
IntHolder	consumerAdminID
IntHolder	proxyID
final ReentrantLock	disconnectLock = new ReentrantLock()
Static Private Attributes
static final double	DEFAULT_MAX_PROCESS_TIME_SECONDS = 2.0

Detailed Description

NCSubscriber is the Java implementation of the Notification Channel subscriber.

This class is used to receive events asynchronously from notification channel suppliers. Replacement of alma.acs.nc.Consumer, no longer supports inheritance mode.

Author:: jslopez

Constructor & Destructor Documentation

alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::NCSubscriber	(	String	channelName,
		ContainerServicesBase	services
	)			throws AcsJException `[inline]`

Creates a new instance of NCSubscriber.

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::refactored::NCSubscriber< T extends IDLEntity >::NCSubscriber	(	String	channelName,
		String	channelNotifyServiceDomainName,
		ContainerServicesBase	services
	)			throws AcsJException `[inline]`

Creates a new instance of NCSubscriber.

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 notification service.
	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::refactored::NCSubscriber< T extends IDLEntity >::addFilter ( String eventType ) throws AcsJCORBAProblemEx [inline, private]

This method manages the filtering capabilities used to control subscriptions.

Exceptions:

AcsJCORBAProblemEx

void alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::addGenericSubscription ( GenericCallback receiver ) [inline]

Subscribes to all events. If in addition to this we also have subscriptions via addSubscription(Class, alma.acs.nc.refactored.AcsEventSubscriber.Callback) then those more specific subscriptions will take precedence.

void alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::addSubscription	(	Class< T >	structClass,
		AcsEventSubscriber.Callback< T >	receiver
	)			throws AcsJException `[inline]`

Add a subscription to a given type of event through filters.The main advantage of using java generics here: Compiler ensure that receiver is consistent with event type.

Parameters:

	structClass	Type of event to subscribe.
	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.

void alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::createProxySupplier ( ) throws AcsJCORBAProblemEx [inline, private]

Creates the proxy Supplier that will be connected to the admin, and stores it in the fields proxyID and proxySupplier.

Exceptions:

AcsJException

void alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::discardAllEvents ( ) throws AcsJCORBAProblemEx [inline, private]

This method is used to discard all events. Is called when there are no subscriptions left or if the removeSubscription() method is called with null as parameter.

Exceptions:

AcsJCORBAProblemEx

void alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::disconnect ( ) [inline]

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.

Todo:: Notice that the consumer admin object is not being destroyed. For doing this we must check if there's no more clients using it. Check if it's possible using TAO extensions.

void alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::disconnect_structured_push_consumer ( ) [inline]

ACS does not provide an implementation of this method.

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

void alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::getAdmin ( ) throws AcsJException [inline, private]

Gets the existing admin object or creates a new one. TODO

Todo:: Allow load balance

Exceptions:

AcsJException

String alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::getChannelDomain ( ) [inline, 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< T extends IDLEntity >::getChannelKind ( ) [inline, 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

String alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::getFilterLanguage ( ) [inline, 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< T extends IDLEntity >::getNotificationFactoryName ( ) [inline, protected]

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

Returns:: string

void alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::offer_change	(	EventType[]	added,
		EventType[]	removed
	)			throws InvalidEventType `[inline]`

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[])

void alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::processEvent	(	T	corbaData,
		EventDescription	eventDescrip
	)			`[inline, protected]`

Called from Corba (via push_structured_event)

The implementation cannot assume any particular event type.

final void alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::push_structured_event ( StructuredEvent structuredEvent ) throws Disconnected [inline]

This method is called each time an event is received.

Parameters:

structuredEvent

The structured event sent by a supplier.

Exceptions:

Disconnected

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

void alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::reconnect ( EventChannelFactory ecf ) [inline]

Implements alma::acs::nc::ReconnectableSubscriber.

void alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::removeGenericSubscription ( ) throws AcsJCORBAProblemEx [inline]

Removes the generic receiver handler.

Exceptions:

AcsJCORBAProblemEx

void alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::removeSubscription ( Class< T > structClass ) throws AcsJException, FilterNotFound, InvalidEventType [inline]

Remove a subscription by removing the corresponding gilter. After invoking this, events of the parameter's type will no longer be received.

Parameters:

structClass

Unsubscribes from this IDL struct (Java class). By passing in null here, no events of any type will be received, even if there was a generic subscription.

Exceptions:

	AcsJException	Thrown if there is some CORBA problem (like this subscriber has never subscribed to the given type).
	FilterNotFound	Thrown if there is no such filter.
	InvalidEventType	Thrown if the given type is invalid.

void alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::resume ( ) [inline]

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.

void alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::startReceivingEvents ( ) throws AcsJException [inline]

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.

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

Exceptions:

AcsJException

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

void alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::suspend ( ) [inline]

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 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>

Member Data Documentation

AnyAide alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::anyAide [protected]

Helper class used to manipulate CORBA anys.

EventChannel alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::channel [protected]

There can be only one notification channel for any given subscriber. Constructed on demand.

final String alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::channelName [protected]

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

final String alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::channelNotifyServiceDomainName [protected]

The channel notification service domain name, can be null.

ConsumerAdmin alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::consumerAdmin [protected]

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

IntHolder alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::consumerAdminID [private]

OSPushConsumer alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::corbaRef = null [protected]

CORBA reference to ourself.

final double alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::DEFAULT_MAX_PROCESS_TIME_SECONDS = 2.0 [static, private]

The default maximum amount of time an event handler is given to process event before a warning message is logged. This is used when an end-user does *not* define the appropriate XML elements within the ACS CDB. See the inline doc on EventChannel.xsd for more info. The time unit is floating point seconds.

final ReentrantLock alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::disconnectLock = new ReentrantLock() [private]

AcsEventSubscriber.GenericCallback alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::genericReceiver = null [protected]

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

final HashMap<String, Double> alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::handlerTimeoutMap [protected]

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

final Helper alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::helper [protected]

Provides access to the naming service among other things.

final boolean alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::isTraceNCEventsEnabled [private]

Whether sending of events should be logged.

final Logger alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::logger [protected]

Provides access to the ACS logging system.

AcsNcReconnectionCallback alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::m_callback [private]

MultipleRepeatGuard alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::multiRepeatGuard [protected]

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

final StopWatch alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::profiler [private]

Used to time the execution of receive methods

IntHolder alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::proxyID [private]

StructuredProxyPushSupplier alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::proxySupplier [protected]

The supplier proxy we are connected to.

Map<String, AcsEventSubscriber.Callback<T> > alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::receivers = new HashMap<String, AcsEventSubscriber.Callback<T>>() [protected]

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

Map<String, Integer> alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity >::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.

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

NCSubscriber.java

alma::acs::nc::refactored::NCSubscriber< T extends IDLEntity > Class Reference

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation