alma.acs.container

Interface ContainerServicesBase

All Known Subinterfaces:

ContainerServices

All Known Implementing Classes:

AlarmSystemContainerServices, ContainerServicesImpl, ContainerServicesProxy, DummyContainerServices, DummyContainerServicesBase, ManagerContainerServices

public interface ContainerServicesBase

Through this interface, the container offers services to its hosted components. The component must call these methods explicitly; in this respect, ContainerServices is different from the other services that the container provides without the component implementation knowing about it. It can be thought of as a callback handle or a library.

Currently, methods are added to this interface as the functionality becomes available. At some point we will have to declutter the interface by introducing 2nd-level interfaces that harbor cohesive functionality. For example, instead of calling myContainerServices.getComponent(...), the new call will then be something like myContainerServices.communication().getComponent(...).

created on Oct 24, 2002 12:56:36 PM

Author:

hsommer

Method Summary

Modifier and Type	Method and Description
<T extends org.omg.PortableServer.Servant & OffShootOperations> OffShoot	activateOffShoot(T cbServant) Activates a CORBA servant that implements alma.ACS.OffShoot.
<T> AcsEventPublisher<T>	createNotificationChannelPublisher(java.lang.String channelName, java.lang.Class<T> eventType) Creates a new AcsEventPublisher object for a given channel.
<T> AcsEventPublisher<T>	createNotificationChannelPublisher(java.lang.String channelName, java.lang.String ncDomain, java.lang.Class<T> eventType) Similar to createNotificationChannelPublisher(String, Class), but with additional NC domain specification.
<T> AcsEventSubscriber<T>	createNotificationChannelSubscriber(java.lang.String channelName, java.lang.Class<T> eventType) Creates a new AcsEventSubscriber object, which is the abstraction of a Notification Channel subscriber (consumer), for the given channel name.
<T> AcsEventSubscriber<T>	createNotificationChannelSubscriber(java.lang.String channelName, java.lang.String ncDomain, java.lang.Class<T> eventType) Creates a new AcsEventSubscriber object, which is the abstraction of a Notification Channel subscriber (consumer), for the given channel name and notify service domain name.
void	deactivateOffShoot(java.lang.Object offshootImpl) Deactivates the offshoot object previously activated through the #activateOffShoot(Object, Class) method.
AdvancedContainerServices	getAdvancedContainerServices() More specialized methods are available from the AdvancedContainerServices.
DAL	getCDB() Convenience method for accessing the Configuration Database.
AcsLogger	getLogger() Gets a Logger object that the component should use for logging.
java.lang.String	getName() Delivers the unique instance name for the component.
java.util.concurrent.ThreadFactory	getThreadFactory() Gets a ThreadFactory, to be used as input for other classes from the concurrent library (such as ThreadPoolExecutor), or simply to create new Threads.

Method Detail

getName

java.lang.String getName()

Delivers the unique instance name for the component. The name must have been specified at deployment time in the CDB (for static components like the famous "LAMP1" example), or must have been given to the manager at runtime by the client who creates a dynamic component (or was invented by the manager if none was given).

Returns:

the unique component instance name

getLogger

AcsLogger getLogger()

Gets a Logger object that the component should use for logging.

The Logger will be set up with a namespace specific to the component that uses this ContainerServices instance.

Specific logger extensions that only apply to certain subsystems can be used by wrapping this logger with a class such as AntennaContextLogger.

Returns:

Logger

getCDB

DAL getCDB()
    throws AcsJContainerServicesEx

Convenience method for accessing the Configuration Database.

Currently more than a convenience, given that the CDB is not yet a Java component, but a separate service...

Returns:

the CDB interface

Throws:

ContainerException

AcsJContainerServicesEx

activateOffShoot

<T extends org.omg.PortableServer.Servant & OffShootOperations> OffShoot activateOffShoot(T cbServant)
                                                                                   throws AcsJContainerServicesEx

Activates a CORBA servant that implements alma.ACS.OffShoot. The purpose of the OffShoot marker interface is to crack down on uncontrolled activation of just any CORBA services by Java components, while allowing this for selected subtypes of OffShoot, like alma.ACS.Callback.

The OffShoot servant can be either a subclass of the xyzPOA skeleton, or a xyzPOATie instance (delegation model). Since ACS 4.1.2, a tie servant is detected, and interception code gets inserted between the POATie skeleton and the offshoot implementation class. This way, the container can intercept (and log) calls to offshoots in the same way as it does for calls to components. It is therefore recommended to use the tie approach for all offshoot servants, unless there is a reason to avoid container interception.

Note that since ACS 9.0 we are using generics to express that the offshoot impl object must be both a corba servant and implement OffShootOperations.

Parameters:

cbServant - the CORBA-generated servant, e.g. CBdoublePOA; must implement alma.ACS.OffShootOperations.

Returns:

The corba-activated offshoot object, which needs a narrow-cast to the subtype, like CBdouble myCBdouble = alma.ACS.CBdoubleHelper.narrow(...).

Throws:

ContainerException - if anything goes wrong, especially if cbServant is not an OffShoot.

AcsJContainerServicesEx

deactivateOffShoot

void deactivateOffShoot(java.lang.Object offshootImpl)
                 throws AcsJContainerServicesEx

Deactivates the offshoot object previously activated through the #activateOffShoot(Object, Class) method. Caution: this method returns immediately, while the underlying POAOperations.deactivate_object(byte[]) still works on the deactivation. If activateOffShoot(Servant) is called too shortly after deactivation, an exception will be thrown. TODO: find a remedy

Parameters:

offshootImpl - the offshoot object implementation

Throws:

AcsJContainerServicesEx - if something goes wrong, e.g., if the corresponding offshoot servant was not active.

getAdvancedContainerServices

AdvancedContainerServices getAdvancedContainerServices()

More specialized methods are available from the AdvancedContainerServices.

getThreadFactory

java.util.concurrent.ThreadFactory getThreadFactory()

Gets a ThreadFactory, to be used as input for other classes from the concurrent library (such as ThreadPoolExecutor), or simply to create new Threads.

All user-created threads should come from the factory returned here, so "new Thread(...)" should not appear anywhere in component code.

The returned thread factory creates new threads configured to run well in the container environment, e.g.

• all threads are daeemon threads so that they can't interfere with container shutdown.
• the priority is the same as that of the calling component thread (which is created by the ORB)
• uncaught user exceptions are logged as WARNING before the thread terminates.
• when a component is removed from the container, surviving user threads created by that component are killed using Thread.stop() (which even though deprecated, seems like the perfect choice in this particular situation). Otherwise a faulty components could permanently take away resources from a running container and from the other components.

Returns:

the thread factory to be used by the component to create new threads.

createNotificationChannelPublisher

<T> AcsEventPublisher<T> createNotificationChannelPublisher(java.lang.String channelName,
                                                            java.lang.Class<T> eventType)
                                                     throws AcsJContainerServicesEx

Creates a new AcsEventPublisher object for a given channel. It is the abstraction of a Corba Notification Channel supplier, a DDS publisher, or a publisher for some other supported pub/sub technology.

The user is expected to call AcsEventPublisher.disconnect() when the publisher is no longer needed. To avoid resource problems, the ContainerServices object calls this method during its own deactivation, just in case the user forgot to do so.

Parameters:

channelName - The Notification Channel name where events will be published.

eventType - The type of event that can be sent using the AcsEventPublisher, e.g. "MySchedulingEvent.class". Specifying the type offers additional compile time checking. It should generally be used unless more than one event type must be sent through this publisher, in which case you can specify a common base type (e.g. "IDLEntity" in case of different IDL-generated structs), or just "Object" for total type freedom (though the underlying pub-sub framework may later throw runtime exceptions if unsupported event types get used).

Returns:

a Notification Channel publisher, that will get automatically stopped and disconnected when the component is unloaded, or the client disconnected, depending on the case, if the user doesn't do so.

Throws:

AcsJContainerServicesEx - if anything goes wrong while creating the publisher

createNotificationChannelPublisher

<T> AcsEventPublisher<T> createNotificationChannelPublisher(java.lang.String channelName,
                                                            java.lang.String ncDomain,
                                                            java.lang.Class<T> eventType)
                                                     throws AcsJContainerServicesEx

Similar to createNotificationChannelPublisher(String, Class), but with additional NC domain specification.

Details of this NC domain concept:

• All publishers and subscribers that access an NC must consistently use the same NC domain name.
• The CDB may specify a mapping of NC domain to a notify service, which then decides where the NC is hosted.
• Specifying the NC domain through the API as opposed to doing it in the NC's CDB description allows mapping of "dynamic" NCs to notify services, whose names are not known at deployment time. This may be the case for NCs created by 3rd party software such as the alarm system.

Parameters:

ncDomain - The Notification Channel Service Domain name.

eventType -

Throws:

AcsJContainerServicesEx

See Also:

#createNotificationChannelSubscriber(String, String)

createNotificationChannelSubscriber

<T> AcsEventSubscriber<T> createNotificationChannelSubscriber(java.lang.String channelName,
                                                              java.lang.Class<T> eventType)
                                                       throws AcsJContainerServicesEx

Creates a new AcsEventSubscriber object, which is the abstraction of a Notification Channel subscriber (consumer), for the given channel name. The created subscriber will be automatically disconnected when the component or client that created it through this method is finished, in case the user doesn't explicitly do it before.

Parameters:

channelName - The Notification Channel name to listen to

eventType - The type of event that can be sent using the AcsEventSubscriber, e.g. "MySchedulingEvent.class". The specific event type should be used unless more than one event types must be received by this subscriber, in which case you can specify a common base type (e.g. "IDLEntity.class" in case of different IDL-generated structs), or just "Object" for total type freedom (though the underlying pub-sub framework may later throw runtime exceptions if unsupported event types are received).

Returns:

a Notification Channel subscriber, to which the user can attach one or more handlers for each data type, and that will be automatically disconnected if the user doesn't do so.

Throws:

AcsJContainerServicesEx - if anything goes wrong while creating the subscriber

createNotificationChannelSubscriber

<T> AcsEventSubscriber<T> createNotificationChannelSubscriber(java.lang.String channelName,
                                                              java.lang.String ncDomain,
                                                              java.lang.Class<T> eventType)
                                                       throws AcsJContainerServicesEx

Creates a new AcsEventSubscriber object, which is the abstraction of a Notification Channel subscriber (consumer), for the given channel name and notify service domain name. The created subscriber will be automatically disconnected when the component or client that created it through this method is finished, in case the user doesn't explicitly do it before.

Details of the NC domain concept:

• All publishers and subscribers that access an NC must consistently use the same NC domain name.
• The CDB may specify a mapping of NC domain to a notify service, which then decides where the NC is hosted.
• Specifying the NC domain through the API as opposed to doing it in the NC's CDB description allows mapping of "dynamic" NCs to notify services, whose names are not known at deployment time. This may be the case for NCs created by 3rd party software such as the alarm system.

Parameters:

channelName - The Notification Channel name to listen to

ncDomain - The Notification Channel Service Domain name.

eventType - See createNotificationChannelPublisher(String, Class).

Returns:

a Notification Channel subscriber, to which the user can attach one or more handlers for each data type, and that will be automatically disconnected if the user doesn't do so.

Throws:

AcsJContainerServicesEx - if anything goes wrong while creating the subscriber