Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

alma::acs::container::corba::AcsCorba Class Reference

List of all members.

Public Member Functions

 AcsCorba (Logger logger)
void setPortOptions (Integer orbPort, Integer orbPortSearchRetry)
synchronized void setLogger (Logger 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
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

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

Private Member Functions

synchronized void setInitialized (boolean initialized)
void initPOAForContainer () throws AcsJContainerEx
void initPOAForComponents () throws AcsJContainerEx
void setORB (ORB orb) throws IllegalArgumentException
ORB createOrb (String[] args, Integer port)

Private Attributes

org.omg.CORBA.ORB m_orb
POAManager sharedPoaManager
POA m_rootPOA
POA m_containerPOA
POA m_componentPOA
Policy[] m_compPolicies
Policy[] m_offshootPolicies
Logger m_logger
boolean m_isInitialized = false
Integer orbPort
Integer orbPortSearchRetry
boolean isOrbChoosingPort = false

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:

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 Logger  logger  )  [inline]
 

ctor


Member Function Documentation

org.omg.CORBA.Object alma::acs::container::corba::AcsCorba::activateComponent Servant  servant,
String  name,
POA  compPOA
throws AcsJContainerEx [inline]
 

Activates a component using a given component POA.

Parameters:
servant 
name 
compPOA 
Returns:
the component as a CORBA object
Exceptions:
AcsJContainerServicesEx 

org.omg.CORBA.Object alma::acs::container::corba::AcsCorba::activateContainer AcsContainer  container,
String  name
throws AcsJContainerEx [inline]
 

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 [inline]
 

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 

void alma::acs::container::corba::AcsCorba::blockOnORB  )  [inline]
 

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)

ORB alma::acs::container::corba::AcsCorba::createOrb String[]  args,
Integer  port
[inline, private]
 

Creates an ORB with a port determined by the values given in setPortOptions(Integer, Integer).

Aside from the logger, no instance variables are used in this method.

Parameters:
args command line arguments for the ORB
port If port == null, OAPort property will not be set.
Returns:

POA alma::acs::container::corba::AcsCorba::createPOAForComponent String  compName  )  throws AcsJContainerEx [inline]
 

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.

boolean alma::acs::container::corba::AcsCorba::deactivateComponentPOAManager POA  compPOA,
final String  compName,
int  timeoutMillis
[inline]
 

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.

void alma::acs::container::corba::AcsCorba::deactivateOffShoot Servant  servant,
POA  compPOA
throws AcsJContainerEx [inline]
 

boolean alma::acs::container::corba::AcsCorba::destroyComponentPOA POA  compPOA,
ComponentServantManager  compServantManager,
int  timeoutMillis
[inline]
 

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)

void alma::acs::container::corba::AcsCorba::doneCorba  )  [inline]
 

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.

ORB alma::acs::container::corba::AcsCorba::getORB  )  [inline]
 

Returns the ORB instance.

Returns:
ORB
Exceptions:
IllegalStateException if the ORB reference is missing or has not been initialized before.

POA alma::acs::container::corba::AcsCorba::getPOAForOffshoots POA  componentPOA  )  throws AcsJContainerEx, AcsJUnexpectedExceptionEx [inline]
 

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 

POA alma::acs::container::corba::AcsCorba::getRootPOA  )  [inline]
 

Returns:
the root POA used by the encapsulated ORB
Exceptions:
IllegalStateException if the ORB has not been initialized before.

synchronized void alma::acs::container::corba::AcsCorba::initCorba String[]  args,
int  port
throws AcsJContainerEx [inline]
 

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 

synchronized POA alma::acs::container::corba::AcsCorba::initCorbaForClient boolean  isAdmin  )  throws Exception [inline]
 

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

void alma::acs::container::corba::AcsCorba::initPOAForComponents  )  throws AcsJContainerEx [inline, private]
 

Creates m_componentPOA as a child of the root POA. This POA will be the parent of the POAs for the individual components. Uses LifespanPolicyValue.PERSISTENT.

Exceptions:
AcsJContainerServicesEx 

void alma::acs::container::corba::AcsCorba::initPOAForContainer  )  throws AcsJContainerEx [inline, private]
 

void alma::acs::container::corba::AcsCorba::initRootPoa ORB  orb  )  [inline, protected]
 

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

synchronized boolean alma::acs::container::corba::AcsCorba::isInitialized  )  [inline]
 

void alma::acs::container::corba::AcsCorba::prepareOrb String[]  args  )  [inline]
 

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 

void alma::acs::container::corba::AcsCorba::runCorba  )  throws AcsJContainerEx [inline]
 

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

Exceptions:
AcsJContainerServicesEx 

synchronized void alma::acs::container::corba::AcsCorba::setInitialized boolean  initialized  )  [inline, private]
 

synchronized void alma::acs::container::corba::AcsCorba::setLogger Logger  logger  )  [inline]
 

void alma::acs::container::corba::AcsCorba::setORB ORB  orb  )  throws IllegalArgumentException [inline, private]
 

void alma::acs::container::corba::AcsCorba::setORBLevelRoundtripTimeout double  timeoutSeconds  )  throws AcsJContainerServicesEx [inline]
 

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)

void alma::acs::container::corba::AcsCorba::setPortOptions Integer  orbPort,
Integer  orbPortSearchRetry
[inline]
 

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

ComponentServantManager alma::acs::container::corba::AcsCorba::setServantManagerOnComponentPOA POA  componentPOA  )  throws AcsJContainerEx [inline]
 

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 

void alma::acs::container::corba::AcsCorba::shutdownORB final boolean  wait_for_completion,
boolean  isOrbThread
[inline]
 

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.

RVtrialAndError alma::acs::container::corba::AcsCorba::trialAndError String[]  args,
int  first,
int  retries
[inline, protected]
 

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

org.omg.CORBA.Object alma::acs::container::corba::AcsCorba::wrapForRoundtripTimeout org.omg.CORBA.Object  corbaRef,
double  timeoutSeconds
throws AcsJContainerServicesEx [inline]
 

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:
corbaRef 
timeoutSeconds 
Returns:
Exceptions:
AcsJContainerServicesEx 
See also:
setORBLevelRoundtripTimeout(double)


Member Data Documentation

int alma::acs::container::corba::AcsCorba::DEFAULT_PORT = 3075 [protected]
 

int alma::acs::container::corba::AcsCorba::DEFAULT_RETRY = 5 [protected]
 

boolean alma::acs::container::corba::AcsCorba::isOrbChoosingPort = false [private]
 

POA alma::acs::container::corba::AcsCorba::m_componentPOA [private]
 

Policy [] alma::acs::container::corba::AcsCorba::m_compPolicies [private]
 

POA alma::acs::container::corba::AcsCorba::m_containerPOA [private]
 

boolean alma::acs::container::corba::AcsCorba::m_isInitialized = false [private]
 

Logger alma::acs::container::corba::AcsCorba::m_logger [private]
 

Policy [] alma::acs::container::corba::AcsCorba::m_offshootPolicies [private]
 

org.omg.CORBA.ORB alma::acs::container::corba::AcsCorba::m_orb [private]
 

POA alma::acs::container::corba::AcsCorba::m_rootPOA [private]
 

Integer alma::acs::container::corba::AcsCorba::orbPort [private]
 

Integer alma::acs::container::corba::AcsCorba::orbPortSearchRetry [private]
 

POAManager alma::acs::container::corba::AcsCorba::sharedPoaManager [private]
 

final String alma::acs::container::corba::AcsCorba::SYSPROP_FIRESTARTER_OAPORT = "acs.firestarter.oaport" [static]
 


The documentation for this class was generated from the following file:
Generated on Thu Apr 30 02:52:32 2009 for ACS Java API by doxygen 1.3.8