OSI Management Facilities

Overview

OSI Management Facilities comprises interfaces, some of which extend those defined in the JIDM module. Those interfaces support facilities that are specific to OSI Management:

• The ability to invoke operations using scope and filtering

• The ability to name objects according to OSI Management principles

• The ability to create and delete objects according to OSI Management principles

• The ability to create DomainPorts and EventPorts associated to OSI AEtitles

OSIMgmt Module

• The ProxyAgent interface

• The ManagedObject interface

• The ManagedObjectFactory interface

• The LocalRoot interface

• The LinkedReplyHandler, EndOfRepliesHandler and MultipleRepliesHandler interfaces

• The RepliesIterator and BufferedRepliesHandler interfaces

• The LName interface

This section describes these interfaces and their operations in detail.

OSIMgmt::LName Interface

• The name of its containing object (superior object).

• Information uniquely identifying this object within the scope of its containing object.

Each managed object must be unambiguously identified within the scope of its superior (container) object by means of an attribute value assertion (AVA) denoting that a specified attribute has a specified value. When used for naming, an AVA is also called a relative distinguished name (RDN).

In OSI Systems Management, the name of a managed object can be expressed in two forms:

• Global form:
  This form specifies an RDN sequence which unequivocally identifies the managed object with respect to the global root.

• Local form:
  This form specifies an RDN sequence which unequivocally identifies the managed object with respect to a predefined context. For OSI systems management, this context is the system managed object and the local form name for the system managed object is the empty sequence.

The global name of a managed object is constructed by concatenating its local name to the global name of the system managed object representing the managed system where the managed object is located.

The local name of a managed object is constructed by appending the RDN that identifies the managed object within the scope of its superior object to the local form name of its superior object.

Through the use of the OSIMgmt::LName library, OSI names can be translated into CosNaming::Names and vice versa. Note that, using this library, code of a client does not need to use the Names Library defined for the CosNaming Service.

Although nothing prevents the use of OSIMgmt::LNames as regular CORBA objects that can be remotely accessed, they will be typically provided as library objects that will be locally accessed by clients of managed objects (CORBA managers).

Description of the LName Operations

• to_ancestor_name() creates a new OSIMgmt::LName object that corresponds to the name of the ancestor managed object situated some number n of levels up (it deletes the last n AVAs of the name in OSI form);

• to_relative_name() creates a new OSIMgmt::LName object that refer to the same managed object through a name relative to the ancestor managed object situated some number n of levels up (it deletes the first mn AVAs of the name in OSI form, where m was the length of the name in OSI form);

• append() creates a new OSIMgmt::LName object by appending the components of the name represented by the OSIMgmt::LName object passed as argument to the components of the current OSIMgmt::Lname;

• append_ava() creates a new OSIMgmt::LName object by appending the provided AVA to the current name in OSI form;

• get_ava() returns the AVA situated in a given position of the name represented by the OSIMgmt::LName object in OSI form;

• equals() returns TRUE if the OSIMgmt::LName object represents the same name as the OSIMgmt::LName object passed as argument; note that this is name equality, not object equality (two names might refer to the same object, but be completely different);

• copy() returns a reference to a new OSIMgmt::LName object whose state is copied from the current OSIMgmt::LName object

Any attempt to invoke to_ancestor_name(), to_relative_name(), and get_ava() passing a value bigger than the actual length of the name represented by the LName object will cause the BAD_PARAM exception to be raised.

Any attempt to extract or copy a value from an unitialized LName object will cause the InvalidName exception to be raised. LNames are initialized when they have been created from an already initialized LName object, or after a call to one of the from_*() operations is successful.

CosNaming::Names and OSI ObjectInstance Names

1. Create an object of type OSIMgmt::LName.

2. Initialize the internal state of the OSIMgmt::LName object with a X711CMI::ObjectInstanceType value, by invoking the from_osi_form() operation.

3. Produce a CosNaming::Name value by invoking the to_idl_form() operation.

The reverse operation implies performing the following steps:

• Create an object of type OSIMgmt::LName.

• Initialize the internal state of the OSIMgmt::LName object with a CosNaming::Name value, by invoking the from_idl_form() operation.

• Produce a X711CMI::ObjectInstanceType value by invoking the to_osi_form() operation.

OSIMgmt::LName objects must be destroyed if not further used. They can be destroyed by invoking the destroy operation they expose.

Binding a Name to an EFD Object shows the code used to bind a name to a CORBA object reference that is pointing to an EFD managed object.

Representation of CosNaming::Names

This section describes how X711CMI::ObjectInstanceType names are mapped into CosNaming::Names.

Each AVA in the OSI ObjectInstance Name will correspond to a CosNaming::NameComponent in the IDL form. The kind field in the CosNaming::NameComponent will always be an empty string. The id field in the CosNaming::NameComponent will correspond to a string with the format:

 

<OID>=<value>

where <OID> corresponds to the value of the registration OID of the Attribute template, in dot notation, and <value> denotes the value of such Attribute, in string format. Blank spaces are not allowed before or after the character "=".

Simple values are mapped according to the following rules:

• If <value> is an integer, then it is the decimal string representation of the integer itself, possibly preceded by a type indicator. All signed integer types are represented with an explicit sign (zero is considered positive for this matter), while all unsigned integer types do not have an explicit sign. If the value is of type long, a "0" precedes the actual value. If it is of type "long long", it is preceded by "00". For example, the value 3 is represented by "+003" if its type is "long long", and by "3" if its type is "unsigned short".

• If <value> is a string, then it is the string embedded in double quotes ()

• If <value> is a boolean, then it is the string TRUE or FALSE

• If <value> is a NULL, then it is the NULL string

• If <value> is a sequence<octet>, then it is the sequence of octets printed as characters embedded in single quotes (). If a given octet is not printable, it is printed in octal representation (character \000 in octal, for example). If the character "\" has to be included, it will be represented by "\\" to distinguish it from the above case

• If <value> is a BIT STRING, it will be received as a sequence<octet> and will be mapped the same way (because it cannot be distinguished from real sequence<octet>)

• If <value> is of an ENUMERATED type, it is the string corresponding to the value without quoting

Complex values are represented according to the following rules:

• If <value> is of a SEQUENCE type, then it is represented as a string which starts with character "{", and contains the string representation of each component of the value separated by commas and ends with character "}". Blank spaces are not allowed before and after "," or after "{" or before "}".

• If <value> is of a SEQUENCE OF type, then it is represented as a string which starts with character "[", contains the string representation of each component of the value separated by commas and ends with character "]". Blank spaces are not allowed before and after "," or after "[" or before "]".

• If <value> is of CHOICE type, then it is represented as a string which starts with the name of the selected field enclosed in parentheses, followed by the string representation of its value. Blank spaces are not allowed after and before parentheses around identifiers of selected fields.

Mapping of ObjectInstance names in nonSpecificForm is not supported. Therefore, a CosNaming::Name will correspond to the mapping of either an OSI Distinguished Name or an OSI RDNSequence. If it corresponds to an OSI Distinguished Name then the first CosNaming::NameComponent will denote the Root object: the id field will be equal to the string root and the kind field will be equal to the empty string. This will help clients using OSIMgmt Facilities as well as implementations of interfaces defined as part of OSIMgmt Facilities ( cmis_get(), cmis_set(), etc.) to distinguish whether a CosNaming::Name is local or global.

CosNaming::Name Associated to an X721::log Object illustrates how the OSI ObjectInstance name in global form corresponding to an X721::logRecord object is mapped to a CosNaming::Name.

Representation of CosNaming::Names in String Format

The defined string format is aligned with the proposal presented in [interopNames]. The single character "/" is used to separate the id field values associated to each component of the managed object name in IDL form (which in turns correspond to AVAs in the OSI form). The value of kind fields is not represented since they correspond to empty strings. Therefore, the string used to represent a managed object name in local form matches the following format:

 

<oid1>=<value-1>/<oid-2>=<value-2>/.../<oid-n>=<value-n>

while the string used to represent a managed object name global form matches the following format:

root/<oid1>=<value-1>/<oid-2>=<value-2>/.../<oid-n>=<value-n>

Locating a logRecord Object shows the code used to obtain a CORBA object reference that points to a given logRecord managed object, given its name.

OSIMgmt::ProxyAgent Interface

As a result of establishing the connection, an OSIMgmt::ProxyAgent object (an object that exports the OSIMgmt::ProxyAgent interface) is created. OSIMgmt::ProxyAgent objects export the JIDM::ProxyAgent interface and support additional operations that are specific to OSI Management.

Connections are established by means of invoking the access_domain() operation exposed by a root JIDM::ProxyAgentFinder object as explained in JIDM::ProxyAgentFinder Interface. The value associated to the XSM environment Key parameter passed to the access_domain() operation shall be OSI Management. Note that the access_domain operation returns a reference to a JIDM::ProxyAgent interface. If the client wants to get visibility of the specific operations defined for the OSIMgmt::ProxyAgent interface, this reference must be narrowed.

OSIMgmt Conventions for Proxy Agent Finding Criteria presents the names and meaning for criteria that can be passed in the invocation to the access_domain() operation when trying to access an OSI managed domain. While the domain title criterion is mandatory, the rest of criteria components are optional.

Semantics of the domain title and controller object parameters were specified in JIDM::ProxyAgentFinder Interface. The criteria, in the case of OSI Systems Management Reference model, may include additional parameters, namely:

• An access control parameter, carrying access control information required to set up the connection and to be used as default access privileges

• A requestor title parameter, used to identify the CORBA manager application that requests the connection

It must be pointed out that invoking the access_domain() operation with two different <key , criteria> pairs will result in creation of two different connections and, consequently, two different OSIMgmt::ProxyAgent objects. As an example, passing the same AEtitle value but two different access control parameter values or two different controller objects in order to get access to a given OSI managed object domain, would imply creation of two different OSIMgmt::ProxyAgents.

The requestor title is mainly required in those scenarios where a requestor needs to create a new connection, not shared with other requestors who use the same destination AEtitle and access control parameter values. Note that sharing an already existing OSIMgmt::ProxyAgent object would mean to accept that other OSI Managers may destroy that object.

Since OSIMgmt::ProxyAgent objects are JIDM::ProxyAgent objects, they provide the means by which CORBA manager objects are able to obtain references to:

• An initial CosLifeCycle::FactoryFinder object located at the OSI managed object domain

• An initial CosNaming::NamingContext object located at the OSI managed object domain

Invoking the find_factories() operation exposed by the initial CosLifeCycle::FactoryFinder object, CORBA manager objects may result in finding factories that enable creation of new members of the OSI managed object domain.

Invoking the resolve() operation exposed by the initial CosNaming::NamingContext object, CORBA manager objects may result in obtaining CORBA object references to existing members of the OSI managed object domain.

In a pure CORBA environment (i.e., both manager and managed object domains are based on CORBA), the OSIMgmt::ProxyAgent would typically hold references to the initial CosLifeCycle::FactoryFinder and CosNaming::NamingContext objects located at the OSI domain being accessed. The scenario is illustrated in OSIMgmt::ProxyAgents in a CORBA Environment. Whether these two interfaces are exported by the same CORBA object or different CORBA objects at the domain is an implementation issue.

Once a CORBA manager object obtains a CORBA object reference associated to an OSI managed object, it can invoke operations exposed by the object. It will do so by using the standard ORB services defined in CORBA:

• The Dynamic Invocation Interface (DII)

• IDL stubs generated from definitions in OMG IDL of interfaces exported by the object (which might have been generated from GDMO definitions according to the specification in reference [XoJIDM]).

The remainder of this sub-section gives Descriptions for the ProxyAgent operations.

The get_domain_factory_finder Operation

The space of keys established for OSI Management environments is described in OSIMgmt Conventions for Factory Finder Keys,

CORBA Managers can create managed objects either using operations exposed by specific factories whose interfaces are derived from namebinding GDMO templates or by using operations exposed by generic factories.

In respect to specific factories, one of the two following scenarios may be supported:

• A specific factory interface is defined for each managed object interface that supports a different operation for each GDMO namebinding template

• A specific factory interface is defined for each GDMO namebinding template

In respect to generic factories, one (or several) of the three following scenarios may be supported:

• The standard CosLifeCycle::GenericFactory interface is used

• The OSIMgmt::ManagedObjectFactory interface is used

• One of the standard factory interfaces defined in reference [SYSMANfacilities] is used

In any case, the factory object would be responsible of checking if the new managed object can be contained in the designated superior object. This implies checking if there is some name binding template declaring that this relationship is valid.

With these considerations in mind, the alternatives for finding factories in OSI Systems Management environments are more precisely described as follows:

• Only the name of the object interface is specified.

  Here, it is implicitly assumed that there is a specific factory interface associated to the managed object interface. Such interface includes a separate operation for each GDMO namebinding template that is associated to the managed object interface. CORBA managers know the name and operations associated to the factory in advance so that they can properly narrow and use the reference returned by the find_factories() operation.

• Only the name of the object factory interface is specified.

  Here, references returned by the find_factories() operation can be narrowed to the IDL interface whose name has been specified. The CORBA manager object who invoked the operation knows the signature and semantics of operations supported by the designated object factory interface. This option will be the one used to obtain references to factories derived from GDMO namebinding templates or to obtain references to generic factories exporting the CosLifeCycle::GenericFactory interface, the OSIMgmt::ManagedObjectFactory interface, or any of the generic factory interfaces defined in reference [SYSMANfacilities].

• Both the name of the object interface and the superior object interface are specified.

  Here, the CORBA manager object provides the necessary information to find the factory associated to a specific GDMO namebinding template for which a specific factory interface is defined.

In case objects are created through CosLifeCycle::GenericFactory objects, the key value passed in the invocation to the create_object() operation would be the name of the interface exported by the new managed object. The Criteria value would be a sequence of <name, value> pairs which would correspond to the rest of arguments needed for creation of the managed object as specified in OSIMgmt Conventions for Managed Object Creation Criteria (name of the managed object, name of superior object, reference object, attribute list, etc).

The get_domain_naming_context Operation

As already explained in The JIDM::ProxyAgent Interface, CORBA manager objects can obtain CORBA object references to members of a managed object domain as a result of invoking the resolve operation exposed by the initial CosNaming::NamingContext object located at the domain. The resolve() operation may also be used to obtain reference to CosNaming::NamingContext objects subordinated to the initial CosNaming::NamingContext object.

Managed objects will be named according to OSI Naming Principles defined in reference [X720]. CORBA manager objects will typically perform the following steps in order to obtain a reference to an OSI managed object:

1. Construct the name of the managed object in OSI form

2. Translate the name from OSI to idl form (see OSIMgmt::LName Interface)

3. Invoke the resolve operation exposed by the initial CosNaming::NamingContext located at the domain where the object is located

Finding a Log Record by Name shows what the fragment of code used to find a LogRecord object by name should look like.

CMIS Operations

A detailed description of CMIS operations is presented in Description of CMIS Operations.

The destroy Operation

Destruction of an OSIMgmt::ProxyAgent object can take place either gracefully or nongracefully, as described in The JIDM::ProxyAgent Interface. A reference to a JIDM::ProxyAgentController object may be passed at the manager side, as described in The JIDM::ProxyAgentController interface.

OSIMgmt::NamingContext Interface

In this sub-section, a basic set of such specialized operations is described. Note that all these operations are optional; no implementation is required to support any of them.

The resolve_with_intf Operation

This operation is useful when accessing a managed domain that is unable to perform location operations based solely on object instance names, that is, when accessing agents that do not support the ActualClass functionality, as specified in reference X720.

The exceptions raised by this operation are the same, and have the same semantics, as those raised by the CosNaming::NamingContext::resolve operation.

The resolve_osi_name Operation

If the class of the object being located is not known, the constant ACTUAL_CLASS may be used instead (provided that the managed domain being accessed supports this functionality).

The exceptions raised by this operation are the same, and have the same semantics, as those raised by the CosNaming::NamingContext::resolve operation.

The translate_osi_name Operation

This operation may raise the InvalidName exception if the input name has not been properly intialized (contains a valid name). Note that translating the name does not require an object with that name to exist.

The translate_idl_name Operation

This operation may raise the InvalidName exception if the input name has not been properly intialized (contains a valid name). Note that translating the name does not require an object with that name to exist.

OSIMgmt::ManagedObject Interface

Operations exposed through the OSIMgmt::ManagedObject interface enable clients of an OSI managed object to obtain the name of the managed object and invoke operations either on the object itself or on selected descendants of the managed object.

Naming

The CORBA naming service (see reference CORBAservices) specifies a transitive rule for naming resolution:

 

ctx->resolve (C1;C2;...;Cn-1;Cn) =
(ctx->resolve (C1;C2;...;Cn-1))->resolve (Cn)

This means that being able to resolve to a leaf in an agent naming tree implies being able to resolve to the same object from any intermediate object in the naming tree, using a relative name.

Given that the naming tree and the containment tree are the same in OSI management, this transitive rule mandates inheritance of CosNaming::NamingContext by every non terminal element of the naming (i.e. containment) tree.

The inheritance of the NamingContext interface only implies interface inheritance, it does not imply inheritance from any standard off-the-shelf implementation of the CORBA Naming Service. In particular, all operations except resolve and list should raise the standard NO_PERMISSION exception when invoked by CORBA managers, and the resolve and list operations may have specialized implementations optimized for the lookup of OSI names.

Typically, the resolution of a name consists in forwarding the request down the tree through each context, the last one setting the response, and sending it back, upward in the tree, to the client. This process can be long in case of deep, distributed object tree. But the implementa-tion is free to use any efficient algorithm given that it provides the same functionality, such as hash tables or delegation. Therefore, this specification does not limit the scalability or perfor-mance of applications implementing it.

Although the resolution of names is governed according to the CORBA naming transitive rule, the NamingContext tree doesnt need to match the OSI naming tree structure.

This implies that a managed object may raise the CannotProceed exception whenever the resolve operation is invoked on it, thus delegating name resolution to an alternative CosNaming::Naming-Context object. If we consider the previous rule, invoking:

 

ctx->resolve (C1;C2;...;Cn-1)

may raise the CannotProceed exception and return ctx' and C1;C2;...;Cn-1 with it. The rule is then formulated as follows:

 

ctx->resolve (C1;C2;...;Cn-1;Cn) =
(ctx'->resolve (C1;C2;...;Cn-1))->resolve (Cn).

Exceptions Raised by OSI Resolve Operations describes the exceptions raised by the resolve operation(s) as they apply in OSI con-texts. Note that this description complies with the description given for the standard CosNaming service in reference CORBAservices, and the one given generically in The JIDM::ProxyAgent Interface.

The remainder of this sub-section gives descriptions of the ManagedObject Attributes and Operations.

Inherited Operations from CosLifeCycle::LifeCycleObject

• The copy() operation performs similarly to a CosLifeCycle::GenericFactory::create_object operation. The object in which the operation is invoked acts as the reference object for the create_object() operation (it is automatically inserted into the creation criteria parameter).

• The move operation is not appropriate in OSI management environments, so if invoked it should raise the NotMovable exception.

• The remove operation deletes the object from the managed domain. Note that deletion of a managed object may cause deletion of its descendants, or might be forbidden if the object has descendants, if such behaviors have been defined. If, for whatever reason, the object could not be destroyed, the NotRemovable exception will be raised.

The object_name Attribute

CMIS Operations

A detailed description about CMIS operations is presented in Description of CMIS Operations.

Generic multi-attribute Operations

The perform_action Operation

If the managed object returns multiple replies to a single action invokation, the UsingMR exception will be raised. See Handling ACTIONs with Multiple Replies for more information on actions with multiple replies.

The delete_mo Operation

OSIMgmt::ManagedObjectFactory Interface

References to objects exporting the OSIMgmt::ManagedObjectFactory interface are typically located by specifying the name of this interface in a factory interface component in the criteria used to find factories.

Three operations are exposed trough the OSIMgmt::ManagedObjectFactory interface:

• The create() operation, which basically comprises all the parameters required to create a managed object using OSI Management principles

• The create_with_autonaming() operation, which leaves to the OSIMgmt::ManagedObjectFactory the responsibility to assign a valid name to the new managed object

• The create_subordinate() operation, which enables creation of a new managed object as subordinate of an existing object

All three operations may receive a reference to an existing managed object whose state is copied into the state of the new managed object. That reference may be nil, in which case no reference object is considered.

Description of CMIS Operations

Scoping entails the identification of those descendant(s) of the base managed object to which a filter is to be applied. Filtering entails the application of a set of tests to each member of the set of previously scoped descendants to extract the subset of those objects that satisfy the filter. The operation is then applied to all the objects in the subset of scoped descendants that satisfy the filter.

As a result of these scoped operations, multiple responses to a single request may happen. This type of interaction is not possible in CORBA, and therefore a callback mechanism is used by means of registering callback objects in the manager application that are the ones responsible to receive the responses (in either asynchronous or deferred synchronous modes).

These callback objects are referred to as Handlers, and are described in OSIMgmt::<reply-handler> Interfaces (asynchronous handlers) and in OSIMgmt::BufferedRepliesHandler Interface (deferred synchronous handlers).

Behavior Common to all Scoped Operations

In case of OSIMgmt::ProxyAgent objects, the following parameters are used to determine the base managed object:

• interface_name:
  specifies the fully scoped name of the interface exported by the base managed object of the scoped operation

• object_name:
  specifies the IDL name of the base managed object of the scoped operation

In case of OSIMgmt::ManagedObject objects, the base managed object for the scoped operation is the managed object itself, therefore these two parameters are not needed.

The following parameters are passed both to OSIMgmt::ProxyAgent objects and to OSIMgmt::ManagedObject objects when invoking scoped operations to control the set of managed objects to which the operation is to be applied (scope and filter), and to specify interacion characteristics (synchronization and access control):

• scope:
  This parameter indicates the subtree, rooted at the base managed object, which is to be searched. The different types of scoping that may be performed are

  • the base object alone

  • the nth level subordinates of the base object

  • the base object and all of its subordinates down to and including the nth level

  • the base object and all of its subordinates (whole subtree)

• filter:
  This parameter specifies the set of assertions that defines the filter test to be applied to the set of managed object(s) that result from applying the scope. Multiple assertions may be grouped using the logical operators AND, OR and NOT. each assertion may be a test for equality, ordering, presence, or set comparison. Assertions about the value of an attribute are evaluated according to the matching rules associated with the attribute syntax. If an attribute value assertion is present in the filter and that attribute is not present in the scoped managed object, then the result of the test for that attribute value assertion shall be evaluated as FALSE. The managed object(s) for which the filter test evaluates to TRUE are selected for the application of the operation. If the filter is not specified, all of the managed objects included by the scope are selected.

• synchronization:
  This parameter indicates how the invoking operation should be synchronized across the selected object instances. Two ways of synchronizing a series of operations are defined: best effort (X711CMI::CMISSyncType(bestEffort)), and atomic (X711CMI::CMISSyncType(atomic)). If this parameter is not supplied, best effort synchronization is performed. If the base managed object alone is selected for the operation, this parameter (if present) is ignored.

• access_control:
  This parameter is information to be used as input to access control functions. This parameter is optional, and is type is X711CMI::AccessControlTypeOpt. If present, then this access control parameter is to be used in the current invocation; if absent, then the default access control parameter specified at OSIMgmt::ProxyAgent creation time (if any) should be used; if neither was specified, then no access control information should be used.

The following parameters are passed both to OSIMgmt::ProxyAgent objects and to OSIMgmt::ManagedObject objects when invoking scoped operations to specify the callback objects to use to receive responses to the scoped operation:

• reply_handler and end_of_replies_handler:
  These parameters specify the object references where the replies to the scoped operation are to be returned (for more details see OSIMgmt::<reply-handler> Interfaces, LinkedReplyHandler).

  If these callback objects became unreachable during the process of performing an scoped operation (due to communications problems, or to the explicit deletion of the callback objects), the managed domain implementation should interrupt processing of the scoped operation, if possible. Specifically, in the case of cmis_get() or scoped_get() operations, this situation would be the way of informing the managed domain that an ongoing "Get" operation must be cancelled.

  In case unconfirmed operations are being requested (for example, an unconfirmed scoped set operation), these parameters should be both specified as nil object references; in this case, no responses will be received.

  If the reply_handler parameter is specified, but the end_of_replies_handlerisspecifiedasanil object reference, then the behaviour of the invoked operation is slightly different: the operation invocation blocks until all responses have been received through the reply_handler object passed in the call - that is, the operation itself becomes the end of replies indication. This allows for sequential scoped operations being invoked without extra coding. Note, however, that the ORB might timeout such invocations if they take too long; configure your ORB timeout appropriately.

  If the reply_handler parameter is specified as a nil object reference, but the end_of_replies_handler is not, or if both are nil but the operation does not accept unconfirmed operation, then the CORBA standard exception BAD_PARAM is raised.

The results of invoking a scoped operation are returned through the OSIMgmt::LinkedReplyHandler object specified when the scoped operation was invoked.

• Information associated with each reply is passed by invoking the send_reply() operation

• If an error occurs during the process, the send_mo_error() or send_subtree_error() operations are called instead, depending on the type of error that had happened

For more details, see OSIMgmt::<reply-handler> Interfaces.

The GET Operations

• attribute_id_list:
  A sequence of ASN1_ObjectIdentifiers corresponding to the Attributes (or Attribute Groups) to be retrieved by the operation. Note that to fill this parameter, the JIDM Specification Translation proccess defines IDL constants of the right type and contents, to facilitate this process (see reference JIDM_ST for details). If the sequence is empty, this is to be interpreted as if the complete list of attributes would have been requested.

The SET Operations

• replace the values of specified attributes with supplied values. The replacement is exact, unless the attribute definition explicitly states otherwise.

• replace the values of specified attributes with default values

• add or remove members to setvalued attributes that are defined to allow the addition or removal of members

To be able to specify the above modifications, the scoped SET operations - cmis_set(), scoped_set() - carry the following extra parameter:

• modification_list

  This parameter contains a set of attribute modification specifications, each of which contains:

  • attribute_id:
    The registration ASN1_ObjectIdentifer of the attribute or attribute group whose value(s) is/are to be modified. An attribute group identifier shall only be specified when the set to default modify operator is specified.

  • attribute_value:
    The value(s) to be used in the modification of the attribute. The use of this attribute is defined by the modify operator. This parameter is optional when the set to default modify operator is specified and if supplied, shall be ignored. If no value is to be passed, then a CORBA any with tc_kind equal to tk_null should be passed

  • modify_operator:
    The way in which the attribute value(s) (if supplied) is/are to be applied to modify the attribute. The modify operator is optional, and if it is not specified then the replace operator shall be assumed.

  If the set of attribute modifications is empty, then no modification is requested.

The ACTION Operations

Action operations may be defined to generate more than one response per managed object that performs the operation.

As actions are generic by definition, the scoped ACTION operations - cmis_action() and scoped_action()- carry the following extra parameters:

• action_name:
  This argument specifies the registration ASN1_ObjectIdentifier of the action to be performed. Note that, to fill this parameter, the JIDM Specification Translation proccess defines IDL constants of the right type and contents, to facilitate this process (see reference JIDM_ST for details).

• action_info:
  This argument carries the specific parameters that correspond to the action, that is, the IDL type that is the mapping of the information syntax for this action. If the action has no information syntax, a CORBA any with tc_kind equal to tk_null will be passed in this argument.

The DELETE Operations

The CREATE Operations

These operations are not scoped, that is, they only affect one object (the one being created), and therefore do not follow the common behaviour outlined above.

Two flavours of the same operation are provided, one synchronous ( cmis_create_sync()) and another asynchronous ( cmis_create()).

Both flavours of the cmis_create() operation use the same input parameters, namely:

• interface_name:
  Specifies the fully scoped name of the interface to be exported by the newly created object

• creation_kind:
  Specifies the type of creation mechanism to be used, and also identifies the use of the next parameter. The possible values are:

  • simple:
    Create the object named in the following parameter

  • autonaming:
    Ignore the contents of the following parameter, and automatically assign a name for the newly created object
    

  • subordinate:
    the name specified in the next parameter is the name of the superior object from the one to be created

• object_name:
  specifies the IDL name of the managed object to be created (if creation_kind is simple) or the name of the superior object (if creation_kind is subordinate). In case creation_kind is autonaming, the contents of this parameter are ignored

• access_control:
  This parameter is information to be used as input to access control functions. This parameter is optional, and its type is X711CMI::AccessControlTypeOpt. If present, then this access control parameter is to be used in the current invocation. If absent, then the default access control parameter specified at OSIMgmt::ProxyAgent creation time (if any) should be used. If neither was specified, then no access control information should be used

• eference_object:
  This parameter indicates the name of a managed object that should be used as a reference when creating the new object

• req_attribute_values:
  Specifies a set of attribute values to be assigned at object creation time

Both operations differ in the way they receive responses:

• cmis_create:
  Performs the operation in an asynchronous way, returning the one and only result into the OSIMgmt::LinkedReplyHandler object passed as input parameter. Note that this is an exception to the process described in OSIMgmt::<reply-handler> Interfaces. There is always one, and only one, response sent to the input LinkedReplyHandler object, and there is no call to the end_of_replies method. The rest of the processing, including the use of the different methods in the LinkedReplyHandler interface, follows exactly what is explained in OSIMgmt::<reply-handler> Interfaces.

• cmis_create_sync:
  Given that there is only one response possible, a synchronous mechanism is also provided for this operation. In this case, there are several output parameters carrying the result of the operation:

  • created_interface_name:
    Interface supported by the newly created object

  • created_object_name:
    Name of the created object

  • creation_time:
    Time when the new object was created (optional)

  • created_attribute_values:
    Values assigned to the attributes of the new object

  Error responses are returned as exceptions in this case.

OSIMgmt::<reply-handler> Interfaces

The LinkerReplyHandler/EndOfRepliesHandler are facilities that allows managed object(s)/proxy agent(s) to send multiple replies to a single scoped operation, using the asynchronous model. The deferred synchronous model is implemented using the BufferedRepliesHandler (see OSIMgmt::BufferedRepliesHandler Interface).

These interfaces are used as arguments for all scoped operations in OSIMgmt::ProxyAgent and OSIMgmt::ManagedObject interfaces.

The scoped operations will be invoked on each managed object within the specified scope which passes the filter condition; the corresponding reply will be sent separately to the OSIMgmt::LinkedReplyHandler object whose reference was passed when the scoped operation was invoked.

After all invocations to send_reply(), send_mo_error() and send_subtree_error() have returned, the end_of_replies() operation is invoked, indicating the complete finalization of the process. Note that with this behaviour, race conditions are avoided.

LinkedReplyHandler/MultipleRepliesHandler objects may be implemented both as local objects (in the client address space) or as remote objects (accessed via CORBA invocations) either in the gateway/CORBA agent/CORBA managed object address space or in a separate CORBA service process.

Common Arguments to LinkedReplyHandler Operations

• object_interface:
  This parameter specifies the fully scoped name of the interface exported by the managed object that generated the current reply

• object_name: This parameter specifies the IDL name of the managed object that generated the current reply

Using an empty string in the object_interface and a zero-length sequence in the object_name arguments, refer to the base object of the corresponding scoped operation.

• current_time:
  This parameter specifies the time at which the response was generated; this parameter is optional, and might not be specified

• reply_info/error_info:
  This parameter carries the information associated with the current reply. If no value is to be passed then a CORBA any with tc_kind equal to tk_null will be passed.

The send_reply Operation

The reply_info argument is a CORBA any, and its contents are different depending on the scoped operation that had been performed, as shown in Contents of reply_info Parameter to send_reply.

The send_mo_error Operation

The error_code argument indicates the type of error that has happened, and the error_info argument is a CORBA any, whose contents might be different depending on the scoped operation that had been performed and the error that had happened.

Also, there are certain cases where the send_mo_error() operation does not provide any additional information, in which case an any with tc_kind equal to the tk_null is passed as value of the error_info parameter.

The send_subtree_error Operation

The error_code argument indicates the type of error that has happened, and the error_info argument is a CORBA any, whose contents might be different depending on the error that had happened.

Also, there are certain error cases where there is no additional information, in which case an any with tc_kind equal to the tk_null is passed as value of the error_info parameter on the send_subtree_error() operation.

The end_of_replies Operation

OSIMgmt::BufferedRepliesHandler Interface

Note that the OSIMgmt::BufferedRepliesHandler interface is a pure extensions of the OSIMgmt::LinkedReplyHandler and OSIMgmt::EndOfRepliesHandler interfaces, and therefore objects exporting this interface can be passed in to operations that take OSIMgmt::LinkedReplyHandler and OSIMgmt::EndOfRepliesHandler as parameters.

The use model for this interface is that of an Iterator, from the client's perspective. That is, the only operations a client should use are those defined in the RepliesIterator interface. The other operations are directly invoked from the Managed Domain, as a result of a scoped operation or action with multiple replies.

These objects can be implemented either in the manager side or in the managed domain side of an interaction, or even provided by an external service.

The remainder of this sub-section gives descriptions of BufferedReplyHandler types and operations.

The Reply Type

The MoError Exception

The SubtreeError Exception

The RepliesIterator Interface

Note that in multithreaded environments, where responses are retrieved from multiple threads (or even from multiple processes), each response will only be received once, so care must be taken in these circumstances.

The get_reply Operation

The get_n_replies Operation

If an error is received, the operation will return all valid replies up to but not including the error, unless the error is the first reply, in which case the corresponding exception is raised. When the error is not returned by this operation, it remains in the buffer as the first response to be retrieved, and therefore the next call to get_reply() or get_n_replies() will raise the exception corresponding to the error.

The operation returns false if there are no more replies to be pulled out and the end of the iterator has been reached, or true otherwise. This means that if this operation is invoked after the Iterator has reached its end, then an empty list is returned, and the return value is false.

Note that the semantic of the iterator is orthogonal to the way replies and errors are received through the LinkedReplyHandler interface, and in addition it allows a programming model where errors are handled separetely from normal replies.

The finished Operation

This operation can be used to work in polling (non blocking) mode with the Iterator, as the client can always ask for what it knows the Iterator already has received/processed. This polling mechanism should only be used from a single thread.

The destroy Operation

Handling ACTIONs with Multiple Replies

Whilst these are not widely used and could easily be replaced by notifications, it was considered desirable to provide this capability to match the same functionality as is provided for generic interfaces.

When actions that generate multiple replies from a single object are invoked through the scoped operations interfaces ( cmis_action() or scoped_action()), no special action has to be taken, as the mechanism to process multiple replies is already in place.

However, actions may also be invoked using IDL operations generated by the GDMO-to-IDL translation process. These interfaces are strongly typed, and synchronous, therefore not allowing the reception of multiple replies.

For these cases, an additional user exception may be raised by the action call, in the event that multiple replies to the same request are generated. This is the UsingMR exception.

The UsingMR exception carries one parameter, a reference to an OSIMgmt::RepliesIterator object, described in OSIMgmt::BufferedRepliesHandler Interface, that is provided by the managed domain and should be used by the manager application to retrieve all responses to the action. In case the managed domain does not provide this mechanism, and yet the multiple replies are generated, then a nil object reference might be passed in the exception, and the manager should invoke the operation using the scoped operations.

OSIMgmt::LocalRoot Interface

In every CORBA-based OSI managed object domain there will exist a CORBA object which plays the role of a local root. This local root object acts as the superior of all local orphan managed objects in the application (that is, it will hold references to local orphan managed objects), and exports the OSIMgmt::LocalRoot interface.

In the case that a local orphan object is created in a certain managed domain, the local root object for that domain must be notified that a new subordinate has been created.

A reference to the local root object is maintained by the JIDM::DomainPort object associated to the managed object domain. The JIDM::DomainPort object passes this reference to every OSIMgmt::ProxyAgent object it creates.

The local root object is a managed object which exports the OSIMgmt::LocalRoot interface (see OSIMgmt::LocalRoot Interface Definition).

Note that the reference returned by the get_domain_naming_context() operation points to the system managed object. A reference to the root managed object supporting the NamingContext interface will be bound under the initial CosNaming::NamingContext of a managed object domain (typically corresponding to the system managed object). Other NamingContexts that exists in the domain may contain that binding as well, thus, allowing resoluction of DistinguishedNames in their context.

Programming Model

In this section, different scenarios are described where the use of this specification will be clarified. This should be considered as a high level tutorial on some potential uses of the JIDM model for OSI management.

Programming Semantics

This concept of transparency is specifically supported by the fulfillment of the semantic rules presented in JIDM Managed Objects.

Creating Managed Objects

1. obtain a reference to a OSIMgmt::ProxyAgent object that enables access to the domain where the managed object is going to be created.

2. obtain a reference to the initial CosLifeCycle::FactoryFinder located at the domain.

3. invoke the find_factories() operation exposed by the initial CosLifeCycle::FactoryFinder object to find a factory for the new managed object.

4. select a factory among the several factory objects that may meet the criteria for finding factories passed to the find_factories() operation.

5. invoke an appropriate operation, exposed by the selected factory, to create the managed object.

Valid key values for finding factories in OSI Systems Management environments were described in section OSIMgmt::ProxyAgent Interface.

Creating OSI Managed Object Directly through CORBA illustrates how, in a pure CORBA environment, manager objects will create a new OSI managed object.

As with JIDM facilities, the OSIMgmt::ProxyAgent created as a result of establishing a connection to a CORBA managed object domain would typically hold references to the root CosNaming::NamingContext object and CosLifeCycle::FactoryFinder objects located at the domain. The following steps are followed:

1. The CORBA manager invokes the get_domain_factory_finder() operation exposed by the OSIMgmt::ProxyAgent object. As a result, a reference to the initial CosLifeCycle::FactoryFinder located at the domain being accessed is returned.

2. The CORBA manager object invokes the find_factories() operation exposed by the initial CosLifeCycle::FactoryFinder object. As a result, a reference to a managed object factory is obtained and returned to the CORBA manager object that requested it.

3. The CORBA manager object invokes a suitable operation on the managed object factory using the CORBA object reference previously obtained. Typically, the CORBA manager will narrow this reference to a wellknown managed object factory interface (see OSIMgmt::ProxyAgent Interface).

4. The managed object factory creates the CORBA managed object and obtains a reference as a result.

5. The managed object factory binds the obtained reference with a name in the local root CosNaming::NamingContext object.

6. The managed object factory notifies the superior managed object that a new subordinate has been created.

7. Finally, if everything is all right, the managed object factory returns a reference to the CORBA manager object. Otherwise, it returns an exception.

Any superior managed object will hold a reference to every managed object which is a subordinate of it. That is the reason why a superior managed object must be notified about creation of subordinate managed objects. Superior managed objects must hold references to subordinate managed objects in order to handle scoping and filtering as well as to handle deletions.

Different implementation approaches are possible for step 4:

• The CosLifeCycle::Factory performs the required actions to allow initialization of the object when it is first activated

• The CosLifeCycle::Factory invokes an initialization operation exposed by the object¹

Different implementation approaches are also possible for step 5:

• Every managed object exports the CosNaming::NamingContext interface and keeps name bindings associated to its subordinates. Note that this implies that the structure of the CORBA naming tree would have to be equivalent to the OSI naming tree, that is, managed objects support the resolve() operation and do not raise the CannotProceed exception.

• The structure of the CORBA naming tree does not match the structure of the OSI naming tree, that is, it is more plain and avoids deep nesting. Note that this approach implies that managed objects support the resolve() operation but may raise the CannotProceed exception.

Finally, for step 6, the following implementation approaches are also valid:

• Make the factory object coincide with the superior of the new managed object. Note that this implies a clear optimization.

• Make the factory object notify the superior object that a new child has born by means of invoking an operation that the superior object exposes for this purpose².

In a CORBA managed object domain, propagation of operations is handled by the objects themselves: each object is responsible for forwarding the operation to its descendants. However, the way in which they perform the propagation is an implementation matter. Analogously, the mechanisms used to notify to the base managed object that all the replies have been sent is an implementation matter. A simple way to implement propagation of operations would be to use recursion, as illustrated in the pseudo-code of Recursive Propagation of Scoped Actions.

In this example, the base managed object passes a reference to an object (end_subs) that will be responsible for:

• Waiting until all subordinates of obj invoke the end_of_replies() operation exposed by the end_subs object

• Triggering invocation of the end_of_replies() operation exposed by the end object.

In the algorithm we have presented, invocation of a scoped operation returns immediately. The OSIMgmt::ProxyAgent object does not handle the end of replies, but passes a reference to the object that will handle it. There is another possibility, which is that invocation of a scoped operation blocks until all replies have been sent. In this case, the OSIMgmt::ProxyAgent object will be responsible for sending the last CMIP response, indicating end of replies. By convention, this behaviour is experimented whenever a nil object reference is passed as the OSIMgmt::EndOfRepliesHandler argument.

Note that synchronous invocations implies supports for multi-threading in the CORBA/CMIP gateway process (The OSIMgmt::ProxyAgent and the OSIMgmt::LinkedReplyHandler objects must concurrently execute).

Invoking Operations on Single Managed Objects

1. Obtain a reference to a OSIMgmt::ProxyAgent object that enables access to some domain of which the managed object is member.

2. Obtain a reference to the initial CosNaming::NamingContext located at the domain, by means of invoking the get_domain_naming_context() operation exposed by the OSIMgmt::ProxyAgent object.

3. Construct the name that unequivocally identifies the managed object within the domain.

4. Invoke the resolve() operation exposed by the initial CosNaming::NamingContext object located at the domain, thus obtaining a CORBA object reference pointing to the managed object.

5. Invoke the operation on the managed object.

Example Code for Invoking Operation on Managed Object shows the code used to set the destination attribute exposed by an Event Forwarding Discriminator.

Note that the same result can be obtained without narrowing the reference returned by a JIDM::ProxyAgentFinder object to an OSIMgmt::ProxyAgent interface, when the access_domain() operation was invoked.

Invoking Operations on a MO Directly through CORBA illustrates how CORBA manager objects invoke operations on a single managed object in a pure CORBA environment.

As already explained, the OSIMgmt::ProxyAgent created as a result of establishing a connection to a CORBA managed object domain would typically hold references to the root CosNaming::NamingContext object and CosLifeCycle::FactoryFinder object located at the domain. Thus, the following steps will be followed:

1. The CORBA manager object invokes the get_domain_naming_context() operation exposed by the OSIMgmt::ProxyAgent object, in order to obtain a reference to the initial CosNaming::NamingContext object.

2. The CORBA manager object invokes the resolve() operation exposed by the initial CosNaming::NamingContext object, passing the name of the managed object upon which it wants to operate. As a result of this, a CORBA object reference to the managed object is obtained and returned to the CORBA manager object that requested it.

3. The CORBA manager object invokes an operation on the managed object using the CORBA object reference previously obtained. IDL stubs or the standard DII can be used when invoking operations on single managed objects. If IDL stubs are used, the CORBA manager object must first narrow the reference to a specific OMG IDL interface.

Invoking Operations with Scoping and Filtering

Invoking Operation with Scoping and Filtering illustrates how CORBA manager objects invoke a scoped operation in a pure CORBA environment.

The following steps will be followed when scoping operations are invoked through operations exposed by the base managed object:

1. A CORBA manager object invokes the resolve() operation exposed by the initial CosNaming::NamingContext object, passing the name of the managed object used as the base managed object in the scoped operation. As a result, a reference to the managed object is returned.

2. The CORBA manager object narrows the obtained CORBA object reference to a new object reference, bound to the OSIMgmt::ManagedObject interface, and invokes the appropriate scoped operation ( scoped_get(), scoped_set(), scoped_action(), scoped_delete()).

3. The CORBA manager objects selects an object that exports the OSIMgmt::MultipleRepliesHandler interface (can create it). When invoking, the CORBA manager object passes a reference to this object (note that the CORBA manager object may be the one exporting the OSIMgmt::MultipleRepliesHandler interface).

4. The base managed object propagates the requests to its descendants.

5. Replies from each of the managed objects satisfying the filter, within the defined scope, are received by the OSIMgmt::MultipleRepliesHandler object. Information associated with each of the replies is passed when invoking the send_reply() operation exposed by the OSIMgmt::MultipleRepliesHandler object.

6. The base managed object is notified when scoped descendants that pass the filter have sent their replies to the OSIMgmt::MultipleRepliesHandler object.

7. The base managed object invokes the end_of_replies() operation exposed by the OSIMgmt::MultipleRepliesHandler object. If an error occurs during the whole process, an exception is generated, converted into a CORBA any value, and passed to the OSIMgmt::LinkedRepliesHandler object by invoking either the send_mo_error() or send_subtree_error() operation.

Code for Invoking Scoped Operations shows what the fragment of code used to find a Log object by name should look like.

Iterator Interfaces for Scoped Operations

The scoped operations both in ProxyAgent and ManagedOobject share the last parameters in the list as in:

 

cmis_get(..., in LinkedReplyHandler lrh, in EndOfRepliesHandler eorh)

The iterator interfaces for other services look like:

 

iter_get(..., in unsigned long how_many, out ReplyList rlist, 
    out ReplyIterator riter)

This operation can be implemented by the pseudo-code shown in Using ReplyIterator.

Note that although this code is simple, implementing it in either a pure CORBA Agent, or a pure CORBA Managed object, or a gateway, may impose unacceptable performance and scalability constraints in the implementation, becauses potentially unbounded buffering must occur in a single point, and concentration of responses through a single CORBA object will also happen.

Other more flexible implementations are possible by combining the simpler pieces together, as in Using ReplyIterator, thereby avoiding the scalability and performance problems - or at least reducing them.

In addition, the BRH objects can be implemented both as local objects (in the client address space) or as remote objects (accessed via CORBA invocations), either in the gateway/CORBA agent/CORBA managed object address space or in a separate CORBA service process.

Reception of Events at CORBA Managers

Forwarding Events from CORBA Managed Object Domains

The only distintion is that the interface of the EventReporter object is well-known and corresponds to the standard Event Forwarding Discriminator interface.

CORBA/CMIP Gateways

Manager-side Gateways

Overview

A CORBA/CMIP gateway runs in one CORBA server. However, a CORBA/CMIP gateway can coexist with one or several JIDM gateways in the same CORBA server. Programs of the CORBA server have access to both ORB services and services encapsulating access to management-specific protocols provided by JIDM gateways at the server.

Any CORBA/CMIP gateway has several CORBA objects associated with it (see Structure of CORBA/CMIP Manager-side Gateways):

• A JIDM::ProxyAgentFinder object for establishing connections to OSI managed object domains accessible via CMIP through the gateway

• One or several JIDM::EventPort objects for receiving notification of events from members of OSI managed object domains accessible via CMIP through the gateway

The JIDM::ProxyAgentFinder object is created during start-up of the CORBA server where the JIDM gateway is going to run. JIDM::EventPort objects at the gateway may be created during or after start-up of that server. This typically requires the existence of a EventPortFactory object at the gateway.

As explained in JIDM Gateways, several JIDM gateways can exist in a CORBA manager and a JIDM::ProxyAgentFinder object is associated with each of them. All of them would be registered in a root JIDM::ProxyAgentFinder object at the CORBA manager (see also Structure of CORBA/CMIP Manager-side Gateways). CORBA managers typically obtain a reference to this local root JIDM::ProxyAgentFinder object by using standard CORBA Initialization Services.

The JIDM::ProxyAgentFinder object is created during start-up of the CORBA server where the JIDM gateway is going to run. JIDM::EventPort objects at the gateway may be created during or after start-up of that server.

As a result of establishing a connection through a CORBA/CMIP gateway, an OSIMgmt::Proxy-Agent object is created at the gateway. OSIMgmt::ProxyAgent objects created this way are responsible for:

• Creating a CosLifeCycle::FactoryFinder object that in turn enables creation of CORBA factories that handle creation of managed objects at the domain

• Creating a CosNaming::NamingContext object that in turn enables creation of CORBA proxy managed objects for each member of the domain

• Sending scoped operation requests

Getting Access to Managed Object Domains

1. The CORBA manager object invokes the access_domain() operation exported by the JIDM::ProxyAgentFinder object located at the gateway. Information that unequivocally identifies the managed object domain to be accessed is passed in the invocation.

2. As a result of invoking the access_domain() operation, a CORBA OSIMgmt::ProxyAgent object is created at the gateway. The new OSIMgmt::ProxyAgent object is bound to a CMIP communication endpoint (a CMIS access point). If a specific domain title was specified in the criteria passed as argument to the access_domain() operation, then a connection is established with the managed object domain. In such a case, the OSIMgmt::ProxyAgent is responsible to manage resources associated with the connection.

3. A reference to the OSIMgmt::ProxyAgent object is returned to the CORBA manager object that requested access to the managed object domain being considered. This reference is returned as a reference to a JIDM::ProxyAgent object. In order to use specific operations in the OSIMgmt::ProxyAgent interface, manager objects must narrow the reference they receive.

Each OSIMgmt::ProxyAgent object encapsulates access to a domain by stablishing a session with that domain.

Different solutions can be implemented:

• OSIMgmt::ProxyAgent objects located in the same CORBA/CMIP gateway may share the same session, but each of them is associated with a different context.

• Each OSIMgmt::ProxyAgent object has a different session associated with it.

Creation of Managed Objects

Different types of factories can be found according to criteria passed in the invocation of the find_factories() operation exported by the initial CosLifeCycle::FactoryFinder visible through the CORBA/CMIP gateway:

• OSIMgmt::ManagedObjectFactory

• CosLifeCycle::GenericFactory

The following steps are followed when a CORBA manager creates a managed object at some domain that is accessible through a CORBA/CMIP gateway (see Creating MOs through a CORBA/CMIP Gateway):

1. The CORBA manager invokes the get_domain_factory_finder() operation exported by the OSIMgmt::ProxyAgent object.

2. The CORBA manager invokes the find_factories() operation exported by the returned CosLifeCycle::FactoryFinder object, passing a valid key value.

3. The CosLifeCycle::FactoryFinder object finds references for appropriate managed object factories at the JIDM gateway. If there is no managed object factory matching the key, the CosLifeCycle::FactoryFinder object creates one. References to managed object factories are returned to the CORBA manager.

4. The CORBA manager object invokes an operation on the managed object factory using the CORBA object reference it obtained. Typically, the CORBA manager object narrows this object reference to a specific managed object factory interface supported by the factory (the CosLifeCycle::GenericFactory or the OSIMgmt::ManagedObjectFactory interface, for example).

5. The CORBA request is received by the CORBA/CMIP gateway and is translated into an appropriate m-create request PDU. This m-create request PDU is sent through the association handled by the OSIMgmt::ProxyAgent.

6. When the response to the m-create request PDU is received, the invoked operation returns with the appropriate result values.

7. If the create operation must return an object reference then a CORBA proxy managed object is also created at the gateway.

Invocation of Operations on Single Managed Objects

1. The CORBA manager invokes the get_domain_naming_context() operation exported by the OSIMgmt::ProxyAgent object.
   

2. A CORBA manager object invokes the resolve() operation exported by the returned CosNaming::NamingContext object, passing the name of the managed object upon which it wants to operate.

3. The CosNaming::NamingContext object finds a reference to the CORBA object acting as the proxy of the managed object and returns it to the CORBA manager that requested it. The CORBA proxy managed object resides in the JIDM gateway. The CosNaming::NamingContext object is responsible for creating the CORBA proxy managed object if it did not exist at the gateway, the first time an existing managed object is accessed.

4. The CORBA manager object invokes an operation on the managed object using the CORBA object reference to the corresponding proxy. IDL stubs or the standard DII can be used to perform this action. Whenever IDL stubs are used, the CORBA manager must narrow the reference, obtained from the CosNaming::NamingContext, to a specific OMG IDL interface.

5. The CORBA request is received by the CORBA/CMIP gateway and translated into an appropriate management request PDU. This request PDU is sent through the association handled by the OSIMgmt::ProxyAgent.

6. When the response to the request PDU is received, the invoked operation returns with the appropriate result values.

Invoking Operations with Scope and Filtering

1. A CORBA manager object invokes the resolve() operation exported by the initial CosNaming::NamingContext object located at the managed object domain, passing the name of the managed object used as base of the scoped operation.

2. The CosNaming::NamingContext object finds a reference to the CORBA object acting as the proxy of the managed object, in the CORBA/CMIP gateway, and returns it to the CORBA manager object requesting it.

3. The CORBA manager object narrows the obtained CORBA object reference to a new object reference, bound to the OSIMgmt::ManagedObject interface, and invokes the appropriate scoped operation ( scoped_get(), scoped_set(), ,In scoped_action , scoped_delete()).

4. In the invocation, the CORBA manager object passes a reference to an OSIMgmt::MultipleRepliesHandler object (this may be a reference it self if the manager exports this interface).

5. The CORBA request is received by the CORBA/CMIP gateway and is translated into an appropriate CMIP request PDU. This CMIP request PDU is sent through the CMIP communication endpoint associated with the OSIMgmt::ProxyAgent through which the reference to proxy managed object was obtained. If a nil object reference was passed as the OSIMgmt::EndOfRepliesHandler, the CMIP request PDU is sent unconfirmed.

6. Replies from each of the managed objects satisfying the filter, within the defined scope, are received by the CORBA/CMIP gateway.

7. Information associated with each of the replies is passed by invoking the send_reply operation exported by the OSIMgmt::MultipleRepliesHandler object. Once all replies have been received, the CORBA/CMIP gateway invokes the end_of_replies() operation exported by the OSIMgmt::MultipleRepliesHandler object.

The gateway is much simpler to program. Actually, it neither needs to maintain a local copy of the naming tree nor to test which managed objects satisfy the filtering. It only needs to:

• Create an object in the CORBA/CMIP gateway that exports the LinkedReplyHandler and the EndOfRepliesHandler interfaces.

• Invoke the scoped operation exported by the base managed object through the OSIMgmt::ManagedObject interface.

Different strategies can be implemented to resolve how each object is going to forward operations to its descendants and detect that there are no pending replies its descendants, but they are transparent to the gateway.

CORBA manager objects can also invoke operations that are directly exported by an OSIMgmt::ProxyAgent and which basically correspond to an encapsulation of CMIS primitives.

Note that references to CORBA proxy managed objects are not necessary in that case (the name of the interface and the managed object are passed as arguments). This may be a way to solve scalability problems.

Event Reception

As already mentioned in Reception of Events at CORBA Managers, different strategies to resolve how CORBA manager objects finally consume events can be implemented. For example, CORBA manager objects can register themselves directly to OSIMgmt::EventPorts or via some additional event channel.

The following steps are followed when a CORBA manager receives an event through an JIDM::EventPort at a CORBA/CMIP gateway (see Creating MOs through a CORBA/CMIP Gateway):

1. During the start up phase of the CORBA Manager Application, one or more application objects register themselves either as CosEventComm::PushConsumers or CosEventComm::PullConsumers in each of the existing OSIMgmt::EventPorts.

2. A m-event-report indication PDU containing notification of an event from a managed object is received by the CORBA/CMIP gateway through some association. This association is bound to a specific title and has a JIDM::EventPort object associated with it which finally receives the event data carried in the PDU.

3. The appropriate response is sent by the CORBA/CMIP gateway back to the application that reported the event, confirming that the event was received at the Manager Application.

4. The JIDM::EventPort invokes the push operation exported by all CosEventComm::PushConsumers objects connected to it. Data of the event is passed in the invocation as an any.

5. The JIDM::EventPort maintains the event until all CosEventComm::PullConsumers objects connected to the port pull the event. Data of the event is obtained by consumers as an any.

6. CosEventChannelAdmin::EventChannel objects can be connected as consumers to the event port. In such a case, manager objects performing management functions can be connected to the channel instead of directly to the event ports.

CMISE service level scenarios

This section presents some scenarios as they would apply to CORBA manager to OSI agent gateway environments. These scenarios also assume that the ProxyAgent object has been pre-viously located or created by the manager object by invoking the access_domain operation on the JIDM::ProxyAgentFinder object.

Creating Managed Objects

The following steps are taken each time an asynchronous M-CREATE request is sent through the CORBA/CMIP Gateway.

1. The CORBA manager object invokes the cmis_create() operation against the OSIMgmt::Proxy-Agent object. The asynchronous cmis_create method takes the additional OSIMgmt::Linke-dReplyHandler object reference against which the response method will be invoked. The other input arguments are the X711CMI CMIS data arguments, the creation method (creation_kind), the object_name (distinguished name) and the interface_name of the object being created.

2. The OSIMgmt::ProxyAgent object implementation transforms the IDL data into a CMIP PDU and sends it over the OSI stack to the OSI agent. Once the PDU has been sent, the asynchronous cmis_create call returns.

3. At some later point, the response comes back to the gateway from the OSI agent over the OSI stack. The gateway implementation internally converts the response to its IDL equivalent.

4. The gateway invokes the send_reply() (or send_mo_error(), send_subtree_error() if an error occurred) method against the OSIMgmt::LinkedReplyHandler object which was passed to the original cmis_create() call, passing the response data as an argument.

The Synchronous Create Operation works as described below.

The following steps are taken each time a synchronous M-CREATE request is sent through the CORBA/CMIP Gateway:

1. The CORBA manager object invokes the cmis_create_sync() operation against the OSIMgmt::ProxyAgent object. The input arguments are the X711CMI CMIS data arguments, the creation method (creation_kind), the object_name (distinguished name) and the interface_name of the object being created.

2. The OSIMgmt::ProxyAgent object implementation transforms the IDL data into a CMIP PDU and sends it over the OSI stack interface to the OSI agent. Once the PDU has been sent, the cmis_create_sync() call blocks, waiting for the response.

3. At some later point, the response comes back to the gateway from the OSI agent over the OSI stack. The gateway implementation internally converts the response to its IDL equivalent.

4. The cmis_create_sync method returns the results of the create operation through the out-arguments of the cmis_create_sync() call. These include the created_interface_name, the created_object_name (distinguished name of the object actually created), the creation_time (time when the managed object was created), and the created_attribute_values (values of attributes of the new object).

Generic Operations on Managed Objects

The following steps are taken each time an M-GET, M-SET, M-ACTION or M-DELETE request is sent through the CORBA/CMIP Gateway:

1. The CORBA manager object invokes the desired operation against the OSIMgmt::Proxy-Agent object. All method invocations which will result in one or more responses take the OSIMgmt::LinkedReplyHandler and OSIMgmt::EndOfRepliesHandler object references - against which the separate response methods will be later invoked. For unconfirmed operations, both object references should be nil. The other input arguments are the X711CMI CMIS scope, filter, synchronization and access control arguments, the object_name (distinguished name) and the interface_name.

2. The OSIMgmt::ProxyAgent object implementation transforms the IDL data into a CMIP PDU and sends it over the OSI stack to the OSI agent. Once the PDU has been sent, operation invocation returns.

3. At some later point, a response comes back to the gateway from the OSI agent over the OSI stack. The gateway implementation internally converts the response to its IDL equivalent.

4. The gateway invokes the send_reply() (or send_mo_error(), send_subtree_error() if an error occurred) method against the OSIMgmt::LinkedReplyHandler object which was passed to the original operation invocation, passing the response data as an argument. If the current reply is the last one, this will be immediately followed by an invocation of the end_of_replies() method against the OSIMgmt::EndOfRepliesHandler object reference which was passed in to the initial request operation.

Cancelling a get Operation

The following steps must be taken in order to get the CORBA/CMIP gateway to send an M-CANCEL-GET request to a pending M-GET:

1. At some point after the initial M-GET request is issued, but before all responses have been received, the CORBA manager deletes the OSIMgmt::LinkedReplyHandler object which was associated with the original request.

2. A response comes back to the gateway from the OSI agent over the OSI stack. The gateway implementation internally converts the response to its IDL equivalent.

3. The gateway attempts to invoke the send_reply() (or send_mo_error(), send_subtree_error() if an error occurred) method against the OSIMgmt::LinkedReplyHandler object which was passed to the original operation invocation, passing the response data as an argument. Since this object no longer exists, a standard CORBA exception OBJECT_NOT_EXITS will be thrown.

4. The gateway catches this exception, which tells it to synthesize an M-CANCEL-GET PDU and send it down the OSI stack to the OSI agent.

Agent Side Gateways

Overview

Any CORBA/CMIP gateway at a CORBA Agent Application has several objects associated with it (see Structure of CORBA/CMIP Manager-side Gateways):

• A JIDM::EventPortFinder CORBA object that enables CORBA managed objects at the agent application to establish connections to JIDM::EventPort objects at remote Manager Applications that are accessible through the gateway.

• A JIDM::DomainPort object that serves request issued from remote Manager Applications that want to get access to managed objects at the local managed object domain.

These objects are created during start-up of the CORBA server where the CORBA/CMIP gateway is going to run.

Several JIDM gateways can exist in a CORBA Agent and a JIDM::EventPortFinder object is associated with each of them. All of them would be registered in a root JIDM::EventPortFinder object at the CORBA Agent (see also OSIMgmt::ProxyAgents in a Gateway).

A root CosNaming::NamingContext object and a root CosLifeCycle::FactoryFinder object exist at any CORBA managed object domain. Whether these two interfaces are exported by the same CORBA object or different CORBA objects is an implementation issue. In addition, an OSIMgmt::LocalRoot object exists in order to deal with local orphan managed objects. References to these CORBA objects can be obtained from a CORBA/CMIP gateway by using the standard Initialization Services and are passed to the JIDM::DomainPort object at creation time.

Handling Access to Managed Objects

Every JIDM::DomainPort object has an AE-title associated with it. This AE-title is used by remote Manager Applications to identify the OSI managed object domain accessible through the JIDM::DomainPort object.

When a new association request is received by the JIDM::DomainPort object that is in a gateway, the JIDM::DomainPort object creates a new OSIMgmt::ProxyAgent object. This object handles CMIS requests received through the newly established association.

A JIDM::DomainPort object in a JIDM gateway holds references to the initial CosNam-ing:: NamingContext and CosLifeCycle::FactoryFinder and OSIMgmt::LocalRoot objects in the managed object domain where the JIDM gateway is located. The JIDM::DomainPort object passes copies of these references to each OSIMgmt::ProxyAgent object it creates.

Creation of Managed Objects

The following steps are followed each time a create PDU indication is received by a CORBA/CMIP gateway:

1. A OSIMgmt::ProxyAgent object receives a m-create indication through the CMIS connection endpoint it holds.

2. The OSIMgmt::ProxyAgent object finds an appropriate factory by invoking the find_factories() operation provided by the initial CosLifeCycle::FactoryFinder object at the managed object domain.

3. The OSIMgmt::ProxyAgent object narrows the obtained Factory object reference to a new object reference associated with a specific factory interface. Next, it invokes the operation for creating managed objects exported by the factory being referenced.

4. The Factory object creates a new CORBA managed object, an instance of the managed object type specified in the CMIP create indication (using the value of the Managed object class field in the CMIP PDU).

5. The Factory object binds an OSI name (the one passed as of the Managed object instance field in the CMIP PDU, but in IDL form) to the new CORBA managed object.

6. The Factory object informs the container (the naming context) of the CORBA managed object that a new subordinate object has been created.

7. When the operation invoked by the OSIMgmt::ProxyAgent object returns (or when an exception is raised), the OSIMgmt::ProxyAgent object constructs and sends an appropriate CMIP response to the remote OSI Manager Application.

Invocation of Operations on Single Managed Objects

The following steps are followed each time a m-set/m-get/m-action PDU indication on a single object is received by a CORBA/CMIP gateway:

1. A OSIMgmt::ProxyAgent object receives a m-set, m-get or m-action indication, referred to a single object, through the CMIS connection endpoint it holds.

2. The OSIMgmt::ProxyAgent object finds a reference to the target managed object by invoking the resolve() operation exported by the initial NamingContext object. The name of the target managed object (base object instance field in the CMIP indication) is passed in the invocation, once it is translated to IDL form (see OSI naming facilities).

3. The OSIMgmt::ProxyAgent object invokes the appropriate operation on the managed object. In a Generic CORBA/CMIP gateway, this may be accomplished by using the Dynamic Invocation API provided by the local ORB.

4. When the management operation invoked by the OSIMgmt::ProxyAgent object returns (or when an exception is raised), the OSIMgmt::ProxyAgent object constructs and sends an appropriate CMIP response to the remote OSI Manager Application.

A reference to the CosNaming::NamingContext acting as the local naming root in the OSI Agent Application is passed to the OSIMgmt::ProxyAgent object at creation time. If the target managed object is going to send multiple replies as a result of invoking an action, an exception is triggered (see the referenced JIDM_ST specification).

Handling CMIP Indications with Scope and Filtering

The following steps are followed each time a scoped m-set/m-get/m-action PDU indication is received by a CORBA/CMIP gateway:

1. An OSIMgmt::ProxyAgent object receives a CMIP m-set, m-get or m-action indication with scope and filtering, through the CMIS connection endpoint it holds.

2. The OSIMgmt::ProxyAgent object finds a reference to the base managed object by means of invoking the resolve() operation exported by a NamingContext object. The name of the base managed object (base object instance field in the CMIP indication) is passed in the invocation, once it is translated to IDL form (see OSIMgmt::NamingContext Interface).

3. The OSIMgmt::ProxyAgent object locally creates a CORBA object which is responsible for handling the different replies and which holds the same CMIS connection endpoint. This object exports two interfaces:

   • OSIMgmt::LinkedReplyHandler, for receiving individual linked replies

   • OSIMgmt::EndOfRepliesHandler, for detecting the end of replies.

4. The OSIMgmt::ProxyAgent object narrows the CORBA object reference pointing to the base managed object instance to a new CORBA object reference associated with the OSIMgmt::ManagedObject interface. Next, it invokes the corresponding scoped operation, now visible through that narrowed reference.

   
   

   
   
   
   
   

   
   Figure: Handling CMIP Indications with Scope and Filtering

   Next, the following steps takes place:

5. The base managed object (root of the subtree to which scope and filtering is going to be applied) propagates the operation to all descendants within the scope of the operation and waits until all descendants satisfying the filter have replied.

6. Every object within the scope that satisfies the filter invokes the send_reply() operation exported by the OSIMgmt::LinkedReplyHandler object, in the gateway, is invoked.

7. The OSIMgmt::LinkedReplyHandler object constructs an appropriate CMIP response and sends it back through the CMIS endpoint connection it holds.

8. The base managed object is informed by its subordinates that there are no pending replies.

9. The base managed object informs the gateway that it has finished by invoking the end_of_replies operation exported by the OSIMgmt::EndOfRepliesHandler object in the gate-way.

10. The OSIMgmt::EndOfRepliesHandler object construct the final CMIP response and sends it to the remote OSI Manager Application.

If the base managed object is not part of the OSI Management Application which received the CMIP indication, then the operation is propagated to the list of all local orphan managed objects that are descendants of the base managed object. This list is obtained by invoking the list_orphan_descendants() operation exported by the local root object.

It is important to point out that the base managed object is informed that there are no pending replies after all descendants satisfying the filter have invoked the send_reply() operation. This way, race conditions are avoided.

Returning from the send_reply() operation does not imply that a CMIP response has already been sent. All responses may be sent together just before the last CMIP response.

The gateway is much simpler to program. Actually, it neither needs to maintain a local copy of the naming tree nor to test which managed objects satisfy the filtering. It only needs to:

• Create an object in the CORBA/CMIP gateway process that exports the LinkedReplyHandler and the EndOfRepliesHandler interfaces

• Invoke the scoped operation exported by the base managed object through the OSIMgmt::ManagedObject interface.

Different strategies can be implemented to resolve how each object forwards operations to its descendants and detects when its descendants have no pending replies, but these strategies are transparent to the gateway.

Interactions between managed objects and the CORBA/CMIP gateway are minimized.

Handling m-delete Indications

CMIP m-delete indications are handled in a similar way as CMIP m-set/m-get/m-action indications with scoping and filtering. We must take into account that deletion of a single managed object may cause deletion of several objects (all its descendants). Every time a managed object is deleted, its superior object is notified.

Basic algorithm:

1. An OSIMgmt::ProxyAgent object receives a CMIP m-delete indication through the CMIS con-nection endpoint it holds.

2. The OSIMgmt::ProxyAgent object finds a reference to the base managed object by invoking the resolve operation exported by a NamingContext object. The name of the target managed object (base object instance field in the CMIP indication) is passed in the invocation, once it is translated to IDL form (see OSIMgmt::NamingContext Interface).

3. The OSIMgmt::ProxyAgent object locally creates a CORBA object which is responsible for handling the different replies. This object holds the same CMIS connection endpoint as the OSIMgmt::ProxyAgent and exports two interfaces:

   • OSIMgmt::LinkedDeletionHandler, for handling each deletion.

   • OSIMgmt::EndOfDeletionsHandler, for detecting the completion of the deletion.

4. The OSIMgmt::ProxyAgent object narrows the CORBA managed object reference to a reference associated with the OSIMgmt::ManagedObject interface. Next, it invokes the scoped_delete() operation visible through that reference.

   
   

   
   
   
   
   

   
   Figure: Handling CMIP Deletion Indications

5. Next, in some situations, the base managed object propagates the delete operation to part/all of its descendants (the delete operation was requested with scope and filtering or deletion of the base managed object implies deletion of all its descendants).

6. For every descendant that is deleted, the confirm_deletion() operation exported by the OSIMgmt::LinkedDeletionHandler object, in the gateway, is invoked. Every managed object is notified when one of its subordinates has been deleted.

7. The OSIMgmt::LinkedDeletionHandler object constructs an appropriate CMIP response and sends it back through the CMIS endpoint connection it holds.

8. The base managed object is informed by its subordinates about the completion of the deletion. If appropriate, the base managed object is deleted and a confirmation is sent to the OSIMgmt::Linked-DeletionHandler object.

9. The base managed object informs the gateway that the deletion has finished by invoking the end_of_deletions() operation exported by the OSIMgmt::EndOfDeletionsHandler object in the gateway.

10. The OSIMgmt::EndOfDeletionsHandler object constructs the final CMIP response and sends it to the remote OSI Manager Application.

In some situations, the base managed object is not part of the OSI Management Application which received the CMIP m-delete indication but deletion must be applied to some descendants which are part of the application.

This situation is resolved by propagating the delete operation to the list of all local orphan managed objects that are descendants of the base managed object. This list is obtained by invoking the list_orphan_descendants() operation exported by the local root object.

The scoped_delete() operation may be invoked in either a non-blocking (asynchronous) or blocking (synchronous) mode. A reference to an OSIMgmt::EndOfDeletionsHandler object reference (for asynchronous request) or a nil object reference (for synchronous request) should be passed as the last argument in the invocation.

Sending m-event-report Requests

At creation time, an EFD tries to find references to CosEventChannel::SupplierAdmin interfaces associated with remote OSIMgmt::EventPort objects. It obtains these references by invoking the find_event_port() operation exported by a JIDM::EventPortFinder object, located in a CORBA/CMIP gateway. It can try to find references for:

• Various JIDM::EventPorts, each of which is bound to one AE_title contained in the list of destinations defined for the PushEFD.

• A single JIDM::EventPort bound to a wildcard address (only valid if automatic event forwarding - recipient manager resolution is supported).

Note that an EFD may register itself as a CosEventComm::PushConsumer or a CosEvent-Comm::PullConsumer in the JIDM::EventPort associated with each of its assigned destinations.

Different implementations are possible but, in general, managed objects report events by pushing them into local CosEventChannelAdmin::EventChannels. EFDs register themselves as event consumers in these event channels.

Multiple implementation strategies can be adopted but they are transparent to remote OSI Manager Applications:

• EFDs may register themselves as CosEventComm::PushConsumers or as CosEvent-Comm::PullConsumers in CosEventChannelAdmin::EventChannels.

• Several CosEventChannelAdmin::EventChannels may be employed (connected in cascades, etc). EFDs must know which event channels they must connect to.

Note that only part of the interfaces exported by an EFD are visible across OSI Management boundaries. From external OSI Manager Applications a PushEFD and PullEFD is just a X711::eventForwardingDiscriminator.

Sending m-event-report Requests - Push Model

1. A PushEFD registers itself as a CosEventComm::PushConsumer in every local event channel that is necessary.

2. CORBA managed objects report events by using the standard event notification services. Each event notification being generated is finally received by some event channel, connected to the PushEFD object.

3. The event channel forwards event notifications to the PushEFD object by invoking the push operation exported by it, through the standard CosEventComm::PushConsumer interface.

4. The PushEFD object supplies the event to JIDM::EventPort objects corresponding to the different destinations.

5. The proxy of an OSIMgmt::EventPort in the CORBA/CMIP gateway constructs a CMIP m-event-report request PDU and sends it through the CMIS communication endpoint it holds.

Sending m-event-report Requests - Pull Model

• Various JIDM::EventPorts, each of which is bound to one AE_title contained in the list of destinations defined for the PushEFD.

• A single JIDM::EventPort bound to a wildcard address (only valid if automatic event forwarding - recipient manager resolution is supported).

A PushEFD registers itself as a Push or Pull Supplier for each destination.

Basic algorithm:

1. A PullEFD registers itself as a CosEventComm::PullConsumer in every event channel that is necessary.

2. CORBA managed objects report events by using the standard event notification services. Each event notification being generated is finally received by some event channel, connected to the PullEFD object.

3. The PullEFD object pulls event notifications received by all event channels where it is registered by means of invoking the pull operation exported by them, through the standard CosEventComm::PullSupplier interface.

4. The PushEFD object supplies the event to OSIMgmt::EventPort objects corresponding to the different destinations.

5. The proxy of an OSIMgmt::EventPort in the CORBA/CMIP gateway constructs a CMIP m-event-report request PDU and sends it through the CMIS communication endpoint it holds.

Footnotes

1.

The Joint Inter-domain Working Group is considering whether this operation should be specified in the standard OSIMgmt::ManagedObject interface.

2.

The Joint Inter-domain Working Group is considering if this operation should be specified in the OSIMgmt::ManagedObject interface.