Qizx fe-4.4p2 API

com.qizx.api
Interface XQueryContext


public interface XQueryContext

Definition of the XQuery Context used for compiling and executing Expressions. This serves both as Static and Dynamic context (in the sense of XQuery).

A XML Library provides a default XQueryContext which can be modified. This default context should be suitable for most applications, with perhaps only a few properties to define, such as base-uri.

Before an Expression is compiled, it inherits the context of the Library from which the expression is created.

After an Expression is compiled, its XQueryContext reflects declarations made in the expression itself. The XQuery context can be inspected and runtime properties modified (mainly the default collation, implicit timezone, current date).


Field Summary
static int INHERIT
          Value used for property NamespaceInheritMode, meaning that namespaces should be inherited in a node copy operation.
static int NO_INHERIT
          Value used for property NamespaceInheritMode, meaning that namespaces should not be inherited in a node copy operation.
static int NO_PRESERVE
          Value used for properties BoundarySpacePolicy, NamespacePreserveMode, ConstructionMode, meaning that - respectively - boundary space, namespaces and schema types should not be preserved.
static int ORDERED
          Value returned by getOrderingMode(): indicates that by default result sequences must be ordered.
static int PRESERVE
          Value used for properties BoundarySpacePolicy, NamespacePreserveMode, ConstructionMode, meaning that - respectively - boundary space, namespaces and schema types should be preserved.
static int UNORDERED
          Value returned by getOrderingMode(): indicates that by default result sequences are not required to be ordered.
 
Method Summary
 void declarePrefix(String prefix, String namespaceURI)
          Adds a predefined namespace declaration.
 void declareVariable(QName variableName, SequenceType variableType)
          Adds a predefined variable declaration.
 String getBaseURI()
          Gets the base URI used to resolve relative URIs in expressions.
 int getBoundarySpacePolicy()
          Gets the default boundary space policy for element constructors.
 int getConstructionMode()
          Gets the construction mode defined in the static context.
 Date getCurrentDate()
          Gets the specific date/time set by setCurrentDate().
 String getDefaultCollation()
          Gets the URI of the default collation defined in the static context.
 String getDefaultElementNamespace()
          Gets the URI of the default element namespace.
 String getDefaultFunctionNamespace()
          Gets the URI of the default function namespace.
 boolean getDefaultOrderEmptyGreatest()
          Gets the default order for empty sequences in 'order by' clauses.
 TimeZone getImplicitTimeZone()
          Returns the current implicit time-zone in the execution context.
 String[] getInScopePrefixes()
          Returns the prefixes of in-scope namespace definitions.
 int getNamespaceInheritMode()
          Gets the default inherit part of the copy-namespaces mode.
 int getNamespacePreserveMode()
          Gets the default preserve part of the copy-namespaces mode.
 String getNamespaceURI(String prefix)
          Retrieves the namespace URI associated with a prefix.
 QName[] getOptionNames()
          Gets the list of options declared in the static context of a query.
 String getOptionValue(QName optionName)
          Returns the string literal declared as value of the specified option.
 int getOrderingMode()
          Gets the default ordering mode for returned sequences.
 boolean getStrictCompliance()
          Returns true if a strict compliance with XQuery Specifications is enforced (not allowing extensions).
 boolean getStrictTyping()
          Returns true if Strict Typing is enabled in this context.
 QName[] getVariableNames()
          Gets the list of global variables declared in the static context.
 SequenceType getVariableType(QName variableName)
          Returns the type associated with a declared variable.
 String getXQueryVersion()
          Gets the supported version of XQuery.
 void setBaseURI(String uri)
          Sets the base URI used to resolve relative URIs in expressions.
 void setBoundarySpacePolicy(int boundarySpacePolicy)
          Sets the default boundary space policy for element constructors.
 void setConstructionMode(int constructionMode)
          Sets the construction mode defined in the static context.
 void setCurrentDate(Date forcedDate)
          Sets a specific date/time for use in query evaluation, instead of the normal value (the system time at start of evaluation).
 void setDefaultCollation(String defaultCollation)
          Sets the URI of the default collation defined in the static context.
 void setDefaultElementNamespace(String defaultElementNamespace)
          Sets the URI of the default element namespace.
 void setDefaultFunctionNamespace(String defaultFunctionNamespace)
          Sets the URI of the default function namespace.
 void setDefaultOrderEmptyGreatest(boolean emptyGreatest)
          Sets the default order for empty sequences in 'order by' clauses.
 void setImplicitTimeZone(TimeZone implicitTimeZone)
          Defines the implicit time-zone in the execution context.
 void setNamespaceInheritMode(int namespaceInheritMode)
          Sets the default inherit part of the copy-namespaces mode.
 void setNamespacePreserveMode(int namespacePreserveMode)
          Sets the default preserve part of the copy-namespaces mode.
 void setOrderingMode(int orderingMode)
          Sets the default ordering mode for returned sequences.
 void setStrictCompliance(boolean strictCompliance)
          Sets the strict compliance flag with XQuery Specifications.
 void setStrictTyping(boolean strictTyping)
          Sets the Strict Typing flag.
 

Field Detail

ORDERED

static final int ORDERED
Value returned by getOrderingMode(): indicates that by default result sequences must be ordered.

See Also:
Constant Field Values

UNORDERED

static final int UNORDERED
Value returned by getOrderingMode(): indicates that by default result sequences are not required to be ordered.

See Also:
Constant Field Values

PRESERVE

static final int PRESERVE
Value used for properties BoundarySpacePolicy, NamespacePreserveMode, ConstructionMode, meaning that - respectively - boundary space, namespaces and schema types should be preserved.

See Also:
Constant Field Values

NO_PRESERVE

static final int NO_PRESERVE
Value used for properties BoundarySpacePolicy, NamespacePreserveMode, ConstructionMode, meaning that - respectively - boundary space, namespaces and schema types should not be preserved.

See Also:
Constant Field Values

INHERIT

static final int INHERIT
Value used for property NamespaceInheritMode, meaning that namespaces should be inherited in a node copy operation.

See Also:
Constant Field Values

NO_INHERIT

static final int NO_INHERIT
Value used for property NamespaceInheritMode, meaning that namespaces should not be inherited in a node copy operation.

See Also:
Constant Field Values
Method Detail

getXQueryVersion

String getXQueryVersion()
Gets the supported version of XQuery.

Returns:
a String representing the XQuery version value

getDefaultOrderEmptyGreatest

boolean getDefaultOrderEmptyGreatest()
Gets the default order for empty sequences in 'order by' clauses.

Returns:
true if the empty sequence or NaN are considered greatest.

setDefaultOrderEmptyGreatest

void setDefaultOrderEmptyGreatest(boolean emptyGreatest)
Sets the default order for empty sequences in 'order by' clauses.

Parameters:
emptyGreatest - true if the empty sequence or NaN are considered greatest.

getNamespaceInheritMode

int getNamespaceInheritMode()
Gets the default inherit part of the copy-namespaces mode.

Returns:
the inherit mode, one of the two values INHERIT or NO_INHERIT

setNamespaceInheritMode

void setNamespaceInheritMode(int namespaceInheritMode)
Sets the default inherit part of the copy-namespaces mode.

Parameters:
namespaceInheritMode - the inherit mode to set, one of the two values INHERIT or NO_INHERIT

getNamespacePreserveMode

int getNamespacePreserveMode()
Gets the default preserve part of the copy-namespaces mode.

Returns:
the default namespace preserve mode, one of the two values PRESERVE or NO_PRESERVE.

setNamespacePreserveMode

void setNamespacePreserveMode(int namespacePreserveMode)
Sets the default preserve part of the copy-namespaces mode.

Parameters:
namespacePreserveMode - the namespace preserve mode to set, one of the two values PRESERVE or NO_PRESERVE.

getBoundarySpacePolicy

int getBoundarySpacePolicy()
Gets the default boundary space policy for element constructors.

Returns:
the default boundary space policy, one of the two values PRESERVE or NO_PRESERVE.

setBoundarySpacePolicy

void setBoundarySpacePolicy(int boundarySpacePolicy)
Sets the default boundary space policy for element constructors.

Parameters:
boundarySpacePolicy - the boundary space policy to set, one of the two values PRESERVE or NO_PRESERVE.

getConstructionMode

int getConstructionMode()
Gets the construction mode defined in the static context.

Returns:
the default construction mode to set, one of the two values PRESERVE or NO_PRESERVE.

setConstructionMode

void setConstructionMode(int constructionMode)
Sets the construction mode defined in the static context.

Parameters:
constructionMode - the construction mode to set, one of the two values PRESERVE or NO_PRESERVE.

getDefaultCollation

String getDefaultCollation()
Gets the URI of the default collation defined in the static context. By default it is the Unicode codepoints collation.

Returns:
the defaultCollation

setDefaultCollation

void setDefaultCollation(String defaultCollation)
                         throws DataModelException
Sets the URI of the default collation defined in the static context.

Parameters:
defaultCollation - the URI of the default collation to set
Throws:
DataModelException - if the collation cannot be resolved

getDefaultElementNamespace

String getDefaultElementNamespace()
Gets the URI of the default element namespace. By default it is the blank namespace.

Returns:
the default element namespace

setDefaultElementNamespace

void setDefaultElementNamespace(String defaultElementNamespace)
Sets the URI of the default element namespace.

Parameters:
defaultElementNamespace - default element namespace to set

getDefaultFunctionNamespace

String getDefaultFunctionNamespace()
Gets the URI of the default function namespace. By default it corresponds to predefined functions (prefix fn:).

Returns:
the URI of the default function namespace, if set, else the empty string.

setDefaultFunctionNamespace

void setDefaultFunctionNamespace(String defaultFunctionNamespace)
Sets the URI of the default function namespace.

Parameters:
defaultFunctionNamespace - the default Function Namespace to set, may not be null

getOrderingMode

int getOrderingMode()
Gets the default ordering mode for returned sequences.

Returns:
the orderingMode, one of the two values ORDERED or UNORDERED

setOrderingMode

void setOrderingMode(int orderingMode)
Sets the default ordering mode for returned sequences.

Parameters:
orderingMode - the ordering mode to set, one of the two values ORDERED or UNORDERED

getBaseURI

String getBaseURI()
Gets the base URI used to resolve relative URIs in expressions.

Returns:
the base URI, if set, else the empty string. Cannot be null

setBaseURI

void setBaseURI(String uri)
Sets the base URI used to resolve relative URIs in expressions.

Parameters:
uri - the base URI, or the empty string. May not be null

getInScopePrefixes

String[] getInScopePrefixes()
Returns the prefixes of in-scope namespace definitions. If used on the context of a compiled Expression,

Returns:
String array containing the namespace prefixes. Cannot be null.

declarePrefix

void declarePrefix(String prefix,
                   String namespaceURI)
Adds a predefined namespace declaration.

If a namespace with the same prefix already exists, it is replaced.

Parameters:
prefix - namespace prefix to be declared
namespaceURI - URi of the namespace to be declared

getNamespaceURI

String getNamespaceURI(String prefix)
Retrieves the namespace URI associated with a prefix.

Parameters:
prefix - a namespace prefix
Returns:
the namespaceURI associated with the prefix, or null if the prefix is undefined.

getVariableNames

QName[] getVariableNames()
Gets the list of global variables declared in the static context.

In the context of a compiled Expression, the variables are those declared in the expression. In the context of a Library session or XQuerySession, the variables can only have been predefined through the method declareVariable(QName, SequenceType).

Returns:
array of QNames of the variables. An empty array is returned when there are no variables.

getVariableType

SequenceType getVariableType(QName variableName)
Returns the type associated with a declared variable.

Parameters:
variableName - qualified name of the variable
Returns:
the type declared for the variable. If the variable is not declared, returns null.

declareVariable

void declareVariable(QName variableName,
                     SequenceType variableType)
Adds a predefined variable declaration.

Parameters:
variableName - qualified name of the variable
variableType - optional type (may be null) declared for the variable

getOptionNames

QName[] getOptionNames()
Gets the list of options declared in the static context of a query.

In the context of a compiled Expression, the options are those declared in the prolog.

Returns:
array of QNames of the options. An empty array is returned when there are no options.

getOptionValue

String getOptionValue(QName optionName)
Returns the string literal declared as value of the specified option.

Parameters:
optionName - name of the option
Returns:
a string literal value

setImplicitTimeZone

void setImplicitTimeZone(TimeZone implicitTimeZone)
Defines the implicit time-zone in the execution context.

Parameters:
implicitTimeZone - a TimeZone to be used as implicit time-zone

getImplicitTimeZone

TimeZone getImplicitTimeZone()
Returns the current implicit time-zone in the execution context. By default it is the system time-zone.

Returns:
the current implicit time-zone

getStrictTyping

boolean getStrictTyping()
Returns true if Strict Typing is enabled in this context.

Returns:
true if Strict Typing is enabled
See Also:
setStrictTyping(boolean)

setStrictTyping

void setStrictTyping(boolean strictTyping)
Sets the Strict Typing flag.

If enabled (not by default), the XQuery compiler will treat as an error any weakly typed expression. This implies that nearly all variables or function parameters need to be declared with a type, and all user functions should have a declared return type. Since Qizx does not support Schema import, some expressions might in addition have to be typed through the use of treat as, casts and functions like fn:exactly-one, fn:one-or-more etc.

Parameters:
strictTyping - true to enforce Strict Typing
See Also:
getStrictTyping()

getStrictCompliance

boolean getStrictCompliance()
Returns true if a strict compliance with XQuery Specifications is enforced (not allowing extensions).

Returns:
true if strict compliance is enforced
See Also:
setStrictCompliance(boolean)

setStrictCompliance

void setStrictCompliance(boolean strictCompliance)
Sets the strict compliance flag with XQuery Specifications.

If not enabled (the default), the following extensions are available:

  • Casting numeric values from/to xs:date, xs:time, xs:dateTime, xs:dayTimeDuration, xs:yearMonthDuration.
  • Allow concat() to have a single argument which is a sequence.

    Parameters:
    strictCompliance - true to enforce strict compliance

  • setCurrentDate

    void setCurrentDate(Date forcedDate)
    Sets a specific date/time for use in query evaluation, instead of the normal value (the system time at start of evaluation).

    Parameters:
    forcedDate - a date/time, or null to use again the system time.

    getCurrentDate

    Date getCurrentDate()
    Gets the specific date/time set by setCurrentDate().

    Returns:
    the value set by setCurrentDate(), or null by default (use system time)

    © 2010 Axyana Software