javax.xml.xquery

Interface XQStaticContext

public interface XQStaticContext

An XQStaticContext represents default values for various XQuery Static Context Components. Further it includes the static XQJ properties for an XQExpression or XQPreparedExpression object.

The following XQuery Static Context Components are supported through the XQStaticContext interface:

As described in the XQuery specification, each of these default values can be overridden or augmented in the query prolog.

In addition XQStaticContext includes the static XQJ properties for an XQExpression or XQPreparedExpression object:

Note that XQStaticContext is a value object, changing attributes in such object doesn't affect any existing XQExpression or XQPreparedExpression object.
In order to take effect, the application needs to explicitly change the XQConnection default values, or specify an XQStaticContext object when creating an XQExpression or XQPreparedExpression.

  XQConnection conn = XQDatasource.getConnection();
  // get the default values from the implementation
  XQStaticContext cntxt = conn.getStaticContext();
  // change the base uri
  cntxt.setBaseURI("http://www.foo.com/xml/");
  // change the implementation defaults
   conn.setStaticContext(cntxt);
 
  // create an XQExpression using the new defaults
  XQExpression expr1 = conn.createExpression();
 
  // creat an XQExpression, using BaseURI "file:///root/user/john/"
  cntxt.setBaseURI("file:///root/user/john/");
  XQExpression expr2 = conn.createExpression(cntxt);
  ... 
 
Method Summary
voiddeclareNamespace(String prefix, String uri)
Declares a namespace prefix and associates it with a namespace URI.
StringgetBaseURI()
Gets the Base URI, if set in the static context, else the empty string.
intgetBindingMode()
Gets the value of the binding mode property.
intgetBoundarySpacePolicy()
Gets the boundary-space policy defined in the static context.
intgetConstructionMode()
Gets the construction mode defined in the static context.
XQItemTypegetContextItemStaticType()
Gets the static type of the context item.
intgetCopyNamespacesModeInherit()
Gets the inherit part of the copy-namespaces mode defined in the static context.
intgetCopyNamespacesModePreserve()
Gets the preserve part of the copy-namespaces mode defined in the static context.
StringgetDefaultCollation()
Gets the URI of the default collation.
StringgetDefaultElementTypeNamespace()
Gets the URI of the default element/type namespace, the empty string if not set.
StringgetDefaultFunctionNamespace()
Gets the URI of the default function namespace, the empty string if not set.
intgetDefaultOrderForEmptySequences()
Gets the default order for empty sequences defined in the static context.
intgetHoldability()
Gets the value of the holdability property.
String[]getNamespacePrefixes()
Returns the prefixes of all the statically known namespaces.
StringgetNamespaceURI(String prefix)
Retrieves the namespace URI associated with a prefix.
intgetOrderingMode()
Gets the ordering mode defined in the static context.
intgetQueryLanguageTypeAndVersion()
Gets the value of the language type and version property.
intgetQueryTimeout()
Retrieves the number of seconds an implementation will wait for a query to execute.
intgetScrollability()
Gets the value of the scrollability property.
voidsetBaseURI(String baseUri)
Sets the Base URI in the static context, specify the empty string to make it undefined.
voidsetBindingMode(int bindingMode)
Sets the binding mode property.
voidsetBoundarySpacePolicy(int policy)
Sets the boundary-space policy in the static context.
voidsetConstructionMode(int mode)
Sets the construction mode in the static context.
voidsetContextItemStaticType(XQItemType contextItemType)
Sets the static type of the context item, specify null to make it unspecified.
voidsetCopyNamespacesModeInherit(int mode)
Sets the inherit part of the copy-namespaces mode in the static context.
voidsetCopyNamespacesModePreserve(int mode)
Sets the preserve part of the copy-namespaces mode in the static context.
voidsetDefaultCollation(String uri)
Sets the URI of the default collation.
voidsetDefaultElementTypeNamespace(String uri)
Sets the URI of the default element/type namespace, the empty string to make it unspecified.
voidsetDefaultFunctionNamespace(String uri)
Sets the URI of the default function namespace, the empty string to make it unspecified.
voidsetDefaultOrderForEmptySequences(int order)
Sets the default order for empty sequences in the static context.
voidsetHoldability(int holdability)
Sets the holdability property.
voidsetOrderingMode(int mode)
Sets the ordering mode in the static context.
voidsetQueryLanguageTypeAndVersion(int langType)
Sets the input query language type and version.
voidsetQueryTimeout(int seconds)
Sets the number of seconds an implementation will wait for a query to execute.
voidsetScrollability(int scrollability)
Sets the scrollability of the result sequence.

Method Detail

declareNamespace

public void declareNamespace(String prefix, String uri)
Declares a namespace prefix and associates it with a namespace URI. If the namespace URI is the empty string, the prefix is removed from the in-scope namespace definitions.

Parameters: prefix the prefix for the namespace URI uri the namespace URI. An empty string undeclares the specific prefix. Cannot be null

Throws: XQException if (1) a null prefix, or (2) a null namespace URI is specified

getBaseURI

public String getBaseURI()
Gets the Base URI, if set in the static context, else the empty string.

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

getBindingMode

public int getBindingMode()
Gets the value of the binding mode property. By default an XQJ implementation operates in immediate binding mode.

Returns: the binding mode. One of XQConstants.BINDING_MODE_IMMEDIATE, orXQConstants.BINDING_MODE_DEFERRED.

getBoundarySpacePolicy

public int getBoundarySpacePolicy()
Gets the boundary-space policy defined in the static context.

Returns: the boundary-space policy value. One of: XQConstants.BOUNDARY_SPACE_PRESERVE, XQConstants.BOUNDARY_SPACE_STRIP.

getConstructionMode

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

Returns: construction mode value. One of: XQConstants.CONSTRUCTION_MODE_PRESERVE, XQConstants.CONSTRUCTION_MODE_STRIP

getContextItemStaticType

public XQItemType getContextItemStaticType()
Gets the static type of the context item. null if unspecified.

Returns: the static type of the context item, if set, else null

getCopyNamespacesModeInherit

public int getCopyNamespacesModeInherit()
Gets the inherit part of the copy-namespaces mode defined in the static context.

Returns: construction mode value. One of: XQConstants.COPY_NAMESPACES_MODE_INHERIT, XQConstants.COPY_NAMESPACES_MODE_NO_INHERIT.

getCopyNamespacesModePreserve

public int getCopyNamespacesModePreserve()
Gets the preserve part of the copy-namespaces mode defined in the static context.

Returns: construction mode value. One of: XQConstants.COPY_NAMESPACES_MODE_PRESERVE, XQConstants.COPY_NAMESPACES_MODE_NO_PRESERVE.

getDefaultCollation

public String getDefaultCollation()
Gets the URI of the default collation.

Returns: the URI of the default collation. Cannot be null.

getDefaultElementTypeNamespace

public String getDefaultElementTypeNamespace()
Gets the URI of the default element/type namespace, the empty string if not set.

Returns: the URI of the default element/type namespace, if set, else the empty string. Cannot be null

getDefaultFunctionNamespace

public String getDefaultFunctionNamespace()
Gets the URI of the default function namespace, the empty string if not set.

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

getDefaultOrderForEmptySequences

public int getDefaultOrderForEmptySequences()
Gets the default order for empty sequences defined in the static context.

Returns: default order for empty sequences value. One of: XQConstants.DEFAULT_ORDER_FOR_EMPTY_SEQUENCES_GREATEST, XQConstants.DEFAULT_ORDER_FOR_EMPTY_SEQUENCES_LEAST.

getHoldability

public int getHoldability()
Gets the value of the holdability property.

Returns: the type of a result's holdability. One of: XQConstants.HOLDTYPE_HOLD_CURSORS_OVER_COMMIT, or XQConstants.HOLDTYPE_CLOSE_CURSORS_AT_COMMIT.

getNamespacePrefixes

public String[] getNamespacePrefixes()
Returns the prefixes of all the statically known namespaces. Use the getNamespaceURI method to look up the namespace URI corresponding to a specific prefix.

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

getNamespaceURI

public String getNamespaceURI(String prefix)
Retrieves the namespace URI associated with a prefix. An XQException is thrown if an unknown prefix is specified, i.e. a prefix not returned by the getInScopeNamespacePrefixes method.

Parameters: prefix the prefix for which the namespace URI is sought. Cannot be null

Returns: the namespace URI. Cannot be null

Throws: XQException if a null prefix is specified or if the prefix is unknown

getOrderingMode

public int getOrderingMode()
Gets the ordering mode defined in the static context.

Returns: ordering mode value. One of: XQConstants.ORDERING_MODE_ORDERED, XQConstants.ORDERING_MODE_UNORDERED.

getQueryLanguageTypeAndVersion

public int getQueryLanguageTypeAndVersion()
Gets the value of the language type and version property. By default an XQJ implementation's default is XQConstants.LANGTYPE_XQUERY.

Returns: the language type and version. One of: XQConstants.LANGTYPE_XQUERY, or XQConstants.LANGTYPE_XQUERYX or a negative value indicating a vendor specific query language type and version.

getQueryTimeout

public int getQueryTimeout()
Retrieves the number of seconds an implementation will wait for a query to execute.

Returns: the query execution timeout value in seconds. A value of 0 indicates no limit.

getScrollability

public int getScrollability()
Gets the value of the scrollability property. By default query results are forward only.

Returns: the type of a result's scrollability. One of: XQConstants.SCROLLTYPE_FORWARD_ONLY, or XQConstants.SCROLLTYPE_SCROLLABLE.

setBaseURI

public void setBaseURI(String baseUri)
Sets the Base URI in the static context, specify the empty string to make it undefined.

Parameters: baseUri the new baseUri, or empty string to make it undefined. Cannot be null.

Throws: XQException if a null base uri is specified

setBindingMode

public void setBindingMode(int bindingMode)
Sets the binding mode property. By default an XQJ implementation operates in immediate binding mode.

Parameters: bindingMode the binding mode. One of: XQConstants.BINDING_MODE_IMMEDIATE, orXQConstants.BINDING_MODE_DEFERRED.

Throws: XQException the specified mode is different from XQConstants.BINDING_MODE_IMMEDIATE, XQConstants.BINDING_MODE_DEFERRED

setBoundarySpacePolicy

public void setBoundarySpacePolicy(int policy)
Sets the boundary-space policy in the static context.

Parameters: policy boundary space policy. One of: XQConstants.BOUNDARY_SPACE_PRESERVE, XQConstants.BOUNDARY_SPACE_STRIP.

Throws: XQException the specified mode is different from XQConstants.BOUNDARY_SPACE_PRESERVE, XQConstants.BOUNDARY_SPACE_STRIP

setConstructionMode

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

Parameters: mode construction mode value. One of: XQConstants.CONSTRUCTION_MODE_PRESERVE, XQConstants.CONSTRUCTION_MODE_STRIP.

Throws: XQException the specified mode is different from XQConstants.CONSTRUCTION_MODE_PRESERVE, XQConstants.CONSTRUCTION_MODE_STRIP

setContextItemStaticType

public void setContextItemStaticType(XQItemType contextItemType)
Sets the static type of the context item, specify null to make it unspecified.

Parameters: contextItemType the static type of the context item; null if unspecified.

Throws: XQException if the contextItemType is not a valid XQItemType

setCopyNamespacesModeInherit

public void setCopyNamespacesModeInherit(int mode)
Sets the inherit part of the copy-namespaces mode in the static context.

Parameters: mode ordering mode value. One of: XQConstants.COPY_NAMESPACES_MODE_INHERIT, XQConstants.COPY_NAMESPACES_MODE_NO_INHERIT.

Throws: XQException the specified mode is different from XQConstants.COPY_NAMESPACES_MODE_INHERIT, XQConstants.COPY_NAMESPACES_MODE_NO_INHERIT

setCopyNamespacesModePreserve

public void setCopyNamespacesModePreserve(int mode)
Sets the preserve part of the copy-namespaces mode in the static context.

Parameters: mode ordering mode value. One of: XQConstants.COPY_NAMESPACES_MODE_PRESERVE, XQConstants.COPY_NAMESPACES_MODE_NO_PRESERVE.

Throws: XQException the specified mode is different from XQConstants.COPY_NAMESPACES_MODE_PRESERVE, XQConstants.COPY_NAMESPACES_MODE_NO_PRESERVE

setDefaultCollation

public void setDefaultCollation(String uri)
Sets the URI of the default collation.

Parameters: uri the namespace URI of the default collation. Cannot be null.

Throws: XQException if a null URI is specified

setDefaultElementTypeNamespace

public void setDefaultElementTypeNamespace(String uri)
Sets the URI of the default element/type namespace, the empty string to make it unspecified.

Parameters: uri the namespace URI of the default element/type namespace, the empty string to make it unspecified. Cannot be null.

Throws: XQException if a null uri is specified

setDefaultFunctionNamespace

public void setDefaultFunctionNamespace(String uri)
Sets the URI of the default function namespace, the empty string to make it unspecified.

Parameters: uri the namespace URI of the default function namespace, the empty string to make it unspecified. Cannot be null.

Throws: XQException if a null URI is specified

setDefaultOrderForEmptySequences

public void setDefaultOrderForEmptySequences(int order)
Sets the default order for empty sequences in the static context.

Parameters: order the default order for empty sequences. One of: XQConstants.DEFAULT_ORDER_FOR_EMPTY_SEQUENCES_GREATEST, XQConstants.DEFAULT_ORDER_FOR_EMPTY_SEQUENCES_LEAST.

Throws: XQException the specified order for empty sequences is different from XQConstants.DEFAULT_ORDER_FOR_EMPTY_SEQUENCES_GREATEST, XQConstants.DEFAULT_ORDER_FOR_EMPTY_SEQUENCES_LEAST

setHoldability

public void setHoldability(int holdability)
Sets the holdability property.

Parameters: holdability the holdability of the result. One of: XQConstants.HOLDTYPE_HOLD_CURSORS_OVER_COMMIT, or XQConstants.HOLDTYPE_CLOSE_CURSORS_AT_COMMIT.

Throws: XQException the specified holdability is different from XQConstants.HOLDTYPE_HOLD_CURSORS_OVER_COMMIT, XQConstants.HOLDTYPE_CLOSE_CURSORS_AT_COMMIT

setOrderingMode

public void setOrderingMode(int mode)
Sets the ordering mode in the static context.

Parameters: mode ordering mode value. One of: XQConstants.ORDERING_MODE_ORDERED, XQConstants.ORDERING_MODE_UNORDERED.

Throws: XQException the specified mode is different from XQConstants.ORDERING_MODE_ORDERED, XQConstants.ORDERING_MODE_UNORDERED

setQueryLanguageTypeAndVersion

public void setQueryLanguageTypeAndVersion(int langType)
Sets the input query language type and version. When this is set to a particular language type and version, then the query is assumed to be in that language and version.

Parameters: langType the query language type and version of the inputs. One of: XQConstants.LANGTYPE_XQUERY (default), or XQConstants.LANGTYPE_XQUERYX. A negative number indicates a vendor specific query language type and version.

Throws: XQException the specified langtype is different from XQConstants.LANGTYPE_XQUERY, XQConstants.LANGTYPE_XQUERYX and is not negative

setQueryTimeout

public void setQueryTimeout(int seconds)
Sets the number of seconds an implementation will wait for a query to execute. If the implementation does not support query timeout it can ignore the specified timeout value. It the limit is exceeded, the behavor of the query is the same as an execution of a cancel by another thread.

Parameters: seconds the query execution timeout value in seconds. A value of 0 indicates no limit

Throws: XQException if the passed in value is negative

setScrollability

public void setScrollability(int scrollability)
Sets the scrollability of the result sequence. By default query results are forward only.

Parameters: scrollability the scrollability of the result. One of: XQConstants.SCROLLTYPE_FORWARD_ONLY, or XQConstants.SCROLLTYPE_SCROLLABLE.

Throws: XQException the specified crollability type is different from XQConstants.SCROLLTYPE_FORWARD_ONLY, XQConstants.SCROLLTYPE_SCROLLABLE