Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

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

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

Inheritance graph
[legend]
Collaboration diagram for alma::acs::nc::SimpleSupplier:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 SimpleSupplier (String cName, ContainerServicesBase services) throws AcsJException
 SimpleSupplier (String cName, String channelNotifyServiceDomainName, ContainerServicesBase services) 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

Protected Member Functions

void destroyNotificationChannel () throws AcsJException
String getChannelKind ()
String getChannelDomain ()
String getNotificationFactoryName ()
EventChannel getNotificationChannel ()
void publishCORBAEvent (StructuredEvent se) throws AcsJException
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
final EventChannel m_channel
final Logger m_logger
final ContainerServicesBase m_services
final AnyAide m_anyAide

Private Attributes

final boolean isTraceEventsEnabled

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


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.

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.

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.

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.

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.

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

Returns the name of the channel.

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

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.

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

Gets a reference to the event channel specified during construction.

Returns:
Reference to the event 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.

void alma::acs::nc::SimpleSupplier::publishCORBAEvent StructuredEvent  se  )  throws AcsJException [inline, protected]
 

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.

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.

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.


Member Data Documentation

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

Whether sending of events should be logged

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

Helper class used to manipulate CORBA anys

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

Channel we'll be sending events to

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

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

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

The channel notification service domain name, can be null.

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

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

Provides channel properties.

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

Standard logger

StructuredProxyPushConsumer alma::acs::nc::SimpleSupplier::m_proxyConsumer [protected]
 

The proxy consumer object used by supplier to push events onto the channel.

final ContainerServicesBase alma::acs::nc::SimpleSupplier::m_services [protected]
 

To access the ORB among other things

SupplierAdmin alma::acs::nc::SimpleSupplier::m_supplierAdmin [protected]
 

Supplier Admin object is responsible for creating & managing proxy consumers.


The documentation for this class was generated from the following file:
Generated on Thu Apr 30 02:54:30 2009 for ACS Java API by doxygen 1.3.8