Copyright © 1997 The Open Group

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

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.

Click here to return to the publication details or order a copy of this publication.

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

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

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.

This operation creates a topological type with a topological type name as specified by the value of thetype_nameparameter and the parent topological types as specified by the value of theparent_typesparameter.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_typeparameter value already exists, and has the same parent topological types as those specified by theparent_typesparameter 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.

- [Toplogy::InvalidTypeName]

Returned if any of the given type names in thetype_nameandparent_typesparameter values are not valid topological type names.

- [Toplogy::NoSuchType]

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

- [ToplogyMetaData::TypeRedefinition]

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

- [Topology::ServerNotContactable]

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

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

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

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.

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_nameparameter value does not exist, no error is returned. In this case, the operation returns FALSE, else it returns a TRUE.

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

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

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

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.

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

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

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

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

Input

There are no input parameters for this operation.

Output/Return

A list of topological type names.

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

- [Topology::ServerNotContactable]

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

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

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

Input

type_name

The name of the topological type to be checked.

Output/Return

A list of names of the parent topological types.

This operation gets the names of the parents for the specified topological type,type_nameparameter 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.

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

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

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

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.

This operation is used to define the initial association rules for the topological type specified by thetype_nameparameter 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

AssocationRuleallows 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].

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

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

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

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.

This operation defines the enforcers for the topological type specified by thetype_nameparameter 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

validateoperation of the enforcer, passing it the entity which is involved in the change.Validatethen checks whatever it deems necessary and returns aVoteas 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.

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

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

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

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.

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

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

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

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

Input

type_name

The name of the topological type.

Output/Return

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

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.

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

**
**

#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 |