Previous section.

Book 2: Inter-Domain Management: Interaction Translation (JIDM_IT)
Copyright © 1999 The Open Group

OSI Management Facilities

Overview

The adopted approach consists in defining a set of CORBA Facilities, referred as OSI Management Facilities, that will be used to implement Management Applications, following the principles defined in the OSI Systems Management Reference Model.

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:

OSIMgmt Module

The OSIMgmt module (see OSIMgmt Module Definition) comprises a collection of interfaces that together define a basic set of services for developing Systems Management Applications based on CORBA. This module contains the following interfaces:

This section describes these interfaces and their operations in detail.



Table: OSIMgmt Module Definition





#ifndef _OSIMGMT_IDL_
#define _OSIMGMT_IDL_
 
#include <JIDM.idl>
#include X501Inf.idl
#include X711CMI.idl
 
#pragma prefix "omg.org"
 
// Macros used in the "raises" clauses
 
#define ROSE_ERRORS\
OSIMgmt::ROSEDuplicateInvocation,\
OSIMgmt::ROSEMistypedArgument,\
OSIMgmt::ROSEResourceLimitation, \
OSIMgmt::ROSEUnrecognizedOperation
 
#define CREATE_ERRORS\
ROSE_ERRORS, \
OSIMgmt::AccessDenied,\
OSIMgmt::ClassInstanceConflict,\
OSIMgmt::DuplicateManagedObjectInstance,\
OSIMgmt::InvalidAttributeValue,\
OSIMgmt::InvalidObjectInstance,\
OSIMgmt::MissingAttributeValue,\
OSIMgmt::NoSuchAttribute,\
OSIMgmt::NoSuchObjectClass,\
OSIMgmt::NoSuchObjectInstance,\
OSIMgmt::NoSuchReferenceObject,\
OSIMgmt::ProcessingFailure,\
OSIMgmt::ProcessingFailureEmpty
 
#define COMMON_ERRORS \
ROSE_ERRORS, \
OSIMgmt::AccessDenied, \
OSIMgmt::ClassInstanceConflict, \
OSIMgmt::ComplexityLimitation, \
OSIMgmt::ComplexityLimitationEmpty, \
OSIMgmt::InvalidScope, \
OSIMgmt::InvalidFilter, \
OSIMgmt::NoSuchObjectClass, \
OSIMgmt::NoSuchObjectInstance, \
OSIMgmt::ProcessingFailure, \
OSIMgmt::ProcessingFailureEmpty, \
OSIMgmt::SyncNotSupported







#define GET_ERRORS \
COMMON_ERRORS, \
OSIMgmt::GetListError, \
OSIMgmt::OperationCancelled
 
#define SET_ERRORS \
COMMON_ERRORS, \
OSIMgmt::SetListError
 
#define ATTRIBUTE_ERRORS \
COMMON_ERRORS, \
OSIMgmt::GetListError, \
OSIMgmt::SetListError
 
#define ACTION_ERRORS \
COMMON_ERRORS, \
OSIMgmt::InvalidArgumentValue, \
OSIMgmt::NoSuchAction, \
OSIMgmt::NoSuchArgument
 
#define DELETE_ERRORS \
COMMON_ERRORS
 
module OSIMgmt
{
// Definitions of ROSE and CMIS exceptions
exception ROSEDuplicateInvocation { };
exception ROSEMistypedArgument { };
exception ROSEResourceLimitation { };
exception ROSEUnrecognizedOperation { };
 
exception AccessDenied { };
exception ClassInstanceConflict
{ X711CMI::BaseManagedObjectIdType error_info; };
exception ComplexityLimitation
{ X711CMI::ComplexityLimitationType error_info; };
exception ComplexityLimitationEmpty { };
exception DuplicateManagedObjectInstance
{ X711CMI::ObjectInstanceType error_info; };
exception GetListError
{ X711CMI::GetListErrorType error_info; };
exception InvalidArgumentValue
{ X711CMI::InvalidArgumentValueType error_info; };
exception InvalidAttributeValue
{ X711CMI::AttributeType error_info; };
exception InvalidFilter
{ X711CMI::CMISFilterType error_info; };







exception InvalidScope
{ X711CMI::ScopeType error_info; };
exception InvalidObjectInstance
{ X711CMI::ObjectInstanceType error_info; };
exception MissingAttributeValue
{ X711CMI::MissingAttributeValueType error_info; };
exception MistypedOperation { };
exception NoSuchAction
{ X711CMI::NoSuchActionType error_info; };
exception NoSuchArgument
{ X711CMI::NoSuchArgumentType error_info; };
exception NoSuchAttribute
{ X711CMI::AttributeIdType error_info; };
exception NoSuchObjectClass
{ X711CMI::ObjectClassType error_info; };
exception NoSuchObjectInstance
{ X711CMI::ObjectInstanceType error_info; };
exception NoSuchReferenceObject
{ X711CMI::ObjectInstanceType error_info; };
exception OperationCancelled { };
exception ProcessingFailure
{ X711CMI::ProcessingFailureType error_info; };
exception ProcessingFailureEmpty { };
exception SetListError
{ X711CMI::SetListErrorType error_info; };
exception SyncNotSupported
{ X711CMI::CMISSyncType error_info; };
exception NoSuchEventType
{ X711CMI::NoSuchEventTypeType error_info; };
exception NoSuchInvokeId
{ X711CMI::InvokeIdTypeType error_info; };
 
// Using Multiple Replies exception for Actions
interface RepliesIterator; // forward declaration
exception UsingMR
{ RepliesIterator replies_iterator; };
 
// Definition of specific types used within this module
typedef string NameString;
typedef sequence<ASN1_ObjectIdentifier> ASN1_ObjectIdentifierSeq;
struct AttributeValue {
ASN1_ObjectIdentifier attribute_id;
ASN1_DefinedAny value;
};
typedef sequence<AttributeValue> AttributeValueSeq;
 
// Type to be used in cmis_create operations
enum CreationKind
{simple, autonaming, subordinate};







// Type to be used in scoped set operations
enum ModifyOperator
{replace, add_member, remove_member, replace_with_default};
 
struct AttributeSetOperator {
ModifyOperator modify_operator;
ASN1_ObjectIdentifier attribute_id;
ASN1_DefinedAny attribute_value;
};
typedef sequence <AttributeSetOperator> SetOperationArgument;
 
// Forward declaration for ReplyHandler interfaces
interface LinkedReplyHandler;
interface EndOfRepliesHandler;
 
// ProxyAgent
interface ProxyAgent : JIDM::ProxyAgent {
 
void cmis_create (
in CORBA::ScopedName interface_name,
in CreationKind creation_kind,
in CosNaming::Name object_name,
in X711CMI::AccessControlTypeOpt access_control,
in CosNaming::Name reference_object,
in AttributeValueSeq req_attribute_values,
in LinkedReplyHandler reply_handler
);
 
void cmis_create_sync (
in CORBA::ScopedName interface_name,
in CreationKind creation_kind,
in CosNaming::Name object_name,
in X711CMI::AccessControlTypeOpt access_control,
in CosNaming::Name reference_object,
in AttributeValueSeq req_attribute_values,
out CORBA::ScopedName created_interface_name,
out CosNaming::Name created_object_name,
out X711CMI::ASN1_GeneralizedTimeOpt creation_time,
out AttributeValueSeq created_attribute_values
) raises (CREATE_ERRORS);







void cmis_get (
in CORBA::ScopedName interface_name,
in CosNaming::Name object_name,
in X711CMI::ScopeType scope,
in X711CMI::CMISFilterType filter,
in X711CMI::CMISSyncType synchronization,
in X711CMI::AccessControlTypeOpt access_control,
in ASN1_ObjectIdentifierSeq attribute_id_list,
in LinkedReplyHandler reply_handler,
in EndOfRepliesHandler end_of_replies_handler
);
 
void cmis_set (
in CORBA::ScopedName interface_name,
in CosNaming::Name object_name,
in X711CMI::ScopeType scope,
in X711CMI::CMISFilterType filter,
in X711CMI::CMISSyncType synchronization,
in X711CMI::AccessControlTypeOpt access_control,
in SetOperationArgument modification_list,
in LinkedReplyHandler reply_handler,
in EndOfRepliesHandler end_of_replies_handler
);
 
void cmis_action (
in CORBA::ScopedName interface_name,
in CosNaming::Name object_name,
in X711CMI::ScopeType scope,
in X711CMI::CMISFilterType filter,
in X711CMI::CMISSyncType synchronization,
in X711CMI::AccessControlTypeOpt access_control,
in ASN1_ObjectIdentifier action_name,
in ASN1_DefinedAny action_info,
in LinkedReplyHandler reply_handler,
in EndOfRepliesHandler end_of_replies_handler
);
 
void cmis_delete (
in CORBA::ScopedName interface_name,
in CosNaming::Name object_name,
in X711CMI::ScopeType scope,
in X711CMI::CMISFilterType filter,
in X711CMI::CMISSyncType synchronization,
in X711CMI::AccessControlTypeOpt access_control,
in LinkedReplyHandler reply_handler,
in EndOfRepliesHandler end_of_replies_handler
);
};







const ASN1_ObjectIdentifier ACTUAL_CLASS = 2.9.3.4.3.42;
interface ManagedObject; // forward declaration
 
interface NamingContext : CosNaming::NamingContext {
// NOTE: These operations are optional
ManagedObject resolve_with_intf (
in CORBA::ScopedName interface_name,
in CosNaming::Name object_name
) raises (NotFound, CannotProceed, InvalidName);
ManagedObject resolve_osi_name (
in ASN1_ObjectIdentifier managed_object_class,
in X711CMI::ObjectInstanceType object_instance
) raises (NotFound, CannotProceed, InvalidName);
 
CosNaming::Name translate_osi_name (
in X711CMI::ObjectInstanceType object_instance
) raises (InvalidName);
 
X711CMI::ObjectInstanceType translate_idl_name (
in CosNaming::Name idl_name
) raises (InvalidName);
};
 
// ManagedObject
interface ManagedObject : NamingContext, CosLifeCycle::LifeCycleObject
{
readonly attribute CosNaming::Name object_name;
 
void scoped_get (
in X711CMI::ScopeType scope,
in X711CMI::CMISFilterType filter,
in X711CMI::CMISSyncType synchronization,
in X711CMI::AccessControlTypeOpt access_control,
in ASN1_ObjectIdentifierSeq attribute_id_list,
in LinkedReplyHandler reply_handler,
in EndOfRepliesHandler end_of_replies_handler
);
 
void scoped_set (
in X711CMI::ScopeType scope,
in X711CMI::CMISFilterType filter,
in X711CMI::CMISSyncType synchronization,
in X711CMI::AccessControlTypeOpt access_control,
in SetOperationArgument modification_list,
in LinkedReplyHandler reply_handler,
in EndOfRepliesHandler end_of_replies_handler
);







void scoped_action (
in X711CMI::ScopeType scope,
in X711CMI::CMISFilterType filter,
in X711CMI::CMISSyncType synchronization,
in X711CMI::AccessControlTypeOpt access_control,
in ASN1_ObjectIdentifier action_name,
in ASN1_DefinedAny action_info,
in LinkedReplyHandler reply_handler,
in EndOfRepliesHandler end_of_replies_handler
);
 
void scoped_delete (
in X711CMI::ScopeType scope,
in X711CMI::CMISFilterType filter,
in X711CMI::CMISSyncType synchronization,
in X711CMI::AccessControlTypeOpt access_control,
in LinkedReplyHandler reply_handler,
in EndOfRepliesHandler end_of_replies_handler
);
 
AttributeValueSeq get_attributes (
in ASN1_ObjectIdentifierSeq attribute_id_list
) raises (GET_ERRORS);
 
AttributeValueSeq set_attributes (
in SetOperationArgument modification_list
) raises (SET_ERRORS);
 
ASN1_DefinedAny perform_action (
in ASN1_ObjectIdentifier action_name,
in ASN1_DefinedAny action_info
) raises (ACTION_ERRORS, UsingMR);
 
void delete_mo () raises (DELETE_ERRORS);
};
 
// ManagedObjectFactory
interface ManagedObjectFactory {
ManagedObject create (
in CORBA::ScopedName interface_name,
in CosNaming::Name object_name,
in ManagedObject reference_object,
in AttributeValueSeq requested_attribute_values
) raises (CREATE_ERRORS);
 
ManagedObject create_with_auto_naming (
in CORBA::ScopedName interface_name,
in ManagedObject reference_object,
in AttributeValueSeq requested_attribute_values
) raises (CREATE_ERRORS);







ManagedObject create_subordinate (
in CORBA::ScopedName interface_name,
in CosNaming::Name superior_name,
in ManagedObject reference_object,
in AttributeValueSeq requested_attribute_values
) raises (CREATE_ERRORS);
};
 
// LocalRoot
typedef sequence<ManagedObject> ManagedObjectSeq;
 
interface LocalRoot : ManagedObject {
exception NoDescendants {};
ManagedObjectSeq list_orphans ( );
ManagedObjectSeq
list_orphan_descendants (in CosNaming::Name object_name)
raises (NoDescendants);
};
 
// LName
interface LName {
exception InvalidName {};
 
readonly attribute boolean is_distinguished_name;
readonly attribute unsigned long num_components;
 
void from_osi_form (in X711CMI::ObjectInstanceType osi_name);
X711CMI::ObjectInstanceType to_osi_form ()
raises(InvalidName);
void from_idl_form (in CosNaming::Name idl_name);
CosNaming::Name to_idl_form ()
raises(InvalidName);
 
LName to_ancestor_name (in unsigned long levels_up)
raises(InvalidName);
LName to_relative_name (in unsigned long levels_up)
raises(InvalidName);
LName append (in LName name);
LName append_ava (in X501Inf::AttributeValueAssertionType ava)
raises(InvalidName);
X501Inf::AttributeValueAssertionType get_ava (in unsigned long index)
raises(InvalidName);
 
boolean equals (in LName name);
LName copy ();







void from_string_form (in NameString name_string);
NameString to_string_form ()
raises(InvalidName);
 
void destroy ();
};
 
// ReplyHandler interfaces
interface LinkedReplyHandler {
void send_reply (
in CORBA::ScopedName object_interface,
in CosNaming::Name object_name,
in X711CMI::ASN1_GeneralizedTimeOpt current_time,
in any reply_info
);
 
void send_mo_error (
in CORBA::ScopedName object_interface,
in CosNaming::Name object_name,
in X711CMI::ASN1_GeneralizedTimeOpt current_time,
in short error_code,
in any error_info
);
 
void send_subtree_error (
in CORBA::ScopedName object_interface,
in CosNaming::Name object_name,
in X711CMI::ASN1_GeneralizedTimeOpt current_time,
in short error_code,
in any error_info
);
};
 
interface EndOfRepliesHandler {
void end_of_replies ( );
};
 
interface MultipleRepliesHandler : LinkedReplyHandler, EndOfRepliesHandler {};
 
// BufferedRepliesHandler
struct Reply {
CORBA::ScopedName object_interface;
CosNaming::Name object_name;
X711CMI::ASN1_GeneralizedTimeOpt current_time;
any reply_info;
};
typedef sequence<Reply> ReplyList;







interface RepliesIterator {
exception MoError {
CORBA::ScopedName object_interface;
CosNaming::Name object_name;
X711CMI::ASN1_GeneralizedTimeOpt current_time;
short error_code;
any error_info;
};
 
exception SubtreeError {
CORBA::ScopedName object_interface;
CosNaming::Name object_name;
X711CMI::ASN1_GeneralizedTimeOpt current_time;
short error_code;
any error_info;
};
 
boolean get_reply (out Reply r) raises (MoError, SubtreeError);
 
boolean get_n_replies (in unsigned long how_many, out ReplyList r_list)
raises (MoError, SubtreeError);
 
boolean finished (out unsigned long num_pending);
void destroy ();
};
 
interface BufferedRepliesHandler : MultipleRepliesHandler, RepliesIterator {};
 
};
 
#define UsingMR OSIMgmt::UsingMR
 
#endif /* _OSIMGMT_IDL_ */


OSIMgmt::LName Interface

In the OSI Systems Management Reference Model, any managed object is contained within one and only one containing managed object. The containment relationship is used for naming managed objects. Actually, any managed object is named by the combination of:

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:

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.


Table: OSIMgmt::LName Library





typedef string NameString;
 
interface LName {
exception InvalidName {};
 
readonly attribute boolean is_distinguished_name;
readonly attribute unsigned long num_components;
 
void from_osi_form (in X711CMI::ObjectInstanceType osi_name);
X711CMI::ObjectInstanceType to_osi_form ()
raises(InvalidName);
void from_idl_form (in CosNaming::Name idl_name);
CosNaming::Name to_idl_form ()
raises(InvalidName);
 
LName to_ancestor_name (in unsigned long levels_up)
raises(InvalidName);
LName to_relative_name (in unsigned long levels_up)
raises(InvalidName);
LName append (in LName name);
LName append_ava (in X501Inf::AttributeValueAssertionType ava)
raises(InvalidName);
X501Inf::AttributeValueAssertionType get_ava (in unsigned long index)
raises(InvalidName);
boolean equals (in LName name);
LName copy ();
 
void from_string_form (in NameString name_string);
NameString to_string_form ()
raises(InvalidName);
 
void destroy ();
};


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
Besides the operations used to translate between different name formats (in this case, OSI name format, IDL naming format and string format), the OSIMgmt::Lname interface defines several additional operations designed to ease the task of programming with an 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
Translation of OSI ObjectInstance names into CosNaming::Names implies performing the following steps:

  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:

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.


Table: Binding a Name to an EFD Object





CosNaming::NamingContext_ptr ctx;
X721::eventForwardingDiscriminator_ptr efd;
X711CMI::ObjectInstanceType local_name;
 
// The OSI name of the EFD object was initialized some way:
 
local_name = ...;
 
// An OSIMgmt::LName variable is initialized:
 
OSIMgmt::LName_ptr efd_name = new OSIMgmt::LName ();
efd_name>from_osi_form (local_name);
 
// A name, in idl form, is bound with the reference to the EFD object:
 
ctx>bind (efd, efd_name->to_idl_form());
 
// free the space associated to the name of the managed object:
 
efd_name>destroy ();


Representation of CosNaming::Names
The internal representation of CosNaming::Names derived from OSI names is transparent to clients of managed objects. In order to develop portable applications, a programmer does not need to know how OSI names (X711CMI::ObjectInstanceType values) are translated into CosNaming::Name values. However, in order to ensure interworking between applications that are linked to different implementations of the OSIMgmt::LName library, a standard representation of CosNaming::Names is specified.

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:

Complex values are represented according to the following rules:

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.





Figure: CosNaming::Name Associated to an X721::log Object


Representation of CosNaming::Names in String Format
This specification defines a simple string format that enables to represent managed object names. Names represented in this format (values of type OSIMgmt::NameString) can be converted (obtained) into (from) OSI Object Instance names or CosNaming::Names using OSIMgmt::LName objects.

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.


Example: Locating a logRecord Object





CosNaming::NamingContext_ptr ctx;
OSIMgmt::NameString log_record_name;
 
// An OSIMgmt::LName variable is initialized with the name
// of the managed object in string format:
 
local_name = 2.9.3.2.2=(string)\PrimaryLog\2.9.3.2.3=0101;
OSIMgmt::LName_ptr log_record_name = new OSIMgmt::LName ();
log_record_name>from_string_form (local_name);
 
// A reference to the logRecord managed object is found by means of
// invoking resolve on the initial CosNaming::NamingContext
// located at the managed object domain:
 
CORBA::Object_ptr obj = ctx>resolve (log_record_name->to_idl_form());
 
// The reference obtained from resolve is narrowed, in order
// to invoke operations on the logRecord object:
 
X721::logRecord_ptr log_record = X721::logRecord::_narrow (obj);
ASN1_GeneralizedTime logging_time = log_record>loggingTimeGet ();
 
// free the space associated to the name of the managed object:
 
log_record_name>destroy ();


OSIMgmt::ProxyAgent Interface

CORBA manager objects that require to get access to managed objects that are members of some given OSI managed object domain must establish a connection with that domain.

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.


Table: OSIMgmt::ProxyAgent Interface





enum CreationKind
{simple, autonaming, subordinate};
 
interface ProxyAgent : JIDM::ProxyAgent {
 
void cmis_create (
in CORBA::ScopedName interface_name,
in CreationKind creation_kind,
in CosNaming::Name object_name,
in X711CMI::AccessControlTypeOpt access_control,
in CosNaming::Name reference_object,
in AttributeValueSeq req_attribute_values,
in LinkedReplyHandler reply_handler
);
 
void cmis_create_sync (
in CORBA::ScopedName interface_name,
in CreationKind creation_kind,
in CosNaming::Name object_name,
in X711CMI::AccessControlTypeOpt access_control,
in CosNaming::Name reference_object,
in AttributeValueSeq req_attribute_values,
out CORBA::ScopedName created_interface_name,
out CosNaming::Name created_object_name,
out X711CMI::ASN1_GeneralizedTimeOpt creation_time,
out AttributeValueSeq created_attribute_values
) raises (CREATE_ERRORS);
 
void cmis_get (
in CORBA::ScopedName interface_name,
in CosNaming::Name object_name,
in X711CMI::ScopeType scope,
in X711CMI::CMISFilterType filter,
in X711CMI::CMISSyncType synchronization,
in X711CMI::AccessControlTypeOpt access_control,
in ASN1_ObjectIdentifierSeq attribute_id_list,
in LinkedReplyHandler reply_handler,
in EndOfRepliesHandler end_of_replies_handler
);






void cmis_set (
in CORBA::ScopedName interface_name,
in CosNaming::Name object_name,
in X711CMI::ScopeType scope,
in X711CMI::CMISFilterType filter,
in X711CMI::CMISSyncType synchronization,
in X711CMI::AccessControlTypeOpt access_control,
in SetOperationArgument modification_list,
in LinkedReplyHandler reply_handler,
in EndOfRepliesHandler end_of_replies_handler
);
 
void cmis_action (
in CORBA::ScopedName interface_name,
in CosNaming::Name object_name,
in X711CMI::ScopeType scope,
in X711CMI::CMISFilterType filter,
in X711CMI::CMISSyncType synchronization,
in X711CMI::AccessControlTypeOpt access_control,
in ASN1_ObjectIdentifier action_name,
in ASN1_DefinedAny action_info,
in LinkedReplyHandler reply_handler,
in EndOfRepliesHandler end_of_replies_handler
);
 
void cmis_delete (
in CORBA::ScopedName interface_name,
in CosNaming::Name object_name,
in X711CMI::ScopeType scope,
in X711CMI::CMISFilterType filter,
in X711CMI::CMISSyncType synchronization,
in X711CMI::AccessControlTypeOpt access_control,
in LinkedReplyHandler reply_handler,
in EndOfRepliesHandler end_of_replies_handler
);
};


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.

Table: OSIMgmt Conventions for Proxy Agent Finding Criteria

Criterion Name Type of Value Meaning
domain title X227ACS::AE_titleType AEtitle associated to the managed object domain for which access is requested. The wildcard address is allowed.
controller object JIDM::ProxyAgentController reference associated to a JIDM::ProxyAgentController object registered by the manager (OPTIONAL)
access control X711CMI::AccessControlType default access privileges for all exchanges on the association (OPTIONAL)
requestor title X227ACS::AE_titleType title used to denote the Manager which requested access to the OSI managed object domain (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:

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:

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.







Figure: OSIMgmt::ProxyAgents in a CORBA Environment

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 remainder of this sub-section gives Descriptions for the ProxyAgent operations.

The get_domain_factory_finder Operation
The get_domain_factory_finder() operation enables obtaining a reference to the initial CosLifeCycle::FactoryFinder object located at the domain being accessed through a given OSIMgmt::ProxyAgent object. As already explained in The JIDM::ProxyAgent Interface, CORBA manager objects can locate appropriate managed object factories by means of invoking the find_factories() operation exposed by this initial CosLifeCycle::FactoryFinder object.

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

Table: OSIMgmt Conventions for Factory Finder Keys

id field kind field Meaning
fully scoped name
of object interface
superior object interface Find factories that create objects whose superior object supports the named interface
fully scoped name
of object interface
object interface Find factories that create objects supporting the named interface
fully scoped name
of factory interface
factory interface Find factories supporting the named factory interface

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:

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

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:

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

Table: OSIMgmt Conventions for Managed Object Creation Criteria

Criterion Name Type of Value Interpretation
managed object interface CORBA::ScopedName Name of interface exported by the new managed object.
managed object name CosNaming::Name When this parameter is supplied, it contains the name of the new managed object.
superior object name CosNaming::Name When this parameter is supplied, it contains the name of the managed object which is to be the superior of the new managed object.
reference object OSIMgmt::ManagedObject When this parameter is supplied, it contains the value of a reference to an existing managed object to be considered as reference for initialization.
attribute list OSIMgmt::AttributeValueSeq When this parameter is supplied, it contains a set of attribute identifiers and values to be assigned to the new managed object.

The get_domain_naming_context Operation
The get_domain_naming_context() operation enables to obtain a reference to the initial CosNaming::NamingContext object located at the domain being accessed through a given OSIMgmt::ProxyAgent object.

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.


Example: Finding a Log Record by Name





OSIMgmt::ProxyAgent_ptr agent;

 
// a reference to a JIDM::ProxyAgent is obtained as a result of
// establishing a connection to the managed object domain where
// the printer is located:
agent = ...;

 
// a reference to the initial CosNaming::NamingContext object
// is obtained:
CosNaming::NamingContext_ptr ctx = agent > get_domain_naming_context
();

 
// the name of the log record is constructed:
OSIMgmt::LName_ptr log_name = new OSIMgmt::LName ();
log_name>from_string_form
(2.9.3.2.2=(string)\PrimaryLog\2.9.3.2.3=0101);
 
// find a reference to the object with the log_name value in IDL form:
CORBA::Object_ptr obj = ctx>resolve (log_name->to_idl_form());
log_name>destroy ();
 
// narrows the value returned by the resolve operation:
X721::logRecord_ptr a_log_rec = X711::logRecord::_narrow (obj);
 
// operations on the log can now be invoked:
ASN1_GeneralizedTime logging_time = a_log_rec>loggingTimeGet ();


CMIS Operations
OSIMgmt::ProxyAgent objects support operations that enable CORBA Managers to operate upon selected descendants of managed objects that are members of a given managed object domain. These operations are referred to as scoped operations.

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

The destroy Operation
Any OSIMgmt::ProxyAgent object exposes the destroy() operation which enables disposing of the object. Disposing of an OSIMgmt::ProxyAgent object means closing the connection established to the corresponding managed object domain. If the OSIMgmt::ProxyAgent object was running in a JIDM gateway server, destruction of the object implies freeing resources used to maintain the associated connection (closing an XMP descriptor, for example).

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

The OSIMgmt::NamingContext interface provides a placeholder for specialized and extended naming operations that may be performed in an OSI management context. This interface extends that of the basic CosNaming::NamingContext.

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.


Table: OSIMgmt::NamingContext Interface





const ASN1_ObjectIdentifier ACTUAL_CLASS = 2.9.3.4.3.42;
 
interface NamingContext : CosNaming::NamingContext {
// NOTE: These operations are optional
ManagedObject resolve_with_intf (
in CORBA::ScopedName interface_name,
in CosNaming::Name object_name
) raises (NotFound, CannotProceed, InvalidName);
 
ManagedObject resolve_osi_name (
in ASN1_ObjectIdentifier managed_object_class,
in X711CMI::ObjectInstanceType object_instance
) raises (NotFound, CannotProceed, InvalidName);
 
CosNaming::Name translate_osi_name (
in X711CMI::ObjectInstanceType object_instance
) raises (InvalidName);
 
X711CMI::ObjectInstanceType translate_idl_name (
in CosNaming::Name idl_name
) raises (InvalidName);
};


The resolve_with_intf Operation
This operation is equivalent to the CosNaming::NamingContext::resolve operation, but takes an extra parameter that indicates the managed object class supported by the object being located.

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
This operation obtains a reference to a managed object given its OSI name (and, potentially, the managed object class to which it belongs). The OSI name includes information such as whether the name is in global form or in local form, and the sequence of attribute value assertions forming the path to the object being located.

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 returns the CosNaming::Name corresponding to the X711CMI::ObjectInstanceType passed as input parameter. This operation is useful should the OSIMgmt::LName functionality not be available.

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 returns the X711CMI::ObjectInstanceType corresponding to the CosNaming::Name passed as input parameter. This operation is useful should the OSIMgmt::LName functionality not be available.

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

The standard X721::top interface inherits from the OSIMgmt::ManagedObject interface. As a consequence, all management interfaces generated by a GDMO to IDL compiler inherit (indirectly) from the OSIMgmt::ManagedObject interface. This inheritance tree is shown in Inheritance Tree.







Figure: Inheritance Tree

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.


Table: OSIMgmt::ManagedObject Interface





interface ManagedObject : NamingContext, CosLifeCycle::LifeCycleObject
{
readonly attribute CosNaming::Name object_name;
 
void scoped_get (
in X711CMI::ScopeType scope,
in X711CMI::CMISFilterType filter,
in X711CMI::CMISSyncType synchronization,
in X711CMI::AccessControlTypeOpt access_control,
in ASN1_ObjectIdentifierSeq attribute_id_list,
in LinkedReplyHandler reply_handler,
in EndOfRepliesHandler end_of_replies_handle);
 
void scoped_set (
in X711CMI::ScopeType scope,
in X711CMI::CMISFilterType filter,
in X711CMI::CMISSyncType synchronization,
in X711CMI::AccessControlTypeOpt access_control,
in SetOperationArgument modification_list,
in LinkedReplyHandler reply_handler,
in EndOfRepliesHandler end_of_replies_handler
);
 
void scoped_action (
in X711CMI::ScopeType scope,
in X711CMI::CMISFilterType filter,
in X711CMI::CMISSyncType synchronization,
in X711CMI::AccessControlTypeOpt access_control,
in ASN1_ObjectIdentifier action_name,
in ASN1_DefinedAny action_info,
in LinkedReplyHandler reply_handler,
in EndOfRepliesHandler end_of_replies_handler
);
 
void scoped_delete (
in X711CMI::ScopeType scope,
in X711CMI::CMISFilterType filter,
in X711CMI::CMISSyncType synchronization,
in X711CMI::AccessControlTypeOpt access_control,
in LinkedReplyHandler reply_handler,
in EndOfRepliesHandler end_of_replies_handler
);
 
AttributeValueSeq get_attributes (
in ASN1_ObjectIdentifierSeq attr_id_list
) raises (GET_ERRORS);






AttributeValueSeq set_attributes (
in SetOperationArgument modification_list
) raises (SET_ERRORS);
 
ASN1_DefinedAny perform_action (
in ASN1_ObjectIdentifier action_id,
in ASN1_DefinedAny action_info
) raises (ACTION_ERRORS, UsingMR);
 
void delete_mo () raises (DELETE_ERRORS);
};


Naming
The OSIMgmt::ManagedObject interface inherits indirectly from the standard CosNaming::NamingContext interface, via the OSIMgmt::NamingContext interface. This means that every managed object exposes operations defined in the CosNaming::NamingContext interface. However, only the resolve and list operations may be invoked by CORBA managers. CORBA managers that invoke any of the other operations in the CosNaming::NamingContext interface should receive the NO_PERMISSION exception. Note that this restriction does not apply to CORBA agents, that may use the other CosNaming::NamingContext operations to register new CORBA managed objects.

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.

Table: Exceptions Raised by OSI Resolve Operations

Exception Raised Description
NotFound Indicates the name does not identify an existing managed object; this is equivalent to the OSI NoSuchObjectInstance error code.
CannotProceed Indicates that implementation of the resolve operation has given up for some reason. However, if the CosNaming::NamingContext reference contained in the exception is not nil, the client may be able to continue the operation using the returned name. If the exception contains a nil CosNaming::NamingContext reference, then the situation is not recoverable, which may happen, for example, in situations such as those that cause the OSI ProcessingFailure error code.
InvalidName Indicates the name is invalid. In OSI management it can occur in at least the following cases:

  • A name, in its OSI form (X711CMI::ObjectInstance), does not contain a valid value as defined in X.720; this is equivalent to the OSI InvalidObjectInstance error code.

  • A name, in its IDL form (CosNaming::Name), does not contain a valid value as defined in OSIMgmt::LName Interface.

  • An object class, provided in either resolve_with_intf or resolve_osi_name, does not exist; this is equivalent to the OSI NoSuchObjectClass error code.

  • The managed object named in either resolve_with_intf or resolve_osi_name does not support the object class provided; this is equivalent to the OSI ClassInstanceConflict error code.

  • The name has a 0 length.

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

Inherited Operations from CosLifeCycle::LifeCycleObject
The OSIMgmt::ManagedObject interface inherits from the standard CosLifeCycle::LifeCycleObject interface. This means that every managed object exposes the operations defined in the CosLifeCycle::LifeCycleObject interface. Specifically, the following semantics for the operations are specified:

The object_name Attribute
This read-only attribute gives access to the name of the managed object in IDL form.
CMIS Operations
OSIMgmt::ManagedObject objects support operations that enable CORBA Managers to operate upon selected descendants of the managed object. These operations are referred as scoped operations, and provide a similar mechanism to that provided by OSIMgmt::ProxyAgent objects.

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

Generic multi-attribute Operations
Besides providing scoped operations (that might affect several managed objects), the OSIMgmt::ManagedObject interface exports also operations to manipulate several attributes of the managed object at the same time. Specifically, operations to get the values associated to multiple attributes ( get_attributes()) and to set the values of multiple attributes ( set_attributes()) are provided. These operations are synchronous (that is, they block until the response is available).
The perform_action Operation
This operation provides a generic mechanism to invoke an action on the managed object. Any action supported by the specific managed object being accessed might be invoked in this way. The action invokation takes a parameter indicating the action to be performed (specified as an ASN1_ObjectIdentifier) and the input parameter corresponding to this action. The return value corresponds to the return type appropriate for the invoked action.

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
The OSIMgmt::ManagedObject includes a delete_mo() operation, that enables the deletion of a managed object without the need to specify any scoping, filtering, synchronization and access control arguments. Note that deletion of a managed object may cause deletion of its descendants, if such behavior has been defined. This call is synchronous (that is, it blocks until the corresponding managed object in the managed domain has effectively been deleted).

OSIMgmt::ManagedObjectFactory Interface

An OSIMgmt::ManagedObjectFactory can be used to create managed objects of more than one type. As a consequence of this, operations exposed through the OSIMgmt::ManagedObjectFactory interface always receive the name of the interface as an input argument.

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.


Table: OSIMgmt::ManagedObjectFactory Interface





struct AttributeValue {
ASN1_ObjectIdentifier attribute_id;
ASN1_DefinedAny value;
};
typedef sequence<AttributeValue> AttributeValueSeq;
 
interface ManagedObjectFactory {
 
ManagedObject create (
in CORBA::ScopedName interface_name,
in CosNaming::Name object_name,
in ManagedObject reference_object,
in AttributeValueSeq requested_attribute_values
) raises (CREATE_ERRORS);
 
ManagedObject create_with_auto_naming (
in CORBA::ScopedName interface_name,
in ManagedObject reference_object,
in AttributeValueSeq requested_attribute_values
) raises (CREATE_ERRORS);
 
ManagedObject create_subordinate (
in CORBA::ScopedName interface_name,
in CosNaming::Name superior_name,
in ManagedObject reference_object,
in AttributeValueSeq requested_attribute_values
) raises (CREATE_ERRORS);
};


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

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

Application of scoped operations involves two phases: scoping and filtering. The base managed object of a scoped operation is defined as the root of the subtree of managed objects to which scoping and filtering is going to be applied.

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
To determine the base managed object applicable to scoped operations, a different mechanism is used by OSIMgmt::ProxyAgent objects and by OSIMgmt::ManagedObject objects.

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

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

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:

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

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

The GET Operations
Besides the parameters specified above, the scoped GET operations (cmis_get, scoped_get) carry the following extra parameter:

The SET Operations
The set() operation may perform one of the following modifications to attributes:

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

The ACTION Operations
The action operation requests the managed objects to perform the specified action and to indicate the result of that action. With respect to confirmations, action operations may be defined to always require confirmation or to allow the invoker to request a confirmation or not.

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:

The DELETE Operations
The scoped DELETE operations ( cmis_delete(), scoped_delete()) are used to request the managed objects selected as a result of applying the scoping and filtering arguments to delete themselves. These operations do not require any additional parameters.
The CREATE Operations
These operations are only available through the OSIMgmt::ProxyAgent interface (that is, they are not available from the OSIMgmt::ManagedObject interface), and provide another mechanism to create objects in the managed domain.

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:

Both operations differ in the way they receive responses:

OSIMgmt::<reply-handler> Interfaces

These <reply-handler> interfaces comprise the LinkedReplyHandler, EndOfRepliesHandler, and MultipleRepliesHandler 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).


Table: Interfaces for Handling Replies to Scoped Operations





interface LinkedReplyHandler {
void send_reply (
in CORBA::ScopedName object_interface;
in CosNaming::Name object_name;
in X711CMI::ASN1_GeneralizedTimeOpt current_time,
in any reply_info
);
 
void send_mo_error (
in CORBA::ScopedName object_interface,
in CosNaming::Name object_name,
in X711CMI::ASN1_GeneralizedTimeOpt current_time,
in short error_code,
in any error_info
);
 
void send_subtree_error (
in CORBA::ScopedName object_interface,
in CosNaming::Name object_name,
in X711CMI::ASN1_GeneralizedTimeOpt current_time,
in short error_code,
in any error_info
);
};
 
interface EndOfRepliesHandler {
void end_of_replies ( );
};
 
interface MultipleRepliesHandler : LinkedReplyHandler, EndOfRepliesHandler {};


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
The following arguments are common to all OSIMgmt::LinkedReplyHandler operations:

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.

The send_reply Operation
The send_reply() operation is used to pass information associated with each reply from managed objects involved in a scoped 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.

Table: Contents of reply_info Parameter to send_reply

Scoped Operation Type carried in the reply_info parameter
ProxyAgent::cmis_create X711CMI::CreateResultAttributeListType
ProxyAgent::cmis_get
ManagedObject::scoped_get
X711CMI::GetResultAttributeListType
ProxyAgent::cmis_set
ManagedObject::scoped_set
X711CMI::SetResultAttributeListType
ProxyAgent::cmis_action
ManagedObject::scoped_action
IDL mapped type corresponding to the ACTION REPLY SYNTAX; if the action has no reply syntax, CORBA any with tc_kind equal to tk_null
ProxyAgent::cmis_delete
ManagedObject::scoped_delete
CORBA any with tc_kind equal to tk_null

The send_mo_error Operation
The send_mo_error() operation indicates that an error has been found for a given managed object.

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.

Table: Contents of error_code & error_info Parameters to send_mo_error

Scoped Operation error_code Type in the error_info parameter
ProxyAgent::cmis_get
ManagedObject::scoped_get
4 X711CMI::GetListErrorGetInfoListType
ProxyAgent::cmis_set
ManagedObject::scoped_set
5 X711CMI::SetListErrorSetInfoListType
ProxyAgent::cmis_action
ManagedObject::scoped_action
16 X711CMI::ActionErrorInfoType
ProxyAgent::cmis_delete
ManagedObject::scoped_delete
17 X711CMI::DeleteErrorDeleteErrorInfoType
all in case of ProcessingFailure 8 X711CMI::SpecificErrorInfoType, or CORBA any with tc_kind equal to tk_null

The send_subtree_error Operation
The send_subtree_error() operation indicates a fatal error in a certain managed object subtree. The client should not expect any further replies from objects in the affected managed object subtree. The interface and name of the base managed object of the subtree that experienced the fatal error are passed as arguments to this 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.

Table: error_code/error_info Parameters to send_subtree_error

Error Condition error_code Type in the error_info Parameter
AccessDenied 1 empty
ClassInstanceConflict 2 empty
ComplexityLimitation 3 X711CMI::ComplexityLimitationType, or empty
GetListError 4 X711CMI::GetListErrorGetInfoListType
SetListError 5 X711CMI::SetListErrorGetInfoListType
InvalidArgumentValue 6 X711CMI::InvalidArgumentValueType
OperationCancelled 7 empty
ProcessingFailure 8 X711CMI::SpecificErrorInfoType, or empty
InvalidFilter 9 X711CMI::CMISFilterType
InvalidScope 10 X711CMI::ScopeType
SyncNotSupported 11 X711CMI::CMISSyncType
NoSuchAction 12 X711CMI::NoSuchActionType
NoSuchArgument 13 X711CMI::NoSuchArgumentType
NoSuchObjectClass 14 X711CMI::ObjectClassType
NoSuchObjectInstance 15 X711CMI::ObjectInstanceType
DuplicateManagedObjectInstance 16 X711CMI::ObjectInstanceType
InvalidAttributeValue 17 X711CMI::AttributeType
InvalidObjectInstance 18 X711CMI::ObjectInstanceType
MissingAttributeValue 19 X711CMI::MissingAttributeValueType
NoSuchAttribute 20 X711CMI::AttributeIdType
NoSuchReferenceObject 21 X711CMI::ObjectInstanceType
MistypedOperation
NoSuchEventType
NoSuchInvokeId
-1 empty (these errors cannot happen in any scoped operation)
communication failure -2 empty
ROSE rejection -3 implementation specific
other unknowns -4 implementation specific

The end_of_replies Operation
The end_of_replies() operation indicates that no more replies are going to be received from the managed objects involved in a scoped operation, therefore signalling the complete finalization of the process. This operation is invoked after all invocations to send_reply(), send_mo_error() and send_subtree_error() from objects within the scope/filter parameters specified in the scoped operation have returned. Note that with this behaviour, race conditions are avoided.

OSIMgmt::BufferedRepliesHandler Interface

The OSIMgmt::BufferedRepliesHandler is a facility that allows client programmers to use a deferred synchronous model to retrieve responses for multiple replies in an on-demand basis. This complements the fully asynchronous model provided by the OSIMgmt::LinkedReplyHandler and OSIMgmt::EndOfRepliesHandler interfaces.


Table: OSIMgmt::BufferedRepliesHandler Interface





struct Reply {
CORBA::ScopedName object_interface;
CosNaming::Name object_name;
X711CMI::ASN1_GeneralizedTimeOpt current_time;
any reply_info;
};
typedef sequence<Reply> ReplyList;
 
interface RepliesIterator {
exception MoError {
CORBA::ScopedName object_interface;
CosNaming::Name object_name;
X711CMI::ASN1_GeneralizedTimeOpt current_time;
short error_code;
any error_info;
};
 
exception SubtreeError {
CORBA::ScopedName object_interface;
CosNaming::Name object_name;
X711CMI::ASN1_GeneralizedTimeOpt current_time;
short error_code;
any error_info;
};
 
boolean get_reply (out Reply r) raises (MoError, SubtreeError);
boolean get_n_replies (in unsigned long how_many, out ReplyList r_list)
raises (MoError, SubtreeError);
 
boolean finished (out unsigned long num_pending);
void destroy ();
};
 
interface BufferedRepliesHandler : MultipleRepliesHandler, RepliesIterator {};


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 Reply type is the structure to hold one reply. The different fields in the structure match those in the signature of the send_reply() operation of the LinkedReplyHandler interface.
The MoError Exception
The MoError exception corresponds to the send_mo_error() operation of the LinkedReplyHandler interface, and the types and values carried by the exception match exactly the parameters of the operation.
The SubtreeError Exception
The SubtreeError exception corresponds to the send_subtree_error() operation of the LinkedReplyHandler interface, and the types and values carried by the exception match exactly the parameters of the operation.
The RepliesIterator Interface
The RepliesIterator is, as its name indicates, an Iterator type interface, where there are operations to access a list of items in the iterator in an ordered manner. Items are accessed once, and only once, regardless of the operation used to access them. The Iterator cannot be backed (reaccess) or reinitiated.

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_reply() operation blocks until the next reply is available, returning it when ready. It returns true when the operation has actually retrieved a response, and returns false when there are no more responses pending to be received (that is, the end_of_replies has been received). In this case, the value returned in the Reply is undefined (must be ignored). Once this operation has returned false, all subsequent invocations to it will also return false. In case an error response is the first to be returned (because it was buffered or received while blocked), the corresponding exception is raised.
The get_n_replies Operation
The get_n_replies() call blocks until how_many replies are available, an error is received, or the iterator reaches its end, whichever happens first. The ReplyList will contain at most how_many non-error replies. Specific implementations may impose an appropriate maximum number for the how_many parameter, to prevent excesive consumption of resources.

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
The finished() operation returns true if the Iterator has completed its background work (therefore knows about ALL responses), and false if the operation is still under way (that is, there might be more responses unknown to the iterator at this time). In both cases, the number of replies immediately available for retrieval is returned (including pending error responses). This operation does not block.

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
The destroy() operation destroys the iterator. Any calls to the Iterator invoked after this would return the standard exception OBJECT_DOES_NOT_EXIST.

Handling ACTIONs with Multiple Replies

Where actions have a reply syntax, objects have the option of using multiple replies (that is, returning a sequence of PDUs, each of the type given in the reply syntax, containing part of the reply). Multiple replies allow data to be returned as it becomes available and have been used for monitoring progress.

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.


Table: UsingMR Exception




exception UsingMR {
RepliesIterator replies_iterator;
};


OSIMgmt::LocalRoot Interface

The term local orphan managed objects, associated to a given OSI managed object domain, is used here to designate those managed objects of which the superior objects are located in a different OSI managed object domain.

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.







Figure: Dealing with Local Orphan Managed Objects

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


Table: OSIMgmt::LocalRoot Interface Definition





typedef sequence<ManagedObject> ManagedObjectSeq;
 
interface LocalRoot : ManagedObject {
exception NoDescendants {};
 
// list all local orphan managed objects:
ManagedObjectSeq list_orphans ( );
 
// list of local orphans that are descendants of the object
// whose name is specified:
ManagedObjectSeq
list_orphan_descendants (in CosNaming::Name object_name)
raises (NoDescendants);
};


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

This section is provided as information only, and does not represent a normative part of this specification.

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

CORBA manager programs create and invoke operations on managed objects in the same way they create and invoke operations on ordinary CORBA objects located in the same CORBA domain. Analogously, they receive events supplied by managed objects as if they were ordinary CORBA objects supplying events to an event channel located in the CORBA domain. Whether this actually happens or not is transparent to the CORBA manager program.

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

Creating Managed Objects

Creating a managed object implies performing the list of actions described in The JIDM::ProxyAgent Interface:

  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.







Figure: Creating OSI Managed Object Directly through CORBA

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:

Different implementation approaches are also possible for step 5:

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

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.


Example: Recursive Propagation of Scoped Actions





obj>scoped_action (scope, filter, sync, act, arg, replies_handler, end_handler)
::=
if <obj satisfies the filter> {
// perform the action on the object and return the result:
result = obj>act (...);
replies_handler>send_reply (obj_intf, obj_name, result);
};
 
// create an OSIMgmt::EndOfRepliesHandler (end_subs) which will
// wait until all descentants notify they have finished propagation:
end_subs = ...;
 
// propagate action through descendants:
sub1>scoped_action (scope1, filter, sync, act, arg, replies, end_subs);

subn>scoped_action (scopen, filter, sync, act, arg, replies, end_subs);


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

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

Invoking an operation on a single managed object implies performing the following actions:

  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.


Example: Example Code for Invoking Operation on Managed Object





OSIMgmt::ProxyAgent_ptr agent;
OSIMgmt::LName local_name;
X721Att::DestinationType new_destinations;

 
// a reference to a OSIMgmt::ProxyAgent is obtained as a result of
// establishing a connection to the managed object domain where
// the EFD is located:
 
agent = ...;

 
// a reference to the initial CosNaming::NamingContext object
// is obtained:
 
CosNaming::NamingContext_ptr ctx = agent>get_domain_naming_context ();
 
// the name of the EFD object is constructed:
 
local_name > for_string_form (2.9.3.2.1=(string)MyEFD);

 
// a reference to the EFD object is obtained and narrowed
// to the X711::eventForwardingDiscriminator interface:
 
CORBA::Object_ptr obj = ctx>resolve (local_name -> to_idl_form ());
 
X721::eventForwardingDiscriminator_ptr efd =
X711::eventForwardingDiscriminator::_narrow (obj);
 
// Finally, the destinationSet operation is invoked on
// the managed object:
 
efd > destinationSet (new_destinations);


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.







Figure: Invoking Operations on a MO Directly through CORBA

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

Scoped operations can be invoked either through OSIMgmt::ProxyAgent or OSIMgmt::ManagedObjects. In the latter case, the base managed object in the selection is the one being referred.

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







Figure: Invoking Operation with Scoping and Filtering

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.


Example: Code for Invoking Scoped Operations





OSIMgmt::ManagedObject_ptr managed_object;
X711Inf::DistinguishedNameType object_name;
OSIMgmt::LName_ptr local_name;
OSIMgmt::MultipleRepliesHandler_ptr handler;

local_name > for_osi_form (object_name);
CORBA::Object_ptr obj = ctx > resolve (local_name -> to_idl_form ());
managed_object = OSIMgmt::ManagedObject::_narrow (obj);
 
managed_object > scoped_action (scope, filter, sync, access_control,
reset, arg, handler, handler);


Iterator Interfaces for Scoped Operations

In other OMG specifications, the iterator pattern is used heavily for operations that return an unbounded list of responses. This sub-section describes how to do this for this specification.

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.


Example: Using ReplyIterator





iter_get(..., in unsigned long how_many,
out ReplyList rlist,
out ReplyIterator riter)
{
BufferedRepliesHandler brh = create_brh(...) // or other creation call
//
cmis_get(..., brh, brh)
brh > get_n_replies(how_many, rlist)
riter = brh // widening does not require narrow()
}


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

Different strategies to resolve how CORBA manager objects finally consume events can be implemented. They are addressed in detail in Introduction and Design Principles.

Forwarding Events from CORBA Managed Object Domains

Different strategies to resolve how CORBA managed objects finally report events can be implemented. They were covered in detail in Introduction and Design Principles.

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

This section is provided as information only, and does not represent a normative part of this specification. In this section, different gateway scenarios are described where the use of this specification is clarified. This should be considered as a high level tutorial on some potential uses of the JIDM model for OSI management. Also, some potential implementation options are discussed.

Manager-side Gateways

Overview
CORBA/CMIP gateways must be used by any CORBA Manager Application needing to interoperate with managed object domains that are not directly accessible via CORBA but are accessible via CMIP.

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

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.







Figure: Structure of CORBA/CMIP Manager-side Gateways

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:







Figure: OSIMgmt::ProxyAgents in a Gateway

Getting Access to Managed Object Domains
The following steps are followed when a CORBA manager object tries to get access to a external managed object domain using a CORBA/CMIP gateway (see References to OSIMgmt::ProxyAgents in a JIDM Gateway):

  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.







Figure: References to OSIMgmt::ProxyAgents in a JIDM Gateway

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

Different solutions can be implemented:

Creation of Managed Objects
Implementors of create operations exported by proxy managed object factories are responsible for constructing the appropriate CMIP m-create requests and for returning the appropriate results.

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:

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.







Figure: Creating MOs through a CORBA/CMIP Gateway

Invocation of Operations on Single Managed Objects
The following steps are followed when a CORBA manager invokes an operation on a managed object that is accessible through a CORBA/CMIP gateway (see Operations on Managed Object through CORBA/CMIP Gateway):

  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.







Figure: Operations on Managed Object through CORBA/CMIP Gateway

Invoking Operations with Scope and Filtering
The following steps are followed when a CORBA manager invokes an operation on a man-aged object that is accessible through a CORBA/CMIP gateway (see 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.







Figure: Invoking Operations with Scope and Filtering


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:

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
Events originated at managed object domains are always received through JIDM::EventPort objects at CORBA Managers. A mechanism is implemented at any CORBA/CMIP gateway that allows event data received at a management connection endpoint to be forwarded to the appropriate JIDM::EventPort object.

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.







Figure: Event Reporting at CORBA/CMIP Manager-side Gateways

CMISE service level scenarios
The OSIMgmt::ProxyAgent objects provide CMIS service level IDL methods, that would allow any CORBA manager application to perform all CMIS operations without the need to have any further CORBA object references to the corresponding CORBA objects. This type of interaction is most useful in gateway situations, although it is applicable to pure CORBA environments as well.

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 Asynchronous Create Operation works as described below.







Figure: Async Creation of MO through CORBA/CMIP Gateway

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.







Figure: Sync Creation of MO through CORBA/CMIP Gateway

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






Figure: Operations on MO through CORBA/CMIP Gateway

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
This scenario describes how the M-CANCEL-GET operation may be sent from a CORBA manager to an OSI agent, assuming that an M-GET request is outstanding.







Figure: Cancelling an Outstanding M-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
CORBA/CMIP gateways must be used by any CORBA Agent Application needing to offer a management interface based on CMIP. A CORBA/CMIP gateway runs in one CORBA server. However, one or several JIDM gateways can coexist in the same CORBA server. Programs in this server have access to both ORB services and services encapsulating access to management-specific protocols provided by JIDM gateways at the server. Besides, there can be several CORBA servers containing JIDM gateways in the same CORBA Agent Application.

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

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







Figure: Structure of CORBA/CMIP Manager-side Gateways

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
A JIDM::DomainPort object resides in the CORBA/CMIP gateway in order to handle access to the managed object domain and serve association request issued from remote Manager Applications.

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.







Figure: Handling Access to Local MOs from a JIDM Gateway

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
In CORBA managed object domains, OSIMgmt::ProxyAgent objects receive PDU indications, perform the appropriate operations and return the appropriate PDU responses.







Figure: Handling Management Create PDU Indications

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
OSIMgmt::ProxyAgent objects receive CMIP m-set/m-get/m-action indications on single objects, perform the appropriate operations and return the appropriate CMIP responses.







Figure: 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
In CORBA-based OSI Agent Applications, OSIMgmt::ProxyAgent objects receive CMIP m-set/ m-get/m-action indications with scope and filtering, perform the appropriate operations and return all the appropriate CMIP responses associated with the generated replies.

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:

  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.







Figure: Handling CMIP Indications with Scope and Filtering (cont.)

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:

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
In CORBA-based OSI managed object domains, OSIMgmt::ProxyAgent objects receive CMIP m-delete indications, perform the appropriate operations and return the appropriate CMIP responses.

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:

  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.







Figure: Handling CMIP Deletion Indications (cont.)

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
Event Forwarding Discriminators (EFDs) are the managed objects that receive event notifications emitted by other managed objects within the same OSI managed object domains, and determine which ones are going to be forwarded, as CMIP m-event-reports requests to specific OSI Manager.

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:

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.


Table: Different Alternatives for EFDs





module X734 {
.........
interface PushEFD : CosEventComm::PushConsumer, X711::eventForwardingDiscriminator ...
{};
interface PullEFD : CosEventComm::PullConsumer, X711::eventForwardingDiscriminator ...
{};
};


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:

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
Basic algorithm:

  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.







Figure: Sending m-event-report Requests - Push Model

Sending m-event-report Requests - Pull Model
At creation time, each PullEFD tries to find references to CosEventChannel::SupplierAdmin interfaces associated with remote JIDM::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:

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.







Figure: Sending m-event-report Requests - Pull Model


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.


Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index