com.hp.ucmdb.api.topology

Interface TopologyQueryService

public interface TopologyQueryService

Interface for querying the UCMDB topology. To create the data structures used by the methods of this interface, use the factory obtained with the getFactory() method.

Here is an example of executing an ad-hoc query and displaying the results:

 TopologyQueryService queryService = ucmdbService.getTopologyQueryService();
 TopologyQueryFactory queryFactory = queryService.getFactory();
 QueryDefinition queryDefinition = queryFactory.createQueryDefinition("Get hosts with more than one network interface");
 String hostNodeName = "Host";
 QueryNode hostNode = queryDefinition.addNode(hostNodeName).ofType("host").queryProperty("display_label");
 QueryNode ipNode = queryDefinition.addNode("IP").ofType("ip").queryProperty("ip_address");
 hostNode.linkedTo(ipNode).withLinkOfType("contained").atLeast(2);
 Topology topology = queryService.executeQuery(queryDefinition);
 Collection hosts = topology.getCIsByName(hostNodeName);
 for (TopologyCI host : hosts) {
     System.out.println("Host " + host.getPropertyValue("display_label"));
     for (TopologyRelation relation : host.getOutgoingRelations()) {
         System.out.println("  has IP " + relation.getEnd2CI().getPropertyValue("ip_address"));
     }
 }
 

Method Summary

Modifier and Type	Method and Description
ExecutableQuery	createExecutableQuery(String queryName) Creates an ExecutableQuery structure.
Query	createQueryStub(String queryName) Creates a Query stub that holds the query name and allows retrieval of the query definition (or reference definition, if applicable).
TopologyCount	evaluateNamedQuery(String queryName) Executes the query of the specified name and return its result count.
TopologyCountByClasses	evaluateNamedQueryWithClassesBreakdown(String queryName, Collection<String> elementNamesToCount) Executes the query of the specified name and return its result count break-down by classes.
TopologyCount	evaluateQuery(ExecutableQuery query) Executes a query stored on the server and returns the result count.
TopologyCount	evaluateQuery(QueryDefinition queryDefinition) Executes a query defined on the client and returns its result count.
TopologyCountByClasses	evaluateQueryWithClassesBreakdown(ExecutableQuery query, Collection<String> elementNamesToCount) Executes a query stored on the server and returns the result count break-down by classes.
TopologyCountByClasses	evaluateQueryWithClassesBreakdown(QueryDefinition queryDefinition, Collection<String> elementNamesToCount) Executes a query defined on the client and return its result count break-down by classes.
Topology	executeNamedQuery(String queryName) Executes the query of the specified name.
Topology	executeNamedQueryInBDMScope(String queryName) Executes the query of the specified name within the BDM scope.
Topology	executeQueriesTree(QueriesExecutionBulk queriesExecutionBulk) Executes tree of queries, returning the top-most query result.
Topology	executeQuery(ExecutableQuery query) Executes a query stored on the server and returns the result.
Topology	executeQuery(QueryDefinition queryDefinition) Executes a query defined on the client.
Topology	executeQueryInBDMScope(ExecutableQuery query) Executes a query that is stored on the server, within the BDM scope, and returns the result.
TopologyQueryFactory	getFactory() Returns the query factory.
LiveQuery	getLiveQuery(String queryName) Returns a query whose result is always kept updated on server side.
Set<String>	hasChanges(Map<String,QueryResultVersion> queries2check) Same as hasChanges(String, QueryResultVersion), but is passed a collection of queries and their version to check for changes
boolean	hasChanges(String queryName, QueryResultVersion queryResultVersion) Checks if the results of the query were changed since the result version was created.
boolean	hasChanges(String queryName, String queryResultVersionAsString) Same as hasChanges(String, QueryResultVersion), but is passed the result of {QueryResultVersion#asString()}.
boolean	isActiveQueryInFailedState(String queryName) Checks if the given query is defined ACTIVE in UCMDB and is currently in FAILED state.
String	queryDefinitionToString(QueryDefinition queryDefinition) Returns the query's string representation.
String	queryReferenceDefinitionToString(QueryReferenceDefinition queryReferenceDefinition) Returns the query refernce's string representation.
void	registerModelListener(ModelListener listener) Deprecated. replaced by registerModelListener(ModelListener listener, ModelEventsFilter filter)
String	registerModelListener(ModelListener listener, ModelEventsFilter filter) Registers a listener to be called when the model stored on the UCMDB server changes.
String	registerModelListener(ModelListener listener, ModelEventsFilter filter, NotificationListenerFuse fuse) Registers a listener to be called when the model stored on the UCMDB server changes.
String	registerModelListener(ModelListener listener, ModelListenerFilter filter) Deprecated. replaced by registerModelListener(ModelListener listener, ModelEventsFilter filter)
String	registerQueryPassivationListener(QueryPassivationListener listener, String queryName)
void	registerQueryResultListener(QueryResultListener listener, String queryName) Registers a listener to be called when the result of the specified server-side query changes.
CisFromCachedQueryResults	retrieveCiIdsFromCachedQueryResults(Collection<UcmdbId> ids, Set<String> queryNames) Searches for each of the given CI IDs in the cached results of the queries given.
CIsChunk	retrieveCIsSortedChunk(ExecutableQuery executableQuery, String nodeName, List<AttributeSortingRule> attributeSortingRules) Executes the executable query and returns the CIs matching the node name, sorted by the specified sorting rules.
CIsChunk	retrieveCIsSortedChunk(ExecutableQuery executableQuery, String nodeName, List<AttributeSortingRule> attributeSortingRules, int chunkIndex) Executes the given executable query and returns 'nth chunk of CIs matching the node name, sorted by the given sorting rules.
CIsChunk	retrieveCIsSortedChunkInBDMScope(ExecutableQuery executableQuery, String nodeName, List<AttributeSortingRule> attributeSortingRules) Executes the executable query within the BDM scope and returns the CIs matching the node name, sorted by the specified sorting rules.
CIsChunk	retrieveCIsSortedChunkInBDMScope(ExecutableQuery executableQuery, String nodeName, List<AttributeSortingRule> attributeSortingRules, int chunkIndex) Executes the given executable query within the BDM scope and returns 'nth chunk of CIs matching the node name, sorted by the given sorting rules.
ElementIdsForChangedCachedQueries	retrieveElementIdsForChangedCachedQueries(QueryNamesAndVersions queryNamesAndVersions, ElementIdsForChangedCachedQueriesOptions options) Checks the results of each of the given queries in the queryNamesAndVersions and, if they're cached and updated, returns that result (as ids only).
Topology	retrieveIndirectLinkPaths(ExecutableQuery executableQuery, Set<IndirectLinkDescriptor> indirectLinkDescriptors) Retrieves the indirect link internal paths for the given descriptors.
Query	stringToInitializedQuery(String str) Returns an initialized Query that holds a copy of the original query or query reference definition used to create the string.
QueryDefinition	stringToQueryDefinition(String str) Returns a copy of the original query definition used to create the string.
void	unregisterModelListener(String listenerId) Unregisters the specified model listener.
void	unregisterQueryPassivationListener(String listenerId)
void	unregisterQueryResultListener(QueryResultListener listener, String queryName) Unregisters the specified listener.
void	updateFilteredModelListener(String listenerId, ModelEventsFilter filter) Updates model listener filter definition.
void	updateFilteredModelListener(String listenerId, ModelListenerFilter filter) Deprecated. replaced by updateFilteredModelListener(String listenerId, ModelEventsFilter filter)
boolean	validateBDMQuery(QueryDefinition queryDefinition) Checks if the query definition is BDM compliant.

Method Detail

createQueryStub

Query createQueryStub(String queryName)

Creates a Query stub that holds the query name and allows retrieval of the query definition (or reference definition, if applicable).

It is possible to create Query stubs for non-existent queries, but further operations on those stubs will fail.

This method does not communicate with the UCMDB server. However, operations from the stub object do communicate with the server. They fetch the query definition and related information. See Query for details.

createExecutableQuery

ExecutableQuery createExecutableQuery(String queryName)

Creates an ExecutableQuery structure. The ExecutableQuery can be used to define customizations over a query execution, such as parameters values, restrictions, seperation to chunks, and so on.

It is possible to create an ExecutableQuery stubs for non-existant queries, but furthur execute operations will fail.

This method does not communicate with the UCMDB server.

getFactory

TopologyQueryFactory getFactory()

Returns the query factory.

Returns:

the query factory.

executeQuery

Topology executeQuery(QueryDefinition queryDefinition)
               throws UcmdbException

Executes a query defined on the client.

Parameters:

queryDefinition - the query to execute.

Returns:

result of the query.

Throws:

UcmdbException

executeNamedQuery

Topology executeNamedQuery(String queryName)
                    throws UcmdbException

Executes the query of the specified name. The query is stored on the server. This is a shortcut that can be used instead of:

 topologyQueryService.executeQuery(topologyQueryFactory.createNamedQuery(queryName).toExecutable());
 

Returns:

result of the query.

Throws:

UcmdbException

validateBDMQuery

boolean validateBDMQuery(QueryDefinition queryDefinition)
                  throws UcmdbException

Checks if the query definition is BDM compliant.

Parameters:

queryDefinition - the query definition.

Returns:

true if the query definition is BDM compliant.

Throws:

UcmdbException

executeNamedQueryInBDMScope

Topology executeNamedQueryInBDMScope(String queryName)
                              throws UcmdbException

Executes the query of the specified name within the BDM scope.

Returns:

result of the query.

Throws:

UcmdbException

executeQuery

Topology executeQuery(ExecutableQuery query)
               throws UcmdbException

Executes a query stored on the server and returns the result.

Returns:

result of the query.

Throws:

UcmdbException

Since:

8.0

executeQueryInBDMScope

Topology executeQueryInBDMScope(ExecutableQuery query)
                         throws UcmdbException

Executes a query that is stored on the server, within the BDM scope, and returns the result.

Returns:

result of the query.

Throws:

UcmdbException

See Also:

ExecutableQuery

evaluateQuery

TopologyCount evaluateQuery(QueryDefinition queryDefinition)
                     throws UcmdbException

Executes a query defined on the client and returns its result count.

Returns:

result count of the query.

Throws:

UcmdbException

evaluateNamedQuery

TopologyCount evaluateNamedQuery(String queryName)
                          throws UcmdbException

Executes the query of the specified name and return its result count.

Parameters:

queryName - The name of a query that is stored on the server

Returns:

result count of the query.

Throws:

UcmdbException

evaluateQueryWithClassesBreakdown

@NotFinalAPI
TopologyCountByClasses evaluateQueryWithClassesBreakdown(ExecutableQuery query,
                                                                      Collection<String> elementNamesToCount)
                                                               throws UcmdbException

Executes a query stored on the server and returns the result count break-down by classes.

The structure returned is hierarchical. For example, host H1 will affect the count of "host", "infrastructure_element", "configuration_item" and "object".

Parameters:

query - the query definition.

elementNamesToCount - the element names to count. If empty or null, counts all elements.

Returns:

result count break down by classes of the query.

Throws:

UcmdbException

evaluateQueryWithClassesBreakdown

@NotFinalAPI
TopologyCountByClasses evaluateQueryWithClassesBreakdown(QueryDefinition queryDefinition,
                                                                      Collection<String> elementNamesToCount)
                                                               throws UcmdbException

Executes a query defined on the client and return its result count break-down by classes.

The structure returned is hierarchical. For example, host H1 will affect the count of "host", "infrastructure_element", "configuration_item" and "object".

Parameters:

queryDefinition - the query definition.

elementNamesToCount - the element names to count. If empty or null, counts all elements.

Returns:

result count break down by classes of the query

Throws:

UcmdbException

evaluateNamedQueryWithClassesBreakdown

@NotFinalAPI
TopologyCountByClasses evaluateNamedQueryWithClassesBreakdown(String queryName,
                                                                           Collection<String> elementNamesToCount)
                                                                    throws UcmdbException

Executes the query of the specified name and return its result count break-down by classes.

The structure returned by this is hierarchical. For example, host H1 will affect the count of "host", "infrastructure_element", "configuration_item" and "object".

Parameters:

queryName - The name of a query that is stored on the server

elementNamesToCount - the element names to count. If empty or null, counts all elements.

Returns:

result count break down by classes of the query.

Throws:

UcmdbException

evaluateQuery

TopologyCount evaluateQuery(ExecutableQuery query)
                     throws UcmdbException

Executes a query stored on the server and returns the result count.

Returns:

result count of the query

Throws:

UcmdbException

getLiveQuery

LiveQuery getLiveQuery(String queryName)

Returns a query whose result is always kept updated on server side. LiveQuery allows to get the query result and track changes over the result.

Parameters:

queryName - the name of the query. A query with this name must exist in the UCMDB and must be active.

Returns:

the live query.

See Also:

LiveQuery

registerQueryResultListener

void registerQueryResultListener(QueryResultListener listener,
                                 String queryName)
                          throws UcmdbException

Registers a listener to be called when the result of the specified server-side query changes. The query must be: stored on the UCMDB server, active, and persistent. There may be a delay of several minutes between the change in topology and the notification. The length of the delay depends on the query's priority and other factors.

Parameters:

listener - client-side implementation of the listener interface.

queryName - name of an active query stored at the server.

Throws:

UcmdbException

Since:

8.0

unregisterQueryResultListener

void unregisterQueryResultListener(QueryResultListener listener,
                                   String queryName)
                            throws UcmdbException

Unregisters the specified listener.

Parameters:

listener - client-side implementation of the listener interface

Throws:

UcmdbException

Since:

8.0

registerQueryPassivationListener

String registerQueryPassivationListener(QueryPassivationListener listener,
                                        String queryName)

unregisterQueryPassivationListener

void unregisterQueryPassivationListener(String listenerId)

registerModelListener

void registerModelListener(ModelListener listener)
                    throws UcmdbException

Deprecated. replaced by registerModelListener(ModelListener listener, ModelEventsFilter filter)

Registers a listener to be called when the model stored on the UCMDB server changes. There may be a delay of several minutes between the change in the model and the notification.

Parameters:

listener - client-side implementation of the listener interface

Throws:

UcmdbException

Since:

8.0

registerModelListener

@NotFinalAPI
String registerModelListener(ModelListener listener,
                                          ModelEventsFilter filter)
                                   throws UcmdbException

Registers a listener to be called when the model stored on the UCMDB server changes. Changes are filtered by the given filter. There may be a delay of several minutes between the change in the model and the notification.

Parameters:

listener - client-side implementation of the listener interface

filter - definition

Returns:

listener id - indentify the listener for remove or update..

Throws:

UcmdbException

Since:

9.0

registerModelListener

@NotFinalAPI
String registerModelListener(ModelListener listener,
                                          ModelEventsFilter filter,
                                          NotificationListenerFuse fuse)
                                   throws UcmdbException

Registers a listener to be called when the model stored on the UCMDB server changes. Changes are filtered by the given filter. There may be a delay of several minutes between the change in the model and the notification. Receives a fuse that defines the maximum notification queue size and provides the callback to call when the queue size reaches that maximum.

Parameters:

listener - client-side implementation of the listener interface

filter - definition

fuse - the notification queue size fuse

Returns:

listener id - indentify the listener for remove or update..

Throws:

UcmdbException

Since:

9.0

registerModelListener

@NotFinalAPI
String registerModelListener(ModelListener listener,
                                          ModelListenerFilter filter)
                                   throws UcmdbException

Deprecated. replaced by registerModelListener(ModelListener listener, ModelEventsFilter filter)

Registers a listener to be called when the model stored on the UCMDB server changes. Changes are filtered. There may be a delay of several minutes between the change in the model and the notification.

Parameters:

listener - client-side implementation of the listener interface

filter - filter definition.

Returns:

listener the listener to register.

Throws:

UcmdbException

Since:

9.0

unregisterModelListener

@NotFinalAPI
void unregisterModelListener(String listenerId)
                                   throws UcmdbException

Unregisters the specified model listener.

Parameters:

listenerId - the listener id returned from registerModelListener(com.hp.ucmdb.api.topology.notification.ModelListener, com.hp.ucmdb.api.topology.notification.ModelEventsFilter).

Throws:

UcmdbException

Since:

9.0

updateFilteredModelListener

@NotFinalAPI
void updateFilteredModelListener(String listenerId,
                                              ModelEventsFilter filter)
                                       throws UcmdbException

Updates model listener filter definition.

Parameters:

listenerId - the listener id returned from registerModelListener(com.hp.ucmdb.api.topology.notification.ModelListener, com.hp.ucmdb.api.topology.notification.ModelEventsFilter)

filter - the filter definition for update.

Throws:

UcmdbException

Since:

9.0

updateFilteredModelListener

@NotFinalAPI
void updateFilteredModelListener(String listenerId,
                                              ModelListenerFilter filter)
                                       throws UcmdbException

Deprecated. replaced by updateFilteredModelListener(String listenerId, ModelEventsFilter filter)

Updates the model listener filter definition.

Parameters:

listenerId - the listener id returned from registerModelListener(com.hp.ucmdb.api.topology.notification.ModelListener, com.hp.ucmdb.api.topology.notification.ModelEventsFilter)

filter - the filter definition for update.

Throws:

UcmdbException

Since:

9.0

retrieveCIsSortedChunk

@NotFinalAPI
CIsChunk retrieveCIsSortedChunk(ExecutableQuery executableQuery,
                                             String nodeName,
                                             List<AttributeSortingRule> attributeSortingRules)

Executes the executable query and returns the CIs matching the node name, sorted by the specified sorting rules. If the number of CIs is greater than the number set in ExecutableQuery.setMaxChunkSize(int), the result is divided into chunks and only the first chunk is returned. The other chunks can be accessed by index using the retrieveCIsSortedChunk(ExecutableQuery executableQuery, String nodeName, List attributeSortingRules, int chunkIndex) method.

You can also use the more verbose method (taking the chunkIndex parameter) to access the first chunk.

Parameters:

executableQuery - the executable query to run.

nodeName - the node name to return the CIs for. Resulting CIs from all other nodes are ignored.

attributeSortingRules - an ordered collection of the sorting rules.

Returns:

the CIs chunk that holds the resulting CIs and information about the availability of more chunks.

retrieveCIsSortedChunk

@NotFinalAPI
CIsChunk retrieveCIsSortedChunk(ExecutableQuery executableQuery,
                                             String nodeName,
                                             List<AttributeSortingRule> attributeSortingRules,
                                             int chunkIndex)

Executes the given executable query and returns 'nth chunk of CIs matching the node name, sorted by the given sorting rules. The result is divided into chunks based on the result size and the the number set in ExecutableQuery.setMaxChunkSize(int). The first chunk has index of 0 (even if it's empty).

Passing an index out of range results in an empty chunk returned.

Parameters:

executableQuery - the executable query to run. May not be null.

nodeName - the node name to return the CIs for. Resulting CIs from all other nodes are ignored. May not be null.

attributeSortingRules - an ordered collection of the sorting rules. May not be null, may be empty. Rules can be created by getFactory().TopologyQueryFactory.createAttributeSortingOrderElement(String, AttributeSortingOrderElementDirection)

chunkIndex - the index of the chunk to retrieve. Must not be negative.

Returns:

the CIs chunk that holds the resulting CIs and information about the availability of more chunks.

retrieveCIsSortedChunkInBDMScope

@NotFinalAPI
CIsChunk retrieveCIsSortedChunkInBDMScope(ExecutableQuery executableQuery,
                                                       String nodeName,
                                                       List<AttributeSortingRule> attributeSortingRules)

Executes the executable query within the BDM scope and returns the CIs matching the node name, sorted by the specified sorting rules. If the number of CIs is greater than the number set in ExecutableQuery.setMaxChunkSize(int), the result is divided into chunks and only the first one is returned. The other chunks can be accessed by index using the retrieveCIsSortedChunk(ExecutableQuery executableQuery, String nodeName, List attributeSortingRules, int chunkIndex) method.

You can also use the more verbose method (taking the chunkIndex parameter) to access the first chunk.

Parameters:

executableQuery - the executable query to run.

nodeName - the node name to return the CIs for. Resulting CIs from all other nodes are ignored.

attributeSortingRules - an ordered collection of the sorting rules.

Returns:

the CIs chunk that holds the resulting CIs and information about the availability of more chunks.

retrieveCIsSortedChunkInBDMScope

@NotFinalAPI
CIsChunk retrieveCIsSortedChunkInBDMScope(ExecutableQuery executableQuery,
                                                       String nodeName,
                                                       List<AttributeSortingRule> attributeSortingRules,
                                                       int chunkIndex)

Executes the given executable query within the BDM scope and returns 'nth chunk of CIs matching the node name, sorted by the given sorting rules. The result is divided into chunks based on the result size and the the number set in ExecutableQuery.setMaxChunkSize(int). The first chunk has index of 0 (even if it's empty).

Passing an index out of range results in an empty chunk returned.

Parameters:

executableQuery - the executable query to run. May not be null.

nodeName - the node name to return the CIs for. Resulting CIs from all other nodes are ignored. May not be null.

attributeSortingRules - an ordered collection of the sorting rules. May not be null, may be empty. Rules can be created by getFactory().TopologyQueryFactory.createAttributeSortingOrderElement(String, AttributeSortingOrderElementDirection)

chunkIndex - the index of the chunk to retrieve. Must not be negative.

Returns:

the CIs chunk that holds the resulting CIs and information about the availability of more chunks.

retrieveCiIdsFromCachedQueryResults

CisFromCachedQueryResults retrieveCiIdsFromCachedQueryResults(Collection<UcmdbId> ids,
                                                              Set<String> queryNames)

Searches for each of the given CI IDs in the cached results of the queries given.

Results of non-cached queries are not searched. Note: If a query was defined active, but was set not to keep result in repository - it will not be searched.

Parameters:

ids - CI IDs. Do not pass relation IDs.

queryNames - queries to search in

Returns:

CisFromCachedQueryResults with a map of UcmdbId to query names and a set of non-cached query names.

retrieveElementIdsForChangedCachedQueries

@NotFinalAPI
ElementIdsForChangedCachedQueries retrieveElementIdsForChangedCachedQueries(QueryNamesAndVersions queryNamesAndVersions,
                                                                                         ElementIdsForChangedCachedQueriesOptions options)

Checks the results of each of the given queries in the queryNamesAndVersions and, if they're cached and updated, returns that result (as ids only).

Given a set of queries to check (along with the last result version that the client has), this method will return the ids participating in the updated results. This method is useful in case only the ids are needed, when the expected queries results are relatively small and when these queries results are guaranteed to be in the CMDB result cache - either QueryDefinitionFirstLoadStrategy.LOAD_ON_SERVER_START or active and executed before.

Only updated (or forced) query results are returned. Each of these is returned as an id collection only. In addition, the result version is returned as well - that version should be supplied to a later invocation of this method to allow only the updated results to be returned.

Note: Like all active queries, an updated result may be during to topological change, definition change or properties change. In addition, a false update may occur (rare case) as well. Additional Note: If a query was defined active, but was set not to keep result in repository - the ids collection will be returned empty, even if the query was updated or enforced to be check.

Parameters:

queryNamesAndVersions - the query names and matching versions to check (or query names to return results for, regardless of versions).

options - an options object - determines the behavior of the service (e.g. are relation ids returned as well?)

Returns:

an object containing the updated queries result (as ids).

hasChanges

@NotFinalAPI
boolean hasChanges(String queryName,
                                QueryResultVersion queryResultVersion)

Checks if the results of the query were changed since the result version was created.

This method applies to saved and active queries whose result is still cached in the CMDB memory. In addition to examining the query definition (QueryDefinition.recalcPriority() or QueryReferenceDefinition.recalcPriority()), it is also possible to query the resulting Topology using the Topology.querySupportsHasChanges() method.

This method does not take into account the properties of CIs and Relations that do not participate in the query properties conditions.

Implementation notes:

• If the result is still cached, calling this method also resets the eviction timeout.
• While it's rare, it is possible to get a false positive from this method (true when it should have been false).

Parameters:

queryName - the query to check.

queryResultVersion - the version to check changes from.

Returns:

true if there were any changes in the query results. false if no changes or if the query does not support changes.

hasChanges

@NotFinalAPI
boolean hasChanges(String queryName,
                                String queryResultVersionAsString)

Same as hasChanges(String, QueryResultVersion), but is passed the result of {QueryResultVersion#asString()}.

Parameters:

queryName - the query to check.

queryResultVersionAsString - the asString() result of the version to check changes from.

Returns:

true if there were any changes in the query results, false if no changes or if the query does not support changes.

See Also:

hasChanges(String, QueryResultVersion)

hasChanges

@NotFinalAPI
Set<String> hasChanges(Map<String,QueryResultVersion> queries2check)

Same as hasChanges(String, QueryResultVersion), but is passed a collection of queries and their version to check for changes

Parameters:

queries2check - a collection of (query name, query result version) pairs

Returns:

a set of query names, sub set of the given query names, whose result has changed.

See Also:

hasChanges(String, QueryResultVersion)

retrieveIndirectLinkPaths

@NotFinalAPI
Topology retrieveIndirectLinkPaths(ExecutableQuery executableQuery,
                                                Set<IndirectLinkDescriptor> indirectLinkDescriptors)

Retrieves the indirect link internal paths for the given descriptors.

Executing a query that contains indirect links without the "show entire path" flag will result in a Topology with "virtual" relations that represents paths of one or more underlying relations. These underlying paths may be retrieved using this method. By supplying the exact same executable query that originated the original topology and a set of request descriptors (source ids, target ids, link node name and, if needed, properties request for the resulting topologies), these underlying paths may be retrieved as a Topology object.

Implementation note: an additional query execution may occur during this request.

Parameters:

executableQuery - the executable query that originated the topology from which the indirect link paths are requried.

indirectLinkDescriptors - the descriptors, created by TopologyQueryFactory.createIndirectLinkDescriptor().

Returns:

the underlying paths topology.

queryDefinitionToString

String queryDefinitionToString(QueryDefinition queryDefinition)
                        throws UcmdbException

Returns the query's string representation.

The conversion from QueryDefinition to string is done in the server, requiring a server request.

This string representation may not be version compatible and should not be serialized for long term storage.

Parameters:

queryDefinition - the query definition to convert to a string

Returns:

String repesentation of the given query definition

Throws:

UcmdbException

stringToQueryDefinition

QueryDefinition stringToQueryDefinition(String str)
                                 throws UcmdbException

Returns a copy of the original query definition used to create the string. The input string is created by a call to queryDefinitionToString.

The conversion from string to QueryDefinition is done on the server, requiring a server request.

Parameters:

str - the query's string represntation

Returns:

query definition represnted by the given str

Throws:

UcmdbException

queryReferenceDefinitionToString

String queryReferenceDefinitionToString(QueryReferenceDefinition queryReferenceDefinition)

Returns the query refernce's string representation.

The conversion from QueryReferenceDefinition to string is done on the server, requiring a server request.

This string representation may not be version compatible and should not be serialized for long term storage.

Parameters:

queryReferenceDefinition - - the query reference definition to convert

Returns:

String representation of the given query definition

stringToInitializedQuery

Query stringToInitializedQuery(String str)

Returns an initialized Query that holds a copy of the original query or query reference definition used to create the string. The input string is created by a call to queryReferenceDefinitionToString or queryDefinitionToString

The conversion is done on the server, requiring a server request.

Note2: Unlike the general contract for Query, the return value from this method does NOT represent a query stored on the CMDB server.

Parameters:

str - - query's string representation

Returns:

an initialized query represented by the given str

executeQueriesTree

@NotFinalAPI
Topology executeQueriesTree(QueriesExecutionBulk queriesExecutionBulk)

Executes tree of queries, returning the top-most query result.

This method receives a bulk of query definitions (and reference definitions) and assumes that they can be used to build a tree of inter-dependant queries (using restrictions and references). The UCMDB will then attempt to execute the top-most query in this tree. Dependencies will be resolved by first attempting to find the relevant query in the given bulk, then by trying to find it in the saved queries repository.

The returned topology is that of the top-most (dependency-wise) query.

If the given query definitions do not resolve to a tree (even with completion from the query repository) - either if there are "holes", cycles or more than one "top" (query that no other queries depend on) an exception will be thrown.

Parameters:

queriesExecutionBulk - a bulk of query definitions that is resolvable to a tree (dependency-wise) with the aid of already saved queries.

Returns:

the topology of the top-most query.

Since:

UCMDB 9.02

isActiveQueryInFailedState

@NotFinalAPI
boolean isActiveQueryInFailedState(String queryName)
                                         throws UcmdbException

Checks if the given query is defined ACTIVE in UCMDB and is currently in FAILED state. An active query might be in FAILED state if its last calculation did not finish successfully. This might result from exceeding predefined calculation fuses, such as maximal number of CIs in the query result, or maximal number of CIs visited during calculation. A query which is in FAILED state will keep returning the last-successful-calculation result when calling evaluateQuery and executeQuery methods in this service. Notifications on changes to query result won't be sent for listeners of query in a FAILED state.

Parameters:

queryName - the query name.

Returns:

true if the query is defined in UCMDB in active mode and it is currently in FAILED state.

Throws:

UcmdbException - If the Query is not defined in UCMDB, or if it not defined ACTIVE

Since:

UCMDB 9.05