Package 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 Details

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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

      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:

    • linksConditionsBuilder

      LinkConditionBuilder linksConditionsBuilder()
      Returns a builder that can be used to build query links expression trees.
      See Also:

    • 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:

    • 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:

    • 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:

    • 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.

    • elementNumber

      Integer elementNumber()