Difference between revisions of "Lazy Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 41: Line 41:
 
* if an item is streamable, its value will be retrieved, and a new item containing the value will be returned.
 
* 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.
 
* other, non-streamable items will simply be passed through.
Materialization is helpful if a value is to be processed more than once. It is even mandatory if the value needs to be retrieved before other actions take place that invalidate the resource, such as a deletion of an addressed file.
+
Materialization is helpful if a value is to be processed more than once. It is even mandatory if the value needs to be retrieved before other actions take place that invalidate the resource, such as the deletion of an addressed file.
 
|-
 
|-
 
| '''Example'''
 
| '''Example'''

Revision as of 20:01, 12 March 2013

This XQuery Module contains functions for handling streamable items.

In contrast to standard XQuery items, a streamable item only contains 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 serves as an example on how large files can be downloaded and written to a file with constant memory consumption:

file:write-binary('output.data', fetch:binary('http://files.basex.org/xml/xmark111mb.zip'))

Conventions

All functions in this module are assigned to the http://basex.org/modules/stream namespace, which is statically bound to the stream prefix.
All errors are assigned to the http://basex.org/errors namespace, which is statically bound to the bxerr prefix.

Functions

stream:materialize

Signatures stream:materialize($item as item()) as item()
Summary Returns a materialized instance of the specified $item:
  • 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 helpful if a value is to be processed more than once. It is even mandatory if the value needs to be retrieved before other actions take place that invalidate the resource, such as the deletion of an addressed file.

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)

stream:is-streamable

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

Changelog

This module was introduced with Version 7.7.