alma.acs.nc

Class NCPublisher<T>

java.lang.Object

OSPushSupplierPOA

alma.acs.nc.NCPublisher<T>

Type Parameters:

T - The event (base) type. If all events published by an instance of this class are of the same type, e.g., MyEventStructFromIDL, then that type should be used; otherwise the common base type IDLEntity should be used.
Note that we currently cannot use the restriction T extends IDLEntity because of ArchiveSupplier which extends NCPublisher<Object>.

All Implemented Interfaces:

AcsEventPublisher<T>, ReconnectableParticipant

Direct Known Subclasses:

ArchiveSupplier

public class NCPublisher<T>
extends OSPushSupplierPOA
implements AcsEventPublisher<T>, ReconnectableParticipant

NCPublisher is the Notificaction Channel implementation to be used with the event channel API to publish events using the Java programming language. It has been created out of the old SimpleSupplier class, to integrate its functionality into the ContainerServices and and to allow using transport mechanisms other than Corba NC under the hood.

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.

Note about refactoring: NCPublisher gets instantiated in module jcont using java reflection. Thus if you change the package, name, or constructor of this class, make sure to fix ContainerServicesImpl.CLASSNAME_NC_PUBLISHER or its use to get the constructor.

Author:

jslopez, hsommer

Nested Class Summary

Nested classes/interfaces inherited from interface alma.acs.nc.AcsEventPublisher

AcsEventPublisher.EventProcessingHandler<U>

Field Summary

Fields

Modifier and Type	Field and Description
protected alma.acs.nc.AnyAide	anyAide Helper class used to manipulate CORBA anys
protected EventChannel	channel Channel we'll be sending events to.
protected java.lang.String	channelName The event channel has exactly one name registered in the naming service.
protected java.lang.String	channelNotifyServiceDomainName The channel notification service domain name, can be null.
protected java.util.concurrent.atomic.AtomicLong	count The total number of successful events published by this particular supplier.
protected AcsEventPublisher.EventProcessingHandler<T>	eventProcessingHandler Optional event processing handler.
protected CircularQueue<T>	eventQueue If the user registers eventProcessingHandler, then we also create this queue; otherwise it remains null.
protected java.lang.Object	eventQueueSync Monitor for access to eventQueue and eventProcessingHandler.
protected Helper	helper Provides code shared among suppliers and consumers.
protected java.util.logging.Logger	logger Provides access to the ACS logging system.
protected StructuredProxyPushConsumer	proxyConsumer The server-side proxy consumer object used by this supplier to push events onto the channel.
protected AcsNcReconnectionCallback	reconnectCallback
protected ContainerServicesBase	services To access the ORB among other things
protected SupplierAdmin	supplierAdmin Supplier Admin object is responsible for creating & managing proxy consumers.

Constructor Summary

Constructors

Constructor and Description
NCPublisher(java.lang.String channelName, ContainerServicesBase services, org.omg.CosNaming.NamingContext namingService) Creates a new instance of NCPublisher.
NCPublisher(java.lang.String channelName, java.lang.String channelNotifyServiceDomainName, ContainerServicesBase services, org.omg.CosNaming.NamingContext namingService) Creates a new instance of NCPublisher.

Method Summary

Modifier and Type	Method and Description
void	disconnect_structured_push_supplier() 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.
void	disconnect() User code must call this method when the Supplier is no longer useful.
void	enableEventQueue(int queueSize, AcsEventPublisher.EventProcessingHandler<T> handler) Enables using a queue for published events.
protected StructuredEvent	getCORBAEvent(java.lang.String typeName, java.lang.String eventName) Method used to create a pre-filled CORBA event.
int	getEventBufferSize()
protected java.lang.String	getNotificationFactoryName() This method returns the notify service name as registered with the CORBA Naming Service.
boolean	increaseEventBufferSize(int bufferSize) Increase the event buffer size
protected void	init(org.omg.CosNaming.NamingContext namingService) Initializes NCPublisher
protected void	publishCORBAEvent(StructuredEvent se, T customData) Method which publishes an entire CORBA StructuredEvent without making any modifications to it.
void	publishEvent(T customStruct) Takes the given Java object and tries to pack it into a CORBA Any and publish it to the notification channel.
protected void	queueUnpublishedEvent(StructuredEvent se, T customData) Method which queue an event that couldn't be published
void	reconnect(EventChannelFactory ecf)
void	setAutoreconnect(boolean autoreconnect) This method sets the attribute autoreconnect which is used to determine if a reconnection to the channel must be done when the exception OBJECT_NOT_EXIST is thrown during the publication of an event.
void	setEventProcessingHandler(AcsEventPublisher.EventProcessingHandler<T> handler) Sets the event processing handler
void	subscription_change(EventType[] added, EventType[] removed) This method gets called by the CORBA framework to notify us that the subscriber situation has changed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

helper

protected Helper helper

Provides code shared among suppliers and consumers.

channelName

protected final java.lang.String channelName

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

channelNotifyServiceDomainName

protected final java.lang.String channelNotifyServiceDomainName

The channel notification service domain name, can be null.

supplierAdmin

protected SupplierAdmin supplierAdmin

Supplier Admin object is responsible for creating & managing proxy consumers. Unlike in NCSubscriber, we do not (yet) share admin objects on the supplier side, so that each NCPublisher instance is responsible alone for its server-side admin object.

proxyConsumer

protected StructuredProxyPushConsumer proxyConsumer

The server-side proxy consumer object used by this supplier to push events onto the channel.

count

protected final java.util.concurrent.atomic.AtomicLong count

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

channel

protected EventChannel channel

Channel we'll be sending events to. Cannot be final because reconnect() modifies it.

logger

protected final java.util.logging.Logger logger

Provides access to the ACS logging system.

services

protected final ContainerServicesBase services

To access the ORB among other things

anyAide

protected final alma.acs.nc.AnyAide anyAide

Helper class used to manipulate CORBA anys

reconnectCallback

protected AcsNcReconnectionCallback reconnectCallback

eventProcessingHandler

protected AcsEventPublisher.EventProcessingHandler<T> eventProcessingHandler

Optional event processing handler. May be null.

See Also:

#registerEventProcessingCallback(alma.acs.nc.AcsEventPublisher.EventProcessingHandler)

eventQueue

protected CircularQueue<T> eventQueue

If the user registers eventProcessingHandler, then we also create this queue; otherwise it remains null.

The queue stores events during Notify Service failures, to allow re-sending them later. The re-sending is implemented in a rather simple way, without using a separate timer and thread; future attempts to publish other events simply check if the queue contains older events, which then get sent first.

eventQueueSync

protected final java.lang.Object eventQueueSync

Monitor for access to eventQueue and eventProcessingHandler.

We assume that compared to the Corba transport of events the overhead to synchronize threads using this object is negligible, so that we don't bother with fancier synchronization techniques.

Constructor Detail

NCPublisher

public NCPublisher(java.lang.String channelName,
                   ContainerServicesBase services,
                   org.omg.CosNaming.NamingContext namingService)
            throws AcsJException

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

Parameters:

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

Throws:

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

NCPublisher

public NCPublisher(java.lang.String channelName,
                   java.lang.String channelNotifyServiceDomainName,
                   ContainerServicesBase services,
                   org.omg.CosNaming.NamingContext namingService)
            throws AcsJException

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

Parameters:

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

Throws:

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

Method Detail

init

protected void init(org.omg.CosNaming.NamingContext namingService)
             throws AcsJException

Initializes NCPublisher

Parameters:

namingService - Naming service

Throws:

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

disconnect

public void disconnect()
                throws AcsJIllegalStateEventEx

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 NCPublisher's methods will cease to function properly.

Specified by:

disconnect in interface AcsEventPublisher<T>

Throws:

AcsJIllegalStateEventEx - if called when already disconnected.

getNotificationFactoryName

protected java.lang.String getNotificationFactoryName()

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

setAutoreconnect

public void setAutoreconnect(boolean autoreconnect)

This method sets the attribute autoreconnect which is used to determine if a reconnection to the channel must be done when the exception OBJECT_NOT_EXIST is thrown during the publication of an event.

Parameters:

autoreconnect - Whether autoreconneting to the channel should be done

subscription_change

public void subscription_change(EventType[] added,
                                EventType[] removed)
                         throws InvalidEventType

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

ACS does not provide an implementation of this method. Probably because of not fully understanding the possibilities of the obtain_subscription_types call (see c'tor above) in the past, we assumed that a supplier could not know whether there is more than one subscriber listening for a given event type on our NC, so that the subscription_change information coming from a single subscriber would not be good enough to make us drop certain event types on the supplier side.

Throws:

InvalidEventType

See Also:

org.omg.CosNotifyComm.NotifySubscribeOperations#subscription_change(org.omg.CosNotification.EventType[], org.omg.CosNotification.EventType[])

disconnect_structured_push_supplier

public void disconnect_structured_push_supplier()

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." In the ACS NC design the life cycle of an NCPublisher is unaffected by that of consumers. Thus we only log a FINE message here.

queueUnpublishedEvent

protected void queueUnpublishedEvent(StructuredEvent se,
                                     T customData)

Method which queue an event that couldn't be published

Parameters:

se - A complete structured event

customData - The user-supplied event data, needed for eventProcessingHandler notification.

publishCORBAEvent

protected void publishCORBAEvent(StructuredEvent se,
                                 T customData)
                          throws AcsJException

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

Parameters:

se - A complete structured event

customData - The user-supplied event data, needed for eventProcessingHandler notification.

Throws:

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

getCORBAEvent

protected StructuredEvent getCORBAEvent(java.lang.String typeName,
                                        java.lang.String eventName)

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.

publishEvent

public void publishEvent(T customStruct)
                  throws AcsJException

Takes the given Java object and tries to pack it into a CORBA Any and publish it to the notification 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.

Specified by:

publishEvent in interface AcsEventPublisher<T>

Parameters:

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

Throws:

AcsJPublishEventFailureEx - If customStruct is not an IDL struct, for which it must be a subclass of IDLEntity.

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

reconnect

public void reconnect(EventChannelFactory ecf)

Specified by:

reconnect in interface ReconnectableParticipant

Parameters:

ecf - The new EventChannelFactory reference as delivered by the NotifyService's callback.

enableEventQueue

public void enableEventQueue(int queueSize,
                             AcsEventPublisher.EventProcessingHandler<T> handler)

Description copied from interface: AcsEventPublisher

Enables using a queue for published events. When using a queue, a handler must be registered so that the user learns about success or failure.

As of ACS 10.1, only a missing NotifyService as diagnosed through a org.omg.CORBA.TRANSIENT exception will cause the publisher to store an event in this queue for later re-sending.

Specified by:

enableEventQueue in interface AcsEventPublisher<T>

Parameters:

queueSize - Number of events that this queue should store. The choice is a tradeoff between memory use and data loss.

handler - The handler that should be notified by the publisher.

increaseEventBufferSize

public boolean increaseEventBufferSize(int bufferSize)

Description copied from interface: AcsEventPublisher

Increase the event buffer size

Specified by:

increaseEventBufferSize in interface AcsEventPublisher<T>

Parameters:

bufferSize - new event buffer size

Returns:

true when the event buffer size has been changed, otherwise return false

getEventBufferSize

public int getEventBufferSize()

Specified by:

getEventBufferSize in interface AcsEventPublisher<T>

Returns:

current event buffer size

setEventProcessingHandler

public void setEventProcessingHandler(AcsEventPublisher.EventProcessingHandler<T> handler)

Description copied from interface: AcsEventPublisher

Sets the event processing handler

Specified by:

setEventProcessingHandler in interface AcsEventPublisher<T>

Parameters:

handler - event processing handler