alma::acs::nc::SimpleSupplier Class Reference

Inheritance diagram for alma::acs::nc::SimpleSupplier:

Collaboration diagram for alma::acs::nc::SimpleSupplier:

Classes
interface	EventProcessingCallback< T extends IDLEntity >
Public Member Functions
	SimpleSupplier (String cName, ContainerServicesBase services) throws AcsJException
	SimpleSupplier (String cName, ContainerServicesBase services, EventProcessingCallback<?extends IDLEntity > evProcCallback) throws AcsJException
	SimpleSupplier (String cName, String channelNotifyServiceDomainName, ContainerServicesBase services) throws AcsJException
	SimpleSupplier (String cName, String channelNotifyServiceDomainName, ContainerServicesBase services, EventProcessingCallback<?extends IDLEntity > evProcCallback) throws AcsJException
void	disconnect ()
String	getChannelName ()
void	subscription_change (EventType[] eventType, EventType[] eventType1) throws InvalidEventType
void	disconnect_structured_push_supplier ()
void	publishEvent (IDLEntity customStruct) throws AcsJException
void	reconnect (gov.sandia.NotifyMonitoringExt.EventChannelFactory ecf)
Protected Member Functions
void	destroyNotificationChannel () throws AcsJException
String	getChannelKind ()
String	getChannelDomain ()
String	getNotificationFactoryName ()
EventChannel	getNotificationChannel ()
StructuredEvent	getCORBAEvent (String typeName, String eventName)
Protected Attributes
final Helper	m_helper
final String	m_channelName
final String	m_channelNotifyServiceDomainName
SupplierAdmin	m_supplierAdmin
StructuredProxyPushConsumer	m_proxyConsumer
volatile long	m_count = 0
EventChannel	m_channel
final Logger	m_logger
final ContainerServicesBase	m_services
final AnyAide	m_anyAide
EventProcessingCallback	eventProcCallback
Package Functions
protected< T extends IDLEntity > void	publishCORBAEvent (StructuredEvent se, T event) throws AcsJException
Private Attributes
final boolean	isTraceEventsEnabled
IntHolder	ih
IntHolder	cp_ih
AcsNcReconnectionCallback	reconnectCallback
CircularQueue	eventBuff

Detailed Description

SimpleSupplier is the standard class to be used with the event channel API to publish events using the Java programming language. It supports publishing events where the data is really a user-defined IDL struct.

Design note on CORBA usage (generally not relevant to ACS NC users): the IDL-struct-data is wrapped by a corba Any, but then pushed on the notification channel inside a "Structured Event" (with the Any object in StructuredEvent::filterable_data[0]). Don't confuse this with Corba's option of sending events directly as Anys. As of 2006-12, HSO is not sure why this complex design was chosen, instead of using structured events without the Any wrapping inside. Possibly it offers some flexibility for generic consumer tools written in languages that have no introspection.

(HSO): figure out if the CORBA impl is thread safe. Fix this class accordingly, or document that it is not thread safe otherwise.

Author:: dfugate

Constructor & Destructor Documentation

alma::acs::nc::SimpleSupplier::SimpleSupplier	(	String	cName,
		ContainerServicesBase	services
	)			throws AcsJException `[inline]`

Creates a new instance of SimpleSupplier. Make sure you call disconnect() when you no longer need this event supplier object.

Parameters:

	cName	name of the notification channel events will be published to.
	services	This is used to get the name of the component and to access the ACS logging system.

Exceptions:

AcsJException

There are literally dozens of CORBA exceptions that could be thrown by the SimpleSupplier class. Instead, these are converted into an ACS Error System exception for the developer's convenience.

alma::acs::nc::SimpleSupplier::SimpleSupplier	(	String	cName,
		ContainerServicesBase	services,
		EventProcessingCallback<?extends IDLEntity >	evProcCallback
	)			throws AcsJException `[inline]`

Creates a new instance of SimpleSupplier. Make sure you call disconnect() when you no longer need this event supplier object.

Parameters:

	cName	name of the notification channel events will be published to.
	services	This is used to get the name of the component and to access the ACS logging system.
	evProcCallback	Callback that handles the events' fate

Exceptions:

AcsJException

There are literally dozens of CORBA exceptions that could be thrown by the SimpleSupplier class. Instead, these are converted into an ACS Error System exception for the developer's convenience.

alma::acs::nc::SimpleSupplier::SimpleSupplier	(	String	cName,
		String	channelNotifyServiceDomainName,
		ContainerServicesBase	services
	)			throws AcsJException `[inline]`

Creates a new instance of SimpleSupplier. Make sure you call disconnect() when you no longer need this event supplier object.

Parameters:

	cName	name of the notification channel events will be published to.
	channelNotifyServiceDomainName	Channel domain name, which is being used to determine notification service.
	services	This is used to get the name of the component and to access the ACS logging system.

Exceptions:

AcsJException

There are literally dozens of CORBA exceptions that could be thrown by the SimpleSupplier class. Instead, these are converted into an ACS Error System exception for the developer's convenience.

alma::acs::nc::SimpleSupplier::SimpleSupplier	(	String	cName,
		String	channelNotifyServiceDomainName,
		ContainerServicesBase	services,
		EventProcessingCallback<?extends IDLEntity >	evProcCallback
	)			throws AcsJException `[inline]`

Creates a new instance of SimpleSupplier. Make sure you call disconnect() when you no longer need this event supplier object.

Parameters:

	cName	name of the notification channel events will be published to.
	channelNotifyServiceDomainName	Channel domain name, which is being used to determine notification service.
	services	This is used to get the name of the component and to access the ACS logging system.
	evProcCallback	Callback that handles the events' fate

Exceptions:

AcsJException

There are literally dozens of CORBA exceptions that could be thrown by the SimpleSupplier class. Instead, these are converted into an ACS Error System exception for the developer's convenience.

References alma::acs::container::ContainerServicesBase::activateOffShoot(), cp_ih, eventBuff, eventProcCallback, getChannelKind(), alma::acs::nc::Helper::getChannelProperties(), alma::acs::nc::Helper::getNotificationChannel(), getNotificationFactoryName(), alma::acs::nc::Helper::getNotifyFactory(), ih, alma::acs::nc::AcsNcReconnectionCallback::init(), alma::acs::nc::ChannelProperties::isTraceEventsEnabled(), isTraceEventsEnabled, m_anyAide, m_channel, m_channelName, m_channelNotifyServiceDomainName, m_helper, m_logger, m_proxyConsumer, m_services, m_supplierAdmin, and reconnectCallback.

Member Function Documentation

void alma::acs::nc::SimpleSupplier::destroyNotificationChannel ( ) throws AcsJException [inline, protected]

Destroys the notification channel, which may be in use by other suppliers or receivers. This feature is luckily not used as of ALMA-5_0_1_9 (2007-12). We must first investigate when/how we can know that it is safe to destroy a channel object.

References alma::acs::nc::Helper::destroyNotificationChannel(), getChannelKind(), m_channel, m_channelName, and m_helper.

Referenced by alma::acs::nc::CorbaNotificationChannel::deactivate().

void alma::acs::nc::SimpleSupplier::disconnect ( ) [inline]

User code must call this method when the Supplier is no longer useful. Failure to do so can result in remote memory leaks. User should not call this method multiple times either. Once disconnect has been called, all of SimpleSupplier's methods will cease to function properly.

References alma::acs::container::ContainerServicesBase::deactivateOffShoot(), alma::acs::nc::AcsNcReconnectionCallback::disconnect(), m_channelName, m_logger, m_proxyConsumer, m_services, m_supplierAdmin, and reconnectCallback.

Referenced by alma::nctest::EventSupplierSpr2005067Impl::EventSupplierSpr2005067Impl::cleanUp(), alma::demo::EventSupplierImpl::EventSupplierImpl::cleanUp(), alma::COUNTER::CounterSupplierImpl::CounterSupplierImpl::cleanUp(), com::cosylab::acs::jms::ACSJMSTopicPublisher::PublisherPoolItem::close(), alma::acs::nc::CorbaNotificationChannel::deactivate(), alma::COUNTER::CounterSupplierImpl::CounterSupplierImpl::initialize(), alma::ACSCOURSE_MOUNT::MountSupplier::main(), alma::COUNTER::CounterSupplierImpl::CounterSupplierImpl::sendBlocks(), and alma::demo::test::client::ArchiveSupplierTest::tearDown().

void alma::acs::nc::SimpleSupplier::disconnect_structured_push_supplier ( ) [inline]

Override this method to do something when a consumer unsubscribes from the channel. Do not call it from your code!

(HSO): The CORBA NC spec (3.3.10.1) says: The disconnect_structured_push_supplier operation is invoked to terminate a connection between the target StructuredPushSupplier and its associated consumer. This operation takes no input parameters and returns no values. The result of this operation is that the target StructuredPushSupplier will release all resources it had allocated to support the connection, and dispose its own object reference. Is it really true what the log message says, that one of many consumers has disconnected, and we should continue for our other consumers? It may be so, given that the life cycle of a SimpleSupplier seemss unaffected of consumers in the ACS NC design.

References m_channelName, and m_logger.

Referenced by alma::nctest::EventSupplierSpr2005067Impl::EventSupplierSpr2005067Impl::cleanUp().

String alma::acs::nc::SimpleSupplier::getChannelDomain ( ) [inline, 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

Reimplemented in alma::acs::nc::ArchiveSupplier.

Referenced by getCORBAEvent().

String alma::acs::nc::SimpleSupplier::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

Reimplemented in alma::acs::nc::ArchiveSupplier.

Referenced by destroyNotificationChannel(), and SimpleSupplier().

String alma::acs::nc::SimpleSupplier::getChannelName ( ) [inline]

Returns the name of the channel.

Reimplemented in alma::acs::nc::CorbaPublisher.

References m_channelName.

Referenced by com::cosylab::acs::jms::ACSJMSTopicPublisher::PublisherPoolItem::sendMessage().

StructuredEvent alma::acs::nc::SimpleSupplier::getCORBAEvent	(	String	typeName,
		String	eventName
	)			`[inline, protected]`

Method used to create a pre-filled CORBA event.

Parameters:

	typeName	The structured event's type_name.
	eventName	Name of the event.

Returns:: A pre-filled CORBA event.

References getChannelDomain().

Referenced by publishEvent(), and alma::acs::nc::ArchiveSupplier::publishEvent().

EventChannel alma::acs::nc::SimpleSupplier::getNotificationChannel ( ) [inline, protected]

Gets a reference to the event channel specified during construction.

Returns:: Reference to the event channel.

References m_channel.

String alma::acs::nc::SimpleSupplier::getNotificationFactoryName ( ) [inline, protected]

This method returns a 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 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::ArchiveSupplier.

References alma::acs::nc::Helper::getNotificationFactoryNameForChannel(), m_channelName, m_channelNotifyServiceDomainName, and m_helper.

Referenced by SimpleSupplier().

protected<T extends IDLEntity> void alma::acs::nc::SimpleSupplier::publishCORBAEvent	(	StructuredEvent	se,
		T	event
	)			throws AcsJException `[inline, package]`

Method which publishes an entire CORBA StructuredEvent without making any modifications to it.

Parameters:

se

A complete structured event

Exceptions:

AcsJException

if the event cannot be published for some reason or another.

References eventBuff, eventProcCallback, m_channelName, m_proxyConsumer, alma::acs::nc::CircularQueue::pop(), alma::acs::nc::CircularQueue::push(), alma::ACSErrTypeCommon::wrappers::AcsJCORBAProblemEx::setInfo(), and alma::ACSErrTypeCommon::wrappers::AcsJCORBAProblemEx::setMinor().

Referenced by publishEvent(), and alma::acs::nc::ArchiveSupplier::publishEvent().

void alma::acs::nc::SimpleSupplier::publishEvent ( IDLEntity customStruct ) throws AcsJException [inline]

Takes a generic Java object and tries to pack it into a CORBA Any and publish it to the event channel. This will fail if the parameter is not CORBA-generated from a user-defined IDL struct. In simple terms, trying to publish native Java types is impossible because they have no CORBA mapping to say Python or C++ types.

Parameters:

customStruct

An instance of the IDL struct (Java class) to be published.

Exceptions:

AcsJException

There are an enormous amount of possibilities pertaining to why an AcsJException would be thrown by publishEvent.

References alma::acs::nc::AnyAide::complexObjectToCorbaAny(), alma::acs::container::ContainerServicesBase::getAdvancedContainerServices(), alma::acs::container::AdvancedContainerServices::getAny(), getCORBAEvent(), alma::acs::container::ContainerServicesBase::getName(), isTraceEventsEnabled, m_anyAide, m_channelName, m_count, m_logger, m_services, and publishCORBAEvent().

Referenced by alma::demo::EventSupplierImpl::EventSupplierImpl::EventProcessingCallbackImpl::eventDropped(), alma::ACSCOURSE_MOUNT::MountSupplier::main(), alma::acs::nc::CorbaNotificationChannel::publish(), alma::COUNTER::CounterSupplierImpl::CounterSupplierImpl::sendBlocks(), alma::nctest::EventSupplierSpr2005067Impl::EventSupplierSpr2005067Impl::sendEvents(), alma::demo::test::EventSupplierImpl::EventSupplierImpl::sendEvents(), alma::demo::test::EventILSupplierImpl::EventSupplierImpl::sendEvents(), alma::demo::EventSupplierImpl::EventSupplierImpl::sendEvents(), alma::acs::eventbrowser::model::EventSupplierImpl::sendEvents(), alma::demo::test::EventSupplierCDBChannel::EventSupplierCDBChannel::sendEvents(), alma::demo::EventSupplierImpl::EventSupplierImpl::sendEventsSpecial(), com::cosylab::acs::jms::ACSJMSTopicPublisher::PublisherPoolItem::sendMessage(), and alma::nctest::clients::ClosedLoopEventTest::testStructWithTypedef().

void alma::acs::nc::SimpleSupplier::reconnect ( gov.sandia.NotifyMonitoringExt.EventChannelFactory ecf ) [inline]

References alma::acs::nc::Helper::getChannelProperties(), alma::acs::nc::Helper::getNotificationChannel(), m_channel, m_channelName, m_helper, and m_logger.

void alma::acs::nc::SimpleSupplier::subscription_change	(	EventType[]	eventType,
		EventType[]	eventType1
	)			throws InvalidEventType `[inline]`

This method gets called by the CORBA framework to notify us that the subscriber situation has changed. By default we ignore this information. See 2.6.3 of Notification Service, v1.1

Override this method so your "smart" Supplier subclass can publish (or not publish) events based on Consumer demands. Not very useful when there are more than one Supplier instances for a given channel. TODO (HSO): not clear what this comment means. Why should not multiple suppliers adjust the events they publish to what the consumers want? Maybe the concern was meant for multiple consumers that have different needs? See also method obtain_subscription_types.

This method becomes extremely useful if we could assume there is only one supplier per channel. That is, the API could intelligently publish events to a given domain/type only when there are consumers subscribed. However, there are problems when there are multiple supplier instances for a channel.

Do not call it from your code!

Parameters:

	eventType	Added subscription array.
	eventType1	Removed subscription array.

Exceptions:

InvalidEventType

Throw this exception when a consumer subscribes (or unsubscribes) to a domain/type that does not exist.

Referenced by alma::demo::test::EventSupplierImpl::EventSupplierImpl::sendEvents(), alma::demo::test::EventILSupplierImpl::EventSupplierImpl::sendEvents(), alma::acs::eventbrowser::model::EventSupplierImpl::sendEvents(), and alma::demo::test::EventSupplierCDBChannel::EventSupplierCDBChannel::sendEvents().

Member Data Documentation

IntHolder alma::acs::nc::SimpleSupplier::cp_ih [private]

Referenced by SimpleSupplier().

CircularQueue alma::acs::nc::SimpleSupplier::eventBuff [private]

Referenced by publishCORBAEvent(), and SimpleSupplier().

EventProcessingCallback alma::acs::nc::SimpleSupplier::eventProcCallback [protected]

Referenced by publishCORBAEvent(), and SimpleSupplier().

IntHolder alma::acs::nc::SimpleSupplier::ih [private]

Referenced by SimpleSupplier().

final boolean alma::acs::nc::SimpleSupplier::isTraceEventsEnabled [private]

Whether sending of events should be logged

Referenced by publishEvent(), and SimpleSupplier().

final AnyAide alma::acs::nc::SimpleSupplier::m_anyAide [protected]

Helper class used to manipulate CORBA anys

Referenced by publishEvent(), alma::acs::nc::ArchiveSupplier::publishEvent(), and SimpleSupplier().

EventChannel alma::acs::nc::SimpleSupplier::m_channel [protected]

Channel we'll be sending events to

Referenced by destroyNotificationChannel(), getNotificationChannel(), reconnect(), and SimpleSupplier().

final String alma::acs::nc::SimpleSupplier::m_channelName [protected]

The event channel has exactly one name registered in the naming service.

Referenced by destroyNotificationChannel(), disconnect(), disconnect_structured_push_supplier(), getChannelName(), alma::acs::nc::CorbaPublisher::getChannelName(), getNotificationFactoryName(), publishCORBAEvent(), publishEvent(), reconnect(), and SimpleSupplier().

final String alma::acs::nc::SimpleSupplier::m_channelNotifyServiceDomainName [protected]

The channel notification service domain name, can be null.

Referenced by getNotificationFactoryName(), and SimpleSupplier().

volatile long alma::acs::nc::SimpleSupplier::m_count = 0 [protected]

The total number of successful events published by this particular supplier. The current count is attached to the EventDescription that gets sent along as additional data (remainder_of_body).

Referenced by publishEvent().

final Helper alma::acs::nc::SimpleSupplier::m_helper [protected]

Provides channel properties.

Referenced by destroyNotificationChannel(), getNotificationFactoryName(), reconnect(), and SimpleSupplier().

final Logger alma::acs::nc::SimpleSupplier::m_logger [protected]

Standard logger

Referenced by disconnect(), disconnect_structured_push_supplier(), publishEvent(), reconnect(), and SimpleSupplier().