Topology Service - Managing Topological Types

Systems Management: Topology Service

Systems Management: Topology Service
Copyright © 1997 The Open Group

Managing Topological Types

This chapter describes how to manage a collection of Topological Types.

All interfaces are expressed in CORBA IDL. They are grouped under TopologyMetaData.idl.

TopologicalTypeManager

This interface provides access to the data that the Topology Service maintains about topological types. These topological types are never accessed directly by users of the Topology Service. Instead a TopologicalTypeManager acts as a proxy proxy to implement the operations that are conceptually performed on the individual topological types themselves.

The topological type on which the operation is to be performed is identified by its topological type name. By convention, this name is passed as a first parameter to the proxy operation on the TopologicalTypeManager.

Although a topological type is not an entity, this interface provides an operation that returns an entity identifier for a given topological type name. This allows the optional use of an event service to generate notifications whose source is a topological type. Topology Service - Create

Previous section.

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

NAME - DESCRIPTION

Create - This operation is used to create a new topological type.

SIGNATURE

boolean create (
		in Topology::TopologicalTypeName type_name,
		in Topology::TopologicalTypeNameList  parent_types);
	raises (Toplogy::InvalidTypeName,
		Toplogy::NoSuchType,
		ToplogyMetaData::TypeRedefinition,
		Topology::TransactionWillRollback,
		Topology::ServerNotContactable);

PARAMETERS

Input

type_name

The name of the topological type to be created.

parent_types

The name of the parent topological types.

Output/Return

A boolean which indicates whether or not a topological type was actually created as a result of this operation.

SEMANTICS

This operation creates a topological type with a topological type name as specified by the value of the type_name parameter and the parent topological types as specified by the value of the parent_types parameter.
Topological types should be identified by the interface type of the corresponding entity interface type of the entities that will be managed by Topology (in the IDL form module::interface).
If the topological type specified by the topo_type parameter value already exists, and has the same parent topological types as those specified by the parent_types parameter value, then no error is returned. In this case the operation returns a FALSE to indicate that the Topology metadata store was not altered, else it returns a TRUE.

EXCEPTIONS RAISED

[Toplogy::InvalidTypeName]

Returned if any of the given type names in the type_name and parent_types parameter values are not valid topological type names.

[Toplogy::NoSuchType]

Returned if the topological type names specified by the parent_types parameter value are not existing topological types.

[ToplogyMetaData::TypeRedefinition]

Returned if passed the name of an existing topological type as the value of the type_name parameter and which has different parents from those specified in the parent_types parameter value.

[Topology::ServerNotContactable]

Returned if the topology server required to complete this operation is not contactable.

Topology Service - Dismiss Previous section.

NAME - DESCRIPTION

Dismiss - This operation is used to notify the Topology Service that an application no longer wishes to support a topological type.

SIGNATURE

boolean dismiss (
		in Topology::TopologicalTypeName type_name)
	raises (Topology::InvalidTypeName,
		Topology::TransactionWillRollback,
		Topology::ServerNotContactable);

PARAMETERS

Input

type_name

The name of the topological type to be deleted.

Output/Return

A boolean which indicates whether or not the topological type was actually removed.

SEMANTICS

This operation notifies the Topology Service that a client is no longer interested in a topological type. The Topology Service will remove the topological type provided:

there are no entities that are managed as instances of the topological type

the topological type is not a parent of any other topological types.

If the topological type specified by the type_name parameter value does not exist, no error is returned. In this case, the operation returns FALSE, else it returns a TRUE.

EXCEPTIONS RAISED

[Toplogy::InvalidTypeName]

Returned if the given type name is not a valid topological type name.

[Toplogy::TypeInUse]

Returned if the given type has instances or other types which inherit from it.

[Topology::ServerNotContactable]

Returned if the topology server required to complete this operation is not contactable.

Topology Service - Exists Previous section.

NAME - DESCRIPTION

Exists - This operation is used to check whether a topological type exists.

SIGNATURE

boolean exists (
		in Topology::TopologicalTypeName type_name)
	raises (Topology::InvalidTypeName,
		Topology::ServerNotContactable);

PARAMETERS

Input

type_name

The name of the topological type to be checked.

Output/Return

A boolean which indicates whether or not a topological type with this name exists.

SEMANTICS

This operation returns a TRUE if a topological type exists with the same name specified by the type_name parameter value, otherwise it returns FALSE.

EXCEPTIONS RAISED

[Toplogy::InvalidTypeName]

Returned if any of the given type name is not a valid topological type name.

[Topology::ServerNotContactable]

Returned if the topology server required to complete this operation is not contactable.

Topology Service - Get_All_Types Previous section.

NAME - DESCRIPTION

Get_All_Types - This operation is used to get all of the topological types which exist in the installation.

SIGNATURE

Topology::TopologicalTypeNameList 
get_all_types()
	raises (Topology::ServerNotContactable);

PARAMETERS

Input

There are no input parameters for this operation.

Output/Return

A list of topological type names.

SEMANTICS

This operation gets a list of all topological types which exist in the installation.

EXCEPTIONS RAISED

[Topology::ServerNotContactable]

Returned if the topology server required to complete this operation is not contactable.

Topology Service - Get_Parents Previous section.

NAME - DESCRIPTION

Get_Parents - This operation is used to get the names of the parents of a topological type.

SIGNATURE

Topology::TopologicalTypeNameList 
get_parents (
		in Topology::TopologicalTypeName type_name)
	raises (Topology::InvalidTypeName,
		Topology::NoSuchType,
		Topology::ServerNotContactable);

PARAMETERS

Input

type_name

The name of the topological type to be checked.

Output/Return

A list of names of the parent topological types.

SEMANTICS

This operation gets the names of the parents for the specified topological type, type_name parameter value. By parents, it is meant just the immediate parents of the topological type rather than all of the topological types from which it inherits.

EXCEPTIONS RAISED

[Toplogy::InvalidTypeName]

Returned if the given type name is not a valid topological type name.

[Topology::NoSuchType]

Returned if the given topological type name does not exist.

[Topology::ServerNotContactable]

Returned if the topology server required to complete this operation is not contactable.

Topology Service - Define_Rules Previous section.

NAME - DESCRIPTION

Define_Rules - This operation is used to define or redefine the association rules for a topological type.

SIGNATURE

void define_rules (
		in Topology::TopologicalTypeName type_name,
		in AssociationRuleList rules)
	raises (TopologyMetaData::InvalidTypeModification,	
		Topology::SchemaViolation,
		Topology::TransactionWillRollback,
		Topology::ServerNotContactable);

PARAMETERS

Input

type_name

The topological type whose rules are to be defined.

rules

The association rules for the given topological type.

Output/Return

There are no output or return parameters for this operation.

SEMANTICS

This operation is used to define the initial association rules for the topological type specified by the type_name parameter value, or if association rules already exist for the topological type, this operation replaces them with the newly defined rules.
For each association rule in the input list the structure AssocationRule allows you to specify:

the role of the topological type

the name of the topological type with which instances of this topological type can be associated

the minimum number of associations allowed with an instance of the associated topological type

the maximum number of associations allowed with an instance of the associated topological type.

A type is considered "in use" if there are in existence instances of that type, or if another type inherits from it:

rules can be added to a type

a rule which is defined in a parent type can never be changed/redefined

if the type is "in use" then rules cannot be removed or modified.

If this operation is invoked within a transaction and the Topological Type is "in use" and the effect would be to remove or modify existing rules, this operation raises no exception. However, at the end of the transaction, the Topology Data Service:

rolls back the transaction

writes the message associated within the exception

[TopologyMetaData::InvalidTypeModification]

to the error log.

If this operation is invoked outside of a transaction, the Topology Data Service itself starts a transaction, performs the operation, and closes the transaction. In this case, if the Topological Type is "in use" and the effect of this operation would be to remove or modify existing rules, this operation fails and raises the exception [TopologyMetaData::InvalidTypeModification].

EXCEPTIONS RAISED

[TopologyMetaData::InvalidTypeModification]

Returned if the effect of this operation would be to remove or modify existing rules.

[Topology::InvalidTypeName]

Returned if the type specified is not a valid topological type name.

[Topology::NoSuchType]

Returned if there is no type defined in the Topology store that matches the given type name.

[Topology::SchemaViolation]

Returned if there is a conflict between the Topology Schema definition and the persistent storage of the topology data, known as Topology data store.

[Topology::ServerNotContacted]

Returned if the topology server required to complete this operation is not contactable.

Topology Service - Define_Enforcers Previous section.

NAME - DESCRIPTION

Define_Enforcers - This operation is used to define or redefine the enforcers for a topological type.

SIGNATURE

void define_enforcers (
		in Topology::TopologicalTypeName type_name,
		in EnforcerRegistrationList enforcers)
	raises (TopologyMetaData::InvalidRegisteredObject,
		Topology::InvalidTypeName,
		Topology::NoSuchType,
		Topology::SchemaViolation,
		Topology::TransactionWillRollback,
		Topology::ServerNotContactable);

PARAMETERS

Input

type_name

The topological type whose enforcers are to be defined.

enforcers

The list of enforcers for the given topological type.

Output/Return

There are no output or return parameters for this operation.

SEMANTICS

This operation defines the enforcers for the topological type specified by the type_name parameter value, or if enforcers already exist for the topological type, this replaces them with the newly defined enforcers.
A type is considered "in use" if there are instances of that type, or if another type inherits from it. If the type is "in use" then rules cannot be added, removed or modified.
There is no return for this operation.
An enforcer is informed by the Topology Service whenever an entity of its associated type is affected in a way that satisfies one or more of its associated invocation conditions. The enforcer is given a veto over the change that produced the effect.
A Topology enforcer must be an object that supports the TopologyEnforcer interface. During the prepare to commit phase of a transaction, Topology will invoke the validate operation of the enforcer, passing it the entity which is involved in the change. Validate then checks whatever it deems necessary and returns a Vote as to whether the transaction should proceed or not.
There are two types of enforcers defined.

A COMMON_ENFORCER is one in which a single object is registered as an enforcer. Thus, all Topology servers will be using this single object to validate modifications involving the specified topological type. This introduces a single point of failure if this object is unreachable.

A NAMED_ENFORCER is one in which Topology is given the name of an object that it can locate in a naming service and will then narrow to the TopologyEnforcer interface. This provides for the use of a Unified Service (where multiple objects are providing the same functionality) or if there is only a single object it can, if necessary, easily be moved to a different host and reregistered with the naming service.

EXCEPTIONS RAISED

[TopologyMetaData::InvalidRegisteredObject]

Returned if an object specified as an enforcer cannot be narrowed to the TopoloygEnforcer interface.

[Topology::InvalidTypeName]

Returned if the type specified is not a valid topological type name..

[Topology::NoSuchType]

Returned if there is no type defined in the Topology store that matches the given type name.

[Topology::SchemaViolation]

Returned if there is a conflict between the Topology Schema definition and the persistent storage of the topology data, known as Topology data store.

[Topology::ServerNotContacted]

Returned if the topology server required to complete this operation is not contactable.

Topology Service - Get_Association_Rules Previous section.

NAME - DESCRIPTION

Get_Association_Rules - This operation is used to get a list of association rules for a topological type.

SIGNATURE

AssociationRuleList 
get_association_rules (
		in Topology::TopologicalTypeName type_name)
	raises (Topology::InvalidTypeName,
		Topology::NoSuchType,
		Topology::ServerNotContactable);

PARAMETERS

Input

type_name

The name of the topological type whose rules are required.

Output/Return

Returns a list of the topology rules for the topological type.

SEMANTICS

The operation returns a list of association rules that represent all of the association rules defined for the topological type as specified in the type_name parameter value. The association rules that only apply to the topological type by inheritance are not returned.

EXCEPTIONS RAISED

[Toplogy::InvalidTypeName]

Returned if the given type name is not a valid topological type name.

[Topology::NoSuchType]

Returned if the given topological type name does not exist.

[Topology::ServerNotContactable]

Returned if the topology server required to complete this operation is not contactable.

Topology Service - Get_Enforcers Previous section.

NAME - DESCRIPTION

Get_Enforcers - This operation is used to get a list of enforcers for a topological type.

SIGNATURE

EnforcerRegistrationList 
get_enforcers (
		in Topology::TopologicalTypeName type_name)
	raises (Topology::InvalidTypeName,
		Topology::NoSuchType,
		Topology::ServerNotContactable);

PARAMETERS

Input

type_name

The name of the topological type.

Output/Return

Returns a list of the enforcers for the topological type specified.

SEMANTICS

This operation returns a list of enforcers that represents all of the enforcers defined for the topological type specified by the type_name parameter value. The enforcers that only apply to the topological type by inheritance are not returned.

EXCEPTIONS RAISED

[Toplogy::Toplogy::InvalidTypeName]

Returned if the given type name is not a valid topological type name.

[Topology::NoSuchType]

Returned if the given topological type name does not exist.

[Topology::ServerNotContactable]

Returned if the topology server required to complete this operation is not contactable.

TopologyMetaData.idl File

#if !defined (TOPOLOGYMETADATA_IDL)
#define TOPOLOGYMETADATA_IDL

#include <TopologyData.idl>
#include <ErrorService.idl>

module TopologyMetaData {
	interface TopologyEnforcer;

	enum Invoke Condition {
		ENTITY_ASSOCIATED,
		ENTITY_DISASSOCIATED,
		ENTITY_STATE_CHANGED,
		AGGREGATE_ENTITY_ASSOCIATED,
		AGGREGATE_ENTITY_DISASSOCIATED,
		AGGREGATE_ENTITY_STATE_CHANGED,
		ASSOCIATED_ENTITY_ASSOCIATED,
		ASSOCIATED_ENTITY_DISASSOCIATED,
		ASSOCIATED_ENTITY_STATE_CHANGED,
		ENTITY_MANAGED,
		ENTITY_UNMANAGED,
		ALL
	};

	typedef sequence<InvokeCondition> InvokeConditionList;

	enum EnforcerType {COMMON_ENFORCER, NAMED_ENFORCER};

	typedef string EnforcerName;
	struct EnforcerRegistration {
		InvokeConditionList invoke_conditions;
		union EnforcerObjectReference switch(EnforcerType) {
			case NAMED_ENFORCER:
				EnforcerName enforcer_name;
			case COMMON_ENFORCER:
			default:
				TopologyEnforcer enforcer_ek;
		}enforcer;
	};

	typedef sequence <EnforcerRegistration> EnforcerRegistrationList;

	const unsigned long NO_LIMIT = ~0;

	struct AssociationRule {
		string role;
		long min_cardinality;
		long max_cardinality;
		Topology::TopologicalTypeName associate_type;
	};

	typedef sequence<AssociationRule> AssociationRuleList;
	exception TypeRedefinition{};
	exception InvalidCardinality{};
	exception TypeInUse{};
	exception InvalidRole{};
	exception NoSuchEnforcerImplementation{};

	interface TopologicalTypeManager: CosTransactions::TransactionalObject {

		// Life-cycle operations

		boolean create (
				in Topology::TopologicalTypeName type_name, 
				in Topology::TopologicalTypeNameList parent_types) 
			raises (Toplogy::InvalidTypeName,
				Toplogy::NoSuchType,
				ToplogyMetaData::TypeRedefinition,
				Topology::TransactionWillRollback,
				Topology::ServerNotContactable);
				
		boolean dismiss (
				in Topology::TopologicalTypeName type_name) 
			raises (Topology::InvalidTypeName,
				Topology::TransactionWillRollback,
				Topology::ServerNotContactable);

		// Query operations

		boolean exists (
				in Topology::TopologicalTypeName type_name) 
			raises (Topology::InvalidTypeName,
				Topology::ServerNotContactable);

		Topology::TopologicalTypeNameList   
		get_all_types() 
			raises (Topology::ServerNotContactable);

		Topology::TopologicalTypeNameList  
		get_parents (
				in Topology::TopologicalTypeName type_name) 
			raises (Topology::InvalidTypeName,
				Topology::NoSuchType,
				Topology::ServerNotContactable);

		AssociationRuleList   
		get_association_rules (
				in Topology::TopologicalTypeName type_name)
			raises (Topology::InvalidTypeName,
				Topology::NoSuchType,
				Topology::ServerNotContactable);

		EnforcerRegistrationList  
		get_enforcers (
				in Topology::TopologicalTypeName type_name) 
			raises (Topology::InvalidTypeName,
				Topology::NoSuchType,
				Topology::ServerNotContactable);

		// Set operations

		void define_rules ( 
				in Topology::TopologicalTypeName type_name, 
				in AssociationRuleList rules) 
			raises (TopologyMetaData::InvalidTypeModification,	
				Topology::SchemaViolation,
				Topology::TransactionWillRollback,
				Topology::ServerNotContactable);

		void define_enforcers ( 
				in Topology::TopologicalTypeName type_name, 
				in EnforcerRegistrationList enforcers) 
			raises (TopologyMetaData::InvalidRegisteredObject,
				Topology::InvalidTypeName,
				Topology::NoSuchType,
				Topology::SchemaViolation,
				Topology::TransactionWillRollback,
				Topology::ServerNotContactable);
	};

	interface TopologyEnforcer : CosTransactions::TransactionalObject {

		// Operations
		CosTransactions::Vote   
		validate ( 
			in Topology::TopologicalEntity affected_entity);
	};
};
#endif   // TOPOLOGYMETADATA_IDL

Contents

Next section

Index