Manipulating Queries in Topology

QueryExecution

The CORBA object QueryExecution models the evaluation of a query. These objects are created by a QueryExecutionFactory CORBA object (see Topology Query ).

This interface supports operations to get the status of a query, stop the execution of the query, retrieve the query string, and retrieve the results from the execution of the query.

The lifecycle of a query consists of its creation via the QueryExecutionFactory at which point the query evaluation begins. The client may then inquire as to the current status of the query, may prematurely stop the query, or may begin requesting query results via the get_next or get_all operations. When the query execution has been completed and the last query result has been requested - either via get_next or get_all - then the QueryExecution object destroys itself.

All interfaces are expressed in CORBA IDL. They are grouped under TopologyQuery.idl.

NAME - DESCRIPTION

Stop - This operation is used to stop (abort) the execution of the query and destroys this QueryExecution.

SIGNATURE

void stop()
	raises (Topology::ServerNotContactable);

SEMANTICS

This operation stops the evaluation of a query and destroys this QueryExecution.

EXCEPTIONS RAISED

[Topology::ServerNotContactable]

Returned if the topology server required to complete this operation is not contactable.

NAME - DESCRIPTION

Get_Status - This operation is used to get the status of a QueryExecution.

SIGNATURE

QueryExecutionStatus get_status()
	raises (Topology::ServerNotContactable);

PARAMETERS

Input/Output

There are no input or output parameters for this operation.

Return

This operation returns the status of the evaluation of a query.

SEMANTICS

This operation returns the status of the evaluation of a query. The meaning of each of the fields in the QueryExecutionStatus is as follows:

truth_of_proposition

indicates whether the query is a true logical proposition on topology

partial

indicates whether the results for this query are all the result that may exist (for example, a possible result may be missing due to one of the topology servers being down in an installation)

finished

indicates whether the evaluation of the query is complete

num_result

indicates the number of individual results that have been obtained so far for this query.

A query represents a logical proposition on topology. This operation sets the truth_of_proposition field of the QueryExecutionStatus to be the result of that logical proposition. The truth_of_proposition flag is the only mechanism through which a client can obtain the result of a query executed with the QueryResultOption of QRO_TRUTH. A query executed with this option will never return any topological data as part of the results, and so it is not possible to determine the result of the logical proposition of a query by looking at the list of results. If truth_of_proposition is FALSE then any result data returned from get_next or get_all will be undefined.

If it is possible that there may be more results to this query than those that can be obtained, then the partial field of the QueryExecutionStatus will be set to TRUE.

When a query is evaluated, it is possible that some of the topology servers in the installation may not be contactable. This may force the evaluation to disregard possible results as one of these topology servers may be needed to obtain a complete result. If this happens then the results of the evaluation will be flagged as partial. The partial flag may also be true when the query was evaluated with a result option of QRO_TRUTH or QRO_ANY.

A query has the following status until a result has been found for the query (that is, before the notification's interimResult has been sent):

truth_of_proposition

= FALSE

partial

= TRUE

finished

= FALSE

num_results

= 0

EXCEPTIONS RAISED

[Topology::ServerNotContactable]

Returned if the topology server required to complete this operation is not contactable.

NAME - DESCRIPTION

Get_Query - This operation is used to return the query string represented by this QueryExecution.

SIGNATURE

string get_query()
	raises (Topology::ServerNotContactable);

PARAMETERS

Input/Output

There are no input or output parameters for this operation.

Return

The TQL query in its expanded form.

SEMANTICS

When a TQL string is given to a QueryExecutionFactory, the string is manipulated before being used to create a QueryExecution. This manipulation includes resolving references to other queries, instantiation of parameters, and optimization. This operation allows a client to obtain the TQL string that results from this manipulation process, and therefore to have access to the "real" query that will be executed by this QueryExeuction.

EXCEPTIONS RAISED

[Topology::ServerNotContactable]

Returned if the topology server required to complete this operation is not contactable.

NAME - DESCRIPTION

Get_Next - This operation is used to get the next individual result for this query and destroys the QueryExeuction if this is the last result.

SIGNATURE

void get_next (	
		out QueryExecutionStatus status,
		out QueryResult result_data)
	raises (Topology::ServerNotContactable);

PARAMETERS

Output

status

The status of the executed query.

result_data

The individual result of the executed query.

SEMANTICS

This operation returns the next individual result that is available for the executed query. Once a result has been retrieved through this operation, the result is removed from the cache and is no longer available. The status is returned as described for get_status. If the num_results field of the status is zero, and the finished field of status is TRUE, then the contents of result_data are undefined. If the execution of the query is complete and this call to get_next returns the last result, then the QueryExecution is destroyed at the completion of this operation.

EXCEPTIONS RAISED

[Topology::ServerNotContactable]

Returned if the topology server required to complete this operation is not contactable.

NAME - DESCRIPTION

Get_All - This operation is used to get all of the remaining results for the executed query and then destroys the QueryExecution.

SIGNATURE

void get_all ( 
		in QueryResultFormat result_format,
		out QueryExecutionStatus status,
		out QueryResults result_data)
	raises (Topology::ServerNotContactable);

PARAMETERS

Input

result_format

Indicates the format in which the result should be returned. Alternatives are as a combination of all of the individual results for the query (COMBINED_RESULT) or as a list of individual results for the query (SEPARATE_RESULTS).

Output

status

The status of the executed query.

result_data

The results of the executed query.

SEMANTICS

This operation returns all of the remaining results for the query (that is, all of the results for the query less those already returned via the get_next operation). The status is returned as described for get_status. If the num_results field of status is zero, and the finished field of status is TRUE, then the contents of result_data are undefined.

The QueryExecution is destroyed after this operation completes.

EXCEPTIONS RAISED

[Topology::ServerNotContactable]

Returned if the topology server required to complete this operation is not contactable.

QueryExecutionFactory

NAME - DESCRIPTION

Create - This operation is used to create a QueryExecution.

SIGNATURE

QueryExecution create (
		in string tql_string, 
		in ParameterBindings parameters,
		in QueryResultOption result_option) 
	raises (CompileError,
		OVTopology::ServerNotContactable);

PARAMETERS

Input

tql_string

The query to be evaluated.

parameters

The actual values for arguments to the query.

result_option

The way that the results will be generated.

Return

A new QueryExecution object.

SEMANTICS

This operation creates a QueryExecution object and returns an object reference it.

If the I result_option is QRO_ALL, the the query is executed and the execution will attempt to find all valid answers to this query. If the result_option is QRO_ANY, then the query is executed and the execution will attempt to find no more than one answer to this query. If the result_option is QRO_TRUTH, then the query is executed and the execution will only attempt to answer the logical proposition formed by this query.

EXCEPTIONS RAISED

[CompileError]

Returned if the query is not syntactically valid. The details of the error which occurred during the compile of the query are included in the error message.

[Topology::ServerNotContactable]

Returned if the topology server required to complete this operation is not contactable.

NAME - DESCRIPTION

Create_With_Filter - This operation allows the client to filter on specific types of entities or specific tags, to reduce the amount of data returned from a query.

SIGNATURE

QueryExecution create_with_filter (
		in string tql_string,
		in ParameterBindings parameters,
		in QueryResultOption result_option,
		in QueryResultFilterList result_filter_list)
	raises (
		CompileError,
		Topology::ServerNotContactable);

PARAMETERS

Input

tql_string

The query to be evaluated.

parameters

The actual values for arguments to the query.

result_option

The way that the results will be generated.

result_filter_list

The filters to be applied to the returned result.

Return

A new QueryExecution object.

SEMANTICS

This operation behaves similarly to the create operation with the additional semantics that as the query is executed and the result is built the specified filters are applied.

The result_filter_list parameter specifies a number of filters to be applied to the results returned to the client. The filter_type field of a particular filter specifies whether the filter applies to topological types (TYPE_FILTER) or to tags (TAG_FILTER). In the case of a topological type filter the select_list specifies 1 or more topological types, in the case of a tag filter the select_list specifies 1 or more tags or the special string "*" which is used to indicate any tag.

If the result_filter_list is an empty sequence then no result filtering occurs, otherwise each item in the sequence specifies a filter which restricts the entities and aggregate entities which appear in the query result.

In order to appear in the result an entity must satisfy all of the type filters in the list. An entity in the result satisfies a filter of type TYPE_FILTER if its topological type matches (taking inheritance of topological types into account) at least one of the topological types in the select_list.

An aggregate entity in the result satisfies a filter of type TAG_FILTER if the aggregate entity matched an AE pattern in the query which was tagged and either the select_list contains the string "*", or the tag for that aggregate entity matches at least one of the tags in the select_list.

EXCEPTIONS RAISED

[CompileError]

Returned if the query is not syntactically valid. The details of the error which occurred during the compile of the query are included in the error message.

[Topology::ServerNotContactable]

Returned if the topology server required to complete this operation is not contactable.

TopologyQuery.idl File

#if !defined (TOPOLOGYQUERY_IDL)
#define TOPOLOGYQUERY_IDL

#include <Topology.idl>
#include <TopologyData.idl>

module TopologyQuery {

	typedef sequence<string> StringList;

	typedef sequence<unsigned long> IndexList;

	enum QueryResultFilterType {TYPE_FILTER, TAG_FILTER};

	struct QueryResultFilter {
		QueryResultFilterType filter_type;
		StringList select_list;
	};

	typedef sequence <QueryResultFilter> QueryResultFilterList;
	struct QueryExecutionStatus {
		boolean truth_of_proposition;
		boolean partial;
		boolean finished;
		short num_results;
	};

	struct QueryResultAssociation {
		unsigned long pred_aggregate;
		unsigned long pred_entity;
		unsigned long pred_role;
		unsigned long succ_aggregate;
		unsigned long succ_entity;
		unsigned long succ_role;
	};

	typedef sequence <QueryResultAssociation> QueryResultAssociationList;
	struct QueryResultEntity {
		Topology::TopologicalEntity entity;
		unsigned long aggregate;
		unsigned long type;
	};

	typedef sequence <QueryResultEntity> QueryResultEntityList;

	struct QueryResultAggregate {
		IndexList entities;
		IndexList tags;
	};

	typedef sequence <QueryResultAggregate> QueryResultAggregateList;

	struct QueryResult {
		QueryResultEntityList entities;
		QueryResultAggregateList aggregates;
		QueryResultAssociationList associations;
		StringList types;
		StringList roles;
		StringList tags;
	};

	typedef sequence <QueryResult> QueryResults;

	enum QueryResultFormat {COMBINED_RESULT, SEPARATE_RESULTS};

	typedef string RegisteredQueryName;

	typedef sequence <RegisteredQueryName> RegisteredQueryNameList;

	enum QueryResultOption {
		QRO_ALL,
		QRO_ANY,
		QRO_TRUTH
	};

	struct ParameterBinding {
		string parameter_name;
		string parameter_value;
	};

	typedef sequence <ParameterBinding> ParameterBindings;

	exception CompileError	{string reason;};

	exception InvalidFilter	{ };

	interface QueryExecution {

		// Life-cycle operations

		void stop ( ) 
			raises (Topology::ServerNotContactable);

		// Status operations

		QueryExecutionStatus 
		get_status ( ) 
			raises (Topology::ServerNotContactable);

		string get_query ( )
			raises (Topology::ServerNotContactable);

		// Result retrieval operations

		void get_next (
				out QueryExecutionStatus status,
				out QueryResult result_data)
			raises (Topology::ServerNotContactable);

		void get_all (
				in QueryResultFormat result_format,
				out QueryExecutionStatus status,
				out QueryResults result_data)
			raises (Topology::ServerNotContactable);
	};

	interface QueryExecutionFactory: CosTransactions::TransactionalObject {

		// Life-cycle operations

		QueryExecution create (
				in string tql_string, 
				in ParameterBindings parameters,
				in QueryResultOption result_option) 
			raises (CompileError,
				OVTopology::ServerNotContactable);

		QueryExecution create_with_filter (
				in string tql_string,
				in ParameterBindings parameters,
				in QueryResultOption result_option,
				in QueryResultFilterList result_filter_list)
			raises (CompileError,
				Topology::ServerNotContactable);
	};
};
#endif //TOPOLOGYQUERY_IDL