Difference between revisions of "Lazy Module"
| Line 1: | Line 1: | ||
This [[Module Library|XQuery Module]] contains functions for handling ''streamable'' items. | This [[Module Library|XQuery Module]] contains functions for handling ''streamable'' items. | ||
| − | In contrast to standard XQuery items, streamable | + | 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: | The following BaseX functions return streamable items: | ||
| Line 38: | Line 38: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
| − | |Returns a materialized instance of the specified {{Code|$item}} | + | |Returns a materialized instance of the specified {{Code|$item}}:<br /> |
| + | * 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, such as the deletion of a resource, take place. | ||
| + | |- | ||
| + | | '''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: | ||
| + | <pre class="brush:xquery"> | ||
| + | let $file := 'data.txt' | ||
| + | let $data := stream:materialize(file:read-text($file)) | ||
| + | return (file:delete($file), $data) | ||
| + | </pre> | ||
|} | |} | ||
Revision as of 20:59, 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:
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, such as the deletion of a resource, take place. |
| 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.
