alma.acs.container

Class ContainerServicesImpl

java.lang.Object

alma.acs.container.ContainerServicesImpl

All Implemented Interfaces:

ContainerServices, ContainerServicesBase

public class ContainerServicesImpl
extends java.lang.Object
implements ContainerServices

Implementation of the ContainerServices interface. To be used by ACS components, as well as any other clients that need access to components.

This class is "cheap" to instantiate because many resources it uses are singletons and or objects otherwise shared among instances. It should thus be ok to create one instance per component or other client.

This class has to be thread-safe, because a component's functional methods can be called from different ORB threads, or because the component could itself create threads, each of them accessing this object.

Author:

hsommer Apr 1, 2003 2:28:01 PM

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	ContainerServicesImpl.CleanUpCallback Deprecated. Should be removed along with old NC Consumer.

Nested classes/interfaces inherited from interface alma.acs.container.ContainerServices

ContainerServices.ComponentListener, ContainerServices.ComponentReleaseCallback, ContainerServices.ComponentReleaseCallbackWithLogging

Field Summary

Fields

Modifier and Type	Field and Description
protected AcsManagerProxy	m_acsManagerProxy Holds and re-establishes the connection to the manager, and encapsulates the handle given by the manager at login.
protected AcsLogger	m_logger
static java.lang.String	PROPERTYNAME_FAKE_UID_FOR_TESTING cheat property that allows testing without identifier archive present, because UIDs will be faked

Constructor Summary

Constructors

Constructor and Description
ContainerServicesImpl(AcsManagerProxy acsManagerProxy, DAL cdb, org.omg.PortableServer.POA componentPOA, AcsCorba acsCorba, AcsLogger logger, int componentHandle, java.lang.String clientCurl, ComponentStateManager componentStateManager, java.util.concurrent.ThreadFactory threadFactory) ctor.

Method Summary

Modifier and Type	Method and Description
<T extends org.omg.PortableServer.Servant & OffShootOperations> OffShoot	activateOffShoot(T servant) Activates a CORBA servant that implements alma.ACS.OffShoot.
<T extends OffShootOperations> OffShoot	activateOffShoot(T offshootImpl, java.lang.Class<T> idlOpInterface) Activates an Object as an OffShoot.
void	assignUniqueEntityId(EntityT entity) Creates a unique id and sets it on the given (binding class) entity object.
void	cleanUp() Cleans up all the resources that need to be closed, like closing opened notification channels
<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 channelNotifyServiceDomainName, java.lang.Class<T> eventType) Similar to ContainerServicesBase.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 channelNotifyServiceDomainName, 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.
java.lang.String[]	findComponents(java.lang.String curlWildcard, java.lang.String typeWildcard) Finds components by their instance name (curl) and/or by their type.
void	fireComponentsAvailable(java.util.List<ComponentDescriptor> compDescs)
void	fireComponentsUnavailable(java.util.List<java.lang.String> compNames)
AdvancedContainerServices	getAdvancedContainerServices() More specialized methods are available from the AdvancedContainerServices.
AlarmSource	getAlarmSource() Returns the AlarmSource owned by this object.
DAL	getCDB() Convenience method for accessing the Configuration Database.
org.omg.CORBA.Object	getCollocatedComponent(ComponentQueryDescriptor spec, boolean markAsDefaul, java.lang.String targetCompUrl) Dynamic version of ContainerServices.getCollocatedComponent(String, String).
org.omg.CORBA.Object	getCollocatedComponent(java.lang.String compUrl, java.lang.String targetCompUrl) Gets a component that will run collocated with a given component.
org.omg.CORBA.Object	getComponent(java.lang.String curl) Gets a component specified by its instance name.
ComponentDescriptor	getComponentDescriptor(java.lang.String curl) Gets the component descriptor which contains meta data for the component.
org.omg.CORBA.Object	getComponentNonSticky(java.lang.String curl) Gets a non-sticky reference to a component.
ComponentStateManager	getComponentStateManager() Delivers the ComponentStateManager object through which the component and the container administrate the state of the component.
org.omg.CORBA.Object	getDefaultComponent(java.lang.String componentIDLType) Gets the default component specified by the component type.
org.omg.CORBA.Object	getDynamicComponent(ComponentQueryDescriptor compDesc, boolean markAsDefault) Gets a component whose instance is not registered in the CDB at deployment time.
org.omg.CORBA.Object	getDynamicComponent(ComponentSpec compSpec, boolean markAsDefault) Gets a component whose instance is not registered in the CDB at deployment time.
AcsLogger	getLogger() The component must retrieve its logger object from this interface (as opposed to using the ClientLogManager singleton) so that the container is free to give away loggers that are somehow tailored to the particular component.
java.lang.String	getName() Gets the component name (which the component does not know statically)
org.omg.CORBA.Object	getReferenceWithCustomClientSideTimeout(org.omg.CORBA.Object originalCorbaRef, double timeoutSeconds) Wraps a component reference (or offshoot reference etc) such that the given timeout is applied on the client side of calls to this (possibly remote) object.
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.
<T,F> T	getTransparentXmlWrapper(java.lang.Class<T> transparentXmlIF, F flatXmlObject, java.lang.Class<F> flatXmlIF) Converts a "flat-XML" remote object (RO) interface (as obtained from the various getComponent methods, in the case of components, or by retrieving offshoots from components, in the case of offshoots) to a "transparent-XML" RO interface.
void	registerCleanUpCallback(ContainerServicesImpl.CleanUpCallback cb) Deprecated. Since ACS 10.2. Should be removed along with old NC Consumer.
void	registerComponentListener(ContainerServices.ComponentListener listener) Allows a client to register a callback object that gets notified when some component(s) in use by the client (= components the client requested previously) dies or comes back to life (with ComponentListener#includeForeignComponents()==false).
void	releaseAllComponents()
void	releaseComponent(java.lang.String curl) Releases the specified component reference.
void	releaseComponent(java.lang.String curl, ContainerServices.ComponentReleaseCallback callback) Releases the reference to the specified component.

Methods inherited from class java.lang.Object

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

Field Detail

PROPERTYNAME_FAKE_UID_FOR_TESTING

public static final java.lang.String PROPERTYNAME_FAKE_UID_FOR_TESTING

cheat property that allows testing without identifier archive present, because UIDs will be faked

See Also:

Constant Field Values

m_acsManagerProxy

protected final AcsManagerProxy m_acsManagerProxy

Holds and re-establishes the connection to the manager, and encapsulates the handle given by the manager at login.

m_logger

protected final AcsLogger m_logger

Constructor Detail

ContainerServicesImpl

public ContainerServicesImpl(AcsManagerProxy acsManagerProxy,
                             DAL cdb,
                             org.omg.PortableServer.POA componentPOA,
                             AcsCorba acsCorba,
                             AcsLogger logger,
                             int componentHandle,
                             java.lang.String clientCurl,
                             ComponentStateManager componentStateManager,
                             java.util.concurrent.ThreadFactory threadFactory)

ctor.

Parameters:

acsManagerProxy -

componentPOA - the POA for the component. Can be the root POA or some other specialized POA.

acsCorba - Encapsulates the ORB and all POAs

logger - logger to be used by this class

componentHandle - handle to be used for identification when sending requests to the manager. For components, this should be the component handle assigned by the manager; for other clients, it should be 0 to indicate that the handle obtained at manager login should be used.

clientCurl -

componentStateManager - can be null if this class is instantiated for a component client outside of a container

threadFactory - to be used for getThreadFactory

Method Detail

getName

public java.lang.String getName()

Gets the component name (which the component does not know statically)

Specified by:

getName in interface ContainerServicesBase

Returns:

the unique component instance name

See Also:

ContainerServicesBase.getName()

getComponentStateManager

public ComponentStateManager getComponentStateManager()

Delivers the ComponentStateManager object through which the component and the container administrate the state of the component.

The component needs to access the ComponentStateManager if it wishes to change its state. If it doesn't, only the container will change the state based on the information it has available. This method should only be called by a component that lives inside a container; a component client that is not a component itself should not call it, would result in a NPE!

Specified by:

getComponentStateManager in interface ContainerServices

Returns:

the state manager

See Also:

ContainerServices.getComponentStateManager()

getLogger

public AcsLogger getLogger()

The component must retrieve its logger object from this interface (as opposed to using the ClientLogManager singleton) so that the container is free to give away loggers that are somehow tailored to the particular component.

The goal is to have "componentName" and other fields in all ALMA log entries, and have tool support for filtering logs by component, subsystem, user, ...

Specified by:

getLogger in interface ContainerServicesBase

Returns:

Logger

See Also:

ContainerServicesBase.getLogger()

registerComponentListener

public void registerComponentListener(ContainerServices.ComponentListener listener)

Description copied from interface: ContainerServices

Allows a client to register a callback object that gets notified when some component(s) in use by the client (= components the client requested previously) dies or comes back to life (with ComponentListener#includeForeignComponents()==false).

If the client wants to get notified even for components that it does not hold a reference to, then ComponentListener#includeForeignComponents() should return true; notification about components that this client does not use may be limited though, e.g. to components collocated in the same container.

Specified by:

registerComponentListener in interface ContainerServices

See Also:

si.ijs.maci.ClientOperations#components_available(si.ijs.maci.ComponentInfo[])

fireComponentsAvailable

public void fireComponentsAvailable(java.util.List<ComponentDescriptor> compDescs)

fireComponentsUnavailable

public void fireComponentsUnavailable(java.util.List<java.lang.String> compNames)

assignUniqueEntityId

public void assignUniqueEntityId(EntityT entity)
                          throws AcsJContainerServicesEx

Description copied from interface: ContainerServices

Creates a unique id and sets it on the given (binding class) entity object. The id will be redundantly stored in an encrypted format so that later it can be verified that the id is indeed the one originally assigned.

Specified by:

assignUniqueEntityId in interface ContainerServices

Parameters:

entity - must be freshly created and

Throws:

AcsJContainerServicesEx

See Also:

ContainerServices.assignUniqueEntityId(EntityT)

findComponents

public java.lang.String[] findComponents(java.lang.String curlWildcard,
                                         java.lang.String typeWildcard)
                                  throws AcsJContainerServicesEx

Description copied from interface: ContainerServices

Finds components by their instance name (curl) and/or by their type. Wildcards can be used for the curl and type. This method returns a possibly empty array of component curls; for each curl, you may then call getComponent to obtain the reference.

Specified by:

findComponents in interface ContainerServices

Parameters:

curlWildcard - (null is understood as "*")

typeWildcard - (null is understood as "*")

Returns:

the curls of the component(s) that match the search.

Throws:

AcsJContainerServicesEx

See Also:

ContainerServices.findComponents(java.lang.String, java.lang.String)

getComponentDescriptor

public ComponentDescriptor getComponentDescriptor(java.lang.String curl)
                                           throws AcsJContainerServicesEx

Description copied from interface: ContainerServices

Gets the component descriptor which contains meta data for the component. (Not to be confused with a component descriptor in the EJB sense.)

To be used primarily after retrieval of a component with getDefaultComponent or getDynamicComponent, when some data like the instance name is not known. The idea behind having this method separately is that in many cases, components are not interested in this information, and are happier to get back from these methods directly the remote reference to another component, instead of always dealing with a ComponentDescriptor.

Specified by:

getComponentDescriptor in interface ContainerServices

Parameters:

curl - the unique name of a component

Returns:

the descriptor from which the various data items can be obtained.

Throws:

AcsJContainerServicesEx

See Also:

ContainerServices.getComponentDescriptor(java.lang.String)

getComponent

public org.omg.CORBA.Object getComponent(java.lang.String curl)
                                  throws AcsJContainerServicesEx

Description copied from interface: ContainerServices

Gets a component specified by its instance name. Delegates to get_component.

• This method is necessarily generic and will require a cast to the requested interface, like in HelloComponent helloComp = HelloComponentHelper.narrow(containerServices.getComponent("HELLOCOMP1"));.
• the more general method get_service offered by the manager is deliberately not represented here. It would currently (Oct.03) offer access to "LogFactory", "NotifyEventChannelFactory", "ArchivingChannel@ARCHIVING.channels", "LoggingChannel", "InterfaceRepository", "CDB", "ACSLogSvc"; It seems that if such access is needed, specialized methods should be added to this interface, like ContainerServicesBase.getCDB().
• if requested, we may come up with some additional way (e.g. a code-generated singleton class) to give type safe access to other components, like done with EJB xxxHome.
• the Container will later shortcut calls for components inside the same process. Like in EJB and CORBA, the implementation must therefore not assume receiving a by-value copy of any parameter from the other component.

Specified by:

getComponent in interface ContainerServices

Parameters:

curl - the ACS CURL of the deployed component instance.

Returns:

the CORBA proxy for the component.

Throws:

AcsJContainerServicesEx - if something goes wrong.

See Also:

ContainerServices.getComponent(String)

getComponentNonSticky

public org.omg.CORBA.Object getComponentNonSticky(java.lang.String curl)
                                           throws AcsJContainerServicesEx

Description copied from interface: ContainerServices

Gets a non-sticky reference to a component. This is typically used by "weak clients" such as graphical user interfaces that only want to observe the running system without interfering with its functioning.

A non-sticky reference does not bind the Manager to keep alive the Component, and the Client requesting a non-sticky reference is not considered when checking for reference counts. The non-sticky reference should not be released, as that call will fail. The Manager can deactivate Components independently of any non-sticky reference. Since a non-sticky reference is not considered in reference counting, it will also not activate the component if it is not already active. As a consequence, asking for a non-sticky reference to a not-active Component throws an exception. The client represented by id (the handle) must have adequate access rights to access the component.

Specified by:

getComponentNonSticky in interface ContainerServices

Parameters:

curl - the component URL (component instance name)

Returns:

the CORBA proxy for the component.

Throws:

AcsJContainerServicesEx - if something goes wrong

getDefaultComponent

public org.omg.CORBA.Object getDefaultComponent(java.lang.String componentIDLType)
                                         throws AcsJContainerServicesEx

Description copied from interface: ContainerServices

Gets the default component specified by the component type. The type is the IDL type, such as IDL:alma/PS/PowerSupply:1.0.

A default instance for the given type must have been declared beforehand (either statically in the CDB config files, or dynamically), otherwise an exception is thrown.

To get more information on the returned component, call ContainerServices.getComponentDescriptor(java.lang.String) with the instance name that you can get from the component using alma.ACS.ACSComponentOperations#name.

Delegates to si.ijs.maci.ManagerOperations#get_default_component.

Specified by:

getDefaultComponent in interface ContainerServices

Returns:

Throws:

AcsJContainerServicesEx

See Also:

ContainerServices.getDefaultComponent(java.lang.String)

getCollocatedComponent

public org.omg.CORBA.Object getCollocatedComponent(java.lang.String compUrl,
                                                   java.lang.String targetCompUrl)
                                            throws AcsJContainerServicesEx

Description copied from interface: ContainerServices

Gets a component that will run collocated with a given component.

Specified by:

getCollocatedComponent in interface ContainerServices

Parameters:

compUrl - the component's name (URL)

targetCompUrl - the name (URL) of the target component, in whose container we also want compUrl to run.

Returns:

the component reference, which should be cast using the appropriate CORBA narrow operation. Never null.

Throws:

AcsJContainerServicesEx - If the call failed and no component reference could be obtained.

getCollocatedComponent

public org.omg.CORBA.Object getCollocatedComponent(ComponentQueryDescriptor spec,
                                                   boolean markAsDefaul,
                                                   java.lang.String targetCompUrl)
                                            throws AcsJContainerServicesEx

Description copied from interface: ContainerServices

Dynamic version of ContainerServices.getCollocatedComponent(String, String).

Specified by:

getCollocatedComponent in interface ContainerServices

Parameters:

spec - the description of the component to be created

markAsDefaul - if true, the new component will become the default component for its IDL type.

targetCompUrl - targetCompUrl the name (URL) of the target component, in whose container we also want compUrl to run.

Returns:

Throws:

AcsJContainerServicesEx - If the call failed and no component reference could be obtained.

getDynamicComponent

public org.omg.CORBA.Object getDynamicComponent(ComponentQueryDescriptor compDesc,
                                                boolean markAsDefault)
                                         throws AcsJContainerServicesEx

Description copied from interface: ContainerServices

Gets a component whose instance is not registered in the CDB at deployment time.

The fields of compSpec can be filled in at various levels of detail, allowing the manager to blend in missing data from static deployment information. For a detailed description of the various options, please refer to the ACS documentation.

To get more information on the returned component, call ContainerServices.getComponentDescriptor(java.lang.String) with the instance name that you've specified or that you can get from the component in case it was assigned (see alma.ACS.ACSComponentOperations#name()).

Delegates to si.ijs.maci.ManagerOperations#get_dynamic_component.

Specified by:

getDynamicComponent in interface ContainerServices

Parameters:

compDesc - the description of the component to be created

markAsDefault - if true, the new component will become the default component for its IDL type.

Throws:

AcsJContainerServicesEx

See Also:

alma.acs.container.ContainerServices#getDynamicComponent(si.ijs.maci.ComponentSpec, boolean)

getDynamicComponent

public org.omg.CORBA.Object getDynamicComponent(ComponentSpec compSpec,
                                                boolean markAsDefault)
                                         throws AcsJContainerServicesEx

Description copied from interface: ContainerServices

Gets a component whose instance is not registered in the CDB at deployment time.

The fields of compSpec can be filled in at various levels of detail, allowing the manager to blend in missing data from static deployment information. For a detailed description of the various options, please refer to the ACS documentation.

To get more information on the returned component, call ContainerServices.getComponentDescriptor(java.lang.String) with the instance name that you've specified or that you can get from the component in case it was assigned (see alma.ACS.ACSComponentOperations#name()).

Delegates to si.ijs.maci.ManagerOperations#get_dynamic_component.

Specified by:

getDynamicComponent in interface ContainerServices

Parameters:

compSpec - the description of the component to be created

markAsDefault - if true, the new component will become the default component for its IDL type.

Throws:

AcsJContainerServicesEx

See Also:

alma.acs.container.ContainerServices#getDynamicComponent(si.ijs.maci.ComponentSpec, boolean)

getReferenceWithCustomClientSideTimeout

public org.omg.CORBA.Object getReferenceWithCustomClientSideTimeout(org.omg.CORBA.Object originalCorbaRef,
                                                                    double timeoutSeconds)
                                                             throws AcsJContainerServicesEx

Description copied from interface: ContainerServices

Wraps a component reference (or offshoot reference etc) such that the given timeout is applied on the client side of calls to this (possibly remote) object. If the total call, including de-/serialization and network travel, takes longer than the given timeout, an org.omg.CORBA.TIMEOUT exception will be thrown.

This allows us to override the general timeout given at the system level (e.g. orb.properties file in case of jacorb) and the container-level timeout given in the CDB container configuration. It is possible to set the timeout to values that are shorter or longer than the default timeout. You should chose a timeout value that matches the expected response time, with a large safety margin of

Note that calls to which the specified timeout should apply must be made on the object reference returned from this method, and not on the original object that gets passed to this method! Some corba implementations may apply the timeout to both objects though, or return the original object.

Specified by:

getReferenceWithCustomClientSideTimeout in interface ContainerServices

timeoutSeconds - the custom client side timeout in seconds, to be used for all calls to the given object reference.

Returns:

A new object reference which should be used to make calls with the specified timeout applied.

Throws:

AcsJContainerServicesEx

getCDB

public DAL getCDB()
           throws AcsJContainerServicesEx

Description copied from interface: ContainerServicesBase

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

Specified by:

getCDB in interface ContainerServicesBase

Returns:

the CDB interface

Throws:

AcsJContainerServicesEx

See Also:

ContainerServicesBase.getCDB()

releaseComponent

public void releaseComponent(java.lang.String curl)

Releases the specified component reference. This involves notification of the manager, as well as calling _release() on the CORBA stub. If the curl is not known to the container, the request will be ignored.

Note that references to other components are released by this method, where the components hosted inside this container act as clients. These referenced components may run inside this or some other container/container.

Since ACS 9.1 this method is implemented by delegating to releaseComponent(String, alma.acs.container.ContainerServices.ComponentReleaseCallback), keeping the old synchronous behavior by blocking on a callback object, with a timeout of 60 seconds. Since ACS 10.0, errors are logged at level DEBUG.

Specified by:

releaseComponent in interface ContainerServices

Parameters:

curl - the name/curl of the component instance as used by the manager

See Also:

ContainerServices.releaseComponent(java.lang.String)

releaseComponent

public void releaseComponent(java.lang.String curl,
                             ContainerServices.ComponentReleaseCallback callback)

Description copied from interface: ContainerServices

Releases the reference to the specified component. Releasing a component reference may result in the deactivation of that component, if no other clients hold (sticky) references.

This call will return as soon as the release request has been delivered to the ACS manager, which means that the reference count evaluation and possible component deactivation will happen only after returning from this call.

If your code must synchronize with the reference evaluation and possible component deactivation in the target container, or if you are interested in exceptions that may occur during component deactivation, then you should supply the optional ComponentRequestCallback object and block execution of your calling thread until you receive the callback.

If an exception (such as no-permission) is thrown during the synchronous first part of the underlying call to the manager, then this exception will not be thrown upward by this method but will instead be reported to the optional callback object, just like any exception that happens later during the asynchronous part of the component release. The idea here is to have either "interested" clients that want to get all exceptions, or "easy" clients that do not care about any exceptions, thus do not provide a callback object, and also do not want to bother about a try/catch block.

Specified by:

releaseComponent in interface ContainerServices

Parameters:

curl - the name/curl of the component instance as used by the manager

callback - may be null if you do not need to wait for component deactivation or to see the results. An new instance of ComponentReleaseCallback is required for every call.

activateOffShoot

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

Description copied from interface: ContainerServicesBase

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.

Specified by:

activateOffShoot in interface ContainerServicesBase

Parameters:

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

AcsJContainerServicesEx

See Also:

ContainerServicesBase.activateOffShoot(org.omg.PortableServer.Servant)

activateOffShoot

public <T extends OffShootOperations> OffShoot activateOffShoot(T offshootImpl,
                                                                java.lang.Class<T> idlOpInterface)
                                                         throws AcsJContainerServicesEx

Description copied from interface: ContainerServices

Activates an Object as an OffShoot.

In contrast to the old ContainerServicesBase.activateOffShoot(Servant) method, which always expects a Servant (either subclass of xyzPOA skeleton or a xyzPOATie instance), this method is more flexible and receives two arguments:

• The object implementing alma.ACS.OffShootOperations, but without restricting it to be a Servant, and
• The operations interface that this object directly implements.

This way, we support

• Activation of "normal" OffShoots:
  offshootImpl should be a corba Servant, either a subclass of the XyzPOA skeleton, or a XyzPOATie instance (delegation model).
  idlOpInterface should be XyzOperations.class.
• OffShoots featuring automatic XML (de-)serialization, similar to what has always been offered for ACS Components.
  offshootImpl should be an object that implements the generated XyzJ interface (which uses XML binding classes and extends OffShootOperations). This object is not expected to be a Corba Servant.
  idlOpInterface should be XyzJ.class.

Since ACS 9.0, when giving an OffShoot with XML entities (de-)serialization, automatic interception code is created to wrap the given object, and a XyzPOATie instance is created automatically and used as the servant. 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.

Specified by:

activateOffShoot in interface ContainerServices

Type Parameters:

T - The type of offshootImpl, one of the xyzJ or xyzOperations interfaces

Parameters:

offshootImpl - the object that implements the OffShoot logic

idlOpInterface - the IDL operations interface implemented by offshootImpl; currently, must be one of xyzOperations or xyzJ

Returns:

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

Throws:

AcsJContainerServicesEx - if anything goes wrong, especially if offshootImpl is does not implement alma.ACS.OffShootOperations.

See Also:

ContainerServicesBase.activateOffShoot(org.omg.PortableServer.Servant)

deactivateOffShoot

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

Description copied from interface: ContainerServicesBase

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 ContainerServicesBase.activateOffShoot(Servant) is called too shortly after deactivation, an exception will be thrown. TODO: find a remedy

Specified by:

deactivateOffShoot in interface ContainerServicesBase

Parameters:

offshootImpl - the offshoot object implementation

Throws:

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

getAdvancedContainerServices

public AdvancedContainerServices getAdvancedContainerServices()

Description copied from interface: ContainerServicesBase

More specialized methods are available from the AdvancedContainerServices.

Specified by:

getAdvancedContainerServices in interface ContainerServicesBase

See Also:

ContainerServicesBase.getAdvancedContainerServices()

getTransparentXmlWrapper

public <T,F> T getTransparentXmlWrapper(java.lang.Class<T> transparentXmlIF,
                                        F flatXmlObject,
                                        java.lang.Class<F> flatXmlIF)
                                 throws AcsJContainerServicesEx

Converts a "flat-XML" remote object (RO) interface (as obtained from the various getComponent methods, in the case of components, or by retrieving offshoots from components, in the case of offshoots) to a "transparent-XML" RO interface. This is only applicable to ROs that contain XML entities in their IDL interface methods, and for which the build process has been set up to generate XML binding classes and the "transparent-XML" interface in addition to the standard Java-IDL compiler output.

In the case that the remote object is a component, the container can fulfill this request in two different ways:

1. Remote component: if the specified component runs in a different container, a dynamic wrapper object will be created around the provided CORBA stub. The wrapper object will translate between entity object parameters in the form of serialized XML (as found in flatXmlIF) and the corresponding Java binding classes (in transparentXmlIF).
2. Collocated component: if the specified component runs in the same container, the container may choose to shortcut the (de-) serialization of XML binding classes. In this case, Java binding classes are transported in memory, and all communication with the other component is done without CORBA.

In either case, the returned Object implements the transparentXmlIF interface. The client component that calls this method should only cast to that interface, and does not need to know which of the two transport mechanisms are being used..

TODO: implement shortcutting of xml (de-)serialization for collocated component or offshoot: ask AcsContainer if it knows componentReference, and if it has transpXml-IF; if so, get component impl directly; check if respective component helper allows direct calls to transpXmlIF (by not implementing _getInterfaceTranslator, or some explicit flag); move intercepting layer (ContainerSealant) so that it's still in between the components.

Specified by:

getTransparentXmlWrapper in interface ContainerServices

Parameters:

transparentXmlIF - remote object interface with XML binding classes.

flatXmlObject - reference to the remote object to be wrapped, which implements flatXmlIF. Currently supported remote objects are ACS Components and OffShoots.

flatXmlIF - remote object interface ("xxxOperations") where entity objects are represented as serialized XML inside a CORBA struct.

Returns:

the object that implements transparentXmlIF.

Throws:

AcsJContainerServicesEx

See Also:

alma.acs.container.ContainerServices#getTransparentXmlComponent(java.lang.Class, org.omg.CORBA.Object, java.lang.Class)

releaseAllComponents

public void releaseAllComponents()

getThreadFactory

public java.util.concurrent.ThreadFactory getThreadFactory()

Description copied from interface: ContainerServicesBase

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.

Specified by:

getThreadFactory in interface ContainerServicesBase

Returns:

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

See Also:

ContainerServicesBase.getThreadFactory()

cleanUp

public void cleanUp()

Cleans up all the resources that need to be closed, like closing opened notification channels

Since:

ACS 8.1.0

registerCleanUpCallback

public void registerCleanUpCallback(ContainerServicesImpl.CleanUpCallback cb)

Deprecated. Since ACS 10.2. Should be removed along with old NC Consumer.

This is a hack: NC classes can register themselves to be notified, in order to release remote Corba resources (and prevent crashes of Notify Service...). Note that without this hack, the lifecycle of NC classes is only managed by the application code, which means that ACS could not enforce the clean up.

Parameters:

cb -

Since:

ACS 8.1.0

createNotificationChannelSubscriber

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

Description copied from interface: ContainerServicesBase

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.

Specified by:

createNotificationChannelSubscriber in interface ContainerServicesBase

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

See Also:

alma.acs.container.ContainerServices#createNotificationChannelSubscriber(String)

createNotificationChannelSubscriber

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

Description copied from interface: ContainerServicesBase

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.

Specified by:

createNotificationChannelSubscriber in interface ContainerServicesBase

Parameters:

channelName - The Notification Channel name to listen to

channelNotifyServiceDomainName - The Notification Channel Service Domain name.

eventType - See ContainerServicesBase.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

See Also:

alma.acs.container.ContainerServices#createNotificationChannelSubscriber(String, String)

createNotificationChannelPublisher

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

Description copied from interface: ContainerServicesBase

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.

Specified by:

createNotificationChannelPublisher in interface ContainerServicesBase

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

See Also:

ContainerServices#createNotificationChannelPublisher(String)

createNotificationChannelPublisher

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

Description copied from interface: ContainerServicesBase

Similar to ContainerServicesBase.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.

Specified by:

createNotificationChannelPublisher in interface ContainerServicesBase

channelNotifyServiceDomainName - The Notification Channel Service Domain name.

Throws:

AcsJContainerServicesEx

See Also:

ContainerServices#createNotificationChannelPublisher(String, String)

getAlarmSource

public AlarmSource getAlarmSource()

Description copied from interface: ContainerServices

Returns the AlarmSource owned by this object. The AlarmSource object allows to raise and clear alarms, among other advanced operations

Specified by:

getAlarmSource in interface ContainerServices

Returns:

The AlarmSource owned by this object