Topology (api-interfaces 11.0.3 API)

All Superinterfaces:

Graph

All Known Subinterfaces:

LiveTopology
```
public interface Topology
extends Graph
```
Result of a topology query execution.
You can retrieve CIs and relations from this result by query node name or as a flat collection. If each CI matches exactly one node, the two techniques give the same result. If a CI matches more than one node, the topology structure holds n+1 instances of the CI where n is the number of nodes that contain the CI. When a CI is retrieved from the collection returned by getCIsByName(java.lang.String), its properties and relations are defined by the node with the specified name. When a CI is retrieved from the collection returned by getAllCIs(), the CI has all of the of the queried properties and connected relations of all instances of that CI.
Similarly, when a Relations relation is matched by more than one query link node, the relation appears in this structure more than once.
When traversing the resulting graph with TopologyCI.getOutgoingRelations() and TopologyCI.getIncomingRelations(), the relations are consistent with the connected CIs. If the CI is taken from a node, the relation will be the one connected to that node. When the CI is taken from the collection of all CIs, it is associated with all the relations to which the CI is connected from all nodes.
Examples:
List all hosts in UCMDB:
```
 QueryDefinition queryDefinition = factory.createQueryDefinition("Get all hosts");
 queryDefinition.addNode("Hosts").ofType("host").queryProperty("host_dnsname");
 Topology topology = topologyQueryService.executeQuery(queryDefinition);
 for (TopologyCI host : topology.getAllCIs()) {
     System.out.println("Host key:" + host.getPropertyValue("host_dnsname");
 }
 
```
List all hosts with their contained resources
```
 QueryDefinition queryDefinition = factory.createQueryDefinition("Get hosts' resources");
 String hostsNodeName = "Hosts";
 QueryNode hostsNode = queryDefinition.addNode(cisNodeName).ofType("host");
 QueryNode resourcesNode = queryDefinition.addNode("Resources").ofType("hostresource").queryKeyProperties();
 hostsNode.linkedTo(resourcesNode).withLinkOfType("composition");
 Topology topology = topologyQueryService.executeQuery(queryDefinition);
 for (TopologyCI host : topology.getCIsByName(hostsNodeName)) {
     System.out.println("Host:");
     printElement(host);
     for (Relation relation : host.getOutgoingRelations()) {
         System.out.println("\tResource:");
         printElement(relation.getEnd2CI(), "\t");
     }
 }
 
```

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`Collection<TopologyCI>`	`getAllCIs()` Returns the collection of all CIs in this result.
`Map<UcmdbId,TopologyCI>`	`getAllCIsAsMap()` Returns the CIs in this result as a map from ID to CI.
`Collection<TopologyRelation>`	`getAllRelations()` Returns the collection of all Relations in this result.
`TopologyCI`	`getCI(UcmdbId id)` Returns the CI from this result having the specified ID.
`Collection<TopologyCI>`	`getCIsByName(String nodeName)` Returns the CIs associated with the specified node.
`Map<UcmdbId,TopologyCI>`	`getCIsByNameAsMap(String nodeName)` Returns the map of the CIs associated with the specified node.
`Set<String>`	`getContainingNodes(UcmdbId id)` Returns the node names associated with the id.
`Map<UcmdbId,Set<String>>`	`getContainingNodesMap()` Returns a map of IDs to their associated node names.
`Topology`	`getNextChunk()` Returns the next partial result of a query result.
`QueryResultVersion`	`getQueryResultVersion()` The version of this topology.
`TopologyRelation`	`getRelation(UcmdbId ucmdbId)` Returns the Relation from this result having the specified ID.
`Collection<TopologyRelation>`	`getRelationsByName(String linkName)` Returns the CIs associated with the specified link.
`Map<UcmdbId,TopologyRelation>`	`getRelationsByNameAsMap(String linkName)` Returns the map of the CIs associated with the specified link.
`boolean`	`hasNextChunk()` Indicates whether more topologies must be retrieved to complete a query result.
`boolean`	`isEmpty()` Returns true if the topology is empty.
`void`	`makeThreadSafe()` Call this method to make the internal topology structure safe to access by multiple threads.
`boolean`	`querySupportsHasChanges()` Returns true if the query that generated this topology supports the "has changes" question.

Methods inherited from interface com.hp.ucmdb.api.topology.Graph
getAllRelationsAsMap

- Method Detail
  - getCIsByName
```
Collection<TopologyCI> getCIsByName(String nodeName)
```
    Returns the CIs associated with the specified node.
  - getCIsByNameAsMap
```
Map<UcmdbId,TopologyCI> getCIsByNameAsMap(String nodeName)
```
    Returns the map of the CIs associated with the specified node.
    
    Returns:
    
    a map of IDs to CIs
  - getRelationsByName
```
Collection<TopologyRelation> getRelationsByName(String linkName)
```
    Returns the CIs associated with the specified link.
  - getRelationsByNameAsMap
```
Map<UcmdbId,TopologyRelation> getRelationsByNameAsMap(String linkName)
```
    Returns the map of the CIs associated with the specified link.
    
    Returns:
    
    a map of IDs to Relations
  - getAllCIs
```
Collection<TopologyCI> getAllCIs()
```
    Returns the collection of all CIs in this result.
    A CI is returned only once. A CI that matches more than one node, is returned with the properties and relations of all instances of the CI.
    
    Specified by:
    
    getAllCIs in interface Graph
  - getAllCIsAsMap
```
Map<UcmdbId,TopologyCI> getAllCIsAsMap()
```
    Returns the CIs in this result as a map from ID to CI.
    
    Specified by:
    
    getAllCIsAsMap in interface Graph
    
    See Also:
    
    getAllCIs()
  - getCI
```
TopologyCI getCI(UcmdbId id)
```
    Returns the CI from this result having the specified ID. The CI returned is from the collection returned by getAllCIs(). If no CI with the specified ID if found in the collection, getCI returns null.
    
    Specified by:
    
    getCI in interface Graph
  - getRelation
```
TopologyRelation getRelation(UcmdbId ucmdbId)
```
    Returns the Relation from this result having the specified ID. The Relation returned is from the collection returned by getAllRelations(). If no Relation with the specified ID if found in the collection, getRelation returns null.
    
    Specified by:
    
    getRelation in interface Graph
  - getAllRelations
```
Collection<TopologyRelation> getAllRelations()
```
    Returns the collection of all Relations in this result.
    A Relation is returned only once. A Relation that matches more than one node is returned with the properties of all instances of the Relation.
    
    Specified by:
    
    getAllRelations in interface Graph
  - getContainingNodes
```
Set<String> getContainingNodes(UcmdbId id)
```
    Returns the node names associated with the id.
  - getContainingNodesMap
```
Map<UcmdbId,Set<String>> getContainingNodesMap()
```
    Returns a map of IDs to their associated node names.
  - hasNextChunk
```
boolean hasNextChunk()
```
    Indicates whether more topologies must be retrieved to complete a query result.
  - getNextChunk
```
Topology getNextChunk()
```
    Returns the next partial result of a query result.
    Usage:
```
 Topology topology = ... //get initial topology
 //process initial topology
 while (topology.hasNextChunk()) {
   topology = topology.getNextChunk();
   //process topology chunk
 }
 
```
    Please note that calling "getNextChunk()" on a Topology object twice might result in an exception.
  - getQueryResultVersion
```
@NotFinalAPI
QueryResultVersion getQueryResultVersion()
```
    The version of this topology.
    
    Returns:
    
    the version of this topology
  - isEmpty
```
boolean isEmpty()
```
    Returns true if the topology is empty. Equivalent to getAllCIs().isEmpty() && getAllRelations().isEmpty()
    
    Returns:
    
    true if the topology is empty.
  - querySupportsHasChanges
```
@NotFinalAPI
boolean querySupportsHasChanges()
```
    Returns true if the query that generated this topology supports the "has changes" question.
    To support "has changes" questions, a query must be:
    - saved and not parameterized, though properties carrier changes are allowed
    - active (not QueryDefinitionRecalcPriority.NOT_ACTIVE)
    If a query supports "has changes", to determine if the query result changed since 'this' topology was created use the TopologyQueryService.hasChanges method with the query name and the query result version attached to this topology.
    Returns:
    
    true if hasChanges is supported by this topology.
    
    See Also:
    
    TopologyQueryService.hasChanges(java.lang.String, com.hp.ucmdb.api.topology.QueryResultVersion)
  - makeThreadSafe
```
void makeThreadSafe()
```
    Call this method to make the internal topology structure safe to access by multiple threads. As this inflict penalties on single-threaded usage, it must be called explicitly.
    This method may be called only before any other topology call. Calling this method after calling any other method may yield an exception. Multiple calls to this method are ignored.
    The Topology is treated as thread-safe only after this method returns.

Interface Topology

Method Summary

Methods inherited from interface com.hp.ucmdb.api.topology.Graph

Method Detail

getCIsByName

getCIsByNameAsMap

getRelationsByName

getRelationsByNameAsMap

getAllCIs

getAllCIsAsMap

getCI

getRelation

getAllRelations

getContainingNodes

getContainingNodesMap

hasNextChunk

getNextChunk

getQueryResultVersion

isEmpty

querySupportsHasChanges

makeThreadSafe