Management Facilities Specification

• The interfaces have been developed with an eye towards the implementation on a generic ORB environment. Every attempt has been made so the interfaces, as well as their semantics, will be portable among all CORBA-compliant, ORB implementations. In the specification of the interfaces, no implementation specific features of any ORB environments are used.

• The interfaces have been designed such that the scalability of the implementation is not limited by the interface defined in IDL.

  For example, if an interface is defined to return a list of items and the list is not guaranteed to be short, then it should not have the entire list returned in one, possibly enormous, set of data. This issue has been addressed primarily through the use of iteratorobjects. When a list of items is to be returned initially, a number of the items are returned along with an object reference to an iterator object. The client may use the iterator object to retrieve the remainder of the list in manageable subsets.

  For complex characteristics of interfaces, we have chosen to represent those characteristics as methods instead of attributes. This not only has scalability advantages, but also performance advantages.

• Certain design decisions were made that effects the programming model that results from the style of interface definition selected. In some cases interfaces have been designed or organized simply so that the programmer suffers the minimal amount of complexity. Two areas where this is particularly true are the organization of the common type definitions and the definitions of exceptions.

SysAdminTypes Module

Specified IDL

//
// Component Name: SysAdminTypes.idl
//
// Description: 
// The SysAdminTypes file defines types and data
// structures that are used frequently throughout the 
// development of system administration applications. 
//

#ifndef SYSADMINTYPES_IDL
#define SYSADMINTYPES_IDL

#include <orb.idl>
#include <CosNaming.idl>

module SysAdminTypes {

	typedef sequence <CORBA::InterfaceDef> InterfaceDefList;

	typedef CosNaming::NameComponent LabelType;

	struct ObjectLabel {
		Object objref;
		LabelType label;
	};

	struct LabelExpression {
		string id_regex;
		string kind_regex;
	};

	typedef sequence <ObjectLabel> ObjectLabelList;

	// The Platform structure defines elements for information
	// related to the hardware and operating system of a
	// client machine. The elements represent the following
	// information.                                        
	
	struct Platform {
		string host_name;
		string machine_hardware_name;
		string operating_system_name;
		string operating_system_version;
		string operating_system_release;
	};

};

#endif //SYSADMINTYPES_IDL

SysAdminExcept Module

Specified IDL

//
// Component Name: SysAdminExcept.idl
//
// Description: 
// The SysAdminExcept module defines the exceptions
// commonly used by system management applications.
//

#ifndef SYSADMINEXCEPT_IDL
#define SYSADMINEXCEPT_IDL

#include <SysAdminTypes.idl>

typedef sequence<any> MsgContext;

#define XPG_FIELDS			\
	string	type_name;		\
	string	catalog;		\
	long	key;			\
	string	default_msg;		\
	long	time_stamp;		\
	MsgContext	msg_context;

module SysAdminException {
	exception ExException {
		XPG_FIELDS

	};

	exception ExFailed {
		XPG_FIELDS
		string    operation_name;
	};

	exception ExInvalid {
		XPG_FIELDS
		string	resource_name;
	};

	exception ExNotUniqueLabel {
	XPG_FIELDS
	SysAdminTypes::LabelType	label;
	};

	exception ExNotFound {
		XPG_FIELDS
		string	resource_name;
	};

	exception ExExists {
		XPG_FIELDS
		string	resource_name;
	};

	exception ExObjNotFound {
		XPG_FIELDS
		string	resource_name;
	};
};

#endif //SYSADMINEXCEPT_IDL  

Identification Module

Interfaces and Operations

Specified IDL

//
// Component Name: Identification.idl
//
// Description: 
// This module defines the methods that implement an object's
// label, which is a name that uniquely identifies the object 
// within an environment.
//

#ifndef IDENTIFICATION_IDL
#define IDENTIFICATION_IDL

#include <SysAdminTypes.idl>

module Identification {
	
	interface Labeled {	

		SysAdminTypes::LabelType get_label();

		void set_label (in SysAdminTypes::LabelType label);

	};
};

#endif //IDENTIFICATION_IDL

Identification::Labeled Interface

The set_label Operation

Syntax

 

void set_label(in SysAdminTypes::LabelType label);

Exceptions

The get_label Operation

Syntax

 

SysAdminTypes::LabelType get_label();

Exceptions

SysAdminLifeCycle Module

The possible definitions for subtypes of the Location interfaces are quite broad and are not specified. Because of this, the scope of applicability of the Location interface and its subtypes is guaranteed only within a single vendor's framework implementation.

Interfaces and Operations

Specified IDL

//
// Component Name: SysAdminLifecycle.idl
//
//
// Description: 
// The SysAdminLifeCycle module defines interfaces 
// for specifying objects. Currently interfaces for copying and
// moving objects are not supported. These will be added as needed.
//

#ifndef SYSADMINLIFECYCLE_IDL
#define SYSADMINLIFECYCLE_IDL

#include <SysAdminTypes.idl>

module SysAdminLifeCycle {

	// The Location interface allows the specification of
	// the location for lifecycle operations to occur.

	interface Location {
	};

	// the HostLocation interface allows the specification
	// of a particular client machine on which the
	// lifecycle operation should execute    

	interface HostLocation : Location {

		SysAdminTypes::Platform get_platform();

	};

};

#endif // SYSADMINLIFECYCLE_IDL 

SysAdminLifeCycle::Location Interface

SysAdminLifeCycle::HostLocation Interface

Inherited Interfaces

The get_platform Operation

Syntax

 

SysAdminTypes::Platform get_platform();

Exceptions

ManagedSets Module

Interfaces and Operations

Specified IDL

//
// Component Name: ManagedSets.idl
//
// Description:  
// The following interfaces provide the functionality
// for support of managed sets.
//

#ifndef MANAGEDSETS_IDL
#define MANAGEDSETS_IDL

#include <SysAdminTypes.idl>
#include <SysAdminExcept.idl>
#include <Identification.idl>

module ManagedSets {

//--------------------------------------------------------------------
//Forward references
//--------------------------------------------------------------------
interface Member;
interface SetIterator;
interface MemberIterator;
interface MemberLabelIterator;
interface Set;
interface FilteredSet;
	
//--------------------------------------------------------------------
//typedefs needed for the managed set interfaces 
//--------------------------------------------------------------------
typedef sequence <Set>                 SetList;
typedef sequence <Member>              MemberList;
typedef SysAdminTypes::ObjectLabel     MemberLabel;
typedef SysAdminTypes::ObjectLabelList MemberLabelList;

	interface Member : Identification::Labeled {

		void add_backref (
			in Set s
		);

		void get_backrefs (
			in unsigned long how_many,
			out SetList s_list,
			out SetIterator iterator
		);

		void remove_backref (
			in Set s
		) raises (
			SysAdminException::ExNotFound
		);

	}; // End Member interface

	interface SetIterator {

		boolean next_one (
			out Set s
		);

		boolean next_n (
			in unsigned long how_many,
			out SetList s_list
		);

		void destroy();
		
	}; // End SetIterator interface


	interface MemberIterator {

		boolean next_one (
			out Member m
		);

		boolean next_n (
			in unsigned long how_many,
			out MemberList m_list
		);

		void destroy();

	}; // End of MemberIterator

	interface ObjectLabelIterator {

		boolean next_one (
			out ObjectLabel ol
		);

		boolean next_n (
			in unsigned long how_many,
			out ObjectLabelList ol_list
		);

		void destroy();

	};  // End of ObjectLabelIterator

	typedef ObjectLabelIterator MemberLabelIterator;


	interface Set : Member {

		unsigned long get_cardinality(); 

		void add_object (
			in boolean add_backref,
			in Member m
		) raises (
			SysAdminException::ExNotUniqueLabel
		);

		void add_n_objects (
			in MemberList m_list,
			out MemberList not_added
		);

		void remove_object (
			in boolean remove_backref,
			in Member m
		) raises (
			SysAdminException::ExNotFound
		);

		void remove_n_objects (
			in boolean remove_backref,
			in MemberList m_list,
			out MemberList not_removed
		);    

		void get_members (
			in unsigned long how_many,
			out MemberList m_list,
			out MemberIterator iterator
		);

		void intersection_members (
			in unsigned long how_many,
			in SetList s_list,
			out MemberList m_list,
			out MemberIterator iterator
		) raises (
			SysAdminException::ExInvalid
		);

		void union_members (
			in unsigned long how_many,
			in SetList s_list,
			out MemberList m_list,
			out MemberIterator iterator
		) raises (
			SysAdminException::ExInvalid
		);

	}; // End of Set interface

	interface FilteredSet : Set {

		void find_members (
			in SysAdminTypes::InterfaceDefList interfaces,
			in SysAdminTypes::LabelExpression regular_expression,
			in unsigned long how_many,
			out MemberLabelList ml_list,
			out MemberLabelIterator iterator
		) raises (
			SysAdminException::ExNotFound
		);

		Member lookup_object (
			in SysAdminTypes::LabelType label,
			in SysAdminTypes::InterfaceDefList interfaces
		) raises (
			SysAdminException::ExNotFound
		);

		SysAdminTypes::ObjectLabelList lookup_labels (
			in MemberList m_list
		);

	}; // End of FilteredSet interface

}; // End ManagedSets module

#endif //MANAGEDSETS_IDL

ManagedSets::Member Interface

• add_backref

• get_backrefs

• remove_backref

Inherited Interfaces

The add_backref Operation

Syntax

 

void add_backref(
	in Set s
);

Exceptions

If the target object already maintains a reference to the input set s, the invocation of add_backref will be a no-op: no exception will be raised and only one reference to the set s will be maintained by the target object.

The get_backrefs Operation

Syntax

 

void get_backrefs(
	in unsigned long how_many,
	out SetList s_list,
	out SetIterator iterator
);

Exceptions

The remove_backref Operation

Objects that inherit from both ManagedSets::Set and CosLifeCycle::LifeCycleObject will inherit the latter's remove operation. If an object which is a Set destroys itself via the remove operation, then it must first remove itself from its member objects' lists of backrefs by invoking remove_backref upon each of them in turn, with the Set's own object reference as the input parameter.

Syntax

 

void remove_backref(
	in Set s
) raises (
	SysAdminException::ExNotFound
);

Exceptions

ManagedSets::SetIterator Interface

• next_one

• next_n

• destroy

The next_one Operation

Syntax

 

boolean next_one(
	out Set s
);

Exceptions

The next_n Operation

Syntax

 

boolean next_n(
	in unsigned long how_many,
	out SetList s_list
);

Exceptions

The destroy Operation

Syntax

 

void destroy();

Exceptions

ManagedSets::MemberIterator Interface

• next_one

• next_n

• destroy

The next_one Operation

Syntax

 

boolean next_one(
	out Member m
);

Exceptions

The next_n Operation

Syntax

 

boolean next_n(
	in unsigned long how_many,
	out MemberList m_list
);

Exceptions

The destroy Operation

Syntax

 

void destroy();

Exceptions

ManagedSets::ObjectLabelIterator Interface

• next_one

• next_n

• destroy

The next_one Operation

Syntax

 

boolean next_one (
	out MemberLabel ol;
);

Exceptions

The next_n Operation

Syntax

 

boolean next_n(
	in unsigned long how_many,
	out ObjectLabelList ol_list
);

Exceptions

The destroy Operation

Syntax

 

void destroy();

Exceptions

ManagedSets::Set Interface

The Set interface defines the following operations that provide basic set object functionality:

• get_cardinality

• add_object

• add_n_objects

• remove_object

• remove_n_objects

• get_members

• intersection_members

• union_members

Inherited Interfaces

The get_cardinality Operation

Syntax

 

unsigned long get_cardinality();

Exceptions

The add_object Operation

If the add_backref parameter is TRUE, then the member object being added is notified to add a back reference to the set. If the add_backref parameter is FALSE, then the newly-contained member object is not notified. This is useful for the case in which a member object adds itself to the set; the object does not need the notification to add a back reference (it already knows it is being added).

Syntax

 

void add_object(
	in boolean add_backref,
	in Member m
) raises (
	SysAdminException::ExNotUniqueLabel
);

Exceptions

If the label of the member being added to the set is not unique among members of the set, the SysAdminException::ExNotUniqueLabel exception may be raised subject to the following conditions:

1. If the input object m has the same label as an already-existing set member and if the CORBA::Object defined is_equivalent method returns TRUE when invoked on the input object m passing the already existing set member, no exception is raised and there remains only one reference to that object from the set.

2. If the input object m has the same label as an already-existing set member and if the CORBA::Object defined is_equivalent method returns FALSE when invoked on the input object m passing the already existing set member, then the SysAdminException::ExNotUniqueLabel exception is raised. The client is thus alerted that it is holding a superfluous reference to the set member which it should discard in favor of the reference that the set already holds.

Note that a label is comprised of two components: an id field and a kind field. The label of the input object m is only considered to be the same as that of an already-existing member if both of these fields are identical to that of the member.

The add_n_objects Operation

Syntax

 

void add_n_objects(
	in MemberList m_list,
	out MemberList not_added
);

Exceptions

The remove_object Operation

If the remove_backref argument is set to TRUE, then the member object being removed is notified to remove its back reference to the set. If the remove_backref argument is FALSE, the contained object is not notified. This operation is useful when a contained object is removed. Upon deletion, it removes itself from all Sets. There is no need for the set object to notify the member object to remove a back reference in this scenario.

Syntax

 

void remove_object(
	in boolean remove_backref,
	in Member m
) raises (
	SysAdminException::ExNotFound
);

Exceptions

The remove_n_objects Operation

Syntax

 

void remove_n_objects(
	in boolean remove_backref,
	in MemberList m_list,
	out MemberList not_removed
);

Exceptions

The get_members Operation

Syntax

 

void get_members (
	in unsigned long how_many,
	out MemberList m_list,
	out MemberIterator iterator
);

Exceptions

The intersection_members Operation

Syntax

 

void intersection_members (
	in unsigned long how_many,
	in SetList s_list,
	out MemberList m_list,
	out MemberIterator iterator
) raises (
	SysAdminException::ExInvalid
);

Exceptions

If s_list is an empty list or if an element of s_list is OBJECT_NIL, the SysAdminException::ExInvalid exception is raised. This is not the same thing as taking the intersection of a Set with the empty set (a Set that contains no Members), which is allowed and which will not cause this exception to be raised.

The union_members Operation

Syntax

 

void union_members (
	in unsigned long how_many,
	in SetList s_list,
	out MemberList m_list,
	out MemberIterator iterator
) raises (
	SysAdminException::ExInvalid
);

Exceptions

If s_list is an empty list or if an element of s_list is OBJECT_NIL, the SysAdminException::ExInvalid exception is raised. This is not the same thing as taking the union of a Set with the empty set (a Set that contains no Members), which is allowed and which will not cause this exception to be raised.

ManagedSets::FilteredSet Interface

The FilteredSet interface defines the following operations that enable the management of managed sets:

• find_members

• lookup_object

• lookup_labels

Inherited Interfaces

The find_members Operation

Both the object references and the labels of the objects are returned. The order of the objects returned is unspecified. If a member of the generic set does not have a label, then it will not match any regular expressions.

The initial size of ml_list is determined by the how_many argument. The rest of the MemberLabel structures, if any, can be retrieved using the returned iterator object. If how_many is greater than or equal to the total number of members that match the filter criteria, then all of the members will be returned in ml_list and iterator will be returned as OBJECT_NIL.

Syntax

 

void find_members (
	in SysAdminTypes::InterfaceDefList interfaces,
	in SysAdminTypes::LabelExpression regular_expression,
	in unsigned long how_many,
	out MemberLabelList ol_list,
	out MemberLabelIterator iterator
) raises (
	SysAdminException::ExNotFound
);

Exceptions

SysAdminException::ExNotFound is raised if no objects in the set meet the specified selection criteria.

The lookup_object Operation

The interfaces argument specifies a sequence of interfaces that the object with the matching label must support in order to be returned. If a zero length sequence of interface definitions is passed, any object with a matching label will be returned.

Syntax

 

Member lookup_object(
	in SysAdminTypes::LabelType label,
	in SysAdminTypes::InterfaceDefList interfaces
)raises(
	SysAdminException::ExNotFound
);

Exceptions

SysAdminException::ExNotFound is raised when no object in the set has the specified label.

The lookup_labels Operation

Syntax

 

SysAdminTypes::ObjectLabelList lookup_labels(
	in MemberList m_list
);

Exceptions

ManagedInstances Module

Interfaces and Operations

Specified IDL

//
// Component Name: ManagedInstances.idl
//
// Description:
// The following interfaces provide the functionality
// for support of instances and instance managers.
//

#ifndef MANAGEDINSTANCES_IDL
#define MANAGEDINSTANCES_IDL

#include <SysAdminTypes.idl>
#include <SysAdminExcept.idl>
#include <SysAdminLifeCycle.idl>
#include <CosLifeCycle.idl>
#include <Policies.idl>
#include <ManagedSets.idl>


module ManagedInstances {

	// Forward reference
	interface Instance;
	interface BasicInstanceManager;
	interface InstanceManager;
	interface Library;

	interface Instance :
		CosLifeCycle::LifeCycleObject,
		ManagedSets::Member
	{
		
		BasicInstanceManager get_manager();

		string get_type_name();

		SysAdminLifeCycle::Location get_resource_location();

	}; // End of Instance interface

	interface Library : 
		CosLifeCycle::FactoryFinder,
		CosLifeCycle::GenericFactory,
		ManagedSets::FilteredSet
	{
	}; // End of Library interface

	interface BasicInstanceManager :
		CosLifeCycle::LifeCycleObject,
		CosLifeCycle::GenericFactory,
		ManagedSets::FilteredSet
	{

		CORBA::InterfaceDef get_instances_interface();

	}; // End of BasicInstanceManager interface

	interface InstanceManager :
		BasicInstanceManager,
		Policies::PolicyObjectAdmin
		        
	{
	}; // End of InstanceManager interface

	interface PolicyRegionsInstanceManager :
		InstanceManager
	{
	}; // End of PolicyRegionsInstanceManager interface

}; // End ManagedInstances module

#endif // MANAGEDINSTANCES_IDL

ManagedInstances::Instance Interface

The ManagedInstance::Instance interface defines the following operations:

• get_manager

• get_type_name

• get_resource_location

Inherited Interfaces

• CosLifeCycle::LifeCycleObject

• ManagedSets::Member

Unique Behavior of Inherited Interfaces

CosLifeCycle::LifeCycleObject

The get_manager Operation

Syntax

 

BasicInstanceManager get_manager();

Exceptions

The get_type_name Operation

Syntax

 

string get_type_name();

Exceptions

The get_resource_location Operation

Syntax

 

SysAdminLifeCycle::Location get_resource_location();

Exceptions

ManagedInstances::BasicInstanceManager Interface

Basic instance managers are created by invoking the create_object operation on a library object that is responsible for supporting object types within a specified scope of influence, which may be some subset of the overall managed environment.

The ManagedInstances::BasicInstanceManager interface defines the following operations:

• get_instances_interface

Inherited Interfaces

• CosLifeCycle::LifeCycleObject

• CosLifeCycle::GenericFactory

• ManagedSets::FilteredSet

Unique Behavior of Inherited Interfaces

CosLifeCycle::LifeCycleObject

CosLifeCycle::GenericFactory

The k argument is used with both the create_object and supports operations. It is defined to take the following:

For the supports operation the k argument is required. It is implementation dependent as to whether just "object interface" or "object implementation", or both, are required to be specified. If the BasicInstanceManager is capable of creating objects of the specified interface and implementation, it returns TRUE, otherwise it returns FALSE.

For the create_object operation, the k argument is optional and may be specified as an empty sequence (that is, sequence of length zero). This is because the basic instance manager already knows the type of object it creates, including the InterfaceDef and ImplementationDef for that type. If the k argument is specified, the values specified must be consistent with the InterfaceDef and ImplementationDef associated with this basic instance manager object. If it is not, the CosLifeCycle::NoFactory exception is raised.

For the create_object operation, after the new instance is created, the add_object operation on the basic instance manager must be invoked to add the new instance to this basic instance manager's set.

The following table defines the name/value pairs that are passed in the the_criteria argument of the create_object call.

If "labelid" or "location" are not specified in the_criteria argument, or if the string passed in the "labelid" matches the id field of the label of any existing members of this instance manager, the CosLifeCycle::InvalidCriteria exception will be raised.

Note that an instance's label is the primary distinguishing characteristic for that instance. For that reason, an instance's label must be unique in space and time. The "labelid" criterion above must be constructed with that end in view.

ManagedSets::FilteredSet

The get_instances_interface Operation

Syntax

 

CORBA::InterfaceDef get_instances_interface();

Exceptions

ManagedInstances::InstanceManager Interface

Instance managers are created by invoking the create_object operation on a library object that is responsible for supporting object types within a specified scope of influence, which may be some subset of the overall managed environment.

The ManagedInstances::InstanceManager interface does not introduce any new operations other than those that are inherited.

Inherited Interfaces

• ManagedInstances::BasicInstanceManager

• Policies::PolicyObjectAdmin

Unique Behavior of Inherited Interfaces

CosLifeCycle::GenericFactory

For the create_object operation, after the new instance is created and added to this instance manager, the add_object operation on the policy region must be invoked to cause the created policy driven base object to be added to the policy region.

The following table defines the name/value pairs that are passed in the the_criteria argument of the create_object call in addition to those defined for BasicInstanceManager

If "policy regions" is not specified in the_criteria argument, the CosLifeCycle::InvalidCriteria exception is raised. If an error occurs during the processing of the "policy regions" criterion, then the CosLifeCycle::CannotMeetCriteria exception is raised and all processing that has so far occurred in the create_object() operation is rolled back as if it was a transaction, including the deletion of the newly-created instance.

If "nested initialization" is not specified, then nested initialization will not take place - the default behavior will be the same as if a value of FALSE had been specified. The ordering of initialization policy objects on which the initialize_policy_driven_object operation will be called is defined as follows:

• The order will be the same as the ordering of policy regions within the "policy regions" name value pair of the the_criteria parameter.

• If nested initialization is to take place, the topmost containing policy region's initialization policy object is used prior to that of the policy region in the parameter¹.

ManagedInstances::Library Interface

• ManagedInstances::BasicInstanceManager

• ManagedInstances::InstanceManager

The library also acts as a factory and factory finder for subtypes of these interfaces.

There may be one or more objects that supports the ManagedInstances::Library interface in an environment.

The ManagedInstances::Library interface does not introduce any new operations other than those that are inherited.

Objects inheriting from the ManagedInstances::Library interface may not be destroyed while instance managers are members of those objects.

Inherited Interfaces

• ManagedSets::FilteredSet

• CosLifeCycle::GenericFactory

• CosLifeCycle::FactoryFinder

Unique Behavior of Inherited Interfaces

ManagedSets::FilteredSet

CosLifeCycle::GenericFactory

The k argument is used with both the create_object and supports operations. It is defined to take the following:

For both the supports and create_object operations the k argument is required. It is implementation dependent as to whether just "object interface" or "object implementation", or both, are required to be specified. The "object interface" must specify a principal IDL interface that supports the BasicInstanceManager interface. For supports, if the Library is capable of creating an instance manager of the specified type and implementation, it returns TRUE, otherwise it returns FALSE. For create_object, if the Library is not capable of creating an instance manager of the specified type and implementation, the CosLifeCycle::NoFactory exception is raised.

The the_criteria argument of the create_object operation may pass the elements defined in the following table:

Note that not all criteria are required to be supported in all implementations. It's important that the client supply sufficient information to describe the type of object the instance manager will create. In some implementations, the type criteria alone may be sufficient for this. Other implementations may require the interface and implementation criteria, but not the type. Within a particular implementation, if sufficient information is not supplied by the client to describe the types of objects the Instance Manager will create, the CosLifeCycle::InvalidCriteria exception is raised.

If the string passed in the "labelid" matches the id field of the label of any existing members of this library, the CosLifeCycle::InvalidCriteria exception is raised.

If an error occurs during the processing of the "initializations" or "validations" criteria, then the CosLifeCycle::CannotMeetCriteria exception is raised and all processing that has so far occurred in the create_object() operation will be rolled back as if it was a transaction, including the deletion of the newly-created instance manager.

CosLifeCycle::FactoryFinder

Note that not all of these selection constraints are required to be supported by all implementations. If the Library does not contain any instance manager objects that meet the specified constraints, or if the factory_key argument is specified as an empty sequence, the CosLifeCycle::NoFactory exception is raised.

ManagedInstances::PolicyRegionsInstanceManager Interface

Inherited Interfaces

Unique Behavior of Inherited Interfaces

CosLifeCycle::GenericFactory

PolicyRegions Module

Interfaces and Operations

Specified IDL

//
// Component Name: PolicyRegions.idl
//
// Description:
// The following interfaces provide the functionality
// for support of policy regions.
//

#ifndef POLICYREGIONS_IDL
#define POLICYREGIONS_IDL

#include <SysAdminTypes.idl>
#include <SysAdminExcept.idl>
#include <SysAdminLifeCycle.idl>
#include <CosLifeCycle.idl>
#include <ManagedSets.idl>
#include <ManagedInstances.idl>

module PolicyRegions {

// forward references
	interface PolicyRegion;
	interface PolicyDrivenBase;

	struct PolicyResult {
		PolicyDrivenBase object_verified;
		PolicyRegion containing_region;
		Policies::ValidationPolicy validation_object_used;
		boolean passed_policy;
		string description;
	};

	typedef sequence<PolicyResult> PolicyResultList;

	enum SelectionCriteria {
		all,
		with_initialization,
		with_validation,
		with_validation_enabled,
		with_initialization_or_validation,
		with_initialization_or_validation_enabled
	};

	typedef sequence<PolicyRegion> PolicyRegionList;

	interface PolicyResultIterator {
		boolean next_one (
				out PolicyResult pr;
		};

		boolean next_n (
			in unsigned long how_many,
			out PolicyResultList pr_list;
		};

		void destroy();

	}; // End PolicyResultIterator interface

	interface PolicyDrivenBase : ManagedInstances::Instance {

		SysAdminTypes::ObjectLabelList get_policy_region_info();
	
		void move_to_policy_region (
			in PolicyRegions::PolicyRegion pr_from,
			in PolicyRegions::PolicyRegion pr_to
		) raises (
			SysAdminException::ExObjNotFound,
			SysAdminException::ExNotFound,
			SysAdminException::ExInvalid
		);

		void add_to_policy_region (
			in PolicyRegions::PolicyRegion pr
		) raises (
			SysAdminException::ExNotFound,
			SysAdminException::ExInvalid
		);

		void remove_from_policy_region (
			in PolicyRegions::PolicyRegion pr
		) raises (
			SysAdminException::ExObjNotFound,
			SysAdminException::ExInvalid
		);

		SysAdminTypes::ObjectLabelList list_enabled_validation_policies (
			in PolicyRegionList policy_regions,
			in CORBA::InterfaceDef interface_def,
			in boolean include_nested
		) raises (
			SysAdminException::ExNotFound
		);

		SysAdminTypes::ObjectLabelList list_initialization_policies
(
			in PolicyRegionList policy_regions,
			in CORBA::InterfaceDef interface_def,
			in boolean include_nested
		) raises (
			SysAdminException::ExNotFound
		);

	}; // End of PolicyDrivenBase interface

	interface PolicyRegion :
		PolicyDrivenBase,
		ManagedSets::FilteredSet,
		CosLifeCycle::GenericFactory
	{

		void add_instance_manager (
			in ManagedInstances::InstanceManager im,
			in Policies::InitializationPolicy initialization_policy,
			in Policies::ValidationPolicy validation_policy
		) raises (
			SysAdminException::ExExists
		);

		void remove_instance_manager (
			in ManagedInstances::InstanceManager im
		) raises (
			SysAdminException::ExObjNotFound,
			SysAdminException::ExExists
		);

		void get_instance_manager_list (
			in SelectionCriteria select
			in unsigned long how_many;
			out SysAdminTypes::ObjectLabelList ol_list;
			out ManagedSets::ObjectLabelIterator iterator;
		);

		void set_initialization_policy (
			in ManagedInstances::InstanceManager im,
			in Policies::InitializationPolicy initialization_policy
		) raises (
			SysAdminException::ExObjNotFound
		);

		SysAdminTypes::ObjectLabel get_initialization_policy (
			in ManagedInstances::InstanceManager im
		) raises (
			SysAdminException::ExObjNotFound
		);

		void set_validation_policy (
			in ManagedInstances::InstanceManager im,
			in Policies::ValidationPolicy validation_policy
		) raises (
			SysAdminException::ExObjNotFound
		);

		SysAdminTypes::ObjectLabel get_validation_policy (
			in ManagedInstances::InstanceManager im
		) raises (
			SysAdminException::ExObjNotFound
		);

		void policy_validation (
			in ManagedInstances::InstanceManager im,
			in boolean enable
		) raises (
			SysAdminException::ExObjNotFound
		);

		boolean is_validation_enabled (
			in ManagedInstances::InstanceManager im
		) raises (
			SysAdminException::ExObjNotFound
		);

		void verify_policy (
			in ManagedSets::Set scope,
			in boolean included_nested,
			in unsigned long how_many,
			out PolicyResultList pr_list,
			out PolicyResultIterator iterator
		);

		PolicyResultList get_policy_failures (
			in ManagedSets::Set scope,
			in boolean include_nested
			in unsigned long how_many,
			out PolicyResultList pr_list,
			out PolicyResultIterator iterator
		);

		SysAdminTypes::ObjectLabelList get_all_initialization_policies
(
			in ManagedInstances::InstanceManager im
		) raises (
			SysAdminException::ExNotFound
		);

		SysAdminTypes::ObjectLabelList get_all_enabled_validation_policies (
			in ManagedInstances::InstanceManager im
		) raises (
			SysAdminException::ExNotFound
		);

	}; // End of PolicyRegion interface

}; // End of PolicyRegions module

#endif // POLICYREGIONS_IDL

PolicyRegions::PolicyResultIterator

• next_one

• next_n

• destroy

The next_one Operation

Syntax

 

boolean next_one (
	out PolicyResult pr;
};

Exceptions

The next_n Operation

Syntax

 

boolean next_n(
	in unsigned long how_many,
	out PolicyResultList pr_list,
};

Exceptions

The destroy Operation

Syntax

 

void destroy();

Exceptions

PolicyRegions::PolicyDrivenBase

The PolicyRegions::PolicyDrivenBase interface defines the following operations:

• get_policy_region_info

• move_to_policy_region

• add_to_policy_region

• remove_from_policy_region

• list_enabled_validation_policies

• list_initialization_policies

Inherited Interfaces

The get_policy_region_info Operation

Syntax

 

SysAdminTypes::ObjectLabelList get_policy_region_info();

Exceptions

The move_to_policy_region Operation

Syntax

 

void move_to_policy_region(
	in PolicyRegions::PolicyRegion pr_from,
	in PolicyRegions::PolicyRegion pr_to
) raises (
	SysAdminException::ExObjNotFound,
	SysAdminException::ExNotFound,
	SysAdminException::ExInvalid
);

Exceptions

SysAdminException::ExObjNotFound is raised when the target object is not currently a member of the pr_from policy region.

SysAdminException::ExNotFound is raised when the target object is being added to a policy region that does not support objects managed by the target object's instance manager.

SysAdminException::ExInvalid is raised when an implementation restriction on policy region membership would be violated by moving this PolicyDrivenBase object to this PolicyRegion.

SysAdminException::ExInvalid is raised when the label of the target object matches that of an object that is already in the PolicyRegion specified by pr_to, and the CORBA::Object defined is_equivalent method returns FALSE when invoked on the target object, passing the already existing PolicyRegion member. In this case the target object is still a member of the source PolicyRegion. If the CORBA::Object defined is_equivalent method returns TRUE in the situation described above, no exception is raised and there remains only one reference to the object in the PolicyRegion.

The add_to_policy_region Operation

Syntax

 

void add_to_policy_region(
	in PolicyRegions::PolicyRegion pr
) raises (
	SysAdminException::ExNotFound,
	SysAdminException::ExInvalid
);

Exceptions

SysAdminException::ExNotFound is raised when the target object is being added to a policy region that does not support objects managed by the target object's instance manager.

SysAdminException::ExInvalid is raised when an implementation restriction on policy region membership would be violated by adding this PolicyDrivenBase object to this PolicyRegion.

SysAdminException::ExInvalid is raised when the label of the target object matches that of an object that is already in the PolicyRegion specified by pr, and the CORBA::Object defined is_equivalent method returns FALSE when invoked on the target object, passing the already existing PolicyRegion member. If the CORBA::Object defined is_equivalent method returns TRUE in this case, no exception is raised and there remains only one reference to the object in the PolicyRegion.

The remove_from_policy_region Operation

Syntax

 

void remove_from_policy_region(
	in PolicyRegions::PolicyRegion pr
) raises (
	SysAdminException::ExObjNotFound,
	SysAdminException::ExInvalid
);

Exceptions

SysAdminException::ExObjNotFound is raised when the target object is not currently a member of the specified policy region.

SysAdminException::ExInvalid is raised if the target object belongs to no other policy regions than the one specified in the pr argument.

The list_enabled_validation_policies Operation

The policy_regions argument is a list of policy regions of which the search is to be limited to. If the target policy driven base object is not a direct member of any of the listed policy regions, those policy regions are ignored in the search. If this argument is passed as an empty sequence (that is, sequence of zero length), all of the policy regions to which the target policy driven base object belongs will be included in the search.

The include_nested argument, if specified as FALSE, indicates that the search is to be limited to policy regions that the target object is directly a member of. If this argument is specified as TRUE, the search will include not only those policy regions to which the target policy driven base object is a direct member, but also all policy regions that are up the containment hierarchy from them.

The interface_def argument allows the validation policy objects being returned to be restricted to those that support the specified interface. If this argument is specified as NULL, all validation policy objects that meet the other selection criteria will be returned.

The validation policies returned will be ordered based on the following set of rules:

• If the policy_regions parameter is not specified, the order is undefined.

• If the policy_regions parameter is specified, the order will be the same as the ordering of policy regions within the parameter.

• If the include_nested parameter is specified as TRUE, then for each policy region in the policy_regions parameter, the topmost containing policy region's validation policy occurs prior to that of the policy region in the parameter².

Syntax

 

SysAdminTypes::ObjectLabelList list_enabled_validation_policies(
	in PolicyRegionList policy_regions,
	in CORBA::InterfaceDef interface_def,
	in boolean include_nested
) raises (
	SysAdminException::ExNotFound
);

Exceptions

SysAdminException::ExNotFound is raised when no validation policy objects meet the selection criteria specified on the call.

The list_initialization_policies Operation

The policy_regions argument is a list of policy regions of which the search is to be limited to. If the target policy driven base object is not a direct member of any of the listed policy regions, those policy regions are ignored in the search. If this argument is passed as an empty sequence (that is, sequence of zero length), all of the policy regions to which the target policy driven base object belongs will be included in the search.

The include_nested argument, if specified as FALSE, indicates that the search is to be limited to policy regions that the target object is directly a member of. If this argument is specified as TRUE, the search will include not only those policy regions to which the target policy driven base object is a direct member, but also all policy regions that are up the containment hierarchy from them.

The interface_def argument allows the initialization policy objects being returned to be restricted to those that support the specified interface. If this argument is specified as NULL, all initialization policy objects that meet the other selection criteria will be returned.

The initialization policies returned will be ordered based on the following set of rules:

• If the policy_regions parameter is not specified, the order is undefined.

• If the policy_regions parameter is specified, the order will be the same as the ordering of policy regions within the parameter.

• If the include_nested parameter is specified as TRUE, then for each policy region in the policy_regions parameter, the topmost containing policy region's initialization policy occurs prior to that of the policy region in the parameter³.

Syntax

 

SysAdminTypes::ObjectLabelList list_initialization_policies(
	in PolicyRegionList policy_regions,
	in CORBA::InterfaceDef interface_def,
	in boolean include_nested
) raises (
	SysAdminException::ExNotFound
);

Exceptions

SysAdminException::ExNotFound is raised when no initialization policy objects meet the selection criteria specified on the call.

PolicyRegions::PolicyRegion Interface

The PolicyRegions::PolicyRegion interface defines the following operations:

• add_instance_manager

• remove_instance_manager

• get_instance_manager_list

• set_initialization_policy

• get_initialization_policy

• set_validation_policy

• get_validation_policy

• policy_validation

• is_validation_enabled

• verify_policy

• get_policy_failures

• get_all_initialization_policies

• get_all_enabled_validation_policies

Inherited Interfaces

• PolicyRegions::PolicyRegionBase

• CosLifeCycle::GenericFactory

• ManagedSets::FilteredSet

Unique Behavior of Inherited Interfaces

CosLifeCycle::LifeCycleObject

The implementation of the remove operation within the PolicyRegions::PolicyRegion interface must insure that the policy region is empty prior to deleting itself. If the policy region is not empty, an exception is raised.

CosLifeCycle::GenericFactory

PolicyRegion uses this interface to provide a convenience function, allowing other PolicyRegion objects similar to itself to be created and initialized.

The k argument is used with both the create_object and supports operations. It is defined to take the following:

kind field	id field
"	object interface"
The fully scoped name of the principal IDL interface for
the type of policy region to be created
T}
"	object implementation"
The name of the implementation to be used with the policy
region to be created
T}

For the supports operation the k argument is required. It is implementation dependent as to whether just "object interface" or "object implementation", or both, are required to be specified. If the PolicyRegion is capable of creating another policy region of the specified interface and implementation, it returns TRUE, otherwise it returns FALSE. Note that a PolicyRegion only creates objects of the same interface and implementation as itself.

For the create_object operation, the k argument is optional and may be specified as an empty sequence (that is, sequence of length zero). This is because the policy region already has a defined interface and implementation. If the k argument is specified, the values specified must be consistent with the interface and implementation of this policy region object. If it is not, the CosLifeCycle::NoFactory exception is raised.

The implementation of the create_object operation within the PolicyRegions::PolicyRegion interface creates another policy region that is contained in the creating region. That is, the new region is made a member of the policy region's set. The new policy region is an exact duplicate of the owner, including the set of supported instance managers and policies, except that it is created empty of members. This is similar to calling the ManagedInstances::PolicyRegionsInstanceManager specifying the target policy region object in the "policy regions" and "model policy region" name/value pairs of the_criteria argument.

For the create_object operation, after the new policy region is created and added to this policy region, the newly created policy region should be added to this policy region's instance manager (which must support the PolicyRegionsInstanceManager interface).

The name/value pairs that are passed in the_criteria argument of the create_object call should contain the named values for labelid and location. These have the same meaning as defined for the ManagedInstances::InstanceManager interface. If these are not specified, the CosLifeCycle::InvalidCriteria exception is raised.

The add_instance_manager Operation

Syntax

 

void add_instance_manager(
	in ManagedInstances::InstanceManager im,
	in Policies::InitializationPolicy initialization_policy,
	in Policies::ValidationPolicy validation_policy
)raises(
	SysAdminException::ExExists
);

Exceptions

SysAdminException::ExExists is raised when the specified instance manager is already a member of the policy region.

The remove_instance_manager Operation

Syntax

 

void remove_instance_manager(
	in ManagedInstances::InstanceManager im
)raises(
	SysAdminException::ExObjNotFound,
	SysAdminException::ExExists
);

Exceptions

The SysAdminException::ExObjNotFound exception is raised if the instance manager object passed in the im parameter is not registered with this policy region.

The SysAdminException::ExExists exception is raised if this policy region currently has any policy driven base objects as members who are also members of the instance manager passed in the im parameter.

The get_instance_manager_list Operation

all

list all instance managers registered with the policy region

with_initialization

list all instance managers that have an InitializationPolicy object registered with the policy region

with_validation

list all instance managers that have a ValidationPolicy object registered with the policy region

with_validation_enabled

list all instance managers that have validation enabled with the policy region

with_initialization_or_validation

list all instance managers that have an InitializationPolicy object or ValidationPolicy object registered with the policy region

with_initialization_or_validation_enabled

list all instance managers that have an InitializationPolicy object registered or have validation enabled with the policy region.

The initial size of ol_list is determined by the how_many argument. The rest of the ObjectLabel structures, if any, can be retrieved using the returned iterator object. When how_many is equal to or greater than the total number of ObjectLabel structures that could potentially be returned, all of the ObjectLabel structures will be returned in ol_list and the iterator will be returned as OBJECT_NIL.

Syntax

 

enum SelectionCriteria {
	all,
	with_initialization,
	with_validation,
	with_validation_enabled,
	with_initialization_or_validation,
	with_initialization_or_validation_enabled
};

void get_instance_manager_list (
	in SelectionCriteria select,
	in unsigned long how_many,
	out ObjectLabelList ol_list,
	out ObjectLabelIterator iterator
);

Exceptions

The set_initialization_policy Operation

Syntax

 

void set_initialization_policy(
	in Instances::InstanceManager im,
	in Policies::InitializationPolicy initialization_policy
)raises(
	SysAdminException::ExObjNotFound
);

Exceptions

SysAdminException::ExObjNotFound is raised when the instance manager to which the initialization policy is being set is not supported by the policy region.

The get_initialization_policy Operation

Syntax

 

SysAdminTypes::ObjectLabel get_initialization_policy (
	in ManagedInstances::InstanceManager im
)raises(
	SysAdminException::ExObjNotFound
);

Exceptions

SysAdminException::ExObjNotFound is raised when the specified instance manager does not have an initialization policy object registered for it.

The set_validation_policy Operation

Syntax

 

void set_validation_policy (
	in ManagedInstances::InstanceManager im,
	in Policies::ValidationPolicy validation_policy
)raises(
	SysAdminException::ExObjNotFound
);

Exceptions

SysAdminException::ExObjNotFound is raised when the instance manager associated with the policy region.

The get_validation_policy Operation

Syntax

 

SysAdminTypes::ObjectLabel get_validation_policy (
	in ManagedInstances::InstanceManager im
)raises(
	SysAdminException::ExObjNotFound
);

Exceptions

SysAdminException::ExObjNotFound is raised when a validation policy object is not registered for the instance manager or the instance manager is not registered in the policy region.

The policy_validation Operation

Syntax

 

void policy_validation(
	in ManagedInstances::InstanceManager im,
	in boolean enable
)raises(
	SysAdminException::ExObjNotFound
);

Exceptions

SysAdminException::ExObjNotFound is raised when the specified instance manager is not supported by the policy region or if there is no ValidationPolicy object for the specified instance manager registered in the policy region.

The is_validation_enabled Operation

Syntax

 

boolean is_validation_enabled(
	in ManagedInstances::InstanceManager im
) raises(
	SysAdminException::ExObjNotFound
);

Exceptions

SysAdminException::ExObjNotFound is raised when the specified instance manager is not supported by the policy region.

The verify_policy Operation

The operation may include all objects within the policy region or be scoped to only include objects within the region that are also members of a set passed in the scope argument. Note that if OBJECT_NIL is passed as the scope argument, or if the object reference of the target policy region itself is passed as the scope argument, all of the members of the policy region will be checked.

If the include_nested boolean is set to TRUE, then policy defined in all of the target policy region's containing policy regions will be used to validate the objects as well.

For any object whose instance manager does not currently have validation enabled within a policy region, no checking is done in respect to policy for that object relative to that region.

Since each object can be checked multiple times when include_nested is TRUE, it is possible for there to be multiple PolicyResult structures in the PolicyResultList for any one object in the target policy region. The PolicyResult structure for each validation that was performed contains:

• An object reference to the object that was checked

• An object reference to the policy region within which the policy is defined

• An object reference to the validation policy object that was used to perform the validation

• A boolean indicator as to whether or not the object passed validation

• A string with a description of the reason for validation failure

This provides sufficient information for the caller to determine exactly what was validated and from where any validation failures originated.

The initial size of pr_list is determined by the how_many argument. The rest of the PolicyResult structures, if any, can be retrieved using the returned iterator object. When how_many is equal to or greater than the total number of PolicyResult structures that could potentially be returned, all of the PolicyResult structures will be returned in pr_list and the iterator will be returned as OBJECT_NIL.

Syntax

 

PolicyResultList verify_policy(
	in ManagedSets::Set scope,
	in boolean include_nested
	in unsigned long how_many,
	out PolicyResultList pr_list,
	out PolicyResultIterator iterator
);

Exceptions

The get_policy_failures Operation

The operation may include all objects within the policy region or be scoped to only include objects within the region that are also members of a set passed in the scope argument. Note that if OBJECT_NIL is passed as the scope argument, or if the object reference of the target policy region itself is passed as the scope argument, all of the members of the policy region will be checked.

If the include_nested boolean is set to TRUE, then policy defined in all of the target policy region's containing policy regions will be used to validate the objects as well.

For any object whose instance manager does not currently have validation enabled within a policy region, no checking is done in respect to policy for that object relative to that region.

Since each object can be checked multiple times when include_nested is TRUE, it is possible for there to be multiple PolicyResult structures in the PolicyResultList for any one object in the target policy region, assuming it failed validation in respect to more than one region. The PolicyResult structure for each failure contains:

• An object reference to the object that was checked

• An object reference to the policy region within which the policy is defined

• An object reference to the validation policy object that was used to perform the validation

• A boolean indicator set to FALSE

• A string with a description of the reason for validation failure

This provides sufficient information for the caller to determine exactly where any validation failures originated from.

The initial size of pr_list is determined by the how_many argument. The rest of the PolicyResult structures, if any, can be retrieved using the returned iterator object. When how_many is equal to or greater than the total number of PolicyResult structures that could potentially be returned, all of the PolicyResult structures will be returned in pr_list and the iterator will be returned as OBJECT_NIL.

Syntax

 

PolicyResultList get_policy_failures(
	in ManagedSets::Set scope,
	in boolean include_nested
	in unsigned long how_many,
	out PolicyResultList pr_list,
	out PolicyResultIterator iterator
);

Exceptions

The get_all_initialization_policies Operation

Syntax

 

SysAdminTypes::ObjectLabelList get_all_initialization_policies(
	in ManagedInstances::InstanceManager im
) raises (
	SysAdminException::ExNotFound
);

Exceptions

SysAdminException::ExNotFound is raised when no initialization policy objects are found that satisfy the request.

The get_all_enabled_validation_policies Operation

Syntax

 

SysAdminTypes::ObjectLabelList get_all_enabled_validation_policies(
	in ManagedInstances::InstanceManager im
) raises (
	SysAdminException::ExNotFound
);

Exceptions

SysAdminException::ExNotFound is raised when no validation policy objects are found that satisfy the request.

Policies Module

Interfaces and Operations

Specified IDL

//
// Component Name: Policies.idl
//
// Description:  
// The following interfaces provide the functionality
// for support of policy objects.
//

#ifndef POLICIES_IDL
#define POLICIES_IDL

#include <SysAdminTypes.idl>
#include <SysAdminExcept.idl>
#include <Identification.idl>
#include <CosLifeCycle.idl>
#include <ManagedSets.idl>

module Policies {

	// forward references
	interface PolicyObject;
	interface PolicyObjectAdmin;
	interface InitializationPolicy;
	interface ValidationPolicy;

	interface PolicyObjectAdmin 
	{

		SysAdminTypes::ObjectLabelList get_initialization_policies();

		InitializationPolicy get_default_initialization (
		) raises (
			SysAdminException::ExNotFound
		);

		SysAdminTypes::ObjectLabelList get_validation_policies();

		ValidationPolicy get_default_validation (
		) raises (
			SysAdminException::ExNotFound
		);

		void add_initialization (
			in InitializationPolicy initialization_policy
		) raises (
			SysAdminException::ExExists,
			SysAdminException::ExInvalid
		);

		void set_default_initialization (
			in InitializationPolicy initialization_policy
		) raises (
			SysAdminException::ExInvalid
		);

		void remove_initialization (
			in InitializationPolicy initialization_policy
		) raises (
			SysAdminException::ExObjNotFound
		);

		void add_validation (
			in ValidationPolicy validation_policy
		) raises (
			SysAdminException::ExExists,
			SysAdminException::ExInvalid
		);

		void remove_validation (
			in ValidationPolicy validation_policy
		) raises (
			SysAdminException::ExObjNotFound
		);

		void set_default_validation (
			in ValidationPolicy validation_policy
		) raises (
			SysAdminException::ExInvalid
		);

		void add_pr_backref (
			in PolicyRegion pr
		);

		void remove_pr_backref (
			in PolicyRegion pr
		) raises (
			SysAdminException::ExNotFound
		);

		void get_pr_backrefs (
			in unsigned long how_many,
			out SetList s_list,
			out SetIterator iterator
		);

	}; // End of PolicyObjectAdmin interface

	// The PolicyObject interface defines the common
	// requirements of policy objects

	interface PolicyObject : 
		Identification::Labeled 
	{
		string get_policy_driven_object_type();

		CORBA::InterfaceDef get_policy_driven_object_interface();

	}; // End of PolicyObject interface

	// The InitializationPolicy interface defines the
	// requirements of an initialization policy object

	interface InitializationPolicy :
		PolicyObject
	{
		void initialize_policy_driven_object (
			in Object object_to_initialize,
			in CosLifeCycle::Criteria override_criteria
		);

	}; // End of InitializationPolicy interface

	// The ValidationPolicy interface defines the
	// requirements of an validation policy object

	interface ValidationPolicy :
		PolicyObject
	{

		boolean validate_policy_driven_object (
			in Object object_to_validate,
			out string description
		);

	}; // End of ValidationPolicy interface

}; // End of Policies module

#endif // POLICIES_IDL

Policies::PolicyObjectAdmin Interface

The Policies::PolicyObjectAdmin interface defines the following operations:

• get_initialization_policies

• get_default_initialization

• get_validation_policies

• get_default_validation

• add_initialization

• set_default_initialization

• remove_initialization

• add_validation

• remove_validation

• set_default_validation

The get_initialization_policies Operation

Syntax

 

SysAdminTypes::ObjectLabelList get_initialization_policies();

Exceptions

The get_default_initialization Operation

Syntax

 

InitializationPolicy get_default_initialization(
)raises(
	SysAdminException::ExNotFound
);

Exceptions

SysAdminException::ExNotFound is raised if a initialization policy object is not found for the object.

The get_validation_policies Operation

Syntax

 

SysAdminTypes::ObjectLabelList get_validation_policies();

Exceptions

The get_default_validation Operation

Syntax

 

ValidationPolicy get_default_validation(
)raises(
	SysAdminException::ExNotFound
);

Exceptions

SysAdminException::ExNotFound is raised if a validation policy object is not registered for the object.

The add_initialization Operation

Syntax

 

void add_initialization(
	in InitializationPolicy initialization_policy
)raises(
	SysAdminException::ExExists,
	SysAdminException::ExInvalid
);

Exceptions

SysAdminException::ExExists is raised if the specified object is already registered for the instance manager.

SysAdminException::ExInvalid is raised if the specified object indicates that it supports a policy driven object type that is not an interface supported by objects managed by the receiving instance manager.

The set_default_initialization Operation

Syntax

 

void set_default_initialization(
	in InitializationPolicy initialization_policy
)raises(
	SysAdminException::ExInvalid
);

Exceptions

SysAdminException::ExInvalid is raised if the input initialization policy object indicates that it supports a policy driven object type that is not an interface supported by objects managed by the receiving instance manager.

The remove_initialization Operation

If the input initialization policy happens to be the instance manager's default initialization policy, then remove_initialization should set the instance manager's default initialization policy to Object::_nil().

Syntax

 

void remove_initialization(
	in InitializationPolicy initialization_policy
)raises(
	SysAdminException::ExObjNotFound
);

Exceptions

SysAdminException::ExObjNotFound is raised when the requested initialization policy object is not currently associated with the instance manager.

The add_validation Operation

Syntax

 

void add_validation(
	in ValidationPolicy validation_policy
)raises(
	SysAdminException::ExExists,
	SysAdminException::ExInvalid
);

Exceptions

SysAdminException::ExExists is raised if the specified validation policy object is already associated with the instance manager.

SysAdminException::ExInvalid is raised if the specified object indicates that it supports a policy driven object type that is not an interface supported by objects managed by the receiving instance manager.

The remove_validation Operation

If the input validation policy happens to be the instance manager's default validation policy, then remove_validation should set the instance manager's default validation policy to Object::_nil().

Syntax

 

void remove_validation(
	in ValidationPolicy validation_policy
)raises(
	SysAdminException::ExObjNotFound
);

Exceptions

SysAdminException::ExObjNotFound is raised when the requested validation policy object is not currently associated with the instance manager.

The set_default_validation Operation

Syntax

 

void set_default_validation(
	in ValidationPolicy validation_policy
)raises(
	SysAdminException::ExInvalid
);

Exceptions

SysAdminException::ExInvalid is raised if the input validation policy object indicates that it supports a policy driven object type that is not an interface supported by objects managed by the receiving instance manager.

The add_pr_backref Operation

Syntax

 

void add_pr_backref (
	in PolicyRegion pr
);

Exceptions

The remove_pr_backref Operation

Syntax

 

void remove_pr_backref (
	in PolicyRegion pr
) raises (
	SysAdminException::ExNotFound
);

Exceptions

SysAdminException::ExNotFound is raised if the target instance manager does not currently have a back reference to the policy region passed in as an input parameter.

The get_pr_backrefs Operation

Syntax

 

void get_pr_backrefs (
	in unsigned long how_many,
	out SetList s_list,
	out SetIterator iterator
);

Exceptions

Policies::PolicyObject Interface

The Policies::PolicyObject interface defines a single operation, get_policy_driven_object_type.

Inherited Interfaces

The get_policy_driven_object_type Operation

Syntax

 

string get_policy_driven_object_type();

Exceptions

The get_policy_driven_object_interface() Operation

Syntax

 

CORBA::InterfaceDef get_policy_driven_object_interface();

Exceptions

Policies::InitializationPolicy Interface

The initialize_policy_driven_object Operation

It is expected that for every specialization of the PolicyDrivenBase type, there will be an implementation of this operation that specifically knows how to initialize objects of that type. Also, the definition of what name/value pairs are passed in the override_criteria parameter will typically be unique to each implementation.

Syntax

 

void initialize_policy_driven_object(
	in Object object_to_initialize,
	in CosLifeCycle::Criteria override_criteria
);

Exceptions

Policies::ValidationPolicy Interface

The validate_policy_driven_object Operation

Syntax

 

boolean validate_policy_driven_object(
	in Object object_to_validate,
	out string description
);

Exceptions

Footnotes

1.

It is possible for a policy region itself to be a member of multiple policy regions. When this occurs, the order of initialization policies used is not defined. Because of this, it is recommended that policy regions should not belong to more than one other policy region if deterministic ordering of initialization policies is required.

2.

It is possible for a policy region itself to be a member of multiple policy regions. When this occurs, the order of validation policies returned is not defined. Because of this, it is recommended that policy regions should not belong to more than one other policy region if deterministic ordering of validation policies is required.

3.

It is possible for a policy region itself to be a member of multiple policy regions. When this occurs, the order of initialization policies returned is not defined. Because of this, it is recommended that policy regions should not belong to more than one other policy region if deterministic ordering of initialization policies is required.

4.

Refer to the operations of the PolicyObjectAdmin interface, described elsewhere in this specification.

5.

It is possible for a policy region itself to be a member of multiple policy regions. When this occurs, the order of initialization policies returned is not defined. Because of this, it is recommended that policy regions should not belong to more than one other policy region if deterministic ordering of initialization policies is required."

6.

It is possible for a policy region itself to be a member of multiple policy regions. When this occurs, the order of validation policies returned is not defined. Because of this, it is recommended that policy regions should not belong to more than one other policy region if deterministic ordering of validation policies is required.