All interfaces are expressed in CORBA IDL. They are grouped under TopologyData.idl.
This interface provides access to the data that the Topology Service maintains about topologically managed entities.
An EntityManager is a collection manager whose components are the
The entity (or entities) on
When first announcing the entity to the Topology Service (via
the
manage
operation) the entity is indicated by a
Many of the operations are designed such that it is not an error to do the same operation on the same entity (or entities) that has previously been done. In these cases the operation returns a boolean value which will indicate whether the data was actually changed (TRUE) or not (FALSE).
The purpose of this section is to describe the interfaces associated with managing entities with the Topology Service. Once an entity is managed by the Topology Service, numerous tasks can be performed, such as creating associations between the entity and other entities, and managing the entity as part of an aggregate entity.
If the entity to be managed does not exist (where no underlying implementation exists), it is necessary to create an empty entity - see the reference manual page for CreateEmptyEntity.
Manage - This operation is used to manage an existing entity and treat it as a topological entity.
boolean manage ( in TopologicalEntity entity, in Topology::TopologicalTypeName topo_type) raises (TypeChanged, Topology::SchemaViolation, Topology::InvalidTypeName, Topology::NoSuchType, Topology::TransactionWillRollback, Topology::ServerNotContactable);
- Input
- entity
The given entity to be managed.
- topo_type
The topological type for the new entity, typically, same as the entity name.
- Return
A boolean which indicates whether or not this operation modified the topology data.
This operation creates a new topological entity of the specified topological type topo_type. The topological type name must conform to the Federated Name syntax (see reference XFN).If the entity specified by the entity parameter value is already topologically managed, and it is of the same topological type as the one specified by the topo_type parameter value, no exception is raised. In this case the operation returns FALSE to indicate that the Topology data store was not altered.
Topology saves the object reference portion of the TopologicalEntity but does not examine it or use it. This object reference may be nil.
- [TypeChanged]
Raised if this operation attempts to change the type of an entity which is already managed in Topology.
- [Topology::InvalidTypeName]
Raised if the given type name does not conform to the X/Open Federated Name syntax.
- [Topology::SchemaViolation]
Raised if this operation is not part of a transaction and the type specified for the entity being managed requires that the entity be part of an association.
- [Topology::NoSuchType]
Returned if the specified topological_type does not exist.
- [Topology::TransactionWillRollback]
Raised if the operation is being performed within a transaction and inconsistencies are discovered in the current data. Topology will not let the transation successfully commit.
- [Topology::ServerNotContactable]
Returned if the topology server required to complete this operation is not contactable.
Unmanage - This operation is used when you want to have Topology stop managing the topological data for an entity.
boolean unmanage ( in Topology::PartitionedIdentifier entity) raises (Topology::SchemaViolation, Topology::ServerNotContactable, Topology::TransactionWillRollback);
- Input
- entity
The given entity for which management of its topology data is to stop.
- Return
A boolean which indicates whether or not this operation modified the topology data.
This operation is used to inform Topology to stop managing the topological data for a given entity. This operation deletes the topological data associated with the entity.If the given entity, entity has not been managed created via the operation manage, then no exception will be raised. In this case, the operation does not modify the data and returns a FALSE to indicate that the topology database was not modified.
If the given entity was constrained to be part of the same aggregate as another entity, the Topology Service will undo (untie) this constraint.
- [Topology::NotManaged]
Raised if the entity specified is not managed by Topology.
- [Topology::SchemaViolation]
Raised if this operation is not part of a transaction and the operation results in a conflict between the Topology Schema definition and the new state of the topology data. This occurs if the Topology Type rules require that an entity be part of an association, but the operation unmanaged an entity which was participating in one such association (thereby removing the association).
- [Topology::TransactionWillRollback]
Raised if the operation is being performed within a transaction and inconsistencies are discovered in the current data. Topology will not let the transation successfully commit.
- [Topology::ServerNotContactable]
Returned if the topology server required to complete this operation is not contactable.
Create_Empty_Entity - This operation is used to create an "empty-entity". Typically this is for managing relationship types where there are no actual entity implementations behind these Topology Service internal structures.
Topology::PartitionedIdentifier create_empty_entity ( in Topology::TopologicalTypeName topo_type) raises (Topology::NoSuchType, Topology::InvalidTypeName, Topology::SchemaViolation, Topology::TransactionWillRollback, Topology::ServerNotContactable);
- Input
- topo_type
The topological type representing this entity.
- Return
This operation returns a PartitionedIdentifier which identifies the internal Topological entity structure.
This operation creates an empty entity, that is, a topologically managed entity which has no underlying object implementation. The empty entity becomes an instance of the topological type specified by the topo_type parameter value.
- [NoSuchType]
Returned if the specified topological_type does not exist.
- [Topology::SchemaViolation]
Raised if this operation is not part of a transaction and the type specified for the entity being managed requires that the entity be part of an association.
- [Topology::TransactionWillRollback]
Raised if the operation is being performed within a transaction and inconsistencies are discovered in the current data. Topology will not let the transation successfully commit.
- [ServerNotContactable]
Returned if the topology server required to complete this operation is not contactable.
Associate - This operation is used to create an association between two entities..
boolean associate ( in Topology::Association assoc ); raises (Topology::SchemaViolation, Topology::NotManaged, Topology::InvalidRoleName, Topology::RoleNotSupported, Topology::TransactionWillRollback, Topology::ServerNotContactable);
- Input
- assoc
The structure that includes the TopologicalEntity identifiers and their roles in the association being proposed.
- Output/Return
A boolean which indicates whether or not this operation modified the topology data.
This operation forms a topological association between the two entities specified in assoc.An association is specified by two sets of <entity, role> pairs.
If the association specified in assoc already exists, no error is returned. In this case, the operation does not modify the data and returns FALSE.
The object reference in the TopologicalEntity identifiers (passed in the Association structure) is disregarded for this operation and may be nil.
- [Topology::NotManaged]
Raised if one of the entities specified in the association is not managed by Topology.
- [Topology::SchemaViolation]
Raised if this operation is not part of a transaction and the operation results in a conflict between the Topology Schema definition and the new state of the topology data. This occurs if the Topology Type rules express a maximum cardinality for an association but the operation adds an association which exceeds this maximum.
- [Topology::InvalidRoleName]
Raised if a role specified in the association does not conform to the X/Open Federated Name syntax.
- [Topology::ServerNotContactable]
Returned if the topology server required to complete this operation is not contactable
- [Topology::RoleNotSupported]
Raised if a role which was specified which is not supported by the entities.
- [Topology::TransactionWillRollback]
Raised if the operation is being performed within a transaction and inconsistencies are discovered in the current data. Topology will not let the transation successfully commit.
Disassociate - This operation is used to delete an association between two entities.
boolean disassociate ( in Topology::Association assoc) raises (Topology::NotManaged, Topology::InvalidRoleName, Topology::SchemaViolation, Topology::TransactionWillRollback, Topology::ServerNotContactable);
- Input
- assoc
The structure that includes the entities and the roles within an association which are to be deleted.
- Return
A boolean which indicates whether or not this operation modified the topology data.
This operation destroys a topological assocation between the two entites specified in the assoc parameter.If the association specified in assoc did not previously exist, no error is returned. In this case, the operation does not modify the data and returns a FALSE.
The object reference in the TopologicalEntity identifiers (passed in the Association structure) is disregarded for this operation and may be nil.
- [Topology::NotManaged]
Raised if one of the entities specified in the association is not managed by Topology.
- [Topology::InvalidRoleName]
Raised if a role specified in the association does not conform to the X/Open Federated Name syntax.
- [Topology::SchemaViolation]
Raised if this operation is not part of a transaction and the operation results in a conflict between the Topology Schema definition and the new state of the topology data. This occurs if the Topology Type rules require that an entity be part of an association, but the operation removed an association which the rules require.
- [Topology::TransactionWillRollback]
Raised if the operation is being performed within a transaction and inconsistencies are discovered in the current data. Topology will not let the transation successfully commit.
- [Topology::ServerNotContactable]
Returned if the topology server required to complete this operation is not contactable.
Tie_Entities - This operation is used to constrain two entities so that they are forced to represent the same Aggregate Entity (AE).
boolean tie_entities ( in AggregationTie tie) raises (Topology::NotManaged, Topology::AggregationConstraintViolation, Topology::TransactionWillRollback, Topology::ServerNotContactable);
- Input
- tie
Indicates the two entities to be tied and a string identifier to distinguish the tie from other ties between these two entities.
- Output/Return
A boolean which indicates whether or not this operation modified the topology data.
This operation constrains two given entities, to represent the same Aggregate Entity (AE).If the tie (between these two entities and with the given identifier) already exists no exception is raised. In this case, the operation does not modify the data and returns FALSE to indicate that the data was not modified.
The object reference in the TopologicalEntity identifiers (passed in the AggregationTie structure) is disregarded for this operation and may be nil.
- [Topology::ServerNotContactable]
Returned if the topology server required to complete this operation is not contactable.
- [Topology::NotManaged]
Raised if one of the entities specified in the tie is not managed by Topology.
- [Topology::AggregationConstraintViolation]
Returned if this operation would result in an Aggregate Entity containing two entities with the same Topological Type, or two entities where the type of one is a child of the type of another.
- [Topology::TransactionWillRollback]
Raised if the operation is being performed within a transaction and inconsistencies are discovered in the current data. Topology will not let the transation successfully commit.
Untie_Entities - This operation is used to stop two entities from being constrained so that they are no longer forced to represent the same Aggregate Entity(AE).
boolean untie_entities ( in AggregationTie tie) raises (Topology::NotManaged, Topology::TransactionWillRollback, Topology::ServiceNotContactable);
- Input
- tie
Indicates the two entities to be tied and a string identifier to distinguish the tie.
- Output/Return
A boolean which indicates whether or not this operation modified the topology data.
This operation removes the specified tie from constraining the two entities to represent the same Aggregate Entity(AE). The tie to be removed is indicated by the two entities and the identifier.If the entities were not previously constrained to represent the same AE, no error is returned. In this case, the operation does not modify the data and returns FALSE.
The object reference in the TopologicalEntity identifiers (passed in the AggregationTie structure) is disregarded for this operation and may be nil.
- [Topology::ServerNotContactable]
Returned if the topology server required to complete this operation is not contactable.
- [Topology::NotManaged]
Raised if one of the entities specified in the tie is not managed by Topology.
- [Topology::TransactionWillRollback]
Raised if the operation is being performed within a transaction and inconsistencies are discovered in the current data. Topology will not let the transation successfully commit.
In_Same_Aggregate - This operation is used to verify whether a list of entities belong to the same Aggregate Entity.
boolean in_same_aggregate ( in Topology::IDList entity_list) raises (Topology::ServerNotContactable, Topology::NotManaged);
- Input
- entity_list
List of entity identifiers.
- Return
A boolean which indicates whether the entities belong to the same Aggregate Entity.
If all of the entities in the entity_list belong to the same Aggregate Entity, then a TRUE is returned. If any one of the entities in the entity_list do not belong to the same Aggregate Entity then FALSE is returned.
- [Topology::ServerNotContactable]
Returned if the topology server required to complete this operation is not contactable.
- [Topology::NotManaged]
Returned if any one or more of the entities in entity_list are not managed by Topology.
Is_Managed - This operation is used to determine whether or not a certain entity is managed by Topology.
boolean is_managed ( in Topology::PartitionedIdentifier entity) raises (Topology::ServerNotContactable);
- Input
- entity
The given entity to be verified if managed by Topology.
- Return
A boolean which indicates whether the entity is managed by Topology.
If the entity is managed by Topology a TRUE is returned, else a FALSE is returned.
- [Topology::ServerNotContactable]
Returned if the topology server required to complete this operation is not contactable.
State_Has_Changed - This operation is used to advise the Topology Service that the non-topological state of an entity has changed.
void state_has_changed ( in Topology::PartionedIdentifier entity) raises (Topology::ServerNotContactable, Topology::NotManaged);
- Input
- entity
The given entity whose non-topological state has changed.
An entity with an enforcer which is interested in its non-topological state must arrange for the correct invocation of this operation. Entities using this operation allow greater integration with other sub-products.This allows an application to place appropriate code for verifying the semantics of a relationship where it belongs - that is, in an enforcer. For example, an application which manages relationships between modems might want to ensure that the baud rate of communicating modems are the same. It can have an enforcer which gets triggered whenever the modems are associated or when the modems have a state change (when their baud rate is changed). The enforcer can then verify that the two modems have the same baud rate. However, since Topology cannot on its own be aware of state changes it must be informed of them via this call.
- [Topology::ServerNotContactable]
Returned if the topology server required to complete this operation is not contactable.
- [Topology::NotManaged]
Raised if the entity specified is not managed by Topology.
Get_Associations - This operation is used to get the associations that involve an entity.
Topology::AssociationList get_associations ( in Topology::PartitionedIdentifier entity) raises (Topology::ServerNotContactable, Topology::NotManaged);
- Input
- entity
The entity for a list of associations is wanted.
- Return
A list of associations, Topology::AssociationList, that involve the given entity, entity.
This operation returns a list of associations, Topology::AssociationList that represents all the associations that involve the entity.
- [Topology::ServerNotContactable]
Returned if the topology server required to complete this operation is not contactable.
- [Topology::NotManaged]
Raised if the entity specified is not managed by Topology.
Get_Topological_Type - This operation gets the topological type for a given entity.
Topology::TopologicalTypeName get_topological_type ( in Topology::PartitionedIdentifier entity) raises (Topology::ServerNotContactable, Topology::NotManaged);
- Input
- entity
The entity of interest.
- Return
The topological type, Topology::TopologicalTypeName, of the entity.
This operation gets the topological type of the topological entity specified by the entity parameter value.
- [Topology::ServerNotContactable]
Returned if the topology server required to complete this operation is not contactable.
- [Topology::NotManaged]
Raised if the entity specified is not managed by Topology.
Get_Ties - Get the list of aggregation ties that involve an entity.
AggregationTieList get_ties ( in Topology::PartitionedIdentifier entity) raises (Topology::ServerNotContactable, Topology::NotManaged);
- Input
- entity
The entity of interest.
- Return
Returns a list of ties that involve the given entity. If the entity is not tied to any other entities then the returned list is empty.
- [Topology::ServerNotContactable]
Returned if the topology server required to complete this operation is not contactable.
- [Topology::NotManaged]
Raised if the entity specified is not managed by Topology.
Get_Entities - This operation gets the topological entities that are part of an Aggregate Entity.
Topology::TopologicalEntityList get_entities ( in Topology::PartitionedIdentifier ae) raises (Topology::ServerNotContactable, Topology::NotManaged);
- Input
- ae
An identifier for an entity within the Aggregate Entity of interest.
- Return
A list of entity identifiers which are in the Aggregate Entity.
This operation gets the topological entities that are part of the Aggregate Entity specified by the ae parameter value. The value of the ae parameter may identify any one of the entities in the Aggregate Entity. The list will always include the entity identifier of the input parameter.
- [Topology::ServerNotContactable]
Returned if the topology server required to complete this operation is not contactable.
- [Topology::NotManaged]
Raised if the entity specified is not managed by Topology.
Get_Topological_Types - This operation gets the topological types of the entities that are part of an Aggregate Entity.
Topology::TopologicalTypeNameList get_topological_types ( in Topology::PartitionedIdentifier ae) raises (Topology::ServerNotContactable, Topology::NotManaged);
- Input
- ae
An entity identifier within the Aggregate Entity.
- Return
A list of Topological Types.
This operation gets the topological types of the topological entities that are part of the Aggregate Entity specified by the ae parameter value. The value of the ae parameter may identify any one of the entities in the aggregate.
- [Topology::ServerNotContactable]
Returned if the topology server required to complete this operation is not contactable.
- [Topology::NotManaged]
Raised if the entity specified is not managed by Topology.
Get_Entity_of_Type - This operation gets the entity of a particular topological type which is part of an Aggregate Entity.
Topology::TopologicalEntity get_entity_of_type ( in Topology::PartitionedIdentifier ae, in Topology::TopologicalTypeName topo_type) raises (Topology::ServerNotContactable, Topology::NotManaged);
- Input
- ae
An entity within an Aggregate Entity.
- topo_type
The topological type of the entity being sought.
- Return
The identifier of an entity with the specified topological type.
This operation gets the entity of a particular topological type which is part of the Aggregate Entity specified by the ae parameter value. The value of the ae parameter may identify any one of the entities in the Aggregate Entity. The operation will only get an entity of the specified topological type topo_type, and not any specializations of that topological type.If an entity of the topological type specified by the topo_type parameter value is found, the entity identifier is returned.
If no entity of the topological type specified by the topo_type parameter value is found, then the PartitionedIdentifier will contain empty strings and the object reference will be nil.
- [Topology::ServerNotContactable]
Returned if the topology server required to complete this operation is not contactable.
- [Topology::NotManaged]
Raised if the entity specified is not managed by Topology.
#if !defined (TOPOLOGYDATA_IDL)
#define TOPOLOGYDATA_IDL
#include <ErrorService.idl>
#include <Topology.idl>
module TopologyData {
interface EntityManager: CosTransactions::TransactionalObject, Entity {
// Operations which deal with a collection of entities
boolean manage (
in Topology::TopologicalEntity entity,
in Topology::TopologicalTypeName topo_type)
raises (TypeChanged,
Topology::SchemaViolation,
Topology::InvalidTypeName,
Topology::NoSuchType,
Topology::TransactionWillRollback,
Topology::ServerNotContactable);
boolean unmanage (
in Topology::PartitionedIdentifier entity)
raises (Topology::SchemaViolation,
Topology::ServerNotContactable,
Topology::TransactionWillRollback);
Topology::PartitionedIdentifier
create_empty_entity (
in Topology::TopologicalTypeName topo_type)
raises (Topology::NoSuchType,
Topology::InvalidTypeName,
Topology::SchemaViolation,
Topology::TransactionWillRollback,
Topology::ServerNotContactable);
boolean associate (
in Topology::Association assoc),
raises (Topology::SchemaViolation,
Topology::NotManaged,
Topology::InvalidRoleName,
Topology::RoleNotSupported,
Topology::TransactionWillRollback,
Topology::ServerNotContactable);
boolean disassociate (
in Topology::Association assoc)
raises (Topology::NotManaged,
Topology::InvalidRoleName,
Topology::SchemaViolation,
Topology::TransactionWillRollback,
Topology::ServerNotContactable);
boolean tie_entities (
in AggregationTie tie)
raises (Topology::NotManaged,
Topology::AggregationConstraintViolation,
Topology::TransactionWillRollback,
Topology::ServerNotContactable);
boolean untie_entities (
in AggregationTie tie)
raises (Topology::NotManaged,
Topology::TransactionWillRollback,
Topology::ServerNotContactable);
boolean in_same_aggregate (
in Topology::IDList entity_list)
raises (Topology::ServerNotContactable,
Topology::NotManaged);
// Operations for which the EntityManager acts as a proxy
// for an individual entity:
boolean is_managed (
in Topology::PartitionedIdentifier entity)
raises (Topology::ServerNotContactable);
void state_has_changed (
in Topology::PartitionedIdentifier entity)
raises (Topology::ServerNotContactable,
Topology::NotManaged);
Topology::AssociationList
get_associations (
in Topology::PartitionedIdentifier entity)
raises (Topology::ServerNotContactable,
Topology::NotManaged);
Topology::TopologicalTypeName
get_topological_type (
in Topology::PartitionedIdentifier entity)
raises (Topology::ServerNotContactable,
Topology::NotManaged);
AggregationTieList
get_ties (
in Topology::PartitionedIdentifier entity)
raises ( Topology::ServerNotContactable,
Topology::NotManaged);
};
interface AEManager: CosTransactions::TransactionalObject {
// Operations for which the EntityManager acts as a proxy
// for an individual aggregate-entity
Topology::TopologicalEntityList
get_entities (
in Topology::PartitionedIdentifier ae)
raises (Topology::ServerNotContactable,
Topology::NotManaged);
Topology::TopologicalTypeNameList
get_topological_types (
in Topology::PartitionedIdentifier ae)
raises (Topology::ServerNotContactable,
Topology::NotManaged);
Topology::TopologicalEntity
get_entity_of_type (
in Topology::PartitionedIdentifier ae,
in Topology::TopologicalTypeName topo_type)
raises (Topology::ServerNotContactable,
Topology::NotManaged);
};
};
#endif //TOPOLOGYDATA_IDL
Contents | Next section | Index |