alma::acs::container::ContainerServices Interface Reference

Inheritance diagram for alma::acs::container::ContainerServices:

Collaboration diagram for alma::acs::container::ContainerServices:

Classes
interface	ComponentListener
Public Member Functions
ComponentStateManager	getComponentStateManager ()
org.omg.CORBA.Object	getComponent (String componentUrl) throws AcsJContainerServicesEx
org.omg.CORBA.Object	getComponentNonSticky (String curl) throws AcsJContainerServicesEx
org.omg.CORBA.Object	getDefaultComponent (String componentIDLType) throws AcsJContainerServicesEx
org.omg.CORBA.Object	getCollocatedComponent (String compUrl, String targetCompUrl) throws AcsJContainerServicesEx
org.omg.CORBA.Object	getCollocatedComponent (ComponentQueryDescriptor compSpec, boolean markAsDefaul, String targetCompUrl) throws AcsJContainerServicesEx
org.omg.CORBA.Object	getDynamicComponent (ComponentQueryDescriptor compSpec, boolean markAsDefault) throws AcsJContainerServicesEx
org.omg.CORBA.Object	getDynamicComponent (ComponentSpec compSpec, boolean markAsDefault) throws AcsJContainerServicesEx
String[]	findComponents (String curlWildcard, String typeWildcard) throws AcsJContainerServicesEx
ComponentDescriptor	getComponentDescriptor (String componentUrl) throws AcsJContainerServicesEx
void	releaseComponent (String componentUrl)
void	registerComponentListener (ComponentListener listener)
org.omg.CORBA.Object	getReferenceWithCustomClientSideTimeout (org.omg.CORBA.Object originalCorbaRef, double timeoutSeconds) throws AcsJContainerServicesEx
void	assignUniqueEntityId (EntityT entity) throws AcsJContainerServicesEx
public< T > T	getTransparentXmlComponent (Class< T > transparentXmlIF, org.omg.CORBA.Object componentReference, Class flatXmlIF) throws AcsJContainerServicesEx

Detailed Description

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

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

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

Author:: hsommer

Member Function Documentation

void alma::acs::container::ContainerServices::assignUniqueEntityId ( EntityT entity ) throws AcsJContainerServicesEx

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.

Parameters:

entity

must be freshly created and

Implemented in alma::acs::container::ContainerServicesImpl.

Referenced by alma::ACSCOURSE_MOUNT::Mount6Impl::Mount6Impl::createMyXmlConfigData(), alma::demo::XmlComponentImpl::XmlComponentImpl::createObsProposal(), and alma::demo::XmlComponentImpl::XmlComponentImpl::initialize().

String [] alma::acs::container::ContainerServices::findComponents	(	String	curlWildcard,
		String	typeWildcard
	)			throws AcsJContainerServicesEx

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.

Parameters:

	curlWildcard	(`null` is understood as "*")
	typeWildcard	(`null` is understood as "*")

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

See also:: si.ijs.maci.ManagerOperations::get_component_info(int, int[], java.lang.String, java.lang.String, boolean)

Implemented in alma::acs::container::ContainerServicesImpl.

Referenced by alma::ACS::MasterComponentImpl::tool::MasterComponentEventLogger::checkCurrentMasterComponents(), and cl::utfsm::samplingSystemUI::core::ComponentsManager::getComponentsName().

org.omg.CORBA.Object alma::acs::container::ContainerServices::getCollocatedComponent	(	ComponentQueryDescriptor	compSpec,
		boolean	markAsDefaul,
		String	targetCompUrl
	)			throws AcsJContainerServicesEx

Dynamic version of getCollocatedComponent(String, String).

Parameters:

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

Exceptions:

AcsJContainerServicesEx

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

Since:: ACS 6.0.4

Implemented in alma::acs::container::ContainerServicesImpl.

org.omg.CORBA.Object alma::acs::container::ContainerServices::getCollocatedComponent	(	String	compUrl,
		String	targetCompUrl
	)			throws AcsJContainerServicesEx

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

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.

Exceptions:

AcsJContainerServicesEx

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

Since:: ACS 5.0.3

Implemented in alma::acs::container::ContainerServicesImpl.

org.omg.CORBA.Object alma::acs::container::ContainerServices::getComponent ( String componentUrl ) throws AcsJContainerServicesEx

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", "LoggingChannel", "InterfaceRepository", "CDB", "ACSLogSvc", "PDB"; It seems that if such access is needed, specialized methods should be added to this interface, like 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.

Parameters:

componentUrl

the ACS CURL of the deployed component instance.

Returns:: the CORBA proxy for the component.

Exceptions:

AcsJContainerServicesEx

if something goes wrong.

Implemented in alma::acs::container::ContainerServicesImpl.

Referenced by alma::ACS::MasterComponentImpl::tool::MasterComponentEventLogger::checkCurrentMasterComponents(), alma::acs::container::OtherComponentClient::getComponent(), alma::demo::LampAccessImpl::LampAccessImpl::getLampBrightnessProperty(), alma::demo::client::LampComponentClient1::LampComponentClient1(), alma::demo::XmlComponentImpl::XmlComponentImpl::sayHello(), alma::demo::client::XmlComponentClient::setUp(), alma::ACS::SpecialTestMasterComponentImpl::SpecialTestMasterComponentTest::setUp(), alma::acs::callbacks::SampleRequester::setUp(), alma::ACS::MasterComponentImpl::MasterComponentTest::setUp(), alma::demo::client::LampAccessClient::setUp(), alma::acs::container::ComponentTestclient::setUp(), alma::acs::container::ComponentTestclient::testComponentListening(), alma::demo::test::DemoTest::testCppComponents(), alma::acs::component::client::AdvancedComponentClientTest::testCreateContainerServices(), alma::acs::container::ComponentTestclient::testGetComponentNonSticky(), alma::demo::test::DemoTest::testJavaMR(), alma::demo::test::DemoTest::testJavaNR(), and alma::acs::container::ComponentTestclient::testTimeout().

ComponentDescriptor alma::acs::container::ContainerServices::getComponentDescriptor ( String componentUrl ) throws AcsJContainerServicesEx

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.

Parameters:

componentUrl

the unique name of a component

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

Exceptions:

ContainerException if componentUrl is unknown or anything else goes wrong

See also:: si.ijs.maci.ComponentInfo

Implemented in alma::acs::container::ContainerServicesImpl.

Referenced by cl::utfsm::samplingSystemUI::core::ComponentsManager::getComponentProperties(), and cl::utfsm::samplingSystemUI::SampTool::initializeComponents().

org.omg.CORBA.Object alma::acs::container::ContainerServices::getComponentNonSticky ( String curl ) throws AcsJContainerServicesEx

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.

Parameters:

curl

the component URL (component instance name)

Returns:: the CORBA proxy for the component.

Exceptions:

AcsJContainerServicesEx

if something goes wrong

Since:: ACS 6.0

Implemented in alma::acs::container::ContainerServicesImpl.

ComponentStateManager alma::acs::container::ContainerServices::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.

Returns:: the state manager

See also:: alma.ACS.ComponentStates

Implemented in alma::acs::container::ContainerServicesImpl.

Referenced by alma::contLogTest::TestLogLevelsCompImpl::TestLogLevelsCompImpl::componentState(), alma::lifecycleTest::TestLifeCycleCompImpl::TestLifeCycleCompImpl::componentState(), alma::test::corbareftest::component::HelloWorldImpl::componentState(), alma::demo::HelloDemoImpl::HelloDemoImpl::componentState(), alma::COUNTER::CounterSupplierImpl::CounterSupplierImpl::componentState(), alma::COUNTER::CounterConsumerImpl::CounterConsumerImpl::componentState(), alma::acs::component::ComponentImplBase::componentState(), and alma::acs::component::client::AdvancedComponentClientTest::testCreateContainerServices().

org.omg.CORBA.Object alma::acs::container::ContainerServices::getDefaultComponent ( String componentIDLType ) throws AcsJContainerServicesEx

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

Parameters:

componentIDLType

Returns:

Exceptions:

AcsJContainerServicesEx

Implemented in alma::acs::container::ContainerServicesImpl.

Referenced by alma::acs::container::corba::ThreadDelayTest::setUp(), alma::acs::container::corba::ContainerMonitorTest::setUp(), and alma::acs::container::corba::ClientPendingReplyTimeoutTest::testClientPendingReplyTimeout().

org.omg.CORBA.Object alma::acs::container::ContainerServices::getDynamicComponent	(	ComponentSpec	compSpec,
		boolean	markAsDefault
	)			throws AcsJContainerServicesEx

More powerful and thus more dangerous version of getDynamicComponent(ComponentQueryDescriptor, boolean) which exposes a CORBA struct directly.

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.

Deprecated:: use getDynamicComponent(ComponentQueryDescriptor, boolean) instead. if you need to set not only the standard fields component_name or component_type, but also the more advanced values component_code or container_name, please send a request to ACS so that access to these fields be included in the ComponentQueryDescriptor given to the recommended version of this method.

Implemented in alma::acs::container::ContainerServicesImpl.

org.omg.CORBA.Object alma::acs::container::ContainerServices::getDynamicComponent	(	ComponentQueryDescriptor	compSpec,
		boolean	markAsDefault
	)			throws AcsJContainerServicesEx

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

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.

Implemented in alma::acs::container::ContainerServicesImpl.

Referenced by alma::acs::container::corba::AcsCorbaTestWithContainer::_testComponentPOALifecycle(), and alma::acs::container::corba::AcsCorbaTestWithContainer::testParallelCalls().

org.omg.CORBA.Object alma::acs::container::ContainerServices::getReferenceWithCustomClientSideTimeout	(	org.omg.CORBA.Object	originalCorbaRef,
		double	timeoutSeconds
	)			throws AcsJContainerServicesEx

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.

Parameters:

	corbaRef	Reference to a component or an offshoot as obtained from some of the other container services methods.
	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.

Implemented in alma::acs::container::ContainerServicesImpl.

Referenced by alma::acs::container::ComponentTestclient::testTimeout().

public<T> T alma::acs::container::ContainerServices::getTransparentXmlComponent	(	Class< T >	transparentXmlIF,
		org.omg.CORBA.Object	componentReference,
		Class	flatXmlIF
	)			throws AcsJContainerServicesEx

Converts a "flat-XML" component interface (as obtained from the various getComponent methods) to a "transparent-XML" component interface. This is only applicable to components 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.

The container can fulfill this request in two different ways:

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

Parameters:

	transparentXmlIF	component interface with XML binding classes.
	componentReference	reference to the component to be wrapped, as obtained through `getComponent(String)`, thus implements `flatXmlIF`.
	flatXmlIF	component interface where entity objects are represented as serialized XML inside a CORBA struct.

Returns:: the object that implements transparentXmlIF.

Implemented in alma::acs::container::ContainerServicesImpl.

Referenced by alma::demo::client::XmlComponentClient::setUp().

void alma::acs::container::ContainerServices::registerComponentListener ( 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).

If the client wants to get notified even for components that it does not hold a reference to, then ComponentListener::includeForeignComponents() should return true. ContainerServices

Parameters:

listener

See also:: si.ijs.maci.ClientOperations::components_available(si.ijs.maci.ComponentInfo[])

Since:: ACS 6.0

Implemented in alma::acs::container::ContainerServicesImpl.

Referenced by alma::acs::container::ComponentTestclient::testComponentListening().

void alma::acs::container::ContainerServices::releaseComponent ( String componentUrl )

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

This method will return only when the component has actually been released, which may take some time in case there are still active requests being processed.

Parameters:

componentUrl

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

Implemented in alma::acs::container::ContainerServicesImpl.

Referenced by alma::acs::container::corba::AcsCorbaTestWithContainer::_testComponentPOALifecycle(), alma::demo::LampAccessImpl::LampAccessImpl::cleanUp(), alma::demo::test::client::SupplierCDBChannelTest::cleanupNC(), alma::demo::test::client::EventILComponentTest::cleanupNC(), alma::demo::test::client::EventComponentTest::cleanupNC(), cl::utfsm::samplingSystemUI::core::SamplingManager::finalize(), alma::acs::container::OtherComponentClient::forceReleaseComponent(), cl::utfsm::samplingSystemUI::core::SamplingManager::getSampReference(), alma::acssamp::jtest::acssampSupplier::sampleLampBrightness(), alma::demo::XmlComponentImpl::XmlComponentImpl::sayHello(), alma::contLogTest::TestLogLevelsCompImpl::TestLogLevelsCompTest::tearDown(), alma::COUNTER::CounterTestImpl::CounterTest::tearDown(), alma::demo::test::client::AbstractNCComponentTest::tearDown(), alma::demo::test::DemoTest::testCppComponents(), alma::acs::container::ComponentTestclient::testGetComponentNonSticky(), alma::demo::test::DemoTest::testJavaMR(), alma::demo::test::DemoTest::testJavaNR(), and alma::acs::container::ComponentTestclient::testTimeout().

The documentation for this interface was generated from the following file:

CommonSoftware/jcont/src/alma/acs/container/ContainerServices.java

alma::acs::container::ContainerServices Interface Reference

Classes

Public Member Functions

Detailed Description

Member Function Documentation