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

alma::acs::nc::Consumer Class Reference

Inheritance diagram for alma::acs::nc::Consumer:

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

Collaboration graph
[legend]
List of all members.

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 AcsJException
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 ()

Protected Member Functions

EventChannel getNotificationChannel (String channelName) throws AcsJException
String getChannelKind ()
String getChannelDomain ()
String getNotificationFactoryName ()
void createConsumer () throws AcsJException
EventChannel getNotificationChannel () throws AcsJException
void configSubscriptions ()
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
EventChannel m_channel
final String m_channelName
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 = null
AnyAide m_anyAide = null

Private Attributes

final StopWatch profiler
final boolean isTraceEventsEnabled

Static Private Attributes

final String RECEIVE_METHOD_NAME = "receive"
final long DEFAULT_MAX_PROCESS_TIME = 2000

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

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

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.
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 [inline]
 

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

void alma::acs::nc::Consumer::addSubscription Class<?extends IDLEntity >  structClass,
Object  receiver
throws AcsJException [inline]
 

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.

void alma::acs::nc::Consumer::addSubscription Class<?extends IDLEntity >  structClass  )  throws AcsJException [inline]
 

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

Parameters:
structClass Type of event to subscribe to (i.e., alma.CORR.DataStruct.class).
Exceptions:
AcsJException Thrown if there is some CORBA problem.

void alma::acs::nc::Consumer::configFilters  )  [inline, 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.

void alma::acs::nc::Consumer::configSubscriptions  )  [inline, 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, and alma::acs::nc::LoggingConsumer.

void alma::acs::nc::Consumer::consumerReady  )  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.

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.

void alma::acs::nc::Consumer::createConsumer  )  throws AcsJException [inline, protected]
 

createConsumer handles the CORBA creation of a consumer.

Exceptions:
AcsJException Any CORBA exceptions encountered are converted to an AcsJException for developer's ease of use.

void alma::acs::nc::Consumer::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.

Reimplemented in alma::acs::nc::CorbaReceiver.

void alma::acs::nc::Consumer::disconnect_structured_push_consumer  )  [inline]
 

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

String alma::acs::nc::Consumer::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::ArchiveConsumer, and alma::acs::nc::LoggingConsumer.

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

Returns:
pointer to a constant string.

alma.acs.nc.Helper alma::acs::nc::Consumer::getHelper  )  [inline]
 

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

Returns:
A valid reference to this instances helper.

EventChannel alma::acs::nc::Consumer::getNotificationChannel  )  throws AcsJException [inline, protected]
 

Gets a reference to the event channel specified during construction.

Returns:
Valid reference to the event channel.
Exceptions:
AcsJException Thrown if the reference is null.

EventChannel alma::acs::nc::Consumer::getNotificationChannel String  channelName  )  throws AcsJException [inline, protected]
 

This method gets a reference to the event channel. If it is not already registered with the naming service, it is created.

Returns:
Reference to the event channel specified by channelName.
Parameters:
channelName Name of the event channel registered with the CORBA Naming Service
Exceptions:
AcsJException Standard ACS Java exception.

String alma::acs::nc::Consumer::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::ArchiveConsumer, and alma::acs::nc::LoggingConsumer.

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

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  )  [inline, 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.

Reimplemented in alma::nctest::clients::FridgeConsumer.

void alma::acs::nc::Consumer::processEvent IDLEntity  corbaData,
EventDescription  eventDescrip
[inline, 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.

void alma::acs::nc::Consumer::push_structured_event StructuredEvent  structuredEvent  )  throws org.omg.CosEventComm.Disconnected [inline]
 

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 alma::acssampGUI::acssampGUIConsumer, cl::utfsm::samplingSystemUI::core::NotificationChannelSuscription, alma::acs::nc::ArchiveConsumer, alma::acs::nc::CorbaReceiver, and alma::acs::nc::LoggingConsumer.

boolean alma::acs::nc::Consumer::removeFilter int  filter  )  throws AcsJException [inline]
 

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

void alma::acs::nc::Consumer::removeSubscription Class  structClass  )  throws AcsJException [inline]
 

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

void alma::acs::nc::Consumer::resume  )  [inline]
 

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.

void alma::acs::nc::Consumer::suspend  )  [inline]
 

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>


Member Data Documentation

final long alma::acs::nc::Consumer::DEFAULT_MAX_PROCESS_TIME = 2000 [static, private]
 

The default maximum amount of time an event handler is given to process event before an exception is logged. this is used when an enduser does *not* define the appropriate XML elements within the ACS CDB. see the inline doc on EventChannel.xsd for more info

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

Whether sending of events should be logged

AnyAide alma::acs::nc::Consumer::m_anyAide = null [protected]
 

Helper class used to manipulate CORBA anys

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

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

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

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.

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

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

OSPushConsumer alma::acs::nc::Consumer::m_corbaRef = null [protected]
 

CORBA reference to ourself

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

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

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.

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

Provides access to the naming service among other things.

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

Provides access to the ACS logging system.

StructuredProxyPushSupplier alma::acs::nc::Consumer::m_proxySupplier [protected]
 

The supplier proxy we are connected to.

final StopWatch alma::acs::nc::Consumer::profiler [private]
 

final String alma::acs::nc::Consumer::RECEIVE_METHOD_NAME = "receive" [static, private]
 


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