Streaming Module

From BaseX Documentation

Jump to: navigation, search

This XQuery Module contains functions for handling streamable items.

In contrast to standard XQuery items, a streamable item contains only a reference to the actual data. The data itself will be retrieved if it is requested by an expression, or if the item is to be serialized. Hence, a streamable item only uses a few bytes, and no additional memory is occupied during serialization.

The following BaseX functions return streamable items:

Some functions are capable of consuming items in a streamable fashion: data will never be cached, but instead passed on to another target (file, the calling expression, etc.). The following streaming functions are currently available:

The XQuery expression below serves as an example on how large files can be downloaded and written to a file with constant memory consumption:

file:write-binary('', fetch:binary(''))


[edit] Conventions

All functions in this module are assigned to the namespace, which is statically bound to the stream prefix.
All errors are assigned to the namespace, which is statically bound to the bxerr prefix.

[edit] Functions

[edit] stream:materialize

Signatures stream:materialize($value as item()*) as item()*
Summary Returns a materialized instance of the specified $value:
  • if an item is streamable, its value will be retrieved, and a new item containing the value will be returned.
  • other, non-streamable items will simply be passed through.

Materialization is advisable if a value is to be processed more than once, and is expensive to retrieve. It is get mandatory whenever a value is invalidated before it is requested (see the example below).

Example In the following example, a file will be deleted before its content is returned. To avoid a "file not found" error, the content will first be materialized:
let $file := 'data.txt'
let $data := stream:materialize(file:read-text($file))
return (file:delete($file), $data)

[edit] stream:is-streamable

Signatures stream:is-streamable($item as item()) as item()
Summary Checks whether the specified $item is streamable.

[edit] Changelog

Version 8.0

This module was introduced with Version 7.7.

Personal tools