Classes
class	RVtrialAndError
Public Member Functions
	AcsCorba (AcsLogger logger)
void	setPortOptions (Integer orbPort, Integer orbPortSearchRetry)
synchronized void	setLogger (AcsLogger logger)
synchronized void	initCorba (String[] args, int port) throws AcsJContainerEx
synchronized boolean	isInitialized ()
synchronized POA	initCorbaForClient (boolean isAdmin) throws Exception
void	runCorba () throws AcsJContainerEx
void	blockOnORB ()
void	shutdownORB (final boolean wait_for_completion, boolean isOrbThread)
void	doneCorba ()
ORB	getORB ()
POA	getRootPOA ()
org.omg.CORBA.Object	activateContainer (AcsContainer container, String name) throws AcsJContainerEx
si.ijs.maci.Container	getContainerCorbaRef (AcsContainer container) throws AcsJContainerEx
POA	createPOAForComponent (String compName) throws AcsJContainerEx
ComponentServantManager	setServantManagerOnComponentPOA (POA componentPOA) throws AcsJContainerEx
POA	getPOAForOffshoots (POA componentPOA) throws AcsJContainerEx, AcsJUnexpectedExceptionEx
org.omg.CORBA.Object	activateComponent (Servant servant, String name, POA compPOA) throws AcsJContainerEx
boolean	deactivateComponentPOAManager (POA compPOA, final String compName, int timeoutMillis)
boolean	destroyComponentPOA (POA compPOA, ComponentServantManager compServantManager, int timeoutMillis)
org.omg.CORBA.Object	activateOffShoot (Servant servant, POA compPOA) throws AcsJContainerEx, AcsJUnexpectedExceptionEx
void	deactivateOffShoot (Servant servant, POA compPOA) throws AcsJContainerEx
void	setORBLevelRoundtripTimeout (double timeoutSeconds) throws AcsJContainerServicesEx
org.omg.CORBA.Object	wrapForRoundtripTimeout (org.omg.CORBA.Object corbaRef, double timeoutSeconds) throws AcsJContainerServicesEx
void	prepareOrb (String[] args)
Static Public Attributes
static final String	ORB_PROFILER_CLASS_PROPERTYNAME = "alma.acs.orb.profiler.class"
static final String	SYSPROP_FIRESTARTER_OAPORT = "acs.firestarter.oaport"
Protected Member Functions
void	initRootPoa (ORB orb)
RVtrialAndError	trialAndError (String[] args, int first, int retries)
Protected Attributes
int	DEFAULT_PORT = 3075
int	DEFAULT_RETRY = 5

Detailed Description

This class contains methods to work with the ORB and POAs on behalf of alma.acs.container.AcsContainer and other classes from the alma.acs.container or alma.acs.component.client package.

An instance of AcsCorba encapsulates an ORB instance, together with the POAs.

POA structure:

RootPOA: does not directly host objects.
ContainerPOA: child of RootPOA, responsible for the container.
ComponentPOA: child of RootPOA, parent for the ComponentPOAxxx POAs, does not directly host objects.
ComponentPOAxxx: child of ComponentPOA; the POA for exactly one component (xxx stands for the component instance name). See createPOAForComponent(String).
offshootPoa: child of a ComponentPOAxxx (created on demand); it is the POA for any number of OffShoot objects for a given component. See getPOAForOffshoots(POA).

This class must not be used directly by ACS applications such as components or component clients. If you feel that you need to access ORB functionality, please request to have it provided in alma.acs.container.ContainerServices or alma.acs.container.AdvancedContainerServices.

created on Nov 4, 2002 2:56:44 PM

Author:: hsommer

Constructor & Destructor Documentation

alma.acs.container.corba.AcsCorba.AcsCorba ( AcsLogger logger )

ctor

Member Function Documentation

org.omg.CORBA.Object alma.acs.container.corba.AcsCorba.activateComponent	(	Servant	servant,
		String	name,
		POA	compPOA
	)			throws AcsJContainerEx

Activates a component using a given component POA.

Parameters:

	servant
	name
	compPOA

Returns:: the component as a CORBA object

Exceptions:

AcsJContainerServicesEx

Referenced by alma.acs.container.ComponentAdapter.activateComponent().

org.omg.CORBA.Object alma.acs.container.corba.AcsCorba.activateContainer	(	AcsContainer	container,
		String	name
	)			throws AcsJContainerEx

Activates the container using the respective POA, so that the container becomes a CORBA object.

Parameters:

	container	the container servant
	name	a name assigned to the container, used as the CORBA id.

Returns:: the container CORBA object, never null

Exceptions:

AcsJContainerEx

if args are null or the activation fails for whatever reason.

org.omg.CORBA.Object alma.acs.container.corba.AcsCorba.activateOffShoot	(	Servant	servant,
		POA	compPOA
	)			throws AcsJContainerEx, AcsJUnexpectedExceptionEx

Activates an offshoot object (which is a regular CORBA object owned by a component).

All offshoot objects for a component are activated using a non-persistent "offshootPOA".

Parameters:

	servant	the offshoot servant.
	compPOA	the POA responsible for the component which activates the offshoot.

Returns:: the activated offshoot corba object.

Exceptions:

AcsJContainerServicesEx

References alma.acs.container.corba.AcsCorba.getPOAForOffshoots().

Referenced by alma.acs.commandcenter.engine.Executor.remoteDaemonForServices().

void alma.acs.container.corba.AcsCorba.blockOnORB ( )

Calls ORB#run() which from the point of view of the caller blocks the thread until the ORB has shut down, optionally performing tasks for the ORB in the meantime (see Corba spec 2.4 , chap. 4.2.3.3)

References alma.acs.container.corba.AcsCorba.getORB().

POA alma.acs.container.corba.AcsCorba.createPOAForComponent ( String compName ) throws AcsJContainerEx

Creates a new POA that is responsible for exactly one component. Dependent CORBA objects (offshoots) are activated through a child POA. The new POA is created as a child of the shared ComponentPOA.

The new component POA uses its own POA manager, which allows discarding requests for this component (w/o discarding requests for other components, the container, or even this component's offshoots).

Parameters:

compName

the name of the component; used to construct the POA name by prepending "ComponentPOA_"

Returns:: the new component POA; never null.

Exceptions:

AcsJContainerServicesEx

if creation of the POA fails.

Referenced by alma.acs.container.ComponentAdapter.ComponentAdapter(), and alma.acs.container.AcsContainer.initialize().

boolean alma.acs.container.corba.AcsCorba.deactivateComponentPOAManager	(	POA	compPOA,
		final String	compName,
		int	timeoutMillis
	)

Deactivates a component's POA manager. The effect is that no further calls will reach the component. This method returns immediately if the POA manager is already inactive. Otherwise it will only return when the active requests are done.

Note for JacORB (1.4 as well as 2.2.4): there seems to be a problem in org.jacorb.poa.RequestController.waitForCompletion with local calls (e.g. collocated component). Instead of duly waiting for completion, that method returns immediately when such calls are still executing. Even worse, RequestController.activeRequestTable seems to never get touched in case of local calls. There is a currently commented out JUnit test that verifies this problem.

The purpose of this method is to allow the container to "drain" a component of requests, so that cleanUp can be called while no functional calls are running or can come in. An alternative to using the component POA manager could be to destroy the component POA before calling cleanUp. This has the disadvantage of also destroying the offshoot child POA, which is needed to properly clean up callback connections.

Note that POAManager#deactivate(boolean, boolean) is called in a separate thread, so that this method itself may well be called from an ORB thread. This method uses etherealize_objects=false and wait_for_completion=true.

Parameters:

	compPOA	the component POA
	compName	component instance name
	timeoutMillis	timeout in milliseconds after which this call returns even if the POA manager is not inactive yet.

Returns:: true if the POA manager is inactive.

References alma.acs.util.StopWatch.getLapTimeMillis(), and alma.acs.logging.AcsLogger.log().

Referenced by alma.acs.container.ComponentAdapter.deactivateComponent().

void alma.acs.container.corba.AcsCorba.deactivateOffShoot	(	Servant	servant,
		POA	compPOA
	)			throws AcsJContainerEx

References alma.acs.container.corba.AcsCorba.getPOAForOffshoots(), and alma.acs.logging.AcsLogger.log().

boolean alma.acs.container.corba.AcsCorba.destroyComponentPOA	(	POA	compPOA,
		ComponentServantManager	compServantManager,
		int	timeoutMillis
	)

Destroys the component POA (and its child the offshoot POA if it exists), waiting at most timeoutMillis milliseconds for active requests to terminate.

Parameters:

	compPOA	the component POA
	compServantManager	the custom servant manager of that POA
	timeoutMillis	the timeout in milliseconds after which the call returns even if the POA has not been destroyed.

Returns:: true if the component was etherealized within the given time, false otherwise

See also:: ComponentServantManager.waitForEtherealize(int)

References alma.acs.container.ComponentServantManager.resetWaitForEtherealize(), and alma.acs.container.ComponentServantManager.waitForEtherealize().

Referenced by alma.acs.container.ComponentAdapter.deactivateComponent().

void alma.acs.container.corba.AcsCorba.doneCorba ( )

Calls m_orb.destroy(). This method must not be invoked from an ORB invocation thread!

The Corba spec v. 2.4 says in section 4.2.3:

ORB#shutdown(boolean) causes all object adapters to be destroyed, since they cannot exist in the absence of an ORB. Shut down is complete when all ORB processing (including request processing and object deactivation or other operations associated with object adapters) has completed and the object adapters have been destroyed. In the case of the POA, this means that all object etherealizations have finished and root POA has been destroyed (implying that all descendent POAs have also been destroyed).
ORB#destroy() destroys the ORB so that its resources can be reclaimed by the application.
For maximum portability and to avoid resource leaks, an application should always call shutdown and destroy on all ORB instances before exiting.
Once an ORB has been destroyed, another call to ORB_init with the same ORBid will return a reference to a newly constructed ORB.
If destroy is called on an ORB that has not been shut down, it will start the shut down process and block until the ORB has shut down before it destroys the ORB.

With ACS 8.0, this method no longer attempts to destroy policy objects, trusting that either an explicit call to AcsCorba.shutdownORB(boolean, boolean)} or the abovementioned implicit call to ORB.shutdown(boolean)} takes care of this.

See also problems reported in COMP-2632.

Referenced by alma.acs.container.AcsContainerRunner.main(), alma.acs.component.client.ComponentClientTestCase.setUp(), alma.acs.component.client.ComponentClientTestCase.tearDown(), and alma.acs.component.client.ComponentClient.tearDown().

si.ijs.maci.Container alma.acs.container.corba.AcsCorba.getContainerCorbaRef ( AcsContainer container ) throws AcsJContainerEx

Encapsulates POA#servant_to_reference(Servant) for the container servant.

Since:: ACS 8.1 when Servant#_this_object(ORB) was replaced by POA#servant_to_reference(Servant) in AcsContainer#loginToManager to avoid a second activation of the container servant, on the RootPOA.

Referenced by alma.acs.container.AcsContainer.loginToManager().

ORB alma.acs.container.corba.AcsCorba.getORB ( )

Returns the ORB instance.

Returns:: ORB

Exceptions:

IllegalStateException

if the ORB reference is missing or has not been initialized before.

References alma.acs.container.corba.AcsCorba.isInitialized().

Referenced by alma.acs.container.corba.AcsCorba.blockOnORB(), alma.acs.component.client.ComponentClientTestCase.connectToManager(), alma.acs.component.client.AdvancedComponentClient.createContainerServices(), alma.acs.component.client.ComponentClientTestCase.getLogReceiver(), alma.acs.container.AdvancedContainerServicesImpl.getORB(), alma.acs.container.corba.AcsCorba.getRootPOA(), alma.acs.commandcenter.meta.Firestarter.giveOrb(), alma.acs.container.AcsContainerRunner.initAcsLogging(), alma.acs.container.AcsEmbeddedContainerRunner.initManagerProxy(), alma.acs.component.client.ComponentClientTestCase.initRemoteLogging(), alma.acs.component.client.ComponentClient.initRemoteLogging(), and alma.acs.commandcenter.engine.Executor.remoteDaemonForServices().

POA alma.acs.container.corba.AcsCorba.getPOAForOffshoots ( POA componentPOA ) throws AcsJContainerEx, AcsJUnexpectedExceptionEx

Creates (or reuses) the non-persistent POA for offshoot objects as a child of the given POA. In spite of the suggestive name 'componentPOA', this POA can actually be any kind of POA, so that also client application can use the offshoot mechanism.

This method is synchronized inside to avoid race conditions between several offshoot POA creation/retrievals, where otherwise the POA would fail to be created even though first it was not found for reuse.

Parameters:

componentPOA

the POA of the component that owns the offshoot object; will become the parent of the offshoot POA.

Returns:: POA non-persistent POA for offshoot objects for the current component.

Exceptions:

AcsJContainerServicesEx

Referenced by alma.acs.container.corba.AcsCorba.activateOffShoot(), and alma.acs.container.corba.AcsCorba.deactivateOffShoot().

POA alma.acs.container.corba.AcsCorba.getRootPOA ( )

Returns:: the root POA used by the encapsulated ORB

Exceptions:

IllegalStateException

if the ORB has not been initialized before.

References alma.acs.container.corba.AcsCorba.getORB().

Referenced by alma.acs.component.client.ComponentClient.ComponentClient(), alma.acs.component.client.AdvancedComponentClient.createContainerServices(), and alma.acs.commandcenter.engine.Executor.remoteDaemonForServices().

synchronized void alma.acs.container.corba.AcsCorba.initCorba	(	String[]	args,
		int	port
	)			throws AcsJContainerEx

Must be called before initCorba if the container is supposed to host the CDB component without the manager knowing about its component nature... see alma.acs.container.ContainerServicesImplCDBHack.

In CDB mode, the container (ORB) will use port 5 0 0 0, which violates the MACI convention that the port for Containers must be between ($ACS_INSTANCE*100 + 3 0 5 0) and ($ACS_INSTANCE*100 + 3 0 9 9). Since the container initiates all communication, this should not cause any problems.

See also:: com.cosylab.cdb.jdal.Server Initializes the ORB and POAs to be used by a Java container.

Calls setPortOptions to ensure that for container ORBs the specified port gets used. Thus any previous settings of port finding options will be overwritten.

Parameters:

	args	command line arguments for the ORB
	port	fixed port to be used by the ORB; this method will fail if the port is busy, since no retries with different ports will be done.

Exceptions:

AcsJContainerServicesEx

References alma.acs.container.corba.AcsCorba.isInitialized(), alma.acs.logging.AcsLogger.log(), alma.acs.container.corba.AcsCorba.ORB_PROFILER_CLASS_PROPERTYNAME, alma.acs.container.corba.AcsCorba.prepareOrb(), and alma.acs.container.corba.AcsCorba.setPortOptions().

Referenced by alma.acs.commandcenter.engine.ExecuteContainer.startLocalJava().

synchronized POA alma.acs.container.corba.AcsCorba.initCorbaForClient ( boolean isAdmin ) throws Exception

Initializes CORBA for the limited needs of a component client application.

If this class is used for client applications (outside a container), not all methods will be available (currently resulting in NPEs). Mainly getORB() is meant to be used.

Parameters:

isAdmin

if true, support for being an ACS administrator client will be created (TODO -- for Exec)

Returns:: the POA to be used by the client (happens to be the root POA)

Exceptions:

Exception

See also:: alma.acs.component.client.ComponentClient

References alma.acs.container.corba.OrbConfigurator.getOptions(), alma.acs.container.corba.OrbConfigurator.getProperties(), alma.acs.container.corba.AcsCorba.initRootPoa(), alma.acs.container.corba.AcsCorba.isInitialized(), and alma.acs.logging.AcsLogger.log().

Referenced by alma.acs.component.client.ComponentClient.ComponentClient(), alma.acs.commandcenter.meta.Firestarter.giveAcsCorba(), and alma.acs.component.client.ComponentClientTestCase.setUp().

void alma.acs.container.corba.AcsCorba.initRootPoa ( ORB orb ) [protected]

Initializes the m_rootPOA and m_poaManager fields with the root POA and its POA manager.

Exceptions:

AcsJContainerServicesEx

Initializes the root poa on the ORB provided as an argument. Also obtains the POA manager, but does not yet initialize it. See runCorba().

Note that this method does not work on m_orb member variable, since in method trialAndError we use tentative OBRs.

Parameters:

orb

Exceptions:

IllegalStateException

if allocation failed, likely due to an unavailable port. TODO: use a better fitting exception instead

Referenced by alma.acs.container.corba.AcsCorba.initCorbaForClient(), alma.acs.container.corba.AcsCorba.prepareOrb(), and alma.acs.container.corba.AcsCorba.trialAndError().

synchronized boolean alma.acs.container.corba.AcsCorba.isInitialized ( )

Referenced by alma.acs.container.corba.AcsCorba.getORB(), alma.acs.commandcenter.meta.Firestarter.giveAcsCorba(), alma.acs.container.corba.AcsCorba.initCorba(), alma.acs.container.corba.AcsCorba.initCorbaForClient(), alma.acs.container.corba.AcsCorba.setORBLevelRoundtripTimeout(), and alma.acs.container.corba.AcsCorba.wrapForRoundtripTimeout().

void alma.acs.container.corba.AcsCorba.prepareOrb ( String[] args )

Gets an ORB and initializes the root POA using initRootPoa(ORB).

If this method has been called before, the same ORB will be returned. Depending on the values given in setPortOptions(Integer, Integer), a fixed port will be used (resulting in a failure if it can't be obtained), or the port will be chosen from a given range, or the ORB will be allowed to pick a port.

This class is fail-fast in that it tries to create an orb instantly on a call to this method. If this first call goes well, subsequent calls will succeed (aside from other general errors).

Parameters:

args

Exceptions:

AcsJContainerServicesEx

References alma.acs.container.corba.AcsCorba.initRootPoa(), alma.acs.container.corba.AcsCorba.RVtrialAndError.orb, and alma.acs.container.corba.AcsCorba.trialAndError().

Referenced by alma.acs.container.corba.AcsCorba.initCorba().

void alma.acs.container.corba.AcsCorba.runCorba ( ) throws AcsJContainerEx

Runs the ORB and POAs. Currently it calls activate on the poa manager.

Exceptions:

AcsJContainerServicesEx

Referenced by alma.acs.commandcenter.engine.ExecuteContainer.startLocalJava().

synchronized void alma.acs.container.corba.AcsCorba.setLogger ( AcsLogger logger )

void alma.acs.container.corba.AcsCorba.setORBLevelRoundtripTimeout ( double timeoutSeconds ) throws AcsJContainerServicesEx

Sets the roundtrip timeout for all calls going out through the ORB that is encapsulated by this class. For example, this applies to all corba calls made by a container and any of its components.

Parameters:

timeoutSeconds

Exceptions:

AcsJContainerServicesEx

See also:: wrapForRoundtripTimeout(Object, double)

References alma.acs.container.corba.AcsCorba.isInitialized().

Referenced by alma.acs.container.AcsContainer.initialize().

void alma.acs.container.corba.AcsCorba.setPortOptions	(	Integer	orbPort,
		Integer	orbPortSearchRetry
	)

Usage of parameters orbPort and orbPortSearchRetry:

     orbPort | orbPortSearchRetry
 (a)  1234   |    null     : try port 1234-1238
 (b)  1234   |     3       : try port 1234-1236
 (c)  1234   |     0       : use port 1234
 (d)  1234   |    -1       : use port 1234

 (e)  null   |    null     : try port 3075-3079
 (f)  null   |     3       : try port 3075-3077
 (g)  null   |     0       : use port 3075
 (h)  null   |    -1       : let orb choose port

Notes:

3075 can be overridden by system property SYSPROP_FIRESTARTER_OAPORT
(h) will fail miserably if an OAPort has been set in this virtual machine before

The implementation of these port options has been moved here from acscommandcenter.Firestarter.

Parameters:

	orbPort	use `null` for default
	orbPortSearchRetry	use `null` for default

References alma.acs.container.corba.AcsCorba.DEFAULT_PORT, alma.acs.container.corba.AcsCorba.DEFAULT_RETRY, and alma.acs.container.corba.AcsCorba.SYSPROP_FIRESTARTER_OAPORT.

Referenced by alma.acs.commandcenter.meta.Firestarter.giveAcsCorba(), and alma.acs.container.corba.AcsCorba.initCorba().

ComponentServantManager alma.acs.container.corba.AcsCorba.setServantManagerOnComponentPOA ( POA componentPOA ) throws AcsJContainerEx

Creates a servant manager of type ComponentServantManager, attaches it to the POA, and activates the servant manager.

This ComponentServantManager can be used as a semaphore to synchronize with component etherealization during POA destruction.

Note that org.omg.PortableServer.POAOperations#get_servant_manager() will not return the ComponentServantManager implementation class, but instead a proxy object (_ServantActivatorStub).

Parameters:

componentPOA

a component POA

Returns:: the new ComponentServantManager.

Exceptions:

AcsJContainerServicesEx

References alma.acs.logging.AcsLogger.log().

Referenced by alma.acs.container.ComponentAdapter.activateComponent().

void alma.acs.container.corba.AcsCorba.shutdownORB	(	final boolean	wait_for_completion,
		boolean	isOrbThread
	)

Calls m_orb.shutdown(wait_for_completion).

If this method is invoked from an ORB thread (as it happens in the Java container in case of shutdown being commanded by the manager), it returns immediately, independently of the wait_for_completion parameter. The Orb.shutdown call will then run asynchronously. Note that shutting down the ORB from within an ORB thread would result in a deadlock (or BAD_INV_ORDER exception) if wait_for_completion is true. The Java container will nonetheless wait for the ORB shutdown, because its main thread blocks on ORB.run and only continues when the ORB is shut down.

: As a workaround for a JacORB bug (http://www.jacorb.org/cgi-bin/bugzilla/show_bug.cgi?id=537), we currently skim off the ConcurrentModificationException that the unsynchronized HashMap of ClientConnectionManager.shutdown may throw. This should be removed when we upgrade JacORB.

Parameters:

	wait_for_completion	blocks this call until ORB has shut down. Will be effectively `false` if `isOrbThread == true`.
	isOrbThread	must be `true` if the calling thread services a Corba invocation, e.g. to AcsContainer#shutdown. Note that JacORB has the proprietary method `isInInvocationContext`, but we need the explicit flag in order to stay ORB-independent.

Referenced by alma.acs.component.client.ComponentClientTestCase.setUp(), alma.acs.commandcenter.meta.Firestarter.shutdown(), alma.acs.container.AcsContainer.shutdown(), alma.acs.component.client.ComponentClientTestCase.tearDown(), and alma.acs.component.client.ComponentClient.tearDown().

RVtrialAndError alma.acs.container.corba.AcsCorba.trialAndError	(	String[]	args,
		int	first,
		int	retries
	)			`[protected]`

trial-and-error: try out some ports, break on success

References alma.acs.container.corba.AcsCorba.initRootPoa().

Referenced by alma.acs.container.corba.AcsCorba.prepareOrb().

org.omg.CORBA.Object alma.acs.container.corba.AcsCorba.wrapForRoundtripTimeout	(	org.omg.CORBA.Object	corbaRef,
		double	timeoutSeconds
	)			throws AcsJContainerServicesEx

Impl note: The corba spec (v 2.4, 4.3.8.1) describes the difference between SetOverrideType.SET_OVERRIDE and SetOverrideType.ADD_OVERRIDE. It is not clear to me (HSO) which one should be used, or if there is no practical difference.

Parameters: