-- IDL module extracted from ITU-T Q.816.2 (03/2007)
/**
Annex A (Normative) – Service-oriented framework support services IDL
*/
/* This IDL code is intended to be stored in a file named "itut_q816_2.idl"
located in the search path used by IDL compilers on your system. Most comments
are formatted to be parsed by an IDL-to-HTML converter. */
#ifndef ITUT_Q816_2_IDL
#define ITUT_Q816_2_IDL
// ********************************
// * *
// * itut_q816_2.idl *
// * *
// ********************************
/*
This file defines an extensible, service-oriented NML-EML interface
in CORBA IDL, more generally an OS-OS interface according to Rec. M.3010,
where one OS takes a client/manager role (e.g., an NMS) and the other OS
takes a server/agent role (e.g., an EMS). The OS in a client role is called
managing system, and the OS in a server role is called managed system.
The IDL uses the modules "globaldefs" and "common" of the service-oriented
modelling IDL of Recommendation X.780.2 and defines a Session Service
according to Recommendation Q.816.2.
The IDL is organised into the following modules, interfaces,
operations, exceptions, attributes, and data types.
module | interface | operation
-------------------+----------------------------+------------------------------
idlVersion | Version_I | getVersion()
session | Session_I | ping()
| | endSession()
nmsSession | NmsSession_I | eventLossOccurred()
| | eventLossCleared()
| | alarmLossOccurred()
emsSession | EmsSession_I | getSupportedManagers()
| | getManager()
| | getEventChannel()
emsSessionFactory | EmsSessionFactory_I | getEmsSession()
module | exception, attribute | data type
-------------------+----------------------------+------------------------------
idlVersion | - | -
session | associatedSession | -
nmsSession | - | -
emsSession | - | managerNames_T
emsSessionFactory | - | -
*/
// Include list
#include "itut_x780_2.idl"
#include "OMGidl/CosNotifyChannelAdmin.idl"
#pragma prefix "itu.int"
/**
A.1 Module idlVersion
*/
/**
* <p>This module contains the definition of the Version interface
* of the NML-EML interface.</p>
**/
module idlVersion
{
/**
* <p>The interface Version_I allows the NMS to query the current
* version of the IDL interface (IDL version) implemented by the EMS.
* In order to use this CORBA interface, the NMS needs to invoke the
* getVersion() service to figure out which version of the NML-EML interface
* the EMS is providing. getVersion() should be called by any NMS
* before other communications with an EMS. The NMS can determine
* from the response string which IDL version of the EMS is available.</p>
*
* <p>For details on how to support multiple versions of the IDL see
* clause 9.1.2.5/Q.816.2 "Server Session Factory interface" and clause
* 10.5.4/X.780.2 "Versioning of CORBA IDL specifications".</p>
**/
interface Version_I
{
/**
* <p>This service returns the version of the IDL interface (IDL version)
* that the corresponding EMS supports.</p>
*
* <p>The format of the return string is as follows:<br>
* <i>Release</i>.<i>Major</i>[.<i>Minor</i>],
* where <i>Release</i>, <i>Major</i> and <i>Minor</i>
* are strings that contain only digits.</p>
*
* <p>For example, "2.1" indicates release 2 and major release 1,
* "1.3" indicates release 1 and major release 3, and so on.
* Note that "x.y" has the same meaning as "x.y.0".
* The minor digit is used for bug fixing of the major release
* (e.g., "1.2.1" is a minor release on "1.2").</p>
*
* @returns string: The IDL version of the NML-EML interface.
**/
string getVersion();
}; // end of interface
}; // end of module
/**
A.2 Module session
*/
/**
* <p>This module contains the definition of the Session interface
* of the NML-EML interface.</p>
**/
module session
{
/**
* <p>The Session_I interface provides capabilities to manage a
* client/server connection, which is called a session. Its main
* purpose is to enable either a client or a server to detect the
* loss of communication with the associated party.</p>
*
* <p>For a single communication session between an NMS and an EMS, there
* are two Session_I objects. One is maintained on the NMS; the other one
* is maintained on the EMS. The Session_I object maintained on the EMS is
* actually an EmsSession_I while the Session_I object maintained on the
* NMS is actually an NmsSession_I (both inherit from Session_I).</p>
*
* <p>Each Session_I object is responsible to "ping" the other Session_I
* object periodically to detect communication failures. Exactly when this
* is done is up to the implementation.</p>
*
* <p>When a Session_I object detects a communication failure, or when
* the endSession() operation is called on it, all resources allocated
* with that communication session must be freed and the Session_I object
* must be deleted.</p>
**/
interface Session_I
{
/**
* <p>This attribute contains a reference to the Session_I object on the
* other side (NMS/EMS) to which the object is associated. It is readonly.
* The attribute can (and should) be checked to make sure the
* NmsSession_I/EmsSession_I association is still valid
* (in particular in case of communication failures).</p>
**/
readonly attribute Session_I associatedSession;
/**
* <p>Allows for the detection of loss of communication.
* It is implementation-specific to differentiate intermittent
* problems from loss of connection.</p>
**/
void ping();
/**
* <p>Allows for a controlled disconnect between associated parties.
* All resources allocated for this session are deleted by the
* operation. Best-effort semantics are expected of invocations of
* this operation (which does not guarantee delivery of the call);
* the default semantics are exactly-once if the operation successfully
* returns or at-most-once if a (standard) exception is returned.</p>
**/
oneway void endSession();
}; // end of interface
}; // end of module
/**
A.3 Module nmsSession
*/
/**
* <p>This module contains the definition of the NmsSession interface
* of the NML-EML interface.</p>
*
* <p>The nmsSession module provides a means for the server to inform the
* NMS in case of notification losses and termination of a loss period.</p>
**/
module nmsSession
{
/**
* <p>This interface is instantiated at the NMS. The NMS passes a handle
* to an instance of this interface in the client parameter of the
* getEmsSession() operation of EmsSessionFactory_I.</p>
*/
interface NmsSession_I : session::Session_I
{
/**
* <p>When an EMS fails to push an event, it can notify all connected
* NMSes by invoking this method on every active NmsSession_I.
* This method should also be invoked on any new NmsSession_I set up
* during the event loss period.</p>
*
* <p>Once the EMS invokes this method on the NmsSession_Is, it sets
* an internal flag to indicate that it has already informed NMSes of
* event loss. As long as this flag is set, the EMS will not invoke
* this method again. It however may invoke alarmLossOccurred()
* if it discards a non-lifecycle event.</p>
*
* <p>When this method is invoked on an NmsSession_I, the NMS comes to
* know that the EMS has failed to push one or more events that may be
* of interest to it. The NMS should consider itself to be potentially
* out-of-sync with the EMS. It should wait until the EMS calls
* eventLossCleared() before resynchronizing with the EMS.</p>
*
* @parm globaldefs::Time_T <b>startTime</b>: The time of detection of
* the first notification loss.
*
* @parm string <b>notificationId</b>: The notificationId of the first
* notification lost.
**/
void eventLossOccurred(
in globaldefs::Time_T startTime,
in string notificationId);
/**
* <p>The EMS invokes this method to indicate that the event (or
* alarm etc.) loss period is over, and that it is now capable of
* providing all relevant notifications.</p>
*
* <p>After invoking this method on the NmsSession_Is, the EMS clears
* the internal flag set by alarmLossOccured() or/and eventLossOccurred().
* If an event or alarm etc. loss occurs again, alarmLossOccurred() or
* eventLossOccurred() will be called again.</p>
*
* <p>How and when the EMS decides to invoke eventLossCleared() is
* an EMS implementation detail.</p>
*
* @parm globaldefs::Time_T <b>endTime</b>: The time of the end of
* the event loss period, as determined by the EMS.
**/
void eventLossCleared(
in globaldefs::Time_T endTime);
/**
* <p>When an EMS discards an alarm, a TCA, a file transfer status,
* or another non-lifecycle event (with regard to the lifecycle of
* the event source), it can notify all connected NMSes by
* invoking this method on every active NmsSession_I. This service
* should also be invoked on any new NmsSession_I set up during
* the event loss period.</p>
*
* <p>Once the EMS invokes this method on the NmsSession_Is, it sets
* an internal flag to indicate that it has already informed NMSes
* of alarm etc. loss. As long as this flag is set, the EMS will not
* invoke this method again. It however may invoke eventLossOccurred()
* if it fails to push a different type of event.</p>
*
* <p>When this method is invoked on an NmsSession_I, the NMS comes to
* know that the EMS has discarded one or more alarms, TCAs, file
* transfer statuses, or notifications of other types that may be
* of interest to it. The NMS should consider itself to be potentially
* out-of-sync with the EMS with respect to these notification types.
* It should wait until the EMS calls eventLossCleared() before
* resynchronizing with the EMS on alarms, TCAs, file transfer statuses,
* and the other non-lifecycle notification types.</p>
*
* @parm globaldefs::Time_T <b>startTime</b>: The time of the first
* notification discard.
*
* @parm string <b>notificationId</b>: The notificationId of the first
* notification discarded.
**/
void alarmLossOccurred(
in globaldefs::Time_T startTime,
in string notificationId);
}; // end of interface
}; // end of module
/**
A.4 Module emsSession
*/
/**
* <p>This module contains the definition of the EmsSession interface
* of the NML-EML interface.</p>
*
* <p>The emsSession module provides a means for the client to
* interrogate the EMS to determine which manager CORBA interfaces
* (i.e., service-oriented façades) it actually supports. The NMS can
* then retrieve an instance of each of the manager interfaces it
* requires. This capability is achieved using generic IDL so that
* new manager interfaces can be easily added.</p>
*
* <p>The module also provides access to the unique OMG event channel
* to be used within the session.</p>
**/
module emsSession
{
/**
* <p>Sequence of manager names, i.e. a list of names of service-oriented
* façades, as defined by NML-EML interface specifications that extend
* this framework and preferably derived from the IDL names of the manager
* CORBA interfaces that inherit from common::Common_I.</p>
**/
typedef sequence<string> managerNames_T;
/**
* <p>A handle to an instance of this interface is gained via the
* emsSessionInterface parameter of the getEmsSession() operation
* of EmsSessionFactory_I.</p>
*/
interface EmsSession_I : session::Session_I
{
/**
* <p>This allows an NMS to request the manager CORBA interfaces that
* the EMS implements.</p>
*
* @parm managerNames_T <b>supportedManagerList</b>: The list of manager names
* supported by the EMS (see managerNames_T type).
*
* @raises globaldefs::ProcessingFailureException<dir>
* EXCPT_INTERNAL_ERROR - Raised in case of non-specific EMS internal
* failure<br>
* EXCPT_ACCESS_DENIED - Raised in case of security violation<br>
* </dir>
**/
void getSupportedManagers(
out managerNames_T supportedManagerList)
raises(globaldefs::ProcessingFailureException);
/**
* <p>This operation allows an NMS to gain access to an instance of
* the specified manager CORBA interface (i.e., service-oriented façade)
* without using the OMG Naming Service.</p>
*
* @parm string <b>managerName</b>: The class or type name of the manager
* object that the client wants to access (see getSupportedManagers()
* operation).
*
* @parm common::Common_I <b>managerInterface</b>: A CORBA IOR for the manager
* object. The actual object returned will implement the specified manager
* interface. However it is returned as a Common_I object (see module
* common) so that this operation can be generic. The client should
* narrow the returned object reference to the correct object type.
*
* @raises globaldefs::ProcessingFailureException<dir>
* EXCPT_NOT_IMPLEMENTED - Raised if the EMS does not support the manager<br>
* EXCPT_INTERNAL_ERROR - Raised in case of non-specific EMS internal
* failure<br>
* EXCPT_ACCESS_DENIED - Raised in case of security violation<br>
* </dir>
**/
void getManager(
in string managerName,
out common::Common_I managerInterface)
raises(globaldefs::ProcessingFailureException);
/**
* <p>This operation allows an NMS to gain access to the OMG event
* channel to receive notifications. It returns a reference to a
* NotifyChannel interface instance (which is an EventChannel) as
* defined by the OMG Notification Service. When the EMS supports
* the OMG Telecom Log Service, this operation will return a
* reference to a NotifyLog interface instance (which is a
* NotifyChannel and an EventLog).</p>
*
* @parm CosNotifyChannelAdmin::EventChannel <b>eventChannel</b>:
* The event channel (NotifyChannel or NotifyLog) to be used
* by the NMS in this session.
*
* @raises globaldefs::ProcessingFailureException<dir>
* EXCPT_INTERNAL_ERROR - Raised in case of non-specific EMS internal
* failure<br>
* EXCPT_ACCESS_DENIED - Raised in case of security violation<br>
* </dir>
**/
void getEventChannel(
out CosNotifyChannelAdmin::EventChannel eventChannel)
raises(globaldefs::ProcessingFailureException);
}; // end of interface
}; // end of module
/**
A.5 Module emsSessionFactory
*/
/**
* <p>This module contains the definition of the EmsSessionFactory
* interface of the NML-EML interface.</p>
**/
module emsSessionFactory
{
/**
* <p>There is a single instance of the EmsSessionFactory_I (per
* supported IDL version). It is the entry point to the server/EMS.
* This instance provides the object reference that the client/NMS
* uses to connect to the server (if the IDL version fits).</p>
*
* <p>This CORBA interface implements the Version interface and will
* return the server’s IDL version (i.e., the version of the NML-EML
* interface) when getVersion() is called on it.</p>
**/
interface EmsSessionFactory_I : idlVersion::Version_I
{
/**
* <p>This operation allows the client/NMS to obtain the EmsSession_I
* object from which all managers of the server/EMS can be obtained
* (i.e., all service-oriented façade objects actually implemented
* by the server/EMS).</p>
*
* @parm string <b>user</b>: The (registered) user or application that is
* trying to access the EMS. The user name can be the empty string
* to indicate that no authentication mechanism is implemented by the
* EMS. The format is defined by the interface specifications
* that extend this framework.
*
* @parm string <b>password</b>: The password/passphrase of the user; it
* can be the empty string. The format and possible encryption are
* defined by the interface specifications that extend this framework.
*
* @parm nmsSession::NmsSession_I <b>client</b>: A handle to the NmsSession_I
* object, instantiated at the NMS, to which the returned EmsSession_I
* object will be associated.
*
* @parm emsSession::EmsSession_I <b>emsSessionInterface</b>:
* A CORBA IOR for the EmsSession_I interface object instantiated
* for the (authenticated) user.
*
* @raises globaldefs::ProcessingFailureException<dir>
* EXCPT_INTERNAL_ERROR - Raised in case of non-specific EMS internal
* failure<br>
* EXCPT_INVALID_INPUT - Raised when client is invalid (see errorReason
* for details provided by the EMS if applicable)<br>
* EXCPT_ACCESS_DENIED - Raised in case of security violation
* (e.g., when user or password is invalid) (see errorReason
* for details provided by the EMS if applicable)<br>
* </dir>
**/
void getEmsSession(
in string user,
in string password,
in nmsSession::NmsSession_I client,
out emsSession::EmsSession_I emsSessionInterface)
raises(globaldefs::ProcessingFailureException);
}; // end of interface
}; // end of module
#endif // end of #ifndef ITUT_Q816_2_IDL