com.hp.ucmdb.api.topology
Interface QueryNode

All Superinterfaces:

DataStoresConditionable<QueryNode>, IdConditionable<QueryNode,CI>, InterQueryRestrictableElement<QueryNode>, PerspectiveContactable<QueryNode>, PropertiesCarrier<QueryNode>, PropertiesConditionable<QueryNode>, QualifierConditionable<QueryNode>, SupportsInvisibility<QueryNode>, TypeConditionable<QueryNode>

public interface QueryNode
extends TypeConditionable<QueryNode>, IdConditionable<QueryNode,CI>, PropertiesConditionable<QueryNode>, DataStoresConditionable<QueryNode>, PropertiesCarrier<QueryNode>, SupportsInvisibility<QueryNode>, InterQueryRestrictableElement<QueryNode>, QualifierConditionable<QueryNode>, PerspectiveContactable<QueryNode>

A node in the query definition.

A node in the query definition may add CIs to the result, be used to constraint the result or both.
A node has:

• A name, which has a default value (see name()).
• A type, with all of its derived types or with the specific type only. The type places a class constraint on the CIs that may match this node.
• An optional properties condition, which limits the CIs matching this node to those that match the given property condition, for example, has a specific value for an attribute. Trivial properties conditions ("and"-ed with each other) can be added using the property method. More complex properties condition tree can be built using the properties condition builder.
• An optional IDs condition, which limits the CIs matching to a specific set.
• Invisibility status - an invisible query node acts only as a condition on its connected query nodes, while a visible node both acts as a condition and possibly enriches the result with (one or more) CIs.
  It is meaningless to define an invisible query node without linking it to other query nodes for it to act as a condition on.
• A set of properties to bring to the result, defined explicitely or by grouping qualifier. By default, CIs in the result do not have properties.
• A reachable set definition, which may add more CIs and relations to the result topology, based on valid steps.

Links

In addition to conditions on the CI itself, a query node can have query links attached to it, specifying topological conditions between CIs (for example, "show all Nodes with at least one IP address"). These links can either be defined by the query node itself, or linked from another query node. These links act either as:

• constraints only, allowing the query to search for specific topologies (graphs) instead of simple sets of objects
• as enrichment points for the topology, adding links matching the query link conditions
• both conditions and enrichment point for the result topology.

Each node with links has a link conditions expression tree which specifies the induced conditions from the links that are connected to it.
By default, links created using linkedTo() and similar methods are added with an "and" condition to the existing tree, and with "cardinality" conditions that say "A CI matching this query node will appear only if there is at least one link attached to it in the correct direction that matches all other conditions (those from QueryLink and those from the QueryNode "other side").
If more precise control is needed, it is possible to define other "cardinality" conditions using the QueryLink interface method.
If even more precise control is needed, it's possible to completely rewrite the entire links expression tree. This enables

• writing a complex logical expression using "and", "or" and sub expressions
• specifying a link in more than one location in the logical expression
• using different cardinality conditions for each instance

Since:

8.0

Method Summary

java.util.Collection<QueryLink<?>>	getQueryLinks() Returns the all the links (incoming and outgoing) that relate to this node.
com.hp.ucmdb.api.topology.indirectlink.IndirectLink	indirectlyLinkedFrom(QueryNode otherNode) Creates a query link specifying that there is are one ore more paths of defined steps (source CI, link, target CI) between results (CIs) of otherNode> and the results of this node.
com.hp.ucmdb.api.topology.indirectlink.IndirectLink	indirectlyLinkedTo(QueryNode otherNode) Creates a query link specifying that there are a one ore more paths of defined steps (source CI, link, target CI) between results (CIs) of this node and results of the otherNode.
DirectLink	linkedFrom(QueryNode otherNode) Creates a query link specifying that results (CIs) from this node are the end2 of some real-world relationship to results from node otherNode.
IncompleteLinkOnPropertyP1	linkedOnPropertyFrom(QueryNode otherNode) Creates a query link specifying that a link (Relation) be created in the result such that a specific property in a CI from the given node's results has has either an "equal" or "not equal" relation to a specific property of a CI from the this node's results.
IncompleteLinkOnPropertyP1	linkedOnPropertyTo(QueryNode otherNode) Creates a query link specifying that a link (Relation) be created in the result such that a specific property in a CI from this node's results has either an "equal" or "not equal" relation to a specific property of a CI from the target node's results.
DirectLink	linkedTo(QueryNode otherNode) Creates a query link that specifies that the results (CIs) from this QueryNode have some real-world relationship (existance or absence of Relations) to the results from another QueryNode.
LinkConditionBuilder	linksConditionsBuilder() Returns a builder that can be used to build query links expression trees.
java.lang.String	name() The name of this element in the query definition it belongs to.
DirectLink	notLinkedFrom(QueryNode otherNode) Creates a condition specifying that CIs matching this node are not linked from any CIs matching otherNode.
DirectLink	notLinkedTo(QueryNode otherNode) Creates a condition specifying that CIs matching this node are not linked to any CIs matching otherNode.
DirectLink	optionallyLinkedFrom(QueryNode otherNode) Similar to linkedFrom, except this method adds the link with an "and at least zero links" ("and" with cardinality 0..UNBOUNDED) condition to the target of the link (this node).
DirectLink	optionallyLinkedTo(QueryNode otherNode) Similar to linkedTo, except this method adds the link with an "and at least zero links" ("and" with cardinality 0..UNBOUNDED) condition to the source of the link (this node).
DirectLink	orLinkedFrom(QueryNode otherNode) Similar to linkedFrom, except this method adds the link with an "or at least one link" ("or" with cardinality 1..UNBOUNDED) condition to the target of the link (this node).
DirectLink	orLinkedTo(QueryNode otherNode) Similar to linkedTo, except this method adds the link with an "or at least one link" ("or" with cardinality 1..UNBOUNDED) condition to the source of the link (this node).
ConditionExpression<LinkConditionElement,LinkConditionOperand>	queryLinkConditions() Returns the current links expression conditions tree for this node, or null if there are no links attached to this node.
com.hp.ucmdb.api.topology.reachableset.ReachableSetDefinition	reachableSetDefinition() Returns the previously defined reachable set, or a new one if none exists. If a reachable set has no steps, it has no effect on the result.
QueryNode	withQueryLinkConditions(ConditionExpression<LinkConditionElement,LinkConditionOperand> conditionExpression) Sets a new links expression condition tree for this node. A validation error will occur if the new expression tree does not have at least one instance of every query link (incoming and outgoing) that relates to this node.
com.hp.ucmdb.api.topology.reachableset.EmptyReachableSetStep	withReachableSetStep() Creates an incomplete reachable set step, which is completed using a from condition, a to condition and a link condition.

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

isTypeStrict, noDerivedTypes, ofConfigurationItemType, ofITWorldType, ofType, strictlyOfType, type

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

ids, withIds, withIds, withIdsFromStrings, withIdsFromStrings, withIdsOf, withIdsOf

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

propertiesCondition, propertiesConditionBuilder, property, property, property, withPropertiesConditions

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

dataStores, isAllDataStores, isInternalDataStoreOnly, withAllDataStores, withDataStores, withDataStores, withInternalDataStoreOnly

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

getDefaultPropertiesToQuery, getPropertiesToQueryPerType, propertiesToQuery, queryKeyProperties, queryProperties, queryPropertiesWithQualifier, queryProperty

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

invisible, isInvisible

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

addInterQueryElementRestrictions, addInterQueryElementRestrictions, interQueryElementRestrictions

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

qualifierMatchingStrategy, qualifiersRestrictiedTo, restrictToQualifiers, restrictToQualifiers, withQualifierMatchingStrategy

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

isPerspectiveContact, setAsPerspectiveContact

Method Detail

name

java.lang.String name()

The name of this element in the query definition it belongs to. The name is unique in the query definition this node is part of.

linkedTo

DirectLink linkedTo(QueryNode otherNode)

Creates a query link that specifies that the results (CIs) from this QueryNode have some real-world relationship (existance or absence of Relations) to the results from another QueryNode.
This method acts both as a factory method (creating the QueryLink object) and as a setter method (setting the new condition to be the link condition of this node).
Calling thisNode.linkedTo(myNode).withLinkOfType("link type").atLeast(2) sets:

• A condition on CIs matching thisNode. CIs will be matched to thisNode if they have a relation of type "link type" to at least two CIs matching myNode and satisfying all other conditions set on thisNode.
• By default, a condition on CIs matching myNode. CIs match myNode if they have a relation of "link type" to at least least one CI matching thisNode and satisfying all other conditions set on myNode). This can be changed using target cardinality methods.
• By default, causes the relations matching the DirectLink (as described above) to appear in the result topology. This can be changed using the invisible method.

The type of the link must be explicitly specified with method ofType, strictlyOfType or ofConfigurationItemType. If the type is not specified, the query is invalid.

This link is added as an "and at least one link" condition ("and" with cardinality 1..UNBOUNDED) to both source and target ends of the link (this node and the otherNode).

See Also:

linkedFrom(com.hp.ucmdb.api.topology.QueryNode)

optionallyLinkedTo

DirectLink optionallyLinkedTo(QueryNode otherNode)

Similar to linkedTo, except this method adds the link with an "and at least zero links" ("and" with cardinality 0..UNBOUNDED) condition to the source of the link (this node). The link is added as an "and at least one link" ("and" with cardinality 1..UNBOUNDED) to its target (the otherNode). nodeA.optionallyLinkedTo(nodeB); is equivalent to nodeA.linkedTo(nodeA).withSourceCardinality(0, QueryLink.UNBOUNDED);

See Also:

linkedTo(com.hp.ucmdb.api.topology.QueryNode)

orLinkedTo

DirectLink orLinkedTo(QueryNode otherNode)

Similar to linkedTo, except this method adds the link with an "or at least one link" ("or" with cardinality 1..UNBOUNDED) condition to the source of the link (this node). The link is added as an "and at least one link" ("and" with cardinality 1..UNBOUNDED) to its target (the otherNode).

See Also:

linkedTo(com.hp.ucmdb.api.topology.QueryNode)

linkedFrom

DirectLink linkedFrom(QueryNode otherNode)

Creates a query link specifying that results (CIs) from this node are the end2 of some real-world relationship to results from node otherNode.

nodeA.linkedFrom(nodeB); is equivalent to nodeB.linkedTo(nodeA);

See Also:

linkedTo(com.hp.ucmdb.api.topology.QueryNode)

optionallyLinkedFrom

DirectLink optionallyLinkedFrom(QueryNode otherNode)

Similar to linkedFrom, except this method adds the link with an "and at least zero links" ("and" with cardinality 0..UNBOUNDED) condition to the target of the link (this node). The link is added as an "and at least one link" ("and" with cardinality 1..UNBOUNDED) to its source (the otherNode).

nodeA.optionallyLinkedFrom(nodeB); is equivalent to nodeA.linkedFrom(nodeB).withTargetCardinality(0, QueryLink.UNBOUNDED); which is also equivalent to nodeB.linkedTo(nodeA).withTargetCardinality(0, QueryLink.UNBOUNDED);

See Also:

linkedFrom(com.hp.ucmdb.api.topology.QueryNode)

orLinkedFrom

DirectLink orLinkedFrom(QueryNode otherNode)

Similar to linkedFrom, except this method adds the link with an "or at least one link" ("or" with cardinality 1..UNBOUNDED) condition to the target of the link (this node). The link is added as an "and at least one link" ("and" with cardinality 1..UNBOUNDED) to its source (the otherNode).

Note: nodeA.orLinkedFrom(nodeB); is NOT equivalent to nodeB.orLinkedTo(nodeA);.

See Also:

linkedFrom(com.hp.ucmdb.api.topology.QueryNode)

notLinkedTo

DirectLink notLinkedTo(QueryNode otherNode)

Creates a condition specifying that CIs matching this node are not linked to any CIs matching otherNode.

Equivalent to: thisNode.linkedTo(otherNode).withSourceCardinality(0,0).withTargetCardinality(0,0);

See Also:

linkedTo(com.hp.ucmdb.api.topology.QueryNode)

notLinkedFrom

DirectLink notLinkedFrom(QueryNode otherNode)

Creates a condition specifying that CIs matching this node are not linked from any CIs matching otherNode.

Equivalent to:thisNode.linkedFrom(otherNode).withSourceCardinality(0,0).withTargetCardinality(0,0);

See Also:

linkedFrom(com.hp.ucmdb.api.topology.QueryNode)

indirectlyLinkedTo

com.hp.ucmdb.api.topology.indirectlink.IndirectLink indirectlyLinkedTo(QueryNode otherNode)

Creates a query link specifying that there are a one ore more paths of defined steps (source CI, link, target CI) between results (CIs) of this node and results of the otherNode.

Calling:

 app.indirectlyLinkedTo(host).
      withStep().from("app").to("service").alongITWorldLink().
      andStep().from("service").to("host").alongITWorldLink().
      andStep().from("service").to("service").alongITWorldLink().
      andStep().from("app").to("host").alongITWorldLink();
 

causes a relation to be created in the result if a result app is directly connected to host or if there is a path app->service(->service->service...)->host.

An indirect link with no steps is invalid.

This link is added as an "and at least one link" condition ("and" with cardinality 1..UNBOUNDED) to both source and target of the link (this node and the otherNode).

Returns:

the indirect link.

indirectlyLinkedFrom

com.hp.ucmdb.api.topology.indirectlink.IndirectLink indirectlyLinkedFrom(QueryNode otherNode)

Creates a query link specifying that there is are one ore more paths of defined steps (source CI, link, target CI) between results (CIs) of otherNode> and the results of this node.

This link is added as an "and at least one link" condition ("and" with cardinality 1..UNBOUNDED) to both source and target of the link (this node and the otherNode).

nodeA.indirectlyLinkedFrom(nodeB)... is equivalent to nodeB.indirectlyLinkedTo(nodeA)...

Returns:

the indirect link.

See Also:

indirectlyLinkedTo(com.hp.ucmdb.api.topology.QueryNode)

linkedOnPropertyTo

IncompleteLinkOnPropertyP1 linkedOnPropertyTo(QueryNode otherNode)

Creates a query link specifying that a link (Relation) be created in the result such that a specific property in a CI from this node's results has either an "equal" or "not equal" relation to a specific property of a CI from the target node's results. The property in the target node does not have to have the same name as the property in this node's results.

Calling:

 network.linkedOnPropertyTo(ip).whenSourceProperty("network_netaddr").isEqualToTargetProperty("ip_netaddr");
 

causes a relation to be created between CI1 (network) and CI2 (ip) if CI1.network_netaddr = CI2.ip_netaddr.

This link is added as an "and at least one link" condition ("and" with cardinality 1..UNBOUNDED) to both source and target of the link (this node and the otherNode).

Returns:

an incomplete link on property, to be completed using equal or not equal on the target property

linkedOnPropertyFrom

IncompleteLinkOnPropertyP1 linkedOnPropertyFrom(QueryNode otherNode)

Creates a query link specifying that a link (Relation) be created in the result such that a specific property in a CI from the given node's results has has either an "equal" or "not equal" relation to a specific property of a CI from the this node's results. The property in the target node does not have to have the same name as the property in this node's results.

This link is added as an "and at least one link" condition ("and" with cardinality 1..UNBOUNDED) to both source and target of the link (this node and the otherNode).

nodeA.linkedOnPropertyFrom(nodeB)... is equivalent to nodeB.linkedOnPropertyTo(nodeA)...

Returns:

an incomplete link on property, to be completed using equal or not equal on the target property

See Also:

linkedOnPropertyFrom(QueryNode)

getQueryLinks

java.util.Collection<QueryLink<?>> getQueryLinks()

Returns the all the links (incoming and outgoing) that relate to this node.

queryLinkConditions

ConditionExpression<LinkConditionElement,LinkConditionOperand> queryLinkConditions()

Returns the current links expression conditions tree for this node, or null if there are no links attached to this node.

See Also:

withQueryLinkConditions(com.hp.ucmdb.api.topology.ConditionExpression)

withQueryLinkConditions

QueryNode withQueryLinkConditions(ConditionExpression<LinkConditionElement,LinkConditionOperand> conditionExpression)

Sets a new links expression condition tree for this node.
A validation error will occur if the new expression tree does not have at least one instance of every query link (incoming and outgoing) that relates to this node.

See Also:

queryLinkConditions(), getQueryLinks(), linksConditionsBuilder().

linksConditionsBuilder

LinkConditionBuilder linksConditionsBuilder()

Returns a builder that can be used to build query links expression trees.

See Also:

withQueryLinkConditions(com.hp.ucmdb.api.topology.ConditionExpression)

withReachableSetStep

com.hp.ucmdb.api.topology.reachableset.EmptyReachableSetStep withReachableSetStep()

Creates an incomplete reachable set step, which is completed using a from condition, a to condition and a link condition.

A reachable set is an extension of the query node that can add more CIs to the result based on allowed steps (Source, Link, Target). The CIs returned from the reachable sets are added after all condition checks and are superimposed on the topology.

Example of usage:

 //service is a QueryNode.
 service.ofType("logical_service").
 withReachableSetStep().from("logical_service").to("business").alongAnyLink().
 andStep().from("business").to("software_element").alongAnyLink().
 andStep().from("host").to("software_element").againstAnyLink().
 andReachableSetDefinition().withMaxNumberOfStepsMatched(4);
 

In the above example, the steps are searched, combining up to four steps back-to-back. The initial sources are the CIs matching this QueryNode. Afterwards, each step "to" can be a source for another step.
For example, the following graph may be returned:

 Service1
 |
 --------------------------------------------
 |                                          |
 | depends on                               | depends on
 |                                          |
 Application1                               Server5
 |
 ---------------------
 |                   |
 | contains          | depends on
 |                   |
 Application2        Server5
 |
 | contains
 |
 Server4
 

Where "Service1" is a CI that was matched by this QueryNode, and every other CI was matched by a step from the previous source CI, up to 4 steps.

In addition, the .containingQueryNode() at the end returns this QueryNode object, allowing for more conditions to be specified.

Calling this method a second time results in adding another step to the already defined reachable set.

Any properties to query

Returns:

incomplete reachable set first step definition.

See Also:

EmptyReachableSetStep, ReachableSetStepFromPart, ReachableSetStepToPart, ReachableSetStepLinkPart, ReachableSetDefinition

reachableSetDefinition

com.hp.ucmdb.api.topology.reachableset.ReachableSetDefinition reachableSetDefinition()

Returns the previously defined reachable set, or a new one if none exists.

If a reachable set has no steps, it has no effect on the result.

See Also:

withReachableSetStep()