Target Communication Framework Services - Context Query

• Version History
• Overview
• Syntax and Semantics
• Commands
  • Query
  • Get Attribute Names
• API

Context Query Service

Version History

Overview

ContextQuery allows to search for context that match a pattern.

This module implements a query based system to specify subsets of contexts. The queries specifies context properties and what values they need to have to match. In addition a query can filter based on a contexts ancestors in the context hierarchy.

A query consists of a sequence of parts separated by "/". This sequence specifies a path through the context tree. A context matches the query if the last part of the query matches the properties of the context and the parent of the context matches the query excluding the last part. The properties of a context matches a part if each property specified in the part matches the property of the same name in the context or if the name of the context matches the string specified in the part. There are also two wild cards. The part "*" matches any context. The part "**" matches any sequence of contexts. If the query starts with a "/" the first part of the query must match a child of the root of the context tree.

The service uses standard format for error reports, see Error Report Format.

Syntax and Semantics

Here is how a query should be formed:

<query> = ['/'], {<part>, '/'}, <part> ;
<part> = <string> | '*' | '**' | <properties> ;
<properties> = <property>, {',', <property>} ;
<property> = <string>, '=', <value> ;
<value> = <string> | <number> | <symbol> ;
<string> = <quoted string> | <symbol> ;
<quoted string> = '"', {any-character - ('"' | '\')|('\'), ('"' | '\')}, '"' ;
<symbol> = <letter>, {<letter> | <digit>} ;
<number> = <digit>, {<digit>} ;
<boolean> = 'true' | 'false' ;
<letter> = ? A-Z, a-z or _ ? ;
<digit> = ? 0-9 ?
<any-character> = ? any character ? ;

Commands

Query

C • <token> • ContextQuery • query • <query> •

Execute a context query and return array of matching context IDs.

Reply:

R • <token> • <error report> • <array of context IDs> •

The contexts are assumed to be placed in a tree. Each context has zero or one parent. If it has zero parents it is a child of the root of the tree.

Examples:

Matches all contexts named "httpd".

Matches any context with a property pid, which has the value 4711.

Matches all contexts which are descendants of the top level context named "server".

Matches all kernel processes in operating systems named "Linux 2.6.14".

All threads in processes with the pid 4711.

All threads which are descendants of the context "server".

Get Attributes Names

C • <token> • ContextQuery • getAttrNames •

Get the list of attribute names available for context queries. The "*" attribute means that a default attribute comparator exists, in which case, the back-end may support additional attributes that are not listed in the reply.

Reply:

R • <token> • <error report> • <array of attributes> •

API

/**
 * ContextQuery allows to search for context that match a pattern.
 *
 * Query Syntax and Semantics
 *
 *        query = [ "/" ], { part, "/" }, part ;
 *        part = string | "*" | "**" | properties ;
 *        properties = property, { ",", property } ;
 *        property = string, "=", value ;
 *        value = string | number | boolean ;
 *        string = quoted string | symbol ;
 *        quoted string = '"', {any-character - ('"' | '\') | ('\', ('"' | '\'))}, '"' ;
 *        symbol = letter, { letter | digit } ;
 *        number = digit, { digit } ;
 *        boolean = "true" | "false" ;
 *        letter = ? A-Z, a-z or _ ? ;
 *        digit = ? 0-9 ? ;
 *        any-character = ? any character ? ;
 *
 * To give a feel for the syntax, here are some examples, and what a user
 * might mean when providing such a query:
 *
 * httpd
 *        Matches all contexts named "httpd".
 *
 * pid=4711
 *        Matches any context with a property pid, which has the value 4711.
 *
 * /server/**
 *        Matches all contexts which are descendants of the top level context
 *        named "server".
 *
 * "Linux 2.6.14"/Kernel/*
 *       Matches all kernel processes in operating systems named "Linux 2.6.14".
 *
 * pid=4711/*
 *        All threads in processes with the pid 4711.
 *
 * /server/** /HasState=true
 *        All threads which are descendants of the context "server".
 *
 * The contexts are assumed to be placed in a tree. Each context has zero
 * or one parent. If it has zero parents it is a child of the root of the
 * tree.
 *
 * A query consists of a sequence of parts separated by "/". This
 * sequence specifies a path through the context tree. A context matches
 * the query if the last part of the query matches the properties of the
 * context and the parent of the context matches the query excluding the
 * last part. The properties of a context matches a part if each property
 * specified in the part matches the property of the same name in the
 * context or if the name of the context matches the string specified in
 * the part. There are also two wild cards. The part "*" matches any
 * context. The part "**" matches any sequence of contexts. If the query
 * starts with a "/" the first part of the query must match a child of
 * the root of the context tree.
 *
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IContextQuery extends IService {

    /**
     * This service name, as it appears on the wire - a TCF name of the service.
     */
    static final String NAME = "ContextQuery";

    /**
     * Execute a context query and return array of matching context IDs.
     * @param query - context query string.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken query(String query, DoneQuery done);

    /**
     * Call back interface for 'query' command.
     */
    interface DoneQuery {
        /**
         * Called when 'query' command is done.
         * @param token - command handle.
         * @param error - error object or null.
         * @param contexts - array of context IDs.
         */
        void doneQuery(IToken token, Exception error, String[] contexts);
    }

    /**
     * Get list of attribute names available for context queries.
     * @param done - command result call back object.
     * @return - pending command handle.
     */
    IToken getAttrNames(DoneGetAttrNames done);

    /**
     * Call back interface for 'getAttrNames' command.
     */
    interface DoneGetAttrNames {
        /**
         * Called when 'query' command is done.
         * @param token - command handle.
         * @param error - error object or null.
         * @param contexts - array of context IDs.
         */
        void doneGetAttrNames(IToken token, Exception error, String[] names);
    }
}