Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
Data Request Broker
2-3-release
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

fr.gael.drb.query
Class Query

java.lang.Object
  extended by fr.gael.drb.query.Query

public class Query
extends Object

Top level class for the evaluation of a query. The Query class is dedicated to the evaluation of an XQuery script. The XQuery shall comply the specifications laid down in the working draft http://www.w3.org/TR/2002/WD-xquery-20021115/ developed by the World Wild Web Consortium (W3C).

Interest of evaluating XQuery scripts

As large amounts of information are handled by the "Data Request Broker" (DRB), the ability to intelligently query the supported data sources becomes increasingly important. One of the great strengths of DRB is its flexibility in representing many different kinds of information from diverse sources. To exploit this flexibility, this class and all other of the present package (i.e. fr.gael.drb.query) implement a query engine that benefits from the emerging XQuery Language that provides features for retrieving and interpreting information from these data.

XQuery language

XQuery is a query language initially designed for querying XML documents. Detached from XML specificities, it provides however a large amount of features for any data source broken down in a tree of nodes and leaves. Almost all data sources have such hierarchical structure and thanks to DRB, it is possible to benefit from XQuery properties applied to these sources.

XQuery is designed to meet the requirements and the use cases identified by the W3C XML Query Working Group. It is designed to be a language in which queries are concise and easily understood. It is also flexible enough to query a broad spectrum of information sources, including both databases and documents. The Query Working Group has identified a requirement for both a human-readable query syntax and an XML-based query syntax. XQuery is designed to meet the first of these requirements. XQuery is derived from an XML query language called "Quilt", which in turn borrowed features from several other languages, including "XPath 1.0", "XQL", "XML-QL", "SQL" and "OQL".

XQuery is currently under development by the World Wild Web Consortium (W3C) Members. The language specifications have, however, reached a mature level of consolidation and it is possible today to consider that the language basics are stable enough to be implemented.

Basic principles of evaluation

The queries are processed in three main stages:

  1. Static compilation of the XQuery script
  2. Query plan optimization
  3. Dynamic evalutation

Static compilation

In the first hand, the query string provided at the construction is statically compiled to generate a tree of expressions, formally called the body expression. To perform this construction the XQuery script is syntactically and lexically parsed. Each XQuery expression (e.g. FLWOR, IF THEN ELSE expressions) produces a expression class in the body expression tree. At this stage an exception may be raised in case of syntax or lexical error also called static errors.

Query plan optimization

Then the expression tree is optimized by re-organizing the tree to minimize the evaluation performances. For instance the body tree corresponding to the query "(1 + 2) - 1" that involves three constants, two operations and a parenthesis expression may be replaced by a single constant expression: "1" such as shown in the figure below.

Dynamic evaluation

After optimization the body expression may be evaluated. This means the expressions will be processed to extract, filter and compute the values as stated in the initial query script. The evaluation may be performed with a context such as described in the section named "Evaluation context" below. The type of the evaluation result is described in the following section named "Evaluation result".

Evaluation context

The evaluation context of an expression is defined as information that is available at the time the expression is evaluated. The assessment context consists of the components listed below.

The first three components of the evaluation context (context item, context position and context size) are called the focus of the expression. The focus enables the processor to keep track of which nodes are being processed by the expression.

The focus for the outermost expression is supplied by the environment in which the expression is evaluated. Certain language constructs, notably the path expression E1/E2,create a new focus for the evaluation of a sub-expression. In these constructs, E2 is evaluated once for each item in the sequence that results from evaluating E1. Each time E2 is evaluated, it is evaluated with a different focus. The focus for evaluating E2 is referred to below as the inner focus, while the focus for evaluating E1 is referred to as the outer focus. The inner focus exists only while E2 is being evaluated. When this evaluation is complete, evaluation of the containing expression continues with its original focus unchanged.

Evaluation result

The value of an expression is always a Sequence, which is an ordered collection of zero or more items (i.e. see Item class). An item is either an atomic value or a node (i.e. AtomicValue class and DrbNode implementation). An atomic value is a value in the value space of an XML Schema atomic type, as defined in http://www.w3.org/TR/xquery/#XMLSchema (that is, a simple type that is not a list type or a union type). A node conforms to one of the seven node kinds described in XQuery 1.0 and XPath 2.0 Data Model (i.e. http://www.w3.org/TR/xquery/#datamodel. Each node has a unique node identity. Some kinds of nodes have typed values, string values, and names, which can be extracted from the node. The typed value of a node is a sequence of zero or more atomic values. The string value of a node is a value of type xs:string. The name of a node is a value of type xs:QName. A sequence containing exactly one item is called a singleton sequence. An item is identical to a singleton sequence containing that item. Sequences are never nested: for example, combining the values 1, (2, 3), and ( ) into a single sequence results in the sequence (1, 2, 3). A sequence containing zero items is called an empty sequence.

Query class usage

The usage of the present Query class is very easy and may be as simple as shown in the next source code sample: 

  import fr.gael.drb.query.Query;
  import fr.gael.drb.DrbItem; 
  import fr.gael.drb.DrbSequence;
  (...)
  try
  {
     Query my_query = new Query("doc.xml/company[1 to 3]/employee");
  }
  catch (Exception exception)
  {
     System..out.println("MyProgram : the query cannot be parsed.");
     System..out.println(exception);
  }
  Sequence result = my_query.evaluate();
  System.out.println(result.getLength() +
     " items resulting from this query");
  for (int i=0; i< result.getLength(); i++)
  {
     System.out.println("Item #" + i +": " + result.item(i));
  }

For a complete description of XQuery language, please refer to the latest XQuery working draft http://www.w3.org/TR/xquery/ .

Constructor Summary
  Query(InputStream stream)
          Builds a Query class instance from an input stream.
  Query(InputStream stream, Environment environment)
          Builds a Query class instance from an input stream considereing a specific environment.
protected Query(InputStream stream, fr.gael.drb.query.StaticContext static_context)
          Builds a Query class instance from an input stream considering a specific static context.
  Query(String query_string)
          Builds a Query class instance from a simple string.
  Query(String query_string, Environment environment)
          Builds a Query class instance from a simple string considereing a specific environment.
protected Query(String query_string, fr.gael.drb.query.StaticContext static_context)
          Builds a Query class instance from a simple string considereing a specific static context.
 
Method Summary
 boolean cancel(String reason)
          Cancel current evaluation.
 DrbNodeList eval()
          Deprecated. this operation has been replaced by the evaluate() series of operations. The main difference consist in the change of output type that now is Sequence and, therefore, may be a collection of mixed nodes, attributes and atomic values.
 DrbNodeList eval(DrbNode context_node)
          Deprecated. this operation has been replaced by the evaluate() series of operations. The main difference consist in the change of output type that now is Sequence and, therefore, may be a collection of mixed nodes, attributes and atomic values.
 DrbNodeList eval(DrbNode context_node, ParameterResolver resolver)
          Deprecated. this operation has been replaced by the evaluate() series of operations. The main difference consist in the change of output type that now is Sequence and, therefore, may be a collection of mixed nodes, attributes and atomic values.
 DrbNodeList eval(ParameterResolver resolver)
          Deprecated. this operation has been replaced by the evaluate() series of operations. The main difference consist in the change of output type that now is Sequence and, therefore, may be a collection of mixed nodes, attributes and atomic values.
 DrbSequence evaluate(DrbItem context_item)
          Launchs a dynamic evaluation of query with respect to an initial context item.
 DrbSequence evaluate(DrbItem context_item, int context_position, int context_size)
          Launchs a dynamic evaluation of query with respect to an initial context item.
static boolean getEffectiveBooleanValue(DrbSequence sequence)
          Returns the effective boolean value of a sequence.
 Environment getEnvironment()
          Returns the environment.
 ExternalVariable[] getExternalVariables()
          Returns the set of external variables of the current context/environment.
static String helpMsgFor(String subject, String name)
          Returns the command line help message for the specified subject.
 boolean isUpdating()
          Identifies queries that can modify the state of the context item.
static void main(String[] args)
          XQuery engine command line (CLI).
static String usage()
          Returns the command line usage of main operation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Query

public Query(String query_string)
      throws StaticException,
             TypeException
Builds a Query class instance from a simple string. In this specific constructor no environment is provided: a default one containing the default definitions (e.g. namespaces, functions, etc.) is instanciated.

Parameters:
query_string - the string containing the XQuery expression to be parsed and furtherly evaluated. This parmeter shall never be null.
Throws:
StaticException - when the parser encourter an error in the specified XQuery script different from type errors. The complete list of errors is provided in the XQuery specifications.
TypeException - when the parser encourter an error that regard the type matching. The complete list of errors is provided in the XQuery specifications.
See Also:
http://www.w3.org/TR/xquery

Query

public Query(InputStream stream)
      throws StaticException,
             TypeException
Builds a Query class instance from an input stream. In this specific constructor no environment is provided: a default one containing the default definitions (e.g. namespaces, functions, etc.) is instanciated.

Parameters:
stream - the input stream feeding the XQuery expression to be parsed and furtherly evaluated. This parmeter shall never be null.
Throws:
StaticException - when the parser encourter an error in the specified XQuery script different from type errors. The complete list of errors is provided in the XQuery specifications.
TypeException - when the parser encourter an error that regard the type matching. The complete list of errors is provided in the XQuery specifications.
See Also:
http://www.w3.org/TR/xquery

Query

public Query(String query_string,
             Environment environment)
      throws StaticException,
             TypeException
Builds a Query class instance from a simple string considereing a specific environment. If the reference to the environment is null, a default one will be considered: this called would be equivalent to the same call without the parameter.

Parameters:
query_string - the string containing the XQuery expression to be parsed and furtherly evaluated. This parmeter shall never be null.
environment - the environment to be considered during the static analysis phase.
Throws:
StaticException - when the parser encourter an error in the specified XQuery script different from type errors. The complete list of errors is provided in the XQuery specifications.
TypeException - when the parser encourter an error that regard the type matching. The complete list of errors is provided in the XQuery specifications.
See Also:
http://www.w3.org/TR/xquery

Query

protected Query(String query_string,
                fr.gael.drb.query.StaticContext static_context)
         throws StaticException,
                TypeException
Builds a Query class instance from a simple string considereing a specific static context. If the reference to the static context is null, a default one will be considered: this called would be equivalent to the same call without the parameter.

Parameters:
query_string - the string containing the XQuery expression to be parsed and furtherly evaluated. This parmeter shall never be null.
static_context - the static context to be considered during the static analysis phase.
Throws:
StaticException - when the parser encourter an error in the specified XQuery script different from type errors. The complete list of errors is provided in the XQuery specifications.
TypeException - when the parser encourter an error that regard the type matching. The complete list of errors is provided in the XQuery specifications.
See Also:
http://www.w3.org/TR/xquery

Query

public Query(InputStream stream,
             Environment environment)
      throws StaticException,
             TypeException
Builds a Query class instance from an input stream considereing a specific environment. If the reference to the environment is null, a default one will be considered: this called would be equivalent to the same call without the parameter.

Parameters:
stream - the input stream feeding the XQuery expression to be parsed and furtherly evaluated. This parameter shall never be null.
environment - the environment to be considered during the static analysis phase.
Throws:
StaticException - when the parser encounter an error in the specified XQuery script different from type errors. The complete list of errors is provided in the XQuery specifications.
TypeException - when the parser encounter an error that regard the type matching. The complete list of errors is provided in the XQuery specifications.
See Also:
http://www.w3.org/TR/xquery

Query

protected Query(InputStream stream,
                fr.gael.drb.query.StaticContext static_context)
         throws StaticException,
                TypeException
Builds a Query class instance from an input stream considering a specific static context. If the reference to the static context is null, a default one will be considered: this called would be equivalent to the same call without the parameter.

Parameters:
stream - the input stream feeding the XQuery expression to be parsed and furtherly evaluated. This parameter shall never be null.
static_context - the static context to be considered during the static analysis phase.
Throws:
StaticException - when the parser encounter an error in the specified XQuery script different from type errors. The complete list of errors is provided in the XQuery specifications.
TypeException - when the parser encounter an error that regard the type matching. The complete list of errors is provided in the XQuery specifications.
See Also:
http://www.w3.org/TR/xquery
Method Detail

getEnvironment

public Environment getEnvironment()
Returns the environment. The returned environment may differ from the one provided at construction. It may have been augmented during the static analysis phase. In particular the external variable potentially declared in the module prologs are already referenced at this stage.

Returns:
the environment augmented during the static analysis phase.

getExternalVariables

public ExternalVariable[] getExternalVariables()
Returns the set of external variables of the current context/environment. The external variable may originate from the environment creator or may have been added during the satic analysis phase of the XQuery processing. Any call of this operation is equivalent to the following code: 
 query.getEnvironment().getExternalVariables()
.

Returns:
the array of external variables, if any, or null otherwise.

isUpdating

public boolean isUpdating()
Identifies queries that can modify the state of the context item. An updating query has a main expression that use the updating operations provided by the "XQuery Update Facility" : insert, delete, replace, rename and transform.

Returns:
true if this query performs updating operations and false otherwise

evaluate

public DrbSequence evaluate(DrbItem context_item,
                            int context_position,
                            int context_size)
                     throws DynamicException,
                            TypeException,
                            CancelException
Launchs a dynamic evaluation of query with respect to an initial context item.

The dynamic context of evaluation is automatically derived from the top level static context resulting from the static analysis phase.

During the dynamic evaluation, a dynamic or a type exception may occur interrupting the processing of the query. They significate that an unrecoverable error has been encountered in an expression may be due to unsatisfied conditions departing from the XQuery specifications.

Moreover, while a dynamic evaluation is operating, a call of cancel() operation may request the immediate interruption of the processing. On the evaluation stop, a CancelException is thrown.

Parameters:
context_item - the initial context item to be put in the focus of the dynamic evaluation context.
context_position - the initial position in the context sequence.
context_size - the initial context size.
Returns:
the sequence resulting from the dynamic evaluation.
Throws:
DynamicException - when an error occurred.
TypeException - when a type error has been encountered.
CancelException - when the evaluation has been interrupted.

evaluate

public DrbSequence evaluate(DrbItem context_item)
                     throws DynamicException,
                            TypeException,
                            CancelException
Launchs a dynamic evaluation of query with respect to an initial context item.

The dynamic context of evaluation is automatically derived from the top level static context resulting from the static analysis phase.

During the dynamic evaluation, a dynamic or a type exception may occur interrupting the processing of the query. They significate that an unrecoverable error has been encountered in an expression may be due to unsatisfied conditions departing from the XQuery specifications.

Moreover, while a dynamic evaluation is operating, a call of cancel() operation may request the immediate interruption of the processing. On the evaluation stop, a CancelException is thrown.

Parameters:
context_item - the initial context item to be put in the focus of the dynamic evaluation context.
Returns:
the sequence resulting from the dynamic evaluation.
Throws:
DynamicException - when an error occurred.
TypeException - when a type error has been encountered.
CancelException - when the evaluation has been interrupted.

cancel

public boolean cancel(String reason)
Cancel current evaluation.

This operation request a call off to the running evaluation. The effective cancellation depends on the nature of the query script and its current processing status. Actually, the expression tree may or not involve expressions that support cancellation request. Basically, the support of this feature has been primarily assigned to time consuming expression such a FLWOR expression. If the script does not involve any expression supporting cancellation requests, it will never stop before the normal end of dynamic evaluation.

When a understanding expression detects a cancellation request, it interrupts is current processing and throws a CancelException in order to inform its holding thread that the evaluation has been called off. If that case the evaluation result may be incomplete and should be used carefully, should the case arise (e.g. a interrupted query tracing records in the logger).

This operation has no effect is no evaluation is currently running. The operation return a boolean status wether the cancellation has been requested or not.

Caller may provide a message detailing the reason of cancellation. This message will be used for formatting the exception message. Caller should consider that its message will be appended to a sentence ending with an expression equivalent to "... has been cancelled due to ". Caller should not begin with an upper-case character appart if mandatory and end its message with a trailing dot for convenient reasons.

Parameters:
reason - reason of cancellation request to be reported in the exception.
Returns:
true if the cancellation request has been sent and false if it has no sense.

eval

public DrbNodeList eval()
Deprecated. this operation has been replaced by the evaluate() series of operations. The main difference consist in the change of output type that now is Sequence and, therefore, may be a collection of mixed nodes, attributes and atomic values.

Evaluates the body expression without initial context node.

Returns:
the list of nodes resulting from the evaluation of the query. The result can be null if the expression does not match any node.
See Also:
http://www.w3.org/TR/xquery

eval

public DrbNodeList eval(ParameterResolver resolver)
Deprecated. this operation has been replaced by the evaluate() series of operations. The main difference consist in the change of output type that now is Sequence and, therefore, may be a collection of mixed nodes, attributes and atomic values.

Evaluates the body expression with a resolver.

Parameters:
resolver - the optional parameter resolver.
Returns:
the list of nodes resulting from the evaluation of the query. The result can be null if the expression does not match any node.
See Also:
http://www.w3.org/TR/xquery

eval

public DrbNodeList eval(DrbNode context_node)
Deprecated. this operation has been replaced by the evaluate() series of operations. The main difference consist in the change of output type that now is Sequence and, therefore, may be a collection of mixed nodes, attributes and atomic values.

Evaluates the body expression with an initial context node. The context node is the default node from witch all relative paths of the query shall refer to. For instance, an initial context node wrapping the current working directory allows to parse path expressions relative to this current working directory.

The initial context instanciated at the beginning of the evaluation has the following properties :

  • Position: the position is defaulted to 1;
  • Bindings: no binding are set.

    See the XQuery specifications for a complete description of what is an evaluation context.

    Parameters:
    context_node - the node to be considered as initial context node.
    Returns:
    the list of nodes resulting from the evaluation of the query. The result can be null if the expression does not match any node.
    See Also:
    http://www.w3.org/TR/xquery

    • eval

    public DrbNodeList eval(DrbNode context_node,
                        ParameterResolver resolver)
    Deprecated. this operation has been replaced by the evaluate() series of operations. The main difference consist in the change of output type that now is Sequence and, therefore, may be a collection of mixed nodes, attributes and atomic values.

    Evaluates the body expression with an initial context node and a resolver. The context node is the default node from witch all relative paths of the query shall refer to. For instance, an initial context node wrapping the current working directory allows to parse path expressions relative to this current working directory.

    The initial context instanciated at the beginning of the evaluation has the following properties :

  • Position: the position is defaulted to 1;
  • Bindings: no binding are set.

    See the XQuery specifications for a complete description of what is an evaluation context. The parameter resolver allows to evaluate queries with variable parameters (i.e. basically XQueries calling the built-in function parameter()).

    Parameters:
    context_node - the context node (may be null).
    resolver - the resolver to be used (may be null).
    Returns:
    the list of nodes resulting from the evaluation of the query. The result can be null if the expression does not match any node.
    See Also:
    http://www.w3.org/TR/xquery

    • getEffectiveBooleanValue

    public static boolean getEffectiveBooleanValue(DrbSequence sequence)
    Returns the effective boolean value of a sequence.

    The effective boolean value of a sequence is defined as the result of applying the fn:boolean function to the value, as defined in the "XQuery 1.0 and XPath 2.0 Functions and Operators".

    The semantics of fn:boolean are repeated here for convenience. fn:boolean returns false if its operand is any of the following:

    Parameters:
    sequence - the sequence to be assessed.
    Returns:
    the computed effective boolean value.

    usage

    public static String usage()
    Returns the command line usage of main operation.

    Returns:
    String object containing a command line usage help.

    helpMsgFor

    public static String helpMsgFor(String subject,
                                String name)
    Returns the command line help message for the specified subject.

    Parameters:
    subject - the type of help requested
    name - name of the thing to be detailed inside the subject
    Returns:
    String object containing a command line help corresponding to the subject or null if the subject is invalid.

    main

    public static void main(String[] args)
    XQuery engine command line (CLI). This command evaluates the XQuery script provided as a string or a file. The output of the evaluation is printed out in the standard output. The output format may have several forms according to the resulting sequence. Basically the resulting nodes are output as XML fragments, the attributes not attached to nodes are written as in XML but prefixed with '@' symbol and finally, the atomic values are printed without decoration, according to the XML Schema lexical space definitions. All items of the output sequence are comma separated. A '()' result dennotes the empty sequence. The warning or error are printed in the log4j logger (c.f. http://logging.apache.org/log4j/docs/index.html for detailed information of the logging system). [ -s <xquery_string> ] Command line string to be evaluated as XQuery script. This parameter cannot be used jointly with -f. At least -s or -f is to be set. [ -f <xquery_file> ] Path to a file containing the sctript to be evaluated. This parameter cannot be used jointly with -s. At least -f or -s is to be set. [ -variable <QName> <value> [ as <type> ]] Pushses an external variable in the environment prior to parse and evaluate the XQuery script. The variable is pushed in the the environment altough it has not been declared has an external variable, to provide it to the potential nested XQuerys (e.g. a call to evaluate-uri() built-in function). <QName> is the qualified name of the variable to declare whether <value> is a string to bind as value of the variable. If <QName> matches a typed external variable declared in the script, <value> is converted to that type before being bound. The trailing \"as <type>\" is optional and shall follow the XQuery sequence type declaration (e.g. as xs:integer+ ). [ -help | --help | -h ] Prints out the present help message. This parameter overides all others. [ -v | --version ] Prints out the current version of the CLI. This parameter overides all others apart the help trigger. It is assumed that DRB classpath and dependecies are correctly configured. The command exits with a 0 status if no error occured and 1 otherwise.

    Parameters:
    args - the concatenation of the arguments forms the XQuery script to be evaluated.
    Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
    		Data Request Broker - DRB API®
    2-3-release
     PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
    SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
    Copyright© 2001-2009 GAEL Consultant. All rights reserved. Use is subject to license terms .