alma.acs.container

Class AcsManagerProxy

java.lang.Object

alma.acs.container.AcsManagerProxy

public class AcsManagerProxy
extends java.lang.Object

Proxy class that encapsulates access to the ACS Manager. See maci.idl for the various types of client, which include container and admin client.

This class is stateful, so there must be one AcsManagerProxy used per client if a process has more than one client to the manager.

Warning: This class is not supposed to be instantiated by components and other non-framework classes. Components should only access this class through ContainerServices.

Author:

hsommer Feb 18, 2003 9:20:14 AM

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.Object	connectorLock The lock should only be held for short periods, the threads executing our API need to be able to retrieve it quickly.
protected java.lang.Thread	connectorThread This thread keeps retrying to log in to the manager.

Constructor Summary

Constructors

Constructor and Description
AcsManagerProxy(java.lang.String managerLoc, org.omg.CORBA.ORB orb, java.util.logging.Logger logger) Constructor stores parameters, but takes no further action.

Method Summary

Modifier and Type	Method and Description
protected void	activateReloginToManagerIfDisconnected()
AcsManagerProxy	createInstance() Creates a new instance, using the same manager, orb and logger.
int	force_release_component(int clientHandle, java.lang.String curl) Calls ManagerOperations#force_release_component(int, String).
ComponentInfo	get_collocated_component(int clientHandle, ComponentSpec c, boolean mark_as_default, java.lang.String target_component_url) Encapsulates si.ijs.maci.ManagerOperations#get_collocated_component(int, si.ijs.maci.ComponentSpec, boolean, java.lang.String).
ComponentInfo[]	get_component_info(int[] componentHandles, java.lang.String name_wc, java.lang.String type_wc, boolean active_only) From maci IDL comments: "Gets all the information that the Manager has about components.
org.omg.CORBA.Object	get_component_non_sticky(int clientHandle, java.lang.String component_url)
org.omg.CORBA.Object	get_component(int clientHandle, java.lang.String component_url, boolean activate) The more restricted version of get_service, only good for getting components.
ComponentInfo	get_default_component(int clientHandle, java.lang.String componentIDLType)
ComponentInfo	get_dynamic_component(int clientHandle, ComponentSpec c, boolean mark_as_default)
org.omg.CORBA.Object	get_service(java.lang.String service_url, boolean includeComponents) Note that in ACS 10.2 the meaning of the second parameter has slightly changed, but should be transparent.
org.omg.CORBA.Object	getComponentNonSticky(int clientHandle, java.lang.String component_url) Gets a component as a "weak client" who does not prevent component unloading in case the other real clients release their references.
static java.lang.String	getLocalManagerCorbaloc()
Manager	getManager() Gets the ACS Manager, either cached or freshly retrieved.
int	getManagerHandle() Returns the handle that the ACS Manager has assigned to the container/client during login.
protected void	handleRuntimeException(java.lang.RuntimeException exc) Invoked by the manager methods on failure.
void	loginToManager(Client managerClient, int attempts) Logs in to the manager, using the provided manager client CORBA object.
void	logoutFromManager() Logs out from the manager.
boolean	pingManager(long timeoutMillis) Pings the manager.
int	register_component(java.lang.String component_url, java.lang.String type, org.omg.CORBA.Object component) From maci IDL comments: "Registers a CORBA object as a component, assigning it a CURL and making it accessible through the Manager.
void	release_component(int clientHandle, java.lang.String component_url, CBlong callback) From maci IDL comments: "Asynchronously release a component.
void	shutdownNotify() Notification that the container is in the process of shutting down.

Methods inherited from class java.lang.Object

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

Field Detail

connectorLock

protected final java.lang.Object connectorLock

The lock should only be held for short periods, the threads executing our API need to be able to retrieve it quickly. TODO: replace with lock from concurrent lib

connectorThread

protected final java.lang.Thread connectorThread

This thread keeps retrying to log in to the manager. Before each attempt, it checks whether some outside-world caller of loginToManager() has meanwhile accomplished to log in. notify() on the lock will awake the thread, interrupt() will terminate the thread. msc(2005-07)

Constructor Detail

AcsManagerProxy

public AcsManagerProxy(java.lang.String managerLoc,
                       org.omg.CORBA.ORB orb,
                       java.util.logging.Logger logger)

Constructor stores parameters, but takes no further action.

Parameters:

managerLoc - corbaloc string for the Manager

orb - active ORB; provided explicitly rather than using AcsCorba, so we can easily reuse this class for clients outside of the container.

logger -

Method Detail

getManager

public Manager getManager()
                   throws AcsJContainerEx

Gets the ACS Manager, either cached or freshly retrieved. Note that no login is done here, so call #loginToManager(Client, boolean) after this.

Returns:

Manager

Throws:

AcsJContainerServicesEx

AcsJContainerEx

activateReloginToManagerIfDisconnected

protected void activateReloginToManagerIfDisconnected()

handleRuntimeException

protected void handleRuntimeException(java.lang.RuntimeException exc)

Invoked by the manager methods on failure. The "handling" of the exception refers to changing the connection status, logging the exception, etc. This method will not throw the given exception, which means that the calling client has to do this herself.

loginToManager

public void loginToManager(Client managerClient,
                           int attempts)
                    throws AcsJContainerEx

Logs in to the manager, using the provided manager client CORBA object. This method only returns when the login succeeded. Otherwise an exception is thrown.

Parameters:

managerClient - the IDL-defined client of the manager (see maci.idl), of which the container is a subclass.

attempts - The number of attempts to find and login (0 means forever) If 0, a background thread is started to re-login if the connection breaks.

Throws:

AcsJContainerServicesEx

AcsJContainerEx

pingManager

public boolean pingManager(long timeoutMillis)

Pings the manager. Uses a separate thread so that life can go on if the manager does not respond, and the ORB timeout is too long for this purpose.

Currently calls get_client_info to see if the manager responds. Todo: should be replaced by a call to Manager.ping when this is available.

Parameters:

timeoutMillis - timout in milliseconds that can restrict the general ORB timeout.

Returns:

true if the manager responded within the given time, false otherwise

See Also:

isLoggedIn(boolean)

logoutFromManager

public void logoutFromManager()

Logs out from the manager. If this fails, a warning is logged, but no exception will be thrown by this method.

get_component_info

public ComponentInfo[] get_component_info(int[] componentHandles,
                                          java.lang.String name_wc,
                                          java.lang.String type_wc,
                                          boolean active_only)
                                   throws AcsJNoPermissionEx

From maci IDL comments: "Gets all the information that the Manager has about components. To invoke this method, the caller must have INTROSPECT_MANAGER access rights, or it must have adequate privileges to access the component (the same as with the get_service method). Information about all components is returned, unless the active_only parameter is set to True, in which case only information about those components that are currently registered with the Manager and activated is returned. Calling this function does not affect the internal state of the Manager."

Parameters:

componentHandles - Handles of the components whose information is requested. If this is an empty sequence, the name_wc and type_wc parameters are used.

name_wc - Wildcard that the component's name must match in order for its information to be returned.

type_wc - Wildcard that the component's type must match in order for its information to be returned.

active_only -

Returns:

si.ijs.maci.ComponentInfo[] A sequence of ComponentInfo structures containing the entire Manager's knowledge about the components. If access is denied to a subset of objects, the handles to those objects are set to 0.

Throws:

AcsJNoPermissionEx

get_service

public org.omg.CORBA.Object get_service(java.lang.String service_url,
                                        boolean includeComponents)
                                 throws AcsJComponentNotAlreadyActivatedEx,
                                        AcsJCannotGetComponentEx,
                                        AcsJComponentConfigurationNotFoundEx,
                                        AcsJNoPermissionEx

Note that in ACS 10.2 the meaning of the second parameter has slightly changed, but should be transparent. Before it was the "activate" option which makes no sense for real services and would typically be "true" when using this method for components rather than real services. Now "true" still means that the service should be activated, but "false" has the new meaning that we don't use the client handle, but instead use dummy handle '0'. This allows the container to get the CDB reference before logging in to the manager.

Returns:

org.omg.CORBA.Object Reference to the service. If the service could not be activated, a nil reference is returned, and the status contains an error code detailing the cause of failure (one of the component_* constants).

Throws:

AcsJComponentNotAlreadyActivatedEx

AcsJCannotGetComponentEx

AcsJComponentConfigurationNotFoundEx

AcsJNoPermissionEx

get_component

public org.omg.CORBA.Object get_component(int clientHandle,
                                          java.lang.String component_url,
                                          boolean activate)
                                   throws AcsJCannotGetComponentEx,
                                          AcsJComponentNotAlreadyActivatedEx,
                                          AcsJComponentConfigurationNotFoundEx,
                                          AcsJNoPermissionEx

The more restricted version of get_service, only good for getting components.

Parameters:

clientHandle - handle of requesting component or other kind of client (for non-container clients this will always be the login-handle)

component_url - to specify the requested component

activate -

status - status out-parameter

Returns:

the component reference (must still be narrowed using the appropriate Corba helper)

Throws:

AcsJCannotGetComponentEx

AcsJComponentNotAlreadyActivatedEx

AcsJComponentConfigurationNotFoundEx

AcsJNoPermissionEx

See Also:

ContainerServices.getComponent(String)

get_component_non_sticky

public org.omg.CORBA.Object get_component_non_sticky(int clientHandle,
                                                     java.lang.String component_url)
                                              throws AcsJCannotGetComponentEx,
                                                     AcsJComponentNotAlreadyActivatedEx,
                                                     AcsJNoPermissionEx

Throws:

AcsJCannotGetComponentEx

AcsJComponentNotAlreadyActivatedEx

AcsJNoPermissionEx

getComponentNonSticky

public org.omg.CORBA.Object getComponentNonSticky(int clientHandle,
                                                  java.lang.String component_url)
                                           throws AcsJComponentNotAlreadyActivatedEx,
                                                  AcsJCannotGetComponentEx,
                                                  AcsJNoPermissionEx

Gets a component as a "weak client" who does not prevent component unloading in case the other real clients release their references. Otherwise similar to get_component with activate==false.

Parameters:

clientHandle -

component_url -

Returns:

the component reference (must still be narrowed using the appropriate Corba helper)

Throws:

AcsJComponentNotAlreadyActivatedEx - if the requested component has not already been activated by some other client

AcsJCannotGetComponentEx

AcsJUnexpectedExceptionEx - if the remote call failed with a (CORBA) runtime exception

AcsJNoPermissionEx

Since:

ACS 6.0

get_default_component

public ComponentInfo get_default_component(int clientHandle,
                                           java.lang.String componentIDLType)
                                    throws AcsJNoDefaultComponentEx,
                                           AcsJCannotGetComponentEx,
                                           AcsJNoPermissionEx

Parameters:

clientHandle - handle of requesting component or other kind of client (for non-container clients this will always be the login-handle)

componentIDLType - the IDL type

Throws:

AcsJNoDefaultComponentEx

AcsJCannotGetComponentEx

AcsJNoPermissionEx

See Also:

ContainerServices.getDefaultComponent(String)

get_dynamic_component

public ComponentInfo get_dynamic_component(int clientHandle,
                                           ComponentSpec c,
                                           boolean mark_as_default)
                                    throws AcsJIncompleteComponentSpecEx,
                                           AcsJInvalidComponentSpecEx,
                                           AcsJComponentSpecIncompatibleWithActiveComponentEx,
                                           AcsJCannotGetComponentEx,
                                           AcsJNoPermissionEx

Parameters:

clientHandle - handle of requesting component or other kind of client (for non-container clients this will always be the login-handle)

c - dynamic version of deployment info, may be incomplete, see ACS documentation

mark_as_default - if true, make the new component instance the default for its type

Returns:

a struct which contains the corba reference, as well as name, type, etc.

Throws:

si.ijs.maci.IncompleteComponentSpec

si.ijs.maci.InvalidComponentSpec - Thrown if there is no valid dynamic component found for given resulting structure.

si.ijs.maci.ComponentSpecIncompatibleWithActiveComponent - Thrown if the resulting structure is incompatible with a component of the same name already active.

AcsJIncompleteComponentSpecEx

AcsJInvalidComponentSpecEx

AcsJComponentSpecIncompatibleWithActiveComponentEx

AcsJCannotGetComponentEx

AcsJNoPermissionEx

get_collocated_component

public ComponentInfo get_collocated_component(int clientHandle,
                                              ComponentSpec c,
                                              boolean mark_as_default,
                                              java.lang.String target_component_url)
                                       throws AcsJIncompleteComponentSpecEx,
                                              AcsJInvalidComponentSpecEx,
                                              AcsJComponentSpecIncompatibleWithActiveComponentEx,
                                              AcsJCannotGetComponentEx,
                                              AcsJNoPermissionEx

Encapsulates si.ijs.maci.ManagerOperations#get_collocated_component(int, si.ijs.maci.ComponentSpec, boolean, java.lang.String).

Parameters:

clientHandle - handle of requesting component or other kind of client (for non-container clients this will always be the login-handle)

c - dynamic version of deployment info, may be incomplete, see ACS documentation

mark_as_default - if true, make the new component instance the default for its type

target_component_url -

Returns:

ComponentInfo struct

Throws:

IncompleteComponentSpec

InvalidComponentSpec

ComponentSpecIncompatibleWithActiveComponent

AcsJIncompleteComponentSpecEx

AcsJInvalidComponentSpecEx

AcsJComponentSpecIncompatibleWithActiveComponentEx

AcsJCannotGetComponentEx

AcsJNoPermissionEx

register_component

public int register_component(java.lang.String component_url,
                              java.lang.String type,
                              org.omg.CORBA.Object component)
                       throws AcsJCannotRegisterComponentEx,
                              AcsJNoPermissionEx

From maci IDL comments: "Registers a CORBA object as a component, assigning it a CURL and making it accessible through the Manager. The component is treated as an immortal component."

Parameters:

component_url -

type -

component -

Returns:

int

Throws:

AcsJCannotRegisterComponentEx

AcsJNoPermissionEx

release_component

public void release_component(int clientHandle,
                              java.lang.String component_url,
                              CBlong callback)
                       throws AcsJNoPermissionEx

From maci IDL comments: "Asynchronously release a component. In order for this operation to be possible, the caller represented by the id must have previously successfully requested the component via a call to get_component. Releasing a component more times than requesting it should be avoided, but it produces no errors. This method will return before the manager/target container have deactivated the component. If the caller wants to synchronize with component deactivation, it must supply the optional CBlong callback."

Parameters:

clientHandle - handle of requesting component or other kind of client (for non-container clients this will always be the login-handle)

component_url -

callback - to synch on actual component release, receive possible exceptions, and returned number of remaining clients (which could be a useful debugging tool).

Throws:

AcsJNoPermissionEx - If this client does not hold a valid reference to the target component.

java.lang.RuntimeException - such as BAD_PARAM, NO_PERMISSION, NO_RESOURCES, OBJECT_NOT_EXIST, TIMEOUT, TRANSIENT UNKNOWN

force_release_component

public int force_release_component(int clientHandle,
                                   java.lang.String curl)
                            throws AcsJNoPermissionEx

Calls ManagerOperations#force_release_component(int, String). This call must not be used by regular component code. It is only provided for setting up tests, writing specialized operator tools, and similar purposes.

Returns:

number of clients of the force-released components.

Throws:

AcsJNoPermissionEx

Since:

ACS 5.0.4

getManagerHandle

public int getManagerHandle()

Returns the handle that the ACS Manager has assigned to the container/client during login. The handle should always be retrieved from here instead of storing its value outside of this class, so that a change in handle after a reconnect can be propagated.

Returns:

handle, or 0 if not logged in

shutdownNotify

public void shutdownNotify()

Notification that the container is in the process of shutting down.

With ACS 7.0.2 this method is no longer synchronized because it deadlocked the shutdown hook thread when the manager proxy was in a login loop. See COMP-2602.

getLocalManagerCorbaloc

public static java.lang.String getLocalManagerCorbaloc()

createInstance

public AcsManagerProxy createInstance()

Creates a new instance, using the same manager, orb and logger. The new instance can then be used to log in to the manager (again) independently of this instance.

There is no communication between this instance and the new instance. For example, a call to shutdownNotify() will not be forwarded.