Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Qizx/open 4.1 API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.qizx.api
Interface Expression

All Superinterfaces:
  ItemFactory

    public interface Expression

extends ItemFactory

Compiled XML Query expression.

An Expression is created with the compileExpression method of `Library` or `XQuerySession`.

Once compiled, an Expression can be evaluated several times. Preparing an Expression for execution involves optional operations like:

- Modifying the XML Query static context: `getContext()`
- Binding a global XQuery variable with a value (simple item or sequence), using one of the bindVariable methods.
- Binding the implicit collection. The implicit collection is used when a XQuery/XPath "path expression" has no explicit root, and no context item is defined.

  For example the path expression `//foo/bar` has no explicit root. Supposing that the collection /a/b has been bound as Implicit Collection in this expression, its evaluation is equivalent to the evaluation of the path expression `collection("/a/b")//foo/bar` .

  The implicit collection is also the Default Collection defined by the XQuery specifications: in the example above, using `collection()//foo/bar` is equivalent to use `//foo/bar`.

  This allows reusing the same query on different collections or documents of a Library.

- Setting a `TraceObserver`.

Execution can be aborted by `cancelEvaluation()` or by a time-out (see setTimeOut).

This class is not thread safe (an Expression is built from an XQuery session which is itself not thread safe).

Method Summary
`void` | `bindImplicitCollection(ItemSequence nodes)` Defines the Implicit Collection as a set of Nodes defined by a sequence (see above for a definition of Implicit Collection).
`void` | `bindVariable(QName varName, boolean value)` Binds a variable to a sequence made of a single boolean value.
`void` | `bindVariable(QName varName, double value)` Binds a variable to a sequence made of a single item of type xs:double.
`void` | `bindVariable(QName varName, float value)` Binds a variable to a sequence made of a single item of type xs:float.
`void` | `bindVariable(QName varName, Item value)` Binds a variable to a sequence made of a single item.
`void` | `bindVariable(QName varName, ItemSequence value)` Binds a variable to a sequence.
`void` | `bindVariable(QName varName, long value, ItemType type)` Binds a variable to a value obtained by converting a long integer to an Item.
`void` | `bindVariable(QName varName, Object value, ItemType type)` Binds a variable to a value obtained by converting a Java object to an Item or a ItemSequence, according to the general Java to XQuery type mapping (see the documentation for details).
`void` | `cancelEvaluation()` Cancels the evaluation started by `evaluate()`.
`ItemSequence` | `evaluate()` Evaluation of the expression, returns a sequence of Items.
`XQueryContext` | `getContext()` Access to the XQuery Context.
`Item` | `getCurrentItem()` Gets the initial value of the current item, accessible by the expression '.'.
`Object` | `getProperty(String name)` Gets a property set by setProperty.
`String` | `getSource()` Returns the source code of the compiled expression.
`SequenceType` | `getStaticType()` Returns the static (or formal) type of the compiled expression.
`int` | `getTimeOut()` Returns the maximum evaluation time, as defined by `setTimeOut(int)`.
`TraceObserver` | `getTraceObserver()` Gets the listener used to receive evaluation traces.
`void` | `setCurrentItem(Item item)` Sets the initial value of the current item, accessible by the expression '.'.
`void` | `setProperty(String name, Object value)` Sets a property which can be used by extension functions.
`void` | `setTimeOut(int maxTime)` Defines a maximum time for evaluation.
`void` | `setTraceObserver(TraceObserver listener)` Sets a listener to receive evaluation traces.

Methods inherited from interface com.qizx.api.ItemFactory
`copySequence, createItem, createItem, createItem, createItem, createItem, createItem, createItem, createSequence, getNodeType, getQName, getQName, getQName, getType`

Method Detail

### getContext

    XQueryContext getContext()

  Access to the XQuery Context.

  Returns:
    the XQuery Context of this expression. This context is initially defined by the context of the XQuery session (or Library) and by the expression itself. It can be modified before each execution.

### getStaticType

    SequenceType getStaticType()

  Returns the static (or formal) type of the compiled expression.

  Since:
    3.1

### getSource

    String getSource()

  Returns the source code of the compiled expression.

  Since:
    4.0

### bindVariable

    void bindVariable(QName varName,
                      Item value)
                      throws CompilationException

  Binds a variable to a sequence made of a single item.

  Parameters:
    `varName` - name of a variable declared in the prolog of the XQuery expression.
    `value` - an item create by ItemFactory or obtained from an ItemSequence
  Throws:
    `CompilationException` - if the variable name is not declared as global in the expression.

### bindVariable

    void bindVariable(QName varName,
                      ItemSequence value)
                      throws CompilationException

  Binds a variable to a sequence.

  Parameters:
    `varName` - name of a variable declared in the prolog of the XQuery expression.
    `value` - sequence bound to the variable, it is first cloned.
  Throws:
    `CompilationException` - if the variable name is not declared as global in the expression.

### bindVariable

    void bindVariable(QName varName,
                      boolean value)
                      throws CompilationException

  Binds a variable to a sequence made of a single boolean value.

  Parameters:
    `varName` - name of a variable declared in the prolog of the XQuery expression.
    `value` - boolean value
  Throws:
    `CompilationException` - if the variable name is not declared as global in the expression.

### bindVariable

    void bindVariable(QName varName,
                      long value,
                      ItemType type)
                      throws CompilationException,
                             EvaluationException

  Binds a variable to a value obtained by converting a long integer to an Item.

  Parameters:
    `varName` - name of a variable declared in the prolog of the XQuery expression.
    `value` - a long integer value
    `type` - optional type. If non null, the value is converted to this type. If null, the default type xs:integer is used.
  Throws:
    `EvaluationException` - if the type is invalid
    `CompilationException` - if the variable name is not declared as global in the expression.

### bindVariable

    void bindVariable(QName varName,
                      double value)
                      throws CompilationException

  Binds a variable to a sequence made of a single item of type xs:double.

  Parameters:
    `varName` - name of a variable declared in the prolog of the XQuery expression.
    `value` - double value
  Throws:
    `CompilationException` - if the variable name is not declared as global in the expression.

### bindVariable

    void bindVariable(QName varName,
                      float value)
                      throws CompilationException

  Binds a variable to a sequence made of a single item of type xs:float.

  Parameters:
    `varName` - name of a variable declared in the prolog of the XQuery expression.
    `value` - float value
  Throws:
    `CompilationException` - if the variable name is not declared as global in the expression.

### bindVariable

    void bindVariable(QName varName,
                      Object value,
                      ItemType type)
                      throws CompilationException,
                             EvaluationException

  Binds a variable to a value obtained by converting a Java object to an Item or a ItemSequence, according to the general Java to XQuery type mapping (see the documentation for details). The object can be an array: it will be converted to a Sequence.

  Parameters:
    `varName` - name of a variable declared in the prolog of the XQuery expression.
    `value` - object to convert to XQuery value
    `type` - optional type. If non null, the object (or its items) will be converted to this type. If null, the object will be converted to the most general applicable type: for example a Java String to xs:string type, an array of double to a sequence of xs:double and so on.
  Throws:
    `EvaluationException` - if the conversion cannot be performed
    `CompilationException` - if the variable name is not declared as global in the expression.

### bindImplicitCollection

    void bindImplicitCollection(ItemSequence nodes)
                                throws EvaluationException

  Defines the Implicit Collection as a set of Nodes defined by a sequence (see above for a definition of Implicit Collection).

  Parameters:
    `nodes` - a sequence of Nodes
  Throws:
    `EvaluationException` - if one of the items in the sequence is not a node, or if the enumeration of the sequence causes a runtime error.

### setCurrentItem

    void setCurrentItem(Item item)

  Sets the initial value of the current item, accessible by the expression '.'.

  Parameters:
    `item` - the current item. If the value is null, the current item becomes undefined.

### getCurrentItem

    Item getCurrentItem()

  Gets the initial value of the current item, accessible by the expression '.'.

  Returns:
    the current item set by setCurrentItem.

### evaluate

    ItemSequence evaluate()
                          throws EvaluationException

  Evaluation of the expression, returns a sequence of Items.

  Returns:
    a sequence of Items which is the result of the evaluation
  Throws:
    `EvaluationException` - thrown by an XQuery dynamic error

### cancelEvaluation

    void cancelEvaluation()

  Cancels the evaluation started by `evaluate()`. Most likely called from a different thread than the evaluation thread (where evaluate is called).

### getTimeOut

    int getTimeOut()

  Returns the maximum evaluation time, as defined by `setTimeOut(int)`. By default, this value is 0, meaning no time limit.

  Returns:
    an int representing the current time out value in milliseconds

### setTimeOut

    void setTimeOut(int maxTime)

  Defines a maximum time for evaluation. If this time is defined and exceeded, the evaluation aborts with a "TIME0000" error code.

  Parameters:
    `maxTime` - maximum execution time in milliseconds. A value <= 0 can be used to specify an unlimited time.

### setTraceObserver

    void setTraceObserver(TraceObserver listener)

  Sets a listener to receive evaluation traces.

  Parameters:
    `listener` - an implementation of TraceObserver whose method trace is called each time the fn:trace is called in the expression.

### getTraceObserver

    TraceObserver getTraceObserver()

  Gets the listener used to receive evaluation traces.

  Returns:
    the trace observer set by setTraceObserver, or null by default

### getProperty

    Object getProperty(String name)

  Gets a property set by setProperty.

  Parameters:
    `name` - name of the property
  Returns:
    value of the property

### setProperty

    void setProperty(String name,
                     Object value)

  Sets a property which can be used by extension functions.

  Parameters:
    `name` - name of the property
    `value` - value of the property

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| © 2010 Axyana Software
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD