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:
This section describes these interfaces and their operations in detail.
#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_ */
|
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.
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).
Any attempt to invoke
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
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.
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 ();
|
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
(
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>
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 ();
|
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.
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
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
It must be pointed out that invoking the
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
Invoking the
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
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 space of keys established for OSI Management environments is
described in
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:
Here, it is implicitly assumed that there is a specific factory
interface associated to the
managed object interface. Such interface includes a separate operation
for each GDMO
namebinding template that is associated to the managed object
interface. CORBA managers
know the name and operations associated to the factory in advance so
that they can
properly narrow and use the reference returned by the
Here, references returned by the
Here, the CORBA manager object provides the necessary information to find the factory associated to a specific GDMO namebinding template for which a specific factory interface is defined.
In case objects are created through CosLifeCycle::GenericFactory
objects, the
key
value passed
in the invocation to the
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. |
As already explained in
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:
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 ();
|
A detailed description of CMIS operations is presented in
Destruction of an OSIMgmt::ProxyAgent object can take place either
gracefully or nongracefully,
as described in
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.
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);
|
};
|
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.
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.
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.
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.
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.
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);
|
};
|
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).
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:
|
The remainder of this sub-section gives descriptions of the ManagedObject Attributes and Operations.
A detailed description about CMIS operations is presented in
If the managed object returns multiple replies to a single
action invokation, the
UsingMR exception will be raised. See
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.
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.
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
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:
If these callback objects became unreachable during the process of
performing an scoped
operation (due to communications problems, or to the explicit deletion
of the callback
objects), the managed domain implementation should interrupt
processing of the scoped
operation, if possible. Specifically, in the case of
In case unconfirmed operations are being requested (for example, an unconfirmed scoped set operation), these parameters should be both specified as nil object references; in this case, no responses will be received.
If the reply_handler parameter is specified, but the end_of_replies_handlerisspecifiedasanil object reference, then the behaviour of the invoked operation is slightly different: the operation invocation blocks until all responses have been received through the reply_handler object passed in the call - that is, the operation itself becomes the end of replies indication. This allows for sequential scoped operations being invoked without extra coding. Note, however, that the ORB might timeout such invocations if they take too long; configure your ORB timeout appropriately.
If the reply_handler parameter is specified as a nil object reference, but the end_of_replies_handler is not, or if both are nil but the operation does not accept unconfirmed operation, then the CORBA standard exception BAD_PARAM is raised.
The results of invoking a scoped operation are returned through the OSIMgmt::LinkedReplyHandler object specified when the scoped operation was invoked.
For more details, see
To be able to specify the above modifications, the scoped SET
operations -
This parameter contains a set of attribute modification specifications, each of which contains:
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 -
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
(
Both flavours of the
Both operations differ in the way they receive responses:
Error responses are returned as exceptions in this case.
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
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
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.
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 reply_info argument is a CORBA
any,
and its contents are different depending on the
scoped operation that had been performed, as shown in
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 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
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 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
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 |
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.
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.
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
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.
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.
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 (
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
exception UsingMR {
|
RepliesIterator replies_iterator;
|
};
|
In every CORBA-based OSI managed object domain there will exist a CORBA object which plays the role of a local root. This local root object acts as the superior of all local orphan managed objects in the application (that is, it will hold references to local orphan managed objects), and exports the OSIMgmt::LocalRoot interface.
In the case that a local orphan object is created in a certain managed domain, the local root object for that domain must be notified that a new subordinate has been created.
A reference to the local root object is maintained by the JIDM::DomainPort object associated to the managed object domain. The JIDM::DomainPort object passes this reference to every OSIMgmt::ProxyAgent object it creates.
The local root object is a managed object which exports the
OSIMgmt::LocalRoot interface (see
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
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.
This concept of transparency is specifically supported by the
fulfillment of the semantic rules
presented in
Valid key values for finding factories in OSI Systems Management
environments were
described in section
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:
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
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).
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
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:
The following steps will be followed when scoping operations are invoked through operations exposed by the base managed object:
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);
|
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
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
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.
The only distintion is that the interface of the EventReporter object is well-known and corresponds to the standard Event Forwarding Discriminator interface.
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
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
The JIDM::ProxyAgentFinder object is created during start-up of the CORBA server where the JIDM gateway is going to run. JIDM::EventPort objects at the gateway may be created during or after start-up of that server.
As a result of establishing a connection through a CORBA/CMIP gateway, an OSIMgmt::Proxy-Agent object is created at the gateway. OSIMgmt::ProxyAgent objects created this way are responsible for:
Each OSIMgmt::ProxyAgent object encapsulates access to a domain by stablishing a session with that domain.
Different solutions can be implemented:
Different types of factories can be found according to criteria passed in the invocation of the
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
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.
As already mentioned in
The following steps are followed when a CORBA manager receives an event through an
JIDM::EventPort at a CORBA/CMIP gateway (see
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.
The following steps are taken each time an asynchronous M-CREATE request is sent through the CORBA/CMIP Gateway.
The Synchronous Create Operation works as described below.
The following steps are taken each time a synchronous M-CREATE request is sent through the CORBA/CMIP Gateway:
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:
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:
Any CORBA/CMIP gateway at a CORBA Agent Application has several objects associated with it
(see
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
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.
Every JIDM::DomainPort object has an AE-title associated with it. This AE-title is used by remote Manager Applications to identify the OSI managed object domain accessible through the JIDM::DomainPort object.
When a new association request is received by the JIDM::DomainPort object that is in a gateway, the JIDM::DomainPort object creates a new OSIMgmt::ProxyAgent object. This object handles CMIS requests received through the newly established association.
A JIDM::DomainPort object in a JIDM gateway holds references to the initial CosNam-ing:: NamingContext and CosLifeCycle::FactoryFinder and OSIMgmt::LocalRoot objects in the managed object domain where the JIDM gateway is located. The JIDM::DomainPort object passes copies of these references to each OSIMgmt::ProxyAgent object it creates.
The following steps are followed each time a create PDU indication is received by a CORBA/CMIP gateway:
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:
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).
The following steps are followed each time a scoped m-set/m-get/m-action PDU indication is received by a CORBA/CMIP gateway:
Next, the following steps takes place:
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
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
Returning from the
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.
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:
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
The
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
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.
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.
A PushEFD registers itself as a Push or Pull Supplier for each destination.
Basic algorithm:
Contents | Next section | Index |