net.sf.saxon.query

Class DynamicQueryContext

java.lang.Object

net.sf.saxon.query.DynamicQueryContext

public class DynamicQueryContext
extends Object

This object represents a dynamic context for query execution. This class is used by the application writer to set up aspects of the dynamic context; it is not used operationally (or modified) by the XQuery processor itself, which copies all required information into its own internal representation.

Constructor Summary

Constructors

Constructor and Description
DynamicQueryContext(Configuration config) Create the dynamic context for a query

Method Summary

Methods

Modifier and Type	Method and Description
void	clearParameters() Reset the parameters to an empty list.
Configuration	getConfiguration() Get the Configuration associated with this dynamic query context
Item	getContextItem() Get the context item for the query, as set using setContextItem() or setContextNode().
DateTimeValue	getCurrentDateTime() Get the date and time set previously using setCurrentDateTime(net.sf.saxon.value.DateTimeValue) or null if none has been set.
ErrorListener	getErrorListener() Get the error listener.
Object	getParameter(String expandedName) Get the actual value of a parameter to the query.
GlobalParameterSet	getParameters() Get all the supplied parameters.
int	getSchemaValidationMode() Ask whether source documents loaded using the doc(), document(), and collection() functions, or supplied as a StreamSource or SAXSource to the transform() or addParameter() method should be subjected to schema validation
PrintStream	getTraceFunctionDestination() Get the destination for output from the fn:trace() function.
TraceListener	getTraceListener() Get the trace listener.
UnparsedTextURIResolver	getUnparsedTextURIResolver() Get the URI resolver for unparsed text.
URIResolver	getURIResolver() Get the URI resolver.
void	initializeController(Controller controller) Apply the settings from this DynamicQueryContext to a Controller
boolean	isApplyFunctionConversionRulesToExternalVariables() Ask whether the function conversion rules should be applied to supplied parameter values.
void	setApplyFunctionConversionRulesToExternalVariables(boolean convert) Say whether the function conversion rules should be applied to supplied parameter values.
void	setContextItem(Item item) Set the context item for evaluating the expression.
void	setContextNode(NodeInfo node) Deprecated. From Saxon 8.7, the method setContextItem(Item) is preferred
void	setCurrentDateTime(DateTimeValue dateTime) Set a value to be used as the current date and time for the query.
void	setErrorListener(ErrorListener listener) Set the error listener.
void	setParameter(String expandedName, Object value) Set a parameter for the query.
void	setParameters(GlobalParameterSet params) Set all the supplied parameters as a HashMap.
void	setParameterValue(String expandedName, Sequence value) Set a parameter for the query.
void	setSchemaValidationMode(int validationMode) Say whether source documents loaded using the doc(), document(), and collection() functions, or supplied as a StreamSource or SAXSource to the transform() or addParameter() method, should be subjected to schema validation.
void	setTraceFunctionDestination(PrintStream stream) Set the destination for output from the fn:trace() function.
void	setTraceListener(TraceListener listener) Set the trace listener.
void	setUnparsedTextURIResolver(UnparsedTextURIResolver resolver) Set an object that will be used to resolve URIs used in fn:unparsed-text() and related functions.
void	setURIResolver(URIResolver resolver) Set an object that will be used to resolve URIs used in fn:document() and related functions.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DynamicQueryContext

public DynamicQueryContext(Configuration config)

Create the dynamic context for a query

Parameters:

config - the Saxon configuration

Since:

8.4.

Method Detail

getSchemaValidationMode

public int getSchemaValidationMode()

Ask whether source documents loaded using the doc(), document(), and collection() functions, or supplied as a StreamSource or SAXSource to the transform() or addParameter() method should be subjected to schema validation

Returns:

the schema validation mode previously set using setSchemaValidationMode(), or the default mode Validation.DEFAULT otherwise.

setSchemaValidationMode

public void setSchemaValidationMode(int validationMode)

Say whether source documents loaded using the doc(), document(), and collection() functions, or supplied as a StreamSource or SAXSource to the transform() or addParameter() method, should be subjected to schema validation. The default value is taken from the corresponding property of the Configuration.

Parameters:

validationMode - the validation (or construction) mode to be used for source documents. One of Validation.STRIP, Validation.PRESERVE, Validation.STRICT, Validation.LAX

Since:

9.2

setApplyFunctionConversionRulesToExternalVariables

public void setApplyFunctionConversionRulesToExternalVariables(boolean convert)

Say whether the function conversion rules should be applied to supplied parameter values. For example, this allows an integer to be supplied as the value for a parameter where the expected type is xs:double. The default is true.

Parameters:

convert - true if function conversion rules are to be applied to supplied values; if false, the supplied value must match the required type exactly.

Since:

9.3

isApplyFunctionConversionRulesToExternalVariables

public boolean isApplyFunctionConversionRulesToExternalVariables()

Ask whether the function conversion rules should be applied to supplied parameter values. For example, this allows an integer to be supplied as the value for a parameter where the expected type is xs:double. The default is true.

Returns:

true if function conversion rules are to be applied to supplied values; if false, the supplied value must match the required type exactly.

Since:

9.3

setContextNode

public void setContextNode(NodeInfo node)

Deprecated. From Saxon 8.7, the method setContextItem(Item) is preferred

Set the context item for evaluating the expression to be a node. If this method is not called, the context node will be undefined. The context node is available as the value of the expression ".". To obtain a NodeInfo by parsing a source document, see the method buildDocument in class QueryProcessor.

Parameters:

node - The node that is to be the context node for the query

Since:

8.4

setContextItem

public void setContextItem(Item item)

Set the context item for evaluating the expression. If this method is not called, the context node will be undefined. The context item is available as the value of the expression ".",. To obtain a node by parsing a source document, see the method buildDocument in class QueryProcessor.

Parameters:

item - The item that is to be the context item for the query

Throws:

IllegalArgumentException - if the supplied item is a node that was built under the wrong Saxon Configuration

NullPointerException - if the supplied item is null

Since:

8.4

getContextItem

public Item getContextItem()

Get the context item for the query, as set using setContextItem() or setContextNode().

Returns:

the context item if set, or null otherwise.

Since:

8.4

setParameter

public void setParameter(String expandedName,
                Object value)

Set a parameter for the query.

Parameters:

expandedName - The name of the parameter in "{uri}local-name" format. It is not an error to supply a value for a parameter that has not been declared, the parameter will simply be ignored. If the parameter has been declared in the query (as an external global variable) then it will be initialized with the value supplied.

value - The value of the parameter. This can be any valid Java object. It follows the same conversion rules as a value returned from a Saxon extension function. An error will occur at query execution time if the supplied value cannot be converted to the required type as declared in the query. For precise control of the type of the value, instantiate one of the classes in the net.sf.saxon.value package, for example net.sf.saxon.value.DayTimeDuration.

Since:

8.4

setParameterValue

public void setParameterValue(String expandedName,
                     Sequence value)

Set a parameter for the query.

Parameters:

expandedName - The name of the parameter in "{uri}local-name" format. It is not an error to supply a value for a parameter that has not been declared, the parameter will simply be ignored. If the parameter has been declared in the query (as an external global variable) then it will be initialized with the value supplied.

value - The value of the parameter. This must be an XPath value in its Saxon representation: no conversion occurs. The value is not checked at this stage against its required type; such checking will happen later, when the query is executed.

Since:

8.8

clearParameters

public void clearParameters()

Reset the parameters to an empty list.

getParameter

public Object getParameter(String expandedName)

Get the actual value of a parameter to the query.

Parameters:

expandedName - the name of the required parameter, in "{uri}local-name" format

Returns:

the value of the parameter, if it exists, or null otherwise

setParameters

public void setParameters(GlobalParameterSet params)

Set all the supplied parameters as a HashMap. The key is the expanded QName in Clark notation, the value is the value as supplied to setParameterValue

Parameters:

params - a structure containing all the parameters

getParameters

public GlobalParameterSet getParameters()

Get all the supplied parameters.

Returns:

a structure containing all the parameters

setURIResolver

public void setURIResolver(URIResolver resolver)

Set an object that will be used to resolve URIs used in fn:document() and related functions.

Parameters:

resolver - An object that implements the URIResolver interface, or null.

Since:

8.4

getURIResolver

public URIResolver getURIResolver()

Get the URI resolver.

Returns:

the user-supplied URI resolver if there is one, or the system-defined one otherwise

Since:

8.4

setUnparsedTextURIResolver

public void setUnparsedTextURIResolver(UnparsedTextURIResolver resolver)

Set an object that will be used to resolve URIs used in fn:unparsed-text() and related functions.

Parameters:

resolver - An object that implements the UnparsedTextURIResolver interface, or null.

Since:

9.5

getUnparsedTextURIResolver

public UnparsedTextURIResolver getUnparsedTextURIResolver()

Get the URI resolver for unparsed text.

Returns:

the user-supplied unparsed text URI resolver if there is one, or the system-defined one otherwise

Since:

8.4

setErrorListener

public void setErrorListener(ErrorListener listener)

Set the error listener. The error listener receives reports of all run-time errors and can decide how to report them.

Parameters:

listener - the ErrorListener to be used

Since:

8.4

getErrorListener

public ErrorListener getErrorListener()

Get the error listener.

Returns:

the ErrorListener in use

Since:

8.4

setTraceListener

public void setTraceListener(TraceListener listener)

Set the trace listener. The trace listener receives reports of all run-time expression evaluation.

Parameters:

listener - the TraceListener to be used

Since:

9.0

getTraceListener

public TraceListener getTraceListener()

Get the trace listener.

Returns:

the TraceListener in use, or null if none is in use

Since:

9.0

setTraceFunctionDestination

public void setTraceFunctionDestination(PrintStream stream)

Set the destination for output from the fn:trace() function. By default, the destination is System.err. If a TraceListener is in use, this is ignored, and the trace() output is sent to the TraceListener.

Parameters:

stream - the PrintStream to which trace output will be sent. If set to null, trace output is suppressed entirely. It is the caller's responsibility to close the stream after use.

Since:

9.1

getTraceFunctionDestination

public PrintStream getTraceFunctionDestination()

Get the destination for output from the fn:trace() function.

Returns:

the PrintStream to which trace output will be sent. If no explicitly destination has been set, returns System.err. If the destination has been set to null to suppress trace output, returns null.

Since:

9.1

getCurrentDateTime

public DateTimeValue getCurrentDateTime()

Get the date and time set previously using setCurrentDateTime(net.sf.saxon.value.DateTimeValue) or null if none has been set.

Returns:

the current date and time, if it has been set.

Since:

8.5

setCurrentDateTime

public void setCurrentDateTime(DateTimeValue dateTime)
                        throws XPathException

Set a value to be used as the current date and time for the query. By default, the "real" current date and time are used. The main purpose of this method is that it allows repeatable results to be achieved when testing queries.

This method also has the effect of setting the implicit timezone.

Parameters:

dateTime - The value to be used as the current date and time. This must include a timezone. The timezone from this value will also be used as the implicit timezone

Throws:

XPathException - if the dateTime does not include a timezone

Since:

8.5

getConfiguration

public Configuration getConfiguration()

Get the Configuration associated with this dynamic query context

Returns:

the Configuration

Since:

8.8

initializeController

public void initializeController(Controller controller)

Apply the settings from this DynamicQueryContext to a Controller

Parameters:

controller - the Controller whose settings are to be initialized