com.hp.ucmdb.api.topology
Interface Topology

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

java.util.Collection<TopologyCI>	getAllCIs() Returns the collection of all CIs in this result.
java.util.Map<UcmdbId,TopologyCI>	getAllCIsAsMap() Returns the CIs in this result as a map from ID to CI.
java.util.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.
java.util.Collection<TopologyCI>	getCIsByName(java.lang.String nodeName) Returns the CIs associated with the specified node.
java.util.Map<UcmdbId,TopologyCI>	getCIsByNameAsMap(java.lang.String nodeName) Returns the map of the CIs associated with the specified node.
java.util.Set<java.lang.String>	getContainingNodes(UcmdbId id) Returns the node names associated with the id.
java.util.Map<UcmdbId,java.util.Set<java.lang.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.
java.util.Collection<TopologyRelation>	getRelationsByName(java.lang.String linkName) Returns the CIs associated with the specified link.
java.util.Map<UcmdbId,TopologyRelation>	getRelationsByNameAsMap(java.lang.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

java.util.Collection<TopologyCI> getCIsByName(java.lang.String nodeName)

Returns the CIs associated with the specified node.

getCIsByNameAsMap

java.util.Map<UcmdbId,TopologyCI> getCIsByNameAsMap(java.lang.String nodeName)

Returns the map of the CIs associated with the specified node.

Returns:

a map of IDs to CIs

getRelationsByName

java.util.Collection<TopologyRelation> getRelationsByName(java.lang.String linkName)

Returns the CIs associated with the specified link.

getRelationsByNameAsMap

java.util.Map<UcmdbId,TopologyRelation> getRelationsByNameAsMap(java.lang.String linkName)

Returns the map of the CIs associated with the specified link.

Returns:

a map of IDs to Relations

getAllCIs

java.util.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

java.util.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

java.util.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

java.util.Set<java.lang.String> getContainingNodes(UcmdbId id)

Returns the node names associated with the id.

getContainingNodesMap

java.util.Map<UcmdbId,java.util.Set<java.lang.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.

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.