com.hp.ucmdb.api.topology

Interface QueryNode

All Superinterfaces:

ComplexTypeConditionHandler<QueryNode>, DataStoresConditionable<QueryNode>, IdConditionable<QueryNode,CI>, InterQueryRestrictableElement<QueryNode>, PerspectiveContactable<QueryNode>, PropertiesCarrier<QueryNode>, PropertiesConditionable<QueryNode>, QualifierConditionable<QueryNode>, SupportsClientProperties<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>, ComplexTypeConditionHandler<QueryNode>, SupportsClientProperties<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.
• An optional set of complex type conditions which specifies a complex conditions on the type of the query element. Each complex condition can add or remove class types to be matched in the result. NOTE: The type of the node can be ignored for the results if needed. Just create a complex condition and declare this type to be ignored in the result. In this case, the results will only be matched to the complex type conditions and not to the type of the node.

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

Modifier and Type	Method and Description
Collection<QueryLink<?>>	getQueryLinks() Returns the all the links (incoming and outgoing) that relate to this node.
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.
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.
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).
QueryNode	queryConcreteProperties() Adds all the concrete properties of the CI to the list of properties to query.
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.
QueryNode	queryPathToConcreteProperties() Adds all the concrete properties of the CI to the list of properties to query, in addition to the concrete properties of all CI types along the path in the class model hierarchy between the CI-type in the TQL query (defined by ofType(String) method) and the CI-type of the CI instance.
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.
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

excludedProperties, excludeProperties, excludeProperty, getDefaultPropertiesToQuery, getPropertiesToQueryPerType, isPropertiesCarrierEmpty, propertiesCarrierBehavior, propertiesToQuery, queryKeyProperties, queryProperties, queryPropertiesWithQualifier, queryProperty, withPropertiesCarrierBehavior

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

Methods inherited from interface com.hp.ucmdb.api.topology.complextype.ComplexTypeConditionHandler

complexTypeConditionsSet, withComplexTypeCondition

Methods inherited from interface com.hp.ucmdb.api.util.SupportsClientProperties

clientProperties, clientProperty, usedNamespaces, withClientProperty

Method Detail

name

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

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

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

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<com.hp.ucmdb.api.topology.LinkConditionElement, com.hp.ucmdb.api.topology.LinkConditionOperand>)

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<com.hp.ucmdb.api.topology.LinkConditionElement, com.hp.ucmdb.api.topology.LinkConditionOperand>)

withReachableSetStep

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

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()

queryConcreteProperties

QueryNode queryConcreteProperties()

Adds all the concrete properties of the CI to the list of properties to query. Concrete properties are defined to be all properties defined for a specific CI type, that are not inherited from a higher level in the class model. The query result includes the concrete properties for each CI instance according to its type. For example, a TQL query that includes a Node CIT returns both Unix and Windows CITs, with different concrete properties for each CIT. CIs of type Unix have the additional attribute Unix-description, while CIs of type Windows have the additional attributes Windows-IE-version, Windows-kernel, etc.

Returns:

this object. The returned object can be used for method chaining.

See Also:

ClassDefinition.getDeclaredAttributes()

queryPathToConcreteProperties

QueryNode queryPathToConcreteProperties()

Adds all the concrete properties of the CI to the list of properties to query, in addition to the concrete properties of all CI types along the path in the class model hierarchy between the CI-type in the TQL query (defined by ofType(String) method) and the CI-type of the CI instance. The query result includes the properties for each CI instance according to its type. For example, a TQL query that includes a Node CIT returns both Unix and Windows CITs, with different properties for each CIT. The path from Node to Windows or Unix in the class model hierarchy is Node -> Computer -> Windows/Unix. All CIs include attributes defined at the level of Node and Computer, such as Node-Key, but CIs of type Unix have the additional attribute Unix-description, while CIs of type Windows have the additional attributes Windows-IE-version, Windows-kernel, etc.

Returns:

this object. The returned object can be used for method chaining.