com.hp.ucmdb.api.topology
Interface QueryDefinition

All Superinterfaces:

BundledResource<QueryDefinition>

public interface QueryDefinition
extends BundledResource<QueryDefinition>

Definition of a UCMDB TQL query.

Examples of simple queries:

• Query host CIs by list of IDs.

   QueryDefinition queryDefinition =
        topologyQueryFactory.createQueryDefinition("Get Hosts by IDs");
   QueryNode queryNode = queryDefinition.addNode("Hosts").ofType("host").withIds(ids);
   queryNode.queryPropertiesWithQualifier("COMPARABLE").queryProperties("host_key", "host_iscomplete"); 

  Full description: Retrieve all CIs of type "host" or a descendant type, using "ids". ids is assumed as a parameter for the code. Also retrieves all properties marked "comparable" and the properties "host_key" and "host_iscomplete" for all CIs in the result topology.

• Query CIs by their properties

   QueryDefinition queryDefinition =
        topologyQueryFactory.createQueryDefinition("Get Hosts");
   QueryNode queryNode = queryDefinition.addNode("Hosts").ofType("host");
   queryNode.property("host_key").like("T%").caseInsensitive();
   queryNode.property("host_iscomplete").isNull();
   queryNode.queryKeyProperties();

  Full description: Retrieve all CIs of type "host" or a descendant where:

  1. A "host_key" property starts with "T" ('%' is used as a wildcard), case insensitive.
  2. A "host_iscomplete" property is empty.
  Also retrieves all key properties of the CIs in the result topology.

• Query CIs' neighbors

   QueryDefinition queryDefinition =
        topologyQueryFactory.createQueryDefinition("Get hosts' neighbors");
   QueryNode cisNode =
        queryDefinition.addNode("CIs").ofType("host").withIdsOf(hosts_ids).invisible();
   QueryNode neighborsNode = queryDefinition.addNode("Neighbors").ofType("configuration_item");
   neighborsNode.queryKeyProperties();
   cisNode.linkedTo(neighborsNode).ofITWorldType().invisible();

  Full description: Retreive all CIs that are neighbours if hosts with the given ids. host_ids assumed as a parameter the code. Both the host CIs and the link between the hosts and their neighbours are invisible - they do not return in the result topology. Also retrieves the key property for these neighbours CIs.

Method Summary

QueryNode	addNode(java.lang.String nodeName) Adds a new node to the query.
java.lang.String	baseQueryName()
java.lang.String	debugDescription() Returns a human-readable full description of this query definition to be used debugging the query definition.
java.lang.String	description()
QueryDefinitionFirstLoadStrategy	firstLoadStrategy() Returns the setting for when a saved query should first be loaded and calculated.
QueryLink	getLink(java.lang.String linkName) Returns the query link with the specified name or null if node does not exist.
QueryNode	getNode(java.lang.String nodeName) Returns the node with the specified name or null if node does not exist.
java.util.Map<java.lang.String,? extends QueryLink>	links() Returns the links defined in this query as a map of names to links.
java.lang.String	name()
java.util.Map<java.lang.String,? extends QueryNode>	nodes() Returns the nodes defined in this query as a map of names to nodes.
QueryDefinitionRecalcPriority	recalcPriority() Returns the setting for how soon a saved query is recalculated after data change.
boolean	removeLink(java.lang.String linkName) Removes the named link from this query definition.
boolean	removeNode(java.lang.String nodeName) Removes the named node from this query definition.
ExecutableQuery	toExecutable() Converts this query definition into an executable query object for passing to TopologyQueryService.executeQuery(ExecutableQuery).
QueryDefinition	withBaseQueryName(java.lang.String baseQueryName) Sets this query to run over the result of another query.
QueryDefinition	withDescription(java.lang.String description) Sets a human-readable description of the query definition purpose.
QueryDefinition	withFirstLoadStrategy(QueryDefinitionFirstLoadStrategy firstLoadStrategy) Sets when a saved query should first be loaded and calculated.
QueryDefinition	withRecalcPriority(QueryDefinitionRecalcPriority recalcPriority) Sets how soon a saved query is recalculated after data change.

Methods inherited from interface com.hp.ucmdb.api.bundles.BundledResource

bundleNames, withBundles

Method Detail

name

java.lang.String name()

Returns:

The name of the query definition.

description

java.lang.String description()

Returns:

A human-readable description of the query definition purpose.

withDescription

QueryDefinition withDescription(java.lang.String description)

Sets a human-readable description of the query definition purpose.

Parameters:

description - the description.

Returns:

this object for method chaining.

addNode

QueryNode addNode(java.lang.String nodeName)

Adds a new node to the query. The resulting object can be used for specifying conditions on IDs, properties, and links, and for specifying which properties are queried for the CIs matched.

The type of the node must be specified or the query is invalid. Specify the type with the ofType or the strictlyOfType method.

Parameters:

nodeName - name of this node. The name must be unique in this query.

getNode

QueryNode getNode(java.lang.String nodeName)

Returns the node with the specified name or null if node does not exist.

getLink

QueryLink getLink(java.lang.String linkName)

Returns the query link with the specified name or null if node does not exist.

nodes

java.util.Map<java.lang.String,? extends QueryNode> nodes()

Returns the nodes defined in this query as a map of names to nodes.

links

java.util.Map<java.lang.String,? extends QueryLink> links()

Returns the links defined in this query as a map of names to links.

toExecutable

ExecutableQuery toExecutable()

Converts this query definition into an executable query object for passing to TopologyQueryService.executeQuery(ExecutableQuery).

recalcPriority

QueryDefinitionRecalcPriority recalcPriority()

Returns the setting for how soon a saved query is recalculated after data change.

withRecalcPriority

QueryDefinition withRecalcPriority(QueryDefinitionRecalcPriority recalcPriority)

Sets how soon a saved query is recalculated after data change.

Note: This is relevant only to saved queries. Query definitions that are executed ad-hoc ignore this parameter.

The default is QueryDefinitionRecalcPriority.LOW.

firstLoadStrategy

QueryDefinitionFirstLoadStrategy firstLoadStrategy()

Returns the setting for when a saved query should first be loaded and calculated.

withFirstLoadStrategy

QueryDefinition withFirstLoadStrategy(QueryDefinitionFirstLoadStrategy firstLoadStrategy)

Sets when a saved query should first be loaded and calculated.

Note: This is relevant only to saved queries. Query definitions that are executed ad-hoc ignore this parameter.

The default is QueryDefinitionFirstLoadStrategy.LOAD_ON_FIRST_REQUEST.

debugDescription

java.lang.String debugDescription()

Returns a human-readable full description of this query definition to be used debugging the query definition.

Returns:

the full description of this query definition.

withBaseQueryName

@NotFinalAPI
QueryDefinition withBaseQueryName(java.lang.String baseQueryName)

Sets this query to run over the result of another query. The scope of the query is not the whole universe but over the subset defined by the a result of another query.

Limitations (not final):

• The base query must have been calculated and a result exists in the result repository before this query definition can be saved or executed. This forces the base query to be active and, unless special measures are taken, it is loaded on server start.
• This query must be loaded on server start. This flag will be set automatically when calling this method.
• You cannot change the base query name of an already saved query.

These limitations do not affect ExecutableQuery#onTopOfQuery.

If a value is set with ExecutableQuery#onTopOfQuery, it overrides the value set here.

Parameters:

baseQueryName - name of the query that specifies the "universe" for this query to run on, or null to disable this feature. May not be empty string.

Returns:

this object for method chaining.

See Also:

ExecutableQuery.onTopOfQuery(java.lang.String)

baseQueryName

@NotFinalAPI
java.lang.String baseQueryName()

Returns:

the base query name for this query definition, or null if no base query was set.

See Also:

withBaseQueryName(String)

removeLink

@NotFinalAPI
boolean removeLink(java.lang.String linkName)

Removes the named link from this query definition.

This method also removes the link from all query link conditions on all nodes.

Parameters:

linkName - the name of the link to remove.

Returns:

true on removal success. false if a link by the given name was not found.

removeNode

@NotFinalAPI
boolean removeNode(java.lang.String nodeName)

Removes the named node from this query definition.

This method also removes all of the node's attached links.

Parameters:

nodeName - the name of the node to remove.

Returns:

true on removal success. false if there is no node with the specified name.