alma.acs.nc

Class Helper

java.lang.Object

alma.acs.nc.Helper

public class Helper
extends java.lang.Object

This class provides methods useful to both supplier and consumer objects, where it is associated with exactly one Notification Channel. It can also be used without any notification channel. Never use a Helper instance for more than once NC!

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	channelName A Helper instance serves only one NC.
protected java.util.Date	channelTimestamp Creation time of the channel to be used in order to know the restart of the Notify Service
protected java.lang.String	domainName The optional NC domain name, e.g.
protected java.util.logging.Logger	m_logger
protected static java.util.Random	random Random number generator, used to randomize client names when used as server-side proxy names.

Constructor Summary

Constructors

Constructor and Description
Helper(java.lang.String channelName, ContainerServicesBase services, org.omg.CosNaming.NamingContext namingService) Same as Helper(String, String, ContainerServicesBase, NamingContext) but without the NC domain; the default NC domain (NAMESERVICE_BINDING_NC_DOMAIN_DEFAULT.value) will be used.
Helper(java.lang.String channelName, java.lang.String domainName, ContainerServicesBase services, org.omg.CosNaming.NamingContext namingService) Creates a new instance of Helper.

Method Summary

Modifier and Type	Method and Description
static java.lang.String	combineChannelAndDomainName(java.lang.String channelName, java.lang.String domainName)
protected EventChannel	createNotificationChannel(java.lang.String channelKind, java.lang.String notifyFactoryName) Tries to create a notification channel (using quality of service and administrative properties specified by configQofS() and configAdminProps() respectively).
protected EventChannel	createNotifyChannel_internal(Property[] initial_qos, Property[] initial_admin, org.omg.CORBA.IntHolder channelIdHolder) Broken out from #createNotificationChannel(String, String, String) to give tests better control about the timing when this call to the event factory is made.
static java.lang.String	createRandomizedClientName(java.lang.String clientName) Appends a random number to the given client name and replaces '/' in the name with '_'.
java.lang.String	createUnsupportedAdminLogMessage(UnsupportedAdmin ex) Corba spec: If the implementation of the target object is not capable of supporting any of the requested administrative property settings, the UnsupportedAdmin exception is raised.
protected void	destroyNotificationChannel(java.lang.String channelKind, org.omg.CosNotifyChannelAdmin.EventChannel channelRef) Destroys the channel and unregisters it from the naming service.
static java.lang.String	extractChannelName(java.lang.String channelWithDomainName)
static java.lang.String	extractDomainName(java.lang.String channelWithDomainName)
ChannelProperties	getChannelProperties() Provides access to the information about the channel contained within the ACS CDB
java.util.Date	getChannelTimestamp() Returns the current channel's timestamp registered in the Naming Service.
ContainerServicesBase	getContainerServices() Returns a reference to the Container Services which are provided by a container or client.
java.util.HashMap<java.lang.String,java.lang.Double>	getEventHandlerTimeoutMap() The following returns a map where each key is the name of an event and the value is the maximum amount of time (in floating point seconds) an event receiver has to process the event before a warning message is logged.
java.util.Date	getLastRegisteredChannelTimestamp() Returns the last timestamp retrieved from the Naming Service
org.omg.CosNaming.NamingContext	getNamingService() Returns a reference to the Naming Service.
static org.omg.CosNaming.NamingContext	getNamingServiceInitial(ContainerServicesBase cs) Deprecated. To be removed once we have fixed the leftover usages in modules jcontnc, laser-core, acssamp, acssampGUI.
EventChannel	getNotificationChannel(EventChannelFactory ecf) The TAO extension's reconnect() methods call this (via NCSubscriber etc), so that we call again org.omg.CosNotifyChannelAdmin.EventChannelFactoryOperations#get_event_channel(int).
protected EventChannel	getNotificationChannel(java.lang.String notifyFactoryName) This method gets a reference to the event channel.
java.lang.String	getNotificationFactoryNameForChannel() Gets the notification channel factory name for the given channel/domain of this Helper class.
EventChannelFactory	getNotifyFactory()
void	initChannelTimestamp() Initialize the channel timestamp attribute by retrieving its value from the Naming Service.
protected void	initializeNotifyFactory(java.lang.String notifyFactoryName)
protected boolean	setChannelTimestamp(EventChannel eventChannel)
void	setLastRegisteredChannelTimestamp(java.util.Date timestamp) Set the last channel timestamp

Methods inherited from class java.lang.Object

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

Field Detail

m_logger

protected final java.util.logging.Logger m_logger

channelName

protected final java.lang.String channelName

A Helper instance serves only one NC.

domainName

protected final java.lang.String domainName

The optional NC domain name, e.g. "ALARMSYSTEM".

channelTimestamp

protected java.util.Date channelTimestamp

Creation time of the channel to be used in order to know the restart of the Notify Service

random

protected static final java.util.Random random

Random number generator, used to randomize client names when used as server-side proxy names. This class is static and thus shared among the subscribers and suppliers of one client or component, to reduce the risk that two subscribers or suppliers create Helper instances at the same time (system time is used as random generator seed) and thereby produce identical sequences of random numbers, which would defy the purpose of avoiding name clashes on the server.

Constructor Detail

Helper

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

Same as Helper(String, String, ContainerServicesBase, NamingContext) but without the NC domain; the default NC domain (NAMESERVICE_BINDING_NC_DOMAIN_DEFAULT.value) will be used.

Parameters:

channelName -

services -

namingService -

Throws:

AcsJException

Helper

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

Creates a new instance of Helper.

Parameters:

channelName - The NC that this Helper is made for.

domainName - The optional NC domain, or null.

services - A reference to the ContainerServices

namingService - Reference to the naming service.

Throws:

AcsJException - Generic ACS exception will be thrown if anything in this class is broken.

Method Detail

extractChannelName

public static java.lang.String extractChannelName(java.lang.String channelWithDomainName)
                                           throws AcsJIllegalArgumentEx

Throws:

AcsJIllegalArgumentEx

extractDomainName

public static java.lang.String extractDomainName(java.lang.String channelWithDomainName)
                                          throws AcsJIllegalArgumentEx

Throws:

AcsJIllegalArgumentEx

combineChannelAndDomainName

public static java.lang.String combineChannelAndDomainName(java.lang.String channelName,
                                                           java.lang.String domainName)

getContainerServices

public ContainerServicesBase getContainerServices()

Returns a reference to the Container Services which are provided by a container or client.

Returns:

A valid reference to the ContainerServices instance.

getNamingServiceInitial

public static org.omg.CosNaming.NamingContext getNamingServiceInitial(ContainerServicesBase cs)
                                                               throws AcsJException

Deprecated. To be removed once we have fixed the leftover usages in modules jcontnc, laser-core, acssamp, acssampGUI.

This method should only be used by specialized framework code, not by application code that uses NCs. It retrieves and returns a reference to the Naming Service based on the Java property ORBInitRef.NameService.

Even specialized code that has an AcsManagerProxy instance available, e.g. via an AdvancedComponentClient, should use the AcsManagerProxy to get the NamingContext reference:

 nctx = NamingContextHelper.narrow(AdvancedComponentClient.getAcsManagerProxy().get_service("NameService", false);
 

.

Returns:

Valid reference to the Naming Service.

Throws:

AcsJException - Thrown when there's a bad corbaloc given for the Naming Service or the reference cannot be narrowed.

See Also:

getNamingService()

getNamingService

public org.omg.CosNaming.NamingContext getNamingService()

Returns a reference to the Naming Service.

Returns:

Valid reference to the Naming Service.

getNotificationChannel

public EventChannel getNotificationChannel(EventChannelFactory ecf)

The TAO extension's reconnect() methods call this (via NCSubscriber etc), so that we call again org.omg.CosNotifyChannelAdmin.EventChannelFactoryOperations#get_event_channel(int).

getNotificationChannel

protected EventChannel getNotificationChannel(java.lang.String notifyFactoryName)
                                       throws AcsJException

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

Parameters:

channelKind - Kind of the channel as registered with the CORBA naming service ("channels").

notifyFactoryName - Name of the notification service as registered with the CORBA naming service.

Returns:

Reference to the event channel specified by channelName. Never null.

Throws:

AcsJException - Standard ACS Java exception.

initializeNotifyFactory

protected void initializeNotifyFactory(java.lang.String notifyFactoryName)
                                throws AcsJException

Parameters:

notifyFactoryName -

Throws:

AcsJException - AcsJCORBAProblemEx if the NotifyService reference cannot be retrieved from the NamingService; AcsJNarrowFailedEx if the NotifyService is not of the required TAO extension type.

createNotificationChannel

protected EventChannel createNotificationChannel(java.lang.String channelKind,
                                                 java.lang.String notifyFactoryName)
                                          throws AcsJException,
                                                 NameAlreadyUsed

Tries to create a notification channel (using quality of service and administrative properties specified by configQofS() and configAdminProps() respectively). If this succeeds, then registers this channel with the naming service.

Should only be invoked when the channel that this supplier or consumer is attempting to connect to does not exist. However even with prior check for the existence of this channel, a race condition with other suppliers or consumers can lead to multiple attempts to create the same channel, which will result in NameAlreadyUsed exception.

Design note: Currently the TAO notification extensions are used to synch channel creation with other clients by supplying the channel name to the factory. If we want to use only standard NC factories then we'd have to implement our own locking mechanisms in all ACS consumer and supplier classes, see http://jira.alma.cl/browse/COMP-2808

Parameters:

channelKind - Kind of the channel as registered with the CORBA naming service.

notifyFactoryName - Name of the notification service as registered with the CORBA naming service.

Returns:

Reference to the newly created channel.

Throws:

AcsJException - Standard ACS Java exception.

NameAlreadyUsed - thrown if the channel of this name already exists.

setChannelTimestamp

protected boolean setChannelTimestamp(EventChannel eventChannel)

getChannelTimestamp

public java.util.Date getChannelTimestamp()

Returns the current channel's timestamp registered in the Naming Service.

initChannelTimestamp

public void initChannelTimestamp()

Initialize the channel timestamp attribute by retrieving its value from the Naming Service. If after 10 attempts the timestamp cannot be retrieved then it's set to the current time.

getLastRegisteredChannelTimestamp

public java.util.Date getLastRegisteredChannelTimestamp()

Returns the last timestamp retrieved from the Naming Service

setLastRegisteredChannelTimestamp

public void setLastRegisteredChannelTimestamp(java.util.Date timestamp)

Set the last channel timestamp

createNotifyChannel_internal

protected EventChannel createNotifyChannel_internal(Property[] initial_qos,
                                                    Property[] initial_admin,
                                                    org.omg.CORBA.IntHolder channelIdHolder)
                                             throws NameAlreadyUsed,
                                                    UnsupportedQoS,
                                                    AcsJNarrowFailedEx,
                                                    AcsJCORBAProblemEx

Broken out from #createNotificationChannel(String, String, String) to give tests better control about the timing when this call to the event factory is made.

Throws:

NameAlreadyUsed - if the call to NotifyFactory#create_named_channel fails with this exception.

AcsJCORBAProblemEx - if the TAO extension throws a NameMapError or if the QoS attributes cause a UnsupportedAdmin.

UnsupportedQoS

AcsJNarrowFailedEx

destroyNotificationChannel

protected void destroyNotificationChannel(java.lang.String channelKind,
                                          org.omg.CosNotifyChannelAdmin.EventChannel channelRef)
                                   throws AcsJException

Destroys the channel and unregisters it from the naming service. ONLY USE THIS METHOD IF YOU KNOW FOR CERTAIN THERE IS ONLY ONE SUPPLIER FOR THE CHANNEL!!! Use this method with extreme caution as it's likely to become deprecated in future versions of ACS!

Parameters:

channelName - name of the channel as registered int the CORBA notification service

channelKind - Kind of the channel as registered with the CORBA naming service.

channelRef - reference to the channel being destroyed. Here we use the plain OMG type instead of the TAO extension subtype, because the extensions are not used for channel destruction.

Throws:

AcsJException - Thrown when the channel isn't registered with the Naming Service.

getChannelProperties

public ChannelProperties getChannelProperties()

Provides access to the information about the channel contained within the ACS CDB

Returns:

This class's channel properties member.

getNotificationFactoryNameForChannel

public java.lang.String getNotificationFactoryNameForChannel()

Gets the notification channel factory name for the given channel/domain of this Helper class.

Details:

• First tries to use the factory name cached from a previous call.
• NC domain ARCHIVING (ArchivingChannel) is mapped to ArchiveNotifyEventChannelFactory.
• NC domain LOGGING (LoggingChannel) is mapped to LoggingNotifyEventChannelFactory.
• If the CDB contains MACI/Channels/NotificationServiceMapping data, we try to find a matching notify service first based on NC name, then on NC domain, then default.
• If no factory has been found, we use NotifyEventChannelFactory.
• Otherwise if the factory name found does not end in NotifyEventChannelFactory, we append NotifyEventChannelFactory.

Returns:

notification channel factory name.

getEventHandlerTimeoutMap

public java.util.HashMap<java.lang.String,java.lang.Double> getEventHandlerTimeoutMap()

The following returns a map where each key is the name of an event and the value is the maximum amount of time (in floating point seconds) an event receiver has to process the event before a warning message is logged.

Parameters:

channelName - name of the channel

Returns:

HashMap described above

getNotifyFactory

public EventChannelFactory getNotifyFactory()

createUnsupportedAdminLogMessage

public java.lang.String createUnsupportedAdminLogMessage(UnsupportedAdmin ex)

Corba spec: If the implementation of the target object is not capable of supporting any of the requested administrative property settings, the UnsupportedAdmin exception is raised. This exception has associated with it a list of name-value pairs of which each name identifies an administrative property whose requested setting could not be satisfied, and each associated value the closest setting for that property that could be satisfied.

Parameters:

ex -

Returns:

a String that contains the information from UnsupportedAdmin

createRandomizedClientName

public static java.lang.String createRandomizedClientName(java.lang.String clientName)

Appends a random number to the given client name and replaces '/' in the name with '_'.

This is used when setting names on NC proxy objects via the TAO extension API. It reduces the risk of creating a new object with an existing name, because TAO has a memory bug and will not delete the badly named object even if it throws the correct NameAlreadyUsed exception. Replacing of slashes is done so that clients of the TAO MC extension API can suppress uninteresting parts of the pathname without mutilating the client name itself, see http://ictjira.alma.cl/browse/ICT-3551.

This method is synchronized just to overcome residual doubts about the thread safety of random#nextInt.

Parameters:

clientName -

Returns:

"clientName-randomNumber"

See Also:

random