Previous section.

Systems Management: Common Management Facilities (XCMF)
Copyright © 1997 The Open Group

Management Facilities Specification

This chapter fully specifies the management facilities described in the previous chapters. In designing the interfaces presented in this specification, several design principles guided the activity.

SysAdminTypes Module

This module defines the common types for the management facilities in this specification. Having these types defined in a common IDL module, allows an application developer to simply recall the appropriate language mapping from an IDL source in a consistent manner. If these types were defined in the module which primarily used them, the application developer would have to remember in which module these various types were defined. This is due to the IDL scoping rules that require operation names to have mappings dependent upon the derived interface by which they are inherited, and types to have mappings dependent upon the defining scope.

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

The design of the interfaces and systems management framework in this specification have been influenced by the philosophy of making a few, general exception types defined in a common IDL module, specializing exceptions by use of their data fields, and the integration with an XPG messaging system. Limiting the number and types of exceptions allows future implementations to specialize an exception without the redefinition or subtyping of the original interface. In addition, it allows clients to have simpler, more robust exception handling code by having a string comparison for a smaller number of exception types. The inclusion of XPG message information in an exception allows the server, at the point of error detection, to specify a minimal amount of context and error information for eventual presentation to the user. As the exception is returned, other servers that pass the exception through to other clients may add additional information related to the context or nature of the error. This approach allows an administrator to receive more information about an exception other than simply "something undesirable happened", and allows the potential for the administrator to alter the operation intelligently and to hopefully succeed upon retry.

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

The Identification module defines interfaces that allow an object to be identified.

Interfaces and Operations


Module Interface Operation
Identification Labeled get_label
    set_label


Table: Interfaces and Operations for the Identification Module

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 Identification::Labeled interface provides the operations needed to allow an object to have a label. The underlying type of the label is a CosNaming::NameComponent, which allows an object's label to also be used as its name within a COS Naming Service name space (see reference COS Volume 1).
The set_label Operation
The set_label operation sets the object's label to the value passed in the label parameter. This operation is only intended to be invoked by an InstanceManager at the time an object is created. Conforming implementations are highly discouraged from allowing subsequent invocations upon objects that have already had their labels set. Such invocations may lead to unpredictable behavior in the other services described in this specification.
Syntax
void set_label(in SysAdminTypes::LabelType label);
Exceptions
CORBA 1.2 standard exceptions.
The get_label Operation
The get_label operation returns the current value of the objects label.
Syntax
SysAdminTypes::LabelType get_label();
Exceptions
CORBA 1.2 standard exceptions.

SysAdminLifeCycle Module

The SysAdminLifecycle module defines the Location and HostLocation interfaces and their operations. These interfaces allow the object that supports them to identify a specific location at which an operation (typically object creation) should be performed. The Location interface is extremely generic and supports no attributes or operations. It is mainly intended to be used as an abstract interface that will be subtyped to form interfaces that provide more specific information about particular types of locations. The HostLocation interface is an example of a subtype of the Location interface that is capable of providing information about a particular type of location: in this case, a host. It is defined due to it's general purpose usefulness, and to provide an example of how the Location interface can be used.

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


Module Interface Operation
SysAdminLifeCycle Location  
  HostLocation get_platform
     
  Inheritance:  
  SysAdminLifeCycle::Location  


Table: Interfaces and Operations for the SysAdminLifeCycle Module

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

The SysAdminLifeCycle::Location interface defines no operations and does not inherit any other interfaces. It is an abstract type that is intended to be inherited by other interfaces. It's primary purpose is to introduce the idea that, for object creation, the location of where to create an object must somehow be specified. However, since the concept of location is very ORB implementation dependent, how to specify location cannot be addressed in this specification. By introducing this interface, it allows other interfaces (such as ManagedInstances::BasicInstanceManager) to specify that they require a Location object in order to perform particular operations.

SysAdminLifeCycle::HostLocation Interface

The SysAdminLifeCycle::HostLocation interface defines the get_platform operation, which returns information related to the platform on which the object currently resides. This information is related to the hardware type and the operating system.
Inherited Interfaces
The SysAdminLifeCycle::HostLocation interface inherits from the SysAdminLifecycle::Location interface to represent the fact that it can be viewed as a specific type of location.
The get_platform Operation
The get_platform operation gets the client machine information of the host on which the target object resides. This information should be accurate even after the target object migrates from one client machine to another. The host_name element of the Platform structure is typically the name by which the client machine is known to the communications network. The machine_hardware_name is the standard name that identifies the hardware on which the object is running. The operating_system_name element is the current operating system under which the object is running. The operating_system_release element specifies the specific release number of the operating system (for example, 5.4). The operating_system_version element specifies the exact version of the operating system. Often times a version of an operating system is determined by its relationship to hardware (for example, generic).
Syntax
SysAdminTypes::Platform get_platform();
Exceptions
CORBA 1.2 standard exceptions.

ManagedSets Module

The ManagedSets module defines interfaces that provide operations for establishing two way reference relationships between objects.

Interfaces and Operations

Module Interface Operation
ManagedSets Set

Inheritance: ManagedSets::Member


get_cardinality
add_object
add_n_objects
remove_object
remove_n_objects
get_members
intersection_members
union_members
 
Member


Inheritance:
Identification::Labeled


add_backref
get_backrefs
remove_backref
 
FilteredSet


Inheritance:
ManagedSets::Set


find_members
lookup_object
lookup_labels
  SetIterator
next_one
next_n
destroy
  MemberIterator
next_one
next_n
destroy
  MemberLabelIterator
next_one
next_n
destroy

Table: Interfaces and Operations for the ManagedSets Module

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

The Member interface defines the following operations that allow an object to be member of a set object:
Inherited Interfaces
The ManagedSets::Member interface inherits from the Identification::Labeled interface.
The add_backref Operation
The add_backref operation adds an object reference to an unordered list. The references are to objects supporting the Set interface. Adding a back reference provides a means for objects to know about the containment relationships of which they are a part. Typically this operation would never be called by client code, but would be called by an implementation of the ManagedSets::Set interface, in particular from the add_object or add_n_objects operations. Arbitrary use of the add_backref operation by client code can, and probably will, result in referential integrity problems in Set-Member relationships. It is made a public part of the Member interface as it is anticipated that set to set member relationships will exist between objects that exist in different vendors' framework implementations.
Syntax
void add_backref( in Set s );

Exceptions
CORBA 1.2 standard 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
The get_backrefs operation returns the object references (back references) for the Sets of which the object is a member. If how_many is greater than or equal to the total number of back references maintained by the target object, then all of the back references will be returned in s_list and iterator will be returned as OBJECT_NIL.
Syntax
void get_backrefs( in unsigned long how_many, out SetList s_list, out SetIterator iterator );

Exceptions
CORBA 1.2 standard exceptions.
The remove_backref Operation
The remove_backref operation removes the back reference to the Set specified by the s argument. Typically this operation would never be called by client code, but would be called by an implementation of the ManagedSets::Set interface, in particular from the remove_object or remove_n_objects operations. Arbitrary use of the remove_backref operation by client code can, and probably will, result in referential integrity problems in Set-Member relationships. It is made a public part of the Member interface as it is anticipated that set to set member relationships will exist between objects that exist in different vendors' framework implementations.

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
If the object upon which this operation is invoked is not a member of the set indicated by the input argument the SysAdminException::ExNotFound exception is raised.

ManagedSets::SetIterator Interface

The SetIterator interface defines the following operations that allow an object to iteratively request a list of sets to which an object is a member. The SetIterator provides a static view of the sets to which the object belonged at the time the iterator was created, and does not reflect subsequent changes to the object's membership in sets. The operations provided are:

The next_one Operation
The next_one operation returns the next object. If the last set object is being returned on this call (or was returned on a previous call), this operation returns FALSE, indicating subsequent calls to the iterator are not needed.
Syntax
boolean next_one( out Set s );

Exceptions
CORBA 1.2 standard exceptions.
The next_n Operation
The next_n operation returns at most the requested number of set objects. If the last set object is being returned on this call (or was returned on a previous call), this operation returns FALSE, indicating subsequent calls to the iterator are not needed.
Syntax
boolean next_n( in unsigned long how_many, out SetList s_list );

Exceptions
CORBA 1.2 standard exceptions.
The destroy Operation
The destroy operation destroys the iterator.
Syntax
void destroy();

Exceptions
CORBA 1.2 standard exceptions.

ManagedSets::MemberIterator Interface

The MemberIterator interface defines the following operation that allows an object to iteratively request a list of members that belong to a set. The MemberIterator provides a static view of the set's members at the time the iterator was created, and does not reflect subsequent changes to the set's membership. The operations provided are:

The next_one Operation
The next_one operation returns the next set member object. If the last set member object is being returned on this call (or was returned on a previous call), this operation returns FALSE, indicating subsequent calls to the iterator are not needed.
Syntax
boolean next_one( out Member m );

Exceptions
CORBA 1.2 standard exceptions.
The next_n Operation
The next_n operation returns at most the requested number of set member objects. If the last set member object is being returned on this call (or was returned on a previous call), this operation returns FALSE, indicating subsequent calls to the iterator are not needed.
Syntax
boolean next_n( in unsigned long how_many, out MemberList m_list );

Exceptions
CORBA 1.2 standard exceptions.
The destroy Operation
The destroy operation destroys the iterator.
Syntax
void destroy();

Exceptions
CORBA 1.2 standard exceptions.

ManagedSets::ObjectLabelIterator Interface

The ObjectLabelIterator interface is a general-purpose iterator interface that defines the following operations that allow an object to iteratively request a list of ObjectLabel structures that correspond to objects that have a special relationship to the target object whose "get" or "list" operation generated the iterator. In the case of ManagedSets, this means that the ObjectLabels correspond to objects that are members of the target set. In the case of PolicyRegions, the ObjectLabels correspond to policy-driven objects that are supported by the target PolicyRegion (see, for example, The get_instance_manager_list Operation ). The ObjectLabelIterator provides a static view of the objects that had this special relationship to the original target object at the time the iterator was created, and does not reflect subsequent changes to the list of objects that continue to have this special relationship. The operations provided are:

The next_one Operation
The next_one operation returns the next ObjectLabel structure. If the last ObjectLabel structure is being returned on this call (or was returned on a previous call), this operation returns FALSE, indicating subsequent calls to the iterator are not needed.
Syntax
boolean next_one ( out MemberLabel ol; );

Exceptions
CORBA 1.2 standard exceptions.
The next_n Operation
The next_n operation returns at most the requested number of ObjectLabel structures. If the last ObjectLabel structure is being returned on this call (or was returned on a previous call), this operation returns FALSE, indicating subsequent calls to the iterator are not needed. If how_many is greater than or equal to the total number of ObjectLabel structures remaining in the iterator object, then all of the ObjectLabel structures will be returned in ol_list and no exception will be raised.
Syntax
boolean next_n( in unsigned long how_many, out ObjectLabelList ol_list );

Exceptions
CORBA 1.2 standard exceptions.
The destroy Operation
The destroy operation destroys the iterator.
Syntax
void destroy();

Exceptions
CORBA 1.2 standard exceptions.

ManagedSets::Set Interface

The set relationship supported by a set object is a many-to-many reference relationship. An object may be a member of an arbitrary number of sets. Sets are a way for system administrator to group objects and to develop subsets of objects and resources to be managed similarly. In addition to the Containment functionality of the basic set, behaviors are supported to provide a means of selecting a subset of the set's membership.

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

Inherited Interfaces
The ManagedSets::Set interface inherits from the ManagedSets::Member interface, thus allowing sets to be arranged into hierarchies.

The get_cardinality Operation
The get_cardinality operation returns the current number of members of the set.
Syntax
unsigned long get_cardinality();

Exceptions
CORBA 1.2 standard exceptions.
The add_object Operation
The add_object operation adds a new object reference to the set of member objects.

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
CORBA 1.2 standard exceptions and SysAdminException::ExNotUniqueLabel.

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
The add_n_objects operation adds new object references to the set of Member object held by a Set. If any of the objects were unable to be added to the Set, their object references are returned for appropriate error handling. If some objects are not able to be added, the remainder of the objects are added. Note that the most likely reason why an object was not added is because its label is identical to that of an object that is already a member of the set (see The add_object Operation ).
Syntax
void add_n_objects( in MemberList m_list, out MemberList not_added );

Exceptions
CORBA 1.2 standard exceptions.
The remove_object Operation
The remove_object operation removes the member object specified by the m argument from a Set object. The remove_object operation does not remove the specified objects. It only removes references to the objects.

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
If the object indicated by the second input parameter is not a member of the target set, the SysAdminException::ExNotFound exception is raised.
The remove_n_objects Operation
The remove_n_objects operation removes the member objects, specified by the s_list argument, from a Set object. The remove_n_objects operation does not remove the specified objects. It only removes references to the objects. 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 member object is not notified. This operation is useful when member objects are to be destroyed. Upon deletion they remove themselves from all Sets. There is no need for the Set object to notify the member objects to remove a back reference in this scenario.
Syntax
void remove_n_objects( in boolean remove_backref, in MemberList m_list, out MemberList not_removed );

Exceptions
CORBA 1.2 standard exceptions.
The get_members Operation
The get_members operation returns the object references of object's members. If how_many is greater than or equal to the total number of members In the Set, then all of the members will be returned in m_list and iterator will be returned as OBJECT_NIL.
Syntax
void get_members ( in unsigned long how_many, out MemberList m_list, out MemberIterator iterator );

Exceptions
CORBA 1.2 standard exceptions.
The intersection_members Operation
The intersection_members operation provides the list of members that are the intersection of sets. Given a list of sets, a list of members will be returned that represents the intersection of the target set and all of the sets specified in the s_list argument. The initial size of m_list is determined by the how_many argument. The rest of the Member objects, if any, can be retrieved using the returned iterator object. When how_many is equal to or greater than the total number of members that could potentially be returned, all of the members will be returned in s_list and the iterator will be returned as OBJECT_NIL.
Syntax
void intersection_members ( in unsigned long how_many, in SetList s_list, out MemberList m_list, out MemberIterator iterator ) raises ( SysAdminException::ExInvalid );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExInvalid.

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
The union_members operation provides the list of members that represent the union of the sets. Given a list of sets, a list of members will be returned that represents the union of the target set and all of the sets specified in the s_list argument. This operation ensures no duplicates in the member list. The initial size of m_list is determined by the how_many argument. The rest of the Member objects, if any, can be retrieved using the returned iterator object. When how_many is equal to or greater than the total number of members that could potentially be returned, all of the members will be returned in s_list and the iterator will be returned as OBJECT_NIL.
Syntax
void union_members ( in unsigned long how_many, in SetList s_list, out MemberList m_list, out MemberIterator iterator ) raises ( SysAdminException::ExInvalid );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExInvalid.

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

An object supporting the FilteredSet interface is called a filtered set. A filtered set is able to filter across the the member objects and return a subset of its membership based on simple search criteria, which supports filtering based on the interfaces supported by members, or the labels of members.

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

Inherited Interfaces
The ManagedSets::FilteredSet interface inherits from the ManagedSets::Set interface:

The find_members Operation
The find_members operation returns a list of the object references for the objects contained in a set meeting the specified selection criteria. Objects may be selected on the basis of the interfaces they support and their labels. The interfaces argument is a sequence of types defined in the InterfaceDef interface. Only objects that support all of the interfaces in the sequence are returned. If this sequence is of zero length, then objects may be returned regardless of their supported interfaces. The regular_expression argument specifies a POSIX 1003.2 regular expression for matching on the basis of object labels. Only objects that have labels matching the regular expression are returned. If a regular expression is not specified, then objects will be selected irrespective of their labels. Note that labels are comprised of two components: an id field and a kind field. A client can specify a regular expression to be matched for one, both, or neither of these fields.

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
CORBA 1.2 standard exceptions and SysAdminException::ExNotFound.

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

The lookup_object Operation
The lookup_object operation returns an object reference to the set member that has the same label as the label specified in the label argument. Labels are unique within sets, therefore at most one object with that label can be found and returned. However, if the kind field of the label argument is specified as a zero length string, only the id field of the label is used in searching for the set member to return. Since the id fields of a set's members are not necessarily unique within the set, this operation will return one of possibly many set members that have the matching id field.

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
CORBA 1.2 standard exceptions and SysAdminException::ExNotFound.

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

The lookup_labels Operation
The lookup_labels operation returns a list of object references and their labels. The objects whose labels are requested are specified by the m_list argument. The objects and their labels are returned in the same order in which they were input in m_list. If m_list contains duplicate members, then the returned ObjectLabelList will contain the corresponding duplicate object labels in list positions that correspond to the input duplicate members' list positions. If the input m_list contains elements that are set to Object::_nil(), then the returned ObjectLabelList will contain ObjectLabels whose objref members are Object::_nil(). Similarly, input objects that are not members of the set cause a Object::_nil() to be placed in the output list in place of the errant input object. Finally, errors in processing a list element (for example, an exception when getting the object's label) cause a Object::_nil() to be placed in the output list in place of the errant object. These "null" ObjectLabels will appear in the output list in list positions that correspond to the appropriate input members' list positions, and the kind field of the label will be used to explain why the object field contains a Object::_nil() value. If m_list is zero-length, then the output ObjectLabelList will also be zero-length.
Syntax
SysAdminTypes::ObjectLabelList lookup_labels( in MemberList m_list );

Exceptions
CORBA 1.2 standard exceptions.

ManagedInstances Module

The ManagedInstances module defines the Instance, BasicInstanceManager, InstanceManager and Library interfaces and their operations. The ManagedInstances::Instance interface defines operations that determine and report the instance manager of an object instance. The ManagedInstances::BasicInstanceManager interface defines operations that encapsulate type-specific information related to object creation and instances of the object type. The ManagedInstances::InstanceManager extends this to also include information related to policy for instances of the object type. The ManagedInstances::Library interface defines operations for the creation and finding of instance manager objects.

Interfaces and Operations


Module Interface Operation
ManagedInstances
Instance


Inheritance
CosLifeCycle::LifeCycleObject
ManagedSets::Member


get_manager
get_type_name
get_resource_location


 
BasicInstanceManager


Inheritance
CosLifeCycle::LifeCycleObject
CosLifeCycle::GenericFactory
ManagedSets::FilteredSet

get_instances_interface

 
InstanceManager


Inheritance
ManagedInstances::BasicInstanceManager
Policies::PolicyObjectAdmin

 

 
Library


Inheritance:
CosLifeCycle::FactoryFinder
CosLifeCycle::GenericFactory
ManagedSets::FilteredSet

 

 
PolicyRegionsInstanceManager


Inheritance:
ManagedInstances::InstanceManager

 


Table: Interfaces and Operations for the Instances Module

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 ManagedInstances::Instance interface defines the operations required for an object to be managed by an instance manager. An instance is able to report the IDL interface name for its principal interface type, and the object reference of the instance manager associated with the type.

The ManagedInstance::Instance interface defines the following operations:

Inherited Interfaces
The Instance interface inherits from the following interfaces:
Unique Behavior of Inherited Interfaces
Operations defined within these interfaces may have unique behavior when inherited by the Instance interface.
CosLifeCycle::LifeCycleObject
The remove operation must invoke the ManagedSets::Set::remove_object operation with it's own object reference specified for removal on all sets that contain the target object at the time of deletion. This operation notifies the sets that one of it's member objects is being removed. This also applies to the instance's membership in its instance manager. The only way that an instance may be removed from its instance manager is by virtue of a client having invoked the instance's inherited remove operation to destroy the instance.
The get_manager Operation
The get_manager operation returns the object reference of the instance manager that manages the target object.
Syntax
BasicInstanceManager get_manager();

Exceptions
CORBA 1.2 standard exceptions.
The get_type_name Operation
The get_type_name operation returns the fully scoped IDL interface name of an instance.
Syntax
string get_type_name();

Exceptions
CORBA 1.2 standard exceptions.
The get_resource_location Operation
The get_resource_location operation returns the object reference of the SysAdminLifeCycle::Location for the location where the current object resides. This operation can be used during life cycle-defined operations. For example, when the location of one object needs to be determined so that another object may be created in the same location, the get_resource_location operation is invoked. The returned object reference is used as an input to the CosLifeCycle::GenericFactory::create_object operation.
Syntax
SysAdminLifeCycle::Location get_resource_location();

Exceptions
CORBA 1.2 standard exceptions.

ManagedInstances::BasicInstanceManager Interface

The ManagedInstances::BasicInstanceManager interface defines operations needed to group objects into sets for purposes of object management. An object supporting the ManagedInstances::BasicInstanceManager interface manages a group of objects of one type. Basic instance managers maintain references to all instances they manage, and are able to report the interface that is supported by instances they manage. Additionally, instance managers are able to create instances of the type of objects they support. Instances created and managed by a BasicInstanceManager must support the ManagedInstances::Instance 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:

Inherited Interfaces
The BasicInstanceManager interface inherits from the following interfaces:
Unique Behavior of Inherited Interfaces
Operations defined within these interfaces may have unique behavior when inherited by the BasicInstanceManager interface:
CosLifeCycle::LifeCycleObject
BasicInstanceManager inherits the remove operation. Conforming implementations of the BasicInstanceManager must disallow the invocation of the remove operation while instances are presently contained by the instance manager. Further, as with instances, an instance manager may only be removed from the library that contains it as a consequence of a client having invoked the remove operation upon the instance manager in order to destroy it.
CosLifeCycle::GenericFactory
BasicInstanceManager uses this interface to create objects of the type it manages.

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 instance to be created.  
T}  
" object implementation"
The name of the implementation to be used with the instance  
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 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.

Name Type Value Interpretation
" labelid"  
A symbolic name for the instance being created.    
The id field of the instance's label will be    
set to this value, and the kind field will be    
set to the concatenation of the Instance Manager's    
id and kind fields (separated by    
a vertical bar, " |" ). Note that the latter
indicates the name of the Library object that    
created the InstanceManager.    
T}    
" location"  
Object reference of an object that indicates the    
location where the new instance should be created.    
T}    

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
BasicInstanceManager inherits the add_object, add_n_objects, remove_object and remove_n_objects operations, among others, via its inheritance from ManagedSets::FilteredSet. Since instances are intended to spend their entire existence as members of the instance manager that created them, these four operations must be constrained to work only in the context of other operations that affect an instance's lifecycle. Specifically, the instance manager's inherited remove_object operation should only be invoked by an instance's inherited CosLifeCycle::LifeCycleObject::remove operation, and add_object, add_n_objects and remove_n_objects must be disabled.
The get_instances_interface Operation
The get_instances_interface operation returns an object reference to a description of the interface supported by instances supported by this basic instance manager.
Syntax
CORBA::InterfaceDef get_instances_interface();

Exceptions
CORBA 1.2 standard exceptions.

ManagedInstances::InstanceManager Interface

The ManagedInstances::InstanceManager interface provides all of the ManagedInstances::BasicInstanceManager capabilities, and in addition provides capabilities that support the specification of policy to be associated with managed instances. This is done through the inheritance of the Policies::PolicyObjectAdmin interface. Instances created and managed by an InstanceManager must support the PolicyRegions::PolicyDrivenBase 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
The InstanceManager interface inherits from the following interfaces:
Unique Behavior of Inherited Interfaces
Operations defined within these interfaces may have unique behavior when inherited by the InstanceManager interface.
CosLifeCycle::GenericFactory
InstanceManager objects have the same unique behaviors for this inherited interface as those described for BasicInstanceManager objects.

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

Name Type Value Interpretation
" policy regions"  
A list of object references of the PolicyRegion    
objects that the new PolicyDrivenBase object should be added to.    
At least one PolicyRegion must be in the list.    
T}    
" nested initialization"  
An indicator if initialization policy    
from nested policy regions should be    
used. TRUE indicates that it should,    
while FALSE indicates that it should not.    
T}    

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:

ManagedInstances::Library Interface

The ManagedInstances::Library interface acts as both a factory for the creation of instance managers and as a factory finder for locating instance managers. This includes all of the various instance manager types defined in this specification, namely:

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
The ManagedInstances::Library interface inherits from the following interfaces:

Unique Behavior of Inherited Interfaces
Operations defined within these interfaces may have unique behavior when inherited by the Library interface:
ManagedSets::FilteredSet
Library inherits the add_object, add_n_objects, remove_object and remove_n_objects operations, among others, via its inheritance from ManagedSets::FilteredSet. Since instance managers are intended to spend their entire existence as members of the library that created them, these four operations must be constrained to work only in the context of other operations that affect an instance manager's lifecycle. Specifically, remove_object may only be invoked by or as a consequence of an instance manager's inherited CosLifeCycle::LifeCycleObject::remove operation, and add_object, add_n_objects and remove_n_objects must be disabled.
CosLifeCycle::GenericFactory
The Library uses this interface to create objects that are instances of the BasicInstanceManager interface as well as objects that are sub-types of BasicInstanceManager (including InstanceManager, and PolicyRegionsInstanceManager).

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 instance manager to be created.  
T}  
" object implementation"
The name of the implementation to be used with the  
instance manager to be created.  
T}  

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:

Name Type Value Interpretation
" labelid"  
A symbolic name for the instance    
manager being created. This value    
will be stored as the id field    
of the instance manager's label. The    
kind field of the instance manager's    
label will be set to the id field    
of the library object upon which this    
operation was invoked. The id and    
kind fields of an instance manager's    
label are then concatenated, with a vertical    
bar (" |" ) between them as a delimiter, to form the
kind field of any instance that the    
instance manager creates.    
T}    
" default initialization"  
Object reference of the default    
initialization policy object    
associated with the instance    
manager being created.    
T}    
" initializations"  
Object references of additional    
initialization policy objects    
associated with the instance manager    
being created.    
T}    
" default validation"  
Object reference of the default    
validation policy object associated    
with the instance manager being created.    
T}    
" validations"  
Object references of additional    
validation policy objects associated    
with the instance manager being    
created.    
T}    
" location"  
Object reference indicating location    
of where the instance manager being    
created should reside.    
T}    
" type"  
The fully scoped name of the principal IDL    
interface of the type of instances    
this instance manager will create.    
T}    
" interface"  
The InterfaceDef associated with    
the type of instances this instance    
manager will create.    
T}    
" implementation"  
The ImplementationDef associated    
with the type of instances this    
instance manager will create.    
T}    

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
The find_factories operation is invoked on instances of the ManagedInstances::Library interface in order to obtain a list of instance managers that meet a set of selection constraints. These constraints are passed in the factory_key argument, and are composed as a sequence of CosNaming::NameComponent structures, each containing a kind field and an id field. The following table defines what can be passed in this argument:

kind field id field
" object interface"
Fully scoped interface name for the instances  
this instance manager creates  
T}  
" object implementation"
Name of the implementation for the instances this instance  
manager creates  
T}  
" initialization policy"
One of " with"
T}  
" validation policy"
One of " with"
T}  
" factory interface"
Fully scoped interface name for the instance manager  
T}  

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

The ManagedInstances::PolicyRegionsInstanceManager interface defines a specialized instance manager that is used to create and manage instances of the PolicyRegions::PolicyRegion interface. It enables a policy region to be initialized when it is created, setting it up similar to another policy region specified at object creation time.
Inherited Interfaces
The PolicyRegionsInstanceManager interface inherits from the ManagedInstances::InstanceManager interface.
Unique Behavior of Inherited Interfaces
Operations within the following interface have unique behavior when inherited by the PolicyRegionsInstanceManager interface:
CosLifeCycle::GenericFactory
The create_object operation is invoked on instances of ManagedInstances::PolicyRegionsInstanceManager in order to create new policy regions. This operation is the same as is defined for the ManagedInstances::InstanceManager interface, with the exception that the_criteria argument can also contain the following element:

Name Type Value Interpretation
" model policy region"  
Object reference to the PolicyRegion that the new PolicyRegion    
should initially be modeled after. This means that the new    
policy region will be initialized to support all of the same    
instance managers (using the    
same InitializationPolicy and ValidationPolicy objects)    
as the model policy region.    
T}    

PolicyRegions Module

The PolicyRegions module defines the PolicyRegion, and PolicyDrivenBase interfaces and their operations. These policy-related interfaces allow administrators to organize applications to reflect site-specific rules of system administration.

Interfaces and Operations


Module Interface Operation
PolicyRegions
PolicyRegion


Inheritance:
PolicyRegions::PolicyDrivenBase
ManagedSets::FilteredSet
CosLifeCycle::GenericFactory


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
 
PolicyDrivenBase


Inheritance:
ManagedInstances::Instance


get_policy_region_info
move_to_policy_region
add_to_policy_region
remove_from_policy_region
list_enabled_validation_policies
list_initialization_policies


Table: Interfaces and Operations for the PolicyRegions Module

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

The PolicyResultIterator interface defines the following operations that allow an object to iteratively request a list of PolicyResult structures that were generated by verifying policy upon members of the current PolicyRegion. The PolicyResultIterator provides a static view of the policy conformance of the target members of the PolicyRegion at the time the iterator was created, and does not reflect subsequent changes to either the objects' membership in the PolicyRegion or their conformance to the current policies of the PolicyRegion. The operations provided are:
The next_one Operation
The next_one operation returns the next PolicyResult structure. If the last PolicyResult structure is being returned on this call (or was returned on a previous call), this operation returns FALSE, indicating subsequent calls to the iterator are not needed.
Syntax
boolean next_one ( out PolicyResult pr; };
Exceptions
CORBA 1.2 standard exceptions.
The next_n Operation
The next_n operation returns at most the requested number of PolicyResult structures. If the last PolicyResult structure is being returned on this call (or was returned on a previous call), this operation returns FALSE, indicating subsequent calls to the iterator are not needed.
Syntax
boolean next_n( in unsigned long how_many, out PolicyResultList pr_list, };
Exceptions
CORBA 1.2 standard exceptions.
The destroy Operation
The destroy operation destroys the iterator.
Syntax
void destroy();
Exceptions
CORBA 1.2 standard exceptions.

PolicyRegions::PolicyDrivenBase

The PolicyDrivenBase interface defines the operations required for an object to be managed by a policy region. It serves as a base interface to be inherited by interfaces for objects that will be managed and subject to policy.

The PolicyRegions::PolicyDrivenBase interface defines the following operations:

Inherited Interfaces
The PolicyRegions::PolicyDrivenBase interface inherits from the ManagedInstances::Instance interface.

The get_policy_region_info Operation
The get_policy_region_info operation returns information about the policy regions that the target object is a member of. This includes both the object reference and the label for each of the policy regions.
Syntax
SysAdminTypes::ObjectLabelList get_policy_region_info();

Exceptions
CORBA 1.2 standard exceptions.
The move_to_policy_region Operation
The move_to_policy_region operation moves the target PolicyDrivenBase object from the PolicyRegion object specified in the pr_from argument to the PolicyRegion object specified in the pr_to argument. The InstanceManager that the target object belongs to must be in the list of instance managers supported by the pr_to policy region. The target object must also be a member of the pr_from policy region.
Syntax
void move_to_policy_region( in PolicyRegions::PolicyRegion pr_from, in PolicyRegions::PolicyRegion pr_to ) raises ( SysAdminException::ExObjNotFound, SysAdminException::ExNotFound, SysAdminException::ExInvalid );

Exceptions
CORBA 1.2 standard exceptions, SysAdminException::ExObjNotFound, SysAdminException::ExNotFound and SysAdminException::ExInvalid.

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
The add_to_policy_region operation adds the target PolicyDrivenBase object to the PolicyRegion set specified in the pr argument. The InstanceManager that the target object belongs to must be in the list of instance managers supported by the policy region.
Syntax
void add_to_policy_region( in PolicyRegions::PolicyRegion pr ) raises ( SysAdminException::ExNotFound, SysAdminException::ExInvalid );

Exceptions
CORBA 1.2 standard exceptions, SysAdminException::ExNotFound and SysAdminException::ExInvalid.

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
The remove_from_policy_region operation removes the target PolicyDrivenBase object from the PolicyRegion set specified in the pr argument. If the specified policy region is the only policy region that the target object belongs to, the target object will not be removed.
Syntax
void remove_from_policy_region( in PolicyRegions::PolicyRegion pr ) raises ( SysAdminException::ExObjNotFound, SysAdminException::ExInvalid );

Exceptions
CORBA 1.2 standard exceptions, SysAdminException::ExObjNotFound and SysAdminException::ExInvalid.

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 list_enabled_validation_policies operation returns a list of validation policies that the target policy driven base object is subject to. Only validation policies for which validation is enabled will be returned. The selection of the validation policies returned can be controlled through the arguments specified on the call to this 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:

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

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExNotFound.

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

The list_initialization_policies Operation
The list_initialization_policies operation returns a list of initialization policies that the target policy driven base object is subject to. The selection of the initialization policies returned can be controlled through the arguments specified on the call to this 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:

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

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExNotFound.

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 operations that provide the ability for system administration applications to group a set of managed resources and to define and uniformly apply the policies to the set of resources. In addition, operations that allow querying the policy region for the policy that applies to a particular instance manager are defined.

The PolicyRegions::PolicyRegion interface defines the following operations:

Inherited Interfaces
The PolicyRegion interface inherits from the following interfaces:
Unique Behavior of Inherited Interfaces
Operations defined within these interfaces may have unique behavior when inherited by the PolicyRegions::PolicyRegion interface:

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
The add_instance_manager operation adds a new supported instance manager to the target object. The target object must be a policy region object. This operation optionally assigns an initialization policy object and validation policy object to the region. The im argument specifies the object reference of the instance manager to be added to the policy region. The validation_policy argument specifies the object reference of the validation policy to be assigned to the policy region. If this parameter is set to the object reference for a validation policy object, policy validation is enabled in the policy region for the instance manager. If this parameter is set to OBJECT_NIL, no policy validation is assigned to the new instance manager and policy validation is not enabled for it. The initialization_policy argument specifies the object reference of the initialization policy object to be assigned to the policy region. If this parameter is set to OBJECT_NIL, no initialization policy is assigned to the new instance manager and no initialization policy is applied. The policy objects specified by the initialization_policy and validation_policy parameters must already have been registered with the instance manager specified by the im parameter4.
Syntax
void add_instance_manager( in ManagedInstances::InstanceManager im, in Policies::InitializationPolicy initialization_policy, in Policies::ValidationPolicy validation_policy )raises( SysAdminException::ExExists );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExExists.

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

The remove_instance_manager Operation
The remove_instance_manager operation removes the specified instance manager from the target object, which must support the PolicyRegions::PolicyRegion interface. There must be no members of the specified instance manager in the policy region for this operation to succeed. The im argument specifies the object reference of the instance manager object that manages the object type that is to be removed from the policy region.
Syntax
void remove_instance_manager( in ManagedInstances::InstanceManager im )raises( SysAdminException::ExObjNotFound, SysAdminException::ExExists );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExObjNotFound and SysAdminException::ExExists.

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
The get_instance_manager_list operation lists the instance manager supported by the target object, which must support the PolicyRegions::PolicyRegion interface. This operation lists the instance manager's object references and labels. The select argument specifies which of the instance managers supported by the target policy region will be returned in the list. The values for this argument have the following meaning:

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
CORBA 1.2 standard exceptions.
The set_initialization_policy Operation
The set_initialization_policy operation assigns the specified initialization policy object to the specified instance manager, replacing any previous assignment. This assignment is in effect only in the policy region represented by the target object. The initialization policy supplies the new instance manager members with initial attribute values. The policy region must already support the specified instance manager. Use the add_instance_manager operation to add a new supported instance manager to a policy region. The im argument is the object reference of the instance manager that defines the instance manager to which the initialization policy is to be assigned in the target policy region. The initialization_policy argument is the object reference of the initialization policy object whose methods return the proper default values. If this parameter is set to OBJECT_NIL, no initialization policy is assigned to the instance manager and the default initialization policy, if set, is applied.
Syntax
void set_initialization_policy( in Instances::InstanceManager im, in Policies::InitializationPolicy initialization_policy )raises( SysAdminException::ExObjNotFound );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExObjNotFound.

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
The get_initialization_policy operation returns the object reference of the initialization policy object assigned to the specified instance manager. The instance manager may have other initialization policy objects for other policy regions. The im argument is the object reference of the instance manager for the initialization policy object to be returned.
Syntax
SysAdminTypes::ObjectLabel get_initialization_policy ( in ManagedInstances::InstanceManager im )raises( SysAdminException::ExObjNotFound );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExObjNotFound.

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

The set_validation_policy Operation
The set_validation_policy operation assigns and enables the specified validation policy object to the specified instance manager, replacing any previous validation policy assignment. This assignment is in effect only in the policy region represented by the target object. The validation policy object supplies methods that validate changes to attributes defined by the instance manager. The im argument specifies the object reference of the instance manger to which the validation policy is to be assigned in the target policy region. If the policy_validation parameter is set to OBJECT_NIL, no validation policy is assigned to the instance manager and the default validation policy, if set, is used if enabled for it.
Syntax
void set_validation_policy ( in ManagedInstances::InstanceManager im, in Policies::ValidationPolicy validation_policy )raises( SysAdminException::ExObjNotFound );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExObjNotFound.

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

The get_validation_policy Operation
The get_validation_policy returns the object reference of the validation policy object assigned to the specified instance manager. The instance manager may have other policy validation objects in other policy regions. The im argument is the object reference of the instance manager whose validation policy object reference is to be returned.
Syntax
SysAdminTypes::ObjectLabel get_validation_policy ( in ManagedInstances::InstanceManager im )raises( SysAdminException::ExObjNotFound );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExObjNotFound.

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
The policy_validation operation enables or disables validation policy for the specified instance manager. This setting applies only to the specified instance manager in the target policy region. The instance manager can have validation policy independently enabled or disabled in other policy regions. The im argument is the object reference of the instance manager whose validation policy state is to be set. The enable argument is set to TRUE if policy validation is to be enabled for the specified instance manager. This argument is set to FALSE if validation policy is to be disabled.
Syntax
void policy_validation( in ManagedInstances::InstanceManager im, in boolean enable )raises( SysAdminException::ExObjNotFound );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExObjNotFound.

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
The is_validation_enabled operation returns TRUE or FALSE, depending on whether validation policy is enabled for the instance manager defined by the im argument. If there is no validation policy object for the instance manager, the method returns FALSE.
Syntax
boolean is_validation_enabled( in ManagedInstances::InstanceManager im ) raises( SysAdminException::ExObjNotFound );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExObjNotFound.

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

The verify_policy Operation
The verify_policy operation is used to verify if objects within the target policy region adhere to the policy for the region. This operation provides positive feedback, with information being returned about every object that was checked, irrespective of whether it passed or failed validation. The returned PolicyResultList contains a PolicyResult structure for every object that was checked, and the passed_policy boolean in that structure can be used to see if the object passed or failed validation. It is the validate_policy_driven_object operation defined on the Policies::ValidationPolicy object that is used to perform the verification.

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:

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
CORBA 1.2 standard exceptions.
The get_policy_failures Operation
The get_policy_failures operation is used to verify if objects within the target policy region adhere to the policy for the region. This operation provides feedback only for objects that failed validation. The returned PolicyResultList contains a PolicyResult structure for every object that failed validation. It is the validate_policy_driven_object operation defined on the Policies::ValidationPolicy object that is used to perform the verification.

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:

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
CORBA 1.2 standard exceptions.
The get_all_initialization_policies Operation
The get_all_initialization_policies operation returns a list of initialization policy objects, within the target policy region and all of it's containing policy regions, that are assigned to the instance manager specified in the im argument. The initialization policies returned will be ordered in the same order as the nesting of policy regions, with the topmost containing policy region's initialization policy occurring first in the sequence and the target policy region's initialization policy occurring last in the sequence5.
Syntax
SysAdminTypes::ObjectLabelList get_all_initialization_policies( in ManagedInstances::InstanceManager im ) raises ( SysAdminException::ExNotFound );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExNotFound.

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

The get_all_enabled_validation_policies Operation
The get_all_enabled_validation_policies operation returns a list of validation policy objects, within the target policy region and all of it's containing policy regions, that are assigned to the instance manager specified in the im argument. Only those validation policy objects for which validation is enabled are returned. The validation policies returned will be ordered in the same order as the nesting of policy regions, with the topmost containing policy region's validation policy occurring first in the sequence and the target policy region's validation policy occurring last in the sequence6.
Syntax
SysAdminTypes::ObjectLabelList get_all_enabled_validation_policies( in ManagedInstances::InstanceManager im ) raises ( SysAdminException::ExNotFound );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExNotFound.

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

Policies Module

The Policies module defines the interfaces related to policy objects. These interfaces support interaction between policy objects and objects supporting the PolicyRegion or the InstanceManager interface.

Interfaces and Operations


Module Interface Operation
Policies
PolicyObject


Inheritance:
Identification::Labeled

get_policy_driven_object_type
  PolicyObjectAdmin
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
add_pr_backref
remove_pr_backref
get_pr_backrefs
  InitializationPolicy

Inheritance: Policies::PolicyObject

initialize_policy_driven_object
  ValidationPolicy

Inheritance: Policies::PolicyObject

validate_policy_driven_object


Table: Interfaces and Operations for the Policies Module

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 operations that all instance managers that have policy associated with them must support. These operations allow the reporting of the policy objects associated with the establishment and enforcement of policy, along with the administration of these policy objects.

The Policies::PolicyObjectAdmin interface defines the following operations:

The get_initialization_policies Operation
The get_initialization_policies operation returns the object references and labels of the initialization policy objects associated with the instance manager.
Syntax
SysAdminTypes::ObjectLabelList get_initialization_policies();

Exceptions
CORBA 1.2 standard exceptions.
The get_default_initialization Operation
The get_default_initialization operation returns the default initialization policy object for the instance manager. If no initialization policy has been explicitly set for the target instance manager in the current policy region, then the default initialization policy will be used to initialize new policy-driven objects during object creation.
Syntax
InitializationPolicy get_default_initialization( )raises( SysAdminException::ExNotFound );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExNotFound.

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

The get_validation_policies Operation
The get_validation_policies operation returns the object references and labels of any validation policy objects associated with the instance manager.
Syntax
SysAdminTypes::ObjectLabelList get_validation_policies();

Exceptions
CORBA 1.2 standard exceptions.
The get_default_validation Operation
The get_default_validation operation returns the default validation policy object for the instance manager. If no validation policy has been explicitly set for the target instance manager in the current policy region, then the default validation policy will be used to validate policy-driven objects if policy validation is enabled for the instance manager in the policy region of interest.
Syntax
ValidationPolicy get_default_validation( )raises( SysAdminException::ExNotFound );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExNotFound.

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

The add_initialization Operation
The add_initialization operation adds a reference to a new initialization policy object for the instance manager. Object::_nil() is not permitted as an input value.
Syntax
void add_initialization( in InitializationPolicy initialization_policy )raises( SysAdminException::ExExists, SysAdminException::ExInvalid );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExExists.

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
The set_default_initialization operation sets the default initialization policy object for the instance manager. If the input initialization policy object is not associated with the instance manager, then the initialization policy object will be added to the instance manager automatically before set_initialization_policy returns control to the caller. If the value of the input initialization_policyis Object::_nil(), then the default initialization policy is set to Object::_nil() and there is effectively no default initialization policy for the instance manager.
Syntax
void set_default_initialization( in InitializationPolicy initialization_policy )raises( SysAdminException::ExInvalid );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExInvalid.

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
The remove_initialization operation removes the reference to the specified initialization policy object from the instance manager. Object::_nil() is not permitted as an input value.

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
CORBA 1.2 standard exceptions and SysAdminException::ExObjNotFound.

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

The add_validation Operation
The add_validation operation adds a reference to a new validation policy object for the instance manager. Object::_nil() is not permitted as an input value.
Syntax
void add_validation( in ValidationPolicy validation_policy )raises( SysAdminException::ExExists, SysAdminException::ExInvalid );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExExists.

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
The remove_validation operation removes a reference to a validation policy object from the instance manager. Object::_nil() is not permitted as an input value.

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
CORBA 1.2 standard exceptions and SysAdminException::ExObjNotFound.

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

The set_default_validation Operation
The set_default_validation operation sets the default validation policy object for the instance manager. If the input validation policy object parameter is not associated with the instance manager, then the validation policy object will be added to the instance manager automatically before set_default_validation returns control to the caller. If the value of the input initialization_policy is Object::_nil(), then the default initialization policy is set to Object::_nil() and there is effectively no default initialization policy for the instance manager.
Syntax
void set_default_validation( in ValidationPolicy validation_policy )raises( SysAdminException::ExInvalid );

Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExInvalid.

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
The add_pr_backref operation adds a reference from the target object to a policy region. The purpose of this operation is to allow instance managers to maintain references to the policy regions that support them. The intended usage is that this operation should only be invoked within the implementation of the policy region's add_instance_manager operation, and not by an arbitrary client.
Syntax
void add_pr_backref ( in PolicyRegion pr );
Exceptions
CORBA 1.2 standard exceptions
The remove_pr_backref Operation
The remove_pr_backref operation removes a reference from the target object to a policy region. The intended usage is that this operation should only be invoked within the implementation of the policy region's remove_instance_manager operation, and not by an arbitrary client.
Syntax
void remove_pr_backref ( in PolicyRegion pr ) raises ( SysAdminException::ExNotFound );
Exceptions
CORBA 1.2 standard exceptions and SysAdminException::ExNotFound.

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
The get_pr_backrefs operation returns as an output parameter a list of references to the policy regions by which the target object is currently supported. It accepts an input parameter, how_many, that designates the maximum desired number of such references to return in the list. The list of returned references is contained in the first output parameter. If the number of policy regions that the target object is currently supported by is great than how_many, a Set iterator object is created as a bi-product of this operation and contained in the second output parameter. This iterator can be used to iterate through the additional supporting policy regions not returned in the first output parameter, using SetIterator operations as previously described in this specification.
Syntax
void get_pr_backrefs ( in unsigned long how_many, out SetList s_list, out SetIterator iterator );
Exceptions
CORBA 1.2 standard exceptions.

Policies::PolicyObject Interface

The Policies::PolicyObject interface defines operations that all policy objects support. It serves as a base interface definition from which all other policy interfaces are derived.

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

Inherited Interfaces
The Policies::PolicyObject interface inherits from the Identification::Labeled interface to ensure that all policy objects have a label.
The get_policy_driven_object_type Operation
The get_policy_driven_object_type operation returns the type name that describes an interface supported by the policy driven objects that this policy object can be associated with. Note that the type does not have to be the principal interface of the policy driven object, only a supported interface.
Syntax
string get_policy_driven_object_type();
Exceptions
CORBA 1.2 standard exceptions.
The get_policy_driven_object_interface() Operation
The get_policy_driven_object_interface() operation returns the CORBA::InterfaceDef that describes an interface supported by the policy-driven objects with which this policy object can be associated. Note that this type does not have to be the principal interface of the policy-driven object, only a supported interface.
Syntax
CORBA::InterfaceDef get_policy_driven_object_interface();
Exceptions
CORBA 1.2 standard exceptions.

Policies::InitializationPolicy Interface

The Policies::InitializationPolicy interface defines a single operation, initialize_policy_driven_object.
The initialize_policy_driven_object Operation
The initialize_policy_driven_object initializes a single policy-driven object. This operation is intended to be called during the processing of the create_object operation by an instance manager, rather than being called directly by a client. In addition to accepting the object to be initialized as an input, initialize_policy_driven_object also accepts a sequence of name/value pairs or criteria. The criteria can be used to override the default values that will be used to initialize the object at creation time. This allows instance specific initialization data to be combined with the policy region specific data (as embodied in the InitializationPolicy object) to define the initial object values.

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
CORBA 1.2 standard exceptions.

Policies::ValidationPolicy Interface

The Policies::ValidationPolicy interface defines a single operation, validate_policy_driven_object.
The validate_policy_driven_object Operation
The validate_policy_driven_object validates a single policy-driven object. This operation is intended to be called by the verify_policy or get_policy_failures operations on a policy region or it can also be called directly by client code. It is expected that for every specialization of the PolicyDrivenBase type, there will be an implementation of this operation that specifically knows how to validate objects of that type. If the object conforms to the policy embodied by this ValidationPolicy object, the operation returns TRUE, otherwise it returns FALSE. When the return value is FALSE, the description out parameter contains a string indicating the reason the object did not conform to policy.
Syntax
boolean validate_policy_driven_object( in Object object_to_validate, out string description );

Exceptions
CORBA 1.2 standard 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.


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

Contents Next section Index