acsdaemon::ServicesDaemon Interface Reference

import "acsdaemon.idl";

Inheritance diagram for acsdaemon::ServicesDaemon:

Collaboration diagram for acsdaemon::ServicesDaemon:

List of all members.

Public Member Functions
ServiceDefinitionBuilder	create_service_definition_builder (in short instance_number) raises (ACSErrTypeCommon::BadParameterEx, ACSErrTypeCommon::NoResourcesEx)
void	start_services (in services_definition_xml definition, in boolean reuse_services, in DaemonSequenceCallback callback) raises (ACSErrTypeCommon::BadParameterEx)
void	stop_services (in services_definition_xml definition, in DaemonSequenceCallback callback) raises (ACSErrTypeCommon::BadParameterEx)
void	start_acs (in DaemonSequenceCallback callback, in short instance_number, in string flags) raises (ACSErrTypeCommon::BadParameterEx)
void	stop_acs (in DaemonSequenceCallback callback, in short instance_number, in string flags) raises (ACSErrTypeCommon::BadParameterEx)
string	status_acs (in short instance_number) raises (acsdaemonErrType::FailedToGetAcsStatusEx)
void	shutdown () raises (maciErrType::NoPermissionEx)
void	set_manager_reference (in short instance_number, in string ref)

---

Detailed Description

The services daemon starts, stops and monitors the ACS services on one or more host machine(s). This daemon must persist any state data (such as user-defined notification service name-to-port mappings) to allow simply restarting it in the event of a crash.

Use of this daemon is the generally recommended startup mechanism for ACS, although for limited tests with all services running on one machine and w/o requirement for service monitoring, it may be sufficient to run the "acsStart" and "acsStop" scripts directly without using the services daemon at all.

There are three different ways to start the ACS services through this daemon:

1. Call directly the start_xyz (stop_xyz) for every service that should be run on this daemon's host. Here the client is responsible for the correct order and timing of these calls. The services will not be validated (e.g. missing manager, more than one naming service). The client must talk to the daemons on all the machines where ACS services should be started/stopped.
2. Create a services definition and have all services started via start_services. This can be done through a new ServiceDefinitionBuilder (from create_service_definition_builder or by reusing its output from previous runs). When there are multiple services daemons running in the system (but only 1 per computer), a client is free to arbitrarily chose one services daemon to define and execute the services definition. For that client, this particular services daemon instance becomes the "master" which can command the other services daemons if their hosts are referenced in the services description.
3. Call start_acs to run default services on the local host. The daemon will either run the acsStart script or otherwise emulate it.

The stopping of the services must be done symmetrically to the starting, i.e. calling stop_xyz methods, stop_services, acsStop.

Todo:

About asynchronous calls that use DaemonSequenceCallback: describe the possible exceptions and intermediate/final result!

About daemon deployment (this info does not quite belong into the interface documentation, but for practical purposes seems justified):
A single instance of this daemon must be running on all computers on which ACS services should be started. The daemon can be started by a boot script, SNMP or other mechanism using the command "acsservicesdaemon". It may be started by a different user than the one later running ACS. The daemon can be found using "corbaloc::host:3014/ACSServicesDaemon".

---

Member Function Documentation

ServiceDefinitionBuilder acsdaemon::ServicesDaemon::create_service_definition_builder

(

in short

instance_number

)

raises (ACSErrTypeCommon::BadParameterEx, ACSErrTypeCommon::NoResourcesEx)

Creates and retrieves a reference to a ServiceDescriptionBuilder instance. (Make sure to call ServiceDescriptionBuilder#close when done with it.)

This call may fail with a NoResourcesEx if 10 instances are already active, or if for another reason the daemon determines that its proper functioning would be jeopardized by creating the ServicesDaemonStartupSequence. This call will fail with BadParameterEx if the "instance_number" is invalid.

Parameters:

instance_number

The ACS instance (as in ACS_INSTANCE env var) to be started. In an operational environment this should always be 0 (i.e. no coexistence of multiple instances!) With ACS 8.0, it will no longer be possible to use collaborating services running as different ACS instances on different machines.

Returns:

ServicesDaemonStartupSequence

void acsdaemon::ServicesDaemon::set_manager_reference	(	in short	instance_number,
		in string	ref
	)

Set corrensponding manager reference. NOTE: this is used to initialize alarm system.

void acsdaemon::ServicesDaemon::shutdown

(

)

raises (maciErrType::NoPermissionEx)

Shuts down the daemon.

Returns:

void

---

void acsdaemon::ServicesDaemon::start_acs	(	in DaemonSequenceCallback	callback,
		in short	instance_number,
		in string	flags
	)			raises (ACSErrTypeCommon::BadParameterEx)

Starts ACS services. Returns immediately. The client will be notified through the callback object when the services are up, or if an error has occurred.

Returns:

void

---

void acsdaemon::ServicesDaemon::start_services	(	in services_definition_xml	definition,
		in boolean	reuse_services,
		in DaemonSequenceCallback	callback
	)			raises (ACSErrTypeCommon::BadParameterEx)

Asynchronously starts the defined services. This method can be called on any services daemon in the system, which will forward the calls to the daemons on the other hosts according to the services definition.

Exceptions are forwarded to the callback handler. If a service cannot be started, the starting sequence will be abandoned, but the services that have been started already will be left running. This allows the client to either fix the problem and call this method again (with reuse_services=true) to complete the startup, or to stop the services. If a defined service is running already, it will be reused if "reuse_services" is true. Otherwise it will be considered a failure (see above).

Todo:

We must define if (and using which rules) the services description should be validated before actually executing the startup, and what exceptions / notifications should be sent to the callback interface. Or should we validate during the synchronous call and throw a BadParameterEx if the service description is invalid because of missing or too many services?

Parameters:

	definition	see ServiceDefinitionBuilder#get_services_definition.
	reuse_services	if true then ServiceAlreadyRunning exceptions from the start_xyz methods will be ignored, otherwise they are considered failures.
	callback	DaemonSequenceCallback instance to receive notifications on startup sequence progress.

See also:

ServicesDaemon::stop_services();

string acsdaemon::ServicesDaemon::status_acs

(

in short

instance_number

)

raises (acsdaemonErrType::FailedToGetAcsStatusEx)

Returns status of ACS (i.e. invokes acsStatus). instance_number ACS instance number

Returns:

string Status of ACS.

---

return a structure or similar instead string

void acsdaemon::ServicesDaemon::stop_acs	(	in DaemonSequenceCallback	callback,
		in short	instance_number,
		in string	flags
	)			raises (ACSErrTypeCommon::BadParameterEx)

Stops ACS services. Returns immediately. The client will be notified through the callback object when the services are stopped, or if an error has occurred.

Returns:

void

---

void acsdaemon::ServicesDaemon::stop_services	(	in services_definition_xml	definition,
		in DaemonSequenceCallback	callback
	)			raises (ACSErrTypeCommon::BadParameterEx)

Asynchronously shuts down the services that were executed via the specified services definition. This method can be called on any services daemon in the system, which will forward the calls to the daemons on the other hosts according to the services definition. The shutdown order is determined by the daemon.

If one of the given services is found to be not running (ServiceNotRunning exception from any of the stop_ methods) then the client will be notified via the callback, but the execution of this method will continue.

Parameters:

	definition	Sequence descriptor XML.
	callback	DaemonSequenceCallback instance to receive notification about completion or problems with the service stop.

Returns:

void

See also:

ServicesDaemonStartupSequence::start_services();

---

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

• acsdaemon.idl