Table of Contents
These XQuery functions provide an access to the XML Library API.
They give XQuery applications the capacity to browse Libraries and Collections, get and modify the metadata, create and delete documents.
Administration functions such as creating and deleting Libraries are documented in the next chapter.
Please note the following points:
objects returned and handled by such functions are in general foreign objects (type xdt:object
) wrapping objects Document, Collection of the Java API of Qizx.
Yet they can be used as the origin of a path expression, in the same way as functions fn:doc
or fn:collection
. This is an extension of the semantics of Path expressions. For example theses two expressions are equivalent:
fn:collection("/shakespeare/comedies")//LINE xlib:collection("/shakespeare/comedies")//LINE
Functions that modify a XML Library (store-document, set-property, delete) should always be wrapped inside a try/catch construct, as they may generate errors. The try/catch also ensures that operations in a sequence are all performed, and in the specified order. This is otherwise not guaranteed, as XQuery is a functional language whose implementation can typically use rewriting and lazy evaluation techniques. Example:
try { xlib:delete-member("/foo/bar.xml"), xlib:commit() } catch($err) { xlib:rollback(), element error { $err } }
fn:collection ($path
as xs:string) as node()* fn:collection ($path-pattern
as xs:string,$predicate
) as node()*
This is the standard collection()
function of XQuery, but with extensions.
Parameter $path
: This argument can have several meanings:
path of a collection inside the current XML Library: all documents within the collection (at any level) are part of the result.
If no such collection can be found, an error is raised.
It can also be a list of documents paths, separated by commas or semicolons.
A normal path (without wildcard characters) is treated as per the function fn:doc()
. So it can either be part of a XML Library, or be an external document (file or URL) parsed on the fly.
If a path contains the wildcard characters *
or ?
, it is treated as a file pattern and expanded. Attention: wildcard characters are currently accepted only in the file name, not in the path of the parent directory.
For example
can be expanded, while collection("/home/data1/*.xml;/home/data2/*.xml")
currently cannot be expanded.collection("/home/*/*.xml;")
All of these documents must be reachable, or an error is raised.
Parameter $path-pattern
: The (extended) second form of the function accept a path pattern with wildcard characters "*
" , "**
"and "?
".
A document whose path matches the pattern is part of the result.
If the pattern matches the path of a Collection, then all documents within the collection (at any level) are added to the result.
If there are not wildcard characters, but the pattern is the path of a Collection, then all documents within the collection (at any level) are part of the result (like in the other form of the function).
The wildcard characters have the following (usual) meaning:
Question mark "?
": matches a single character.
Star "*
": matches any sequence of characters but the slash.
For example the pattern /a/b/*.xml
matches the document path /a/b/doc.xml
.
Double star "**
": matches any sequence of characters including the slash.
For example the pattern /**/doc.xml
matches the document path /a/b/doc.xml
.
Parameter $predicate
: This is a logical expression on the properties of Collections and Documents in a XML Library.
Properties can be predefined (like path
and nature
) or can be added by function xlib:set-property
(see below).
Example: this expression returns the document nodes of all documents within the library whose property 'import-date' is more recent than the value below:
collection("/", import-date > xs:date('2006-12-31'))
Returned value: a sequence of document nodes. An error can be raised in some cases (see above).
xlib:collection ($path
as xs:string)
as xdt:object[Collection]?
Finds a Collection by path.
Parameter $path
: path of the collection inside the current XML Library.
Returned value: a Collection handle, or the empty sequence if the collection cannot be found.
Attention, this is not equivalent to fn:collection
: here a handle to a collection is returned. It is meant for handling metadata properties or locking. However this object can also be used as the origin of a path expression.
xlib:parent-collection ($lib-member
)
as xdt:object[Collection]?
Returns the parent (enclosing) Collection of a Document or a Collection.
Parameter $lib-member
: handle of a Collection or a Document, or its path as a string.
Returned value: a Collection handle, or the empty sequence if the object is the root collection.
xlib:parent-collection ($node
as node())
as xdt:object[Collection]?
Returns the parent (enclosing) Collection of a XML node.
Parameter $node
: a node of a Document stored in a XML Library.
Returned value: a Collection handle, or the empty sequence if the node does not belong to a document of a XML Library.
xlib:document ($path
as xs:string)
as xdt:object[Document]?
Finds a document by its complete path in the XML Library. Returns a descriptor of the document, which can be used for handling metadata, locking.
Parameter $path
: path of the document inside the current XML Library.
Returned value: a Document handle, or the empty sequence if the document cannot be found.
xlib:document($collection
as xdt:object[Collection], $name as xs:string)
as xdt:object[Document]?
Finds a document by its name and its parent collection. Returns a descriptor of the document, which can be used for handling metadata, locking.
Parameter $name
: simple name of the document.
Returned value: a Document handle, or the empty sequence if the document cannot be found.
xlib:document ($node
as node())
as xdt:object[Document]?
Finds the XML Document that contains a given node.
Parameter $node
: a node of the XQuery Data Model.
Returned value: a Document handle, or the empty sequence if the node does not belong to a XML Document (i.e. a constructed or parsed node).
xlib:get-children ($collection
as xdt:object)
as xdt:object[LibraryMember]*
Returns Library Members (Documents and Collections) directly contained in a collection.
Parameter $collection: handle of a collection.
Returned value: a sequence of documents and collections. So it is possible to write:
for $doc in xlib:get-children($collection) return ...
xlib:query-properties ($path-pattern
as xs:string,$predicate
) as xdt:object[LibraryMember]*
This function searches for Documents and Collections whose properties satisfy a logical expression ($predicate). It is similar to the extended fn:collection
function, but it returns a sequence of Documents and Collections, while fn:collection returns the root nodes of found documents.
Parameter $path-pattern
: This is a path pattern with wildcard characters "*
" , "**
" and "?
".
A document or collection whose path matches the pattern is part of the result (provided that its properties satisfy the second argument predicate
).
If there are not wildcard characters, but the pattern is the path of a Collection, then all documents and sub-collections within the collection (at any level) are part of the result, provided that their properties satisfy the second argument $predicate
.
The wildcard characters have the following (usual) meaning:
Question mark "?
": matches a single character.
Star "*
": matches any sequence of characters but the slash.
For example the pattern /a/b/*.xml
matches the document path /a/b/doc.xml
.
Double star "**
": matches any sequence of characters including the slash.
For example the pattern /**/doc.xml
matches the document path /a/b/doc.xml
.
Parameter $predicate
: This is a logical expression that must be satisfied by the properties of Collections and Documents which have been selected by the previous argument $path-pattern
.
Properties can be predefined (like path
and nature
) or can be added by function xlib:set-property
(see below).
Returned value: a sequence of Library members (Documents and Collections).
Example: look for documents whose property creation-date
is greater than a given value and have a description
property which is a XML fragment containing the words "suitable
" and "purpose
".
for $doc in xlib:queryProperties ("/2005/propositions/*", creation-date > xs:date("2003-03-03") and x:fulltext(description, "suitable AND purpose")) return xlib:property($doc, "path")
function xlib:property-names ($lib-member
)
as xs:string*
Lists the metadata properties associated with an object in the library.
Predefined properties, created by default, are described in reference documentation.
Parameter $lib-member
: handle of a Collection or a Document, or its path as a string.
Returned value: a sequence of the property names. The value of each property can be retrieved with the following function.
function xlib:get-property ($lib-member
,$property-name
as xs:string) as item()?
Retrieves the value of a metadata property associated with an object in the library.
Predefined properties, created by default, are described in reference documentation.
Parameter $lib-member
: handle of a Collection or a Document, or its path as a string.
Parameter $property-name
: name of the property.
Returned value: the current value of the property, any serializable object.
function xlib:set-property ($lib-member
,$property-name
as xs:string, $value as item())
Sets the value of a metadata property of an object in the library. The property is created if necessary.
This function may be called only if the object is locked by a transaction, directly or indirectly (a document is locked if the enclosing collection is locked, or an enclosing closure collection is locked, or the whole library is locked).
Parameter $lib-member
: handle of a Collection or a Document, or its path as a string.
Parameter $property-name
: name of the property. The "path
" and "nature
" property names are reserved and cannot be modified.
Parameter $value
: the new value of the property, any serializable object, in particular it can be a Node. Notice that it is not recommended to store massive amounts of data in properties.
Returned value: none.
function xlib:lock ($lib-member
*,$timeout
as xs:integer?) as xs:boolean
Locks an object (Collection or Document) for modification. The object will be unlocked only by a commit or a rollback.
It is not possible to make several calls to the lock function without invoking commit or rollback before each new lock (in other terms, only one lock is allowed per commit).
Parameter $lib-member
: a sequence of Collection or a Document handles or paths.
Parameter $timeout
: (optional) an integer number of milliseconds to wait if the object is already locked by another transaction. If the object is not unlocked within this duration, the function returns false.
Returned value: If the objects could be locked, returns true. If false is returned, it can mean that one of the objects is locked by another session, or that one object was deleted by another session, or that the library member sequence was empty.
function xlib:commit()
Commits the current transaction and guarantees the modifications to be permanent.
All locked objects are unlocked. The changes become visible to other users (if they use refresh) and to new connections.
Returned value: none (empty sequence).
function xlib:rollback()
Cancels the changes made in the current transaction and unlocks all locked objects.
Returned value: none (empty sequence).
function xlib:write-document ($path
as xs:string,$contents
as node()) as xdt:object[Document] function xlib:write-document ($collection
as xdt:object[Collection],$name
as xs:string,$contents
as node()) as xdt:object[Document]
Creates or overwrites a document: this function can be used to edit document contents in XQuery, for example by transforming the contents of an existing document (using XQuery or XSLT) and storing back the result on the same document.
In Qizx a document can only be replaced as a whole: it is not possible for example to only modify a sub-element, an attribute, or to append inside an existing document. Therefore it is not efficient to repeatedly modify a massive document; this can however be quite acceptable if the document is relatively small (say up to 100 Kb in size).
Future versions of Qizx will most likely support XQuery Update (an extension of XQuery that allows specifying transformations). However the same principle will apply, a XQuery Update produces a new document that replaces the former one as a whole.
Parameter $path
: full path of the document inside the XML Library.
Parameter $collection
: the enclosing collection. This object must be locked.
Parameter $name
: name of the document, or a path relative to the collection (the enclosing collections are created automatically if necessary).
Parameter $contents
: an node (element or document-node) and its subtree which become the contents of the stored document.
Returned value: a handle on the new document. It can be used to set metadata properties on the document.
function xlib:delete-member ($lib-member
)
Deletes a document or a collection.
Parameter $lib-member
: handle of a Collection or a Document, or its path as a string.
Returned value: none.
function xlib:rename-member($src-path
as xs:string,$dst-path
as xs:string)
Renames a document or a collection.
Parameter $src-path
: original path of the Library member.
Parameter $dst-path
: destination path of the Library member. Must not correspond with an existing library member. Must point inside an existing Collection.
Returned value: none.
function xlib:copy-member($src-path
as xs:string,$dst-path
as xs:string)
Copies a document or a collection.
Parameter $src-path
: path of the source Library member. If it is a Collection, all the documents and sub-collections contained within are recursively copied.
Parameter $dst-path
: destination path of the Library member. Must not correspond with an existing library member. Must point inside an existing Collection.
Returned value: none.
The properties described here are created automatically when a document is stored into an XML Library.
NB: this can be controlled through the configuration property doc_node_stats
.
The LibraryMemberObserver
Collection
interface is the API allows implementing a handler which modifies this list (by adding other properties or deleting the predefined properties).
path of the Library member. Cannot be modified.
Value type: String.
Nature of the Library member.
Value type: String. Possible values are "document" and "collection".
Date at which the document was imported (created or modified).
Value type: Date (xs:dateTime).
If an access-control mechanism is defined, the name of the User who created or modified the document. The User descriptor is associated with the Library session.
Size in bytes of the document. This value represents an internal storage size. It is in general 10% to 30% smaller than the size of a serialized representation of the document in XML.
Value type: integer (xs:integer).
statistics: number of nodes of each kind in the document.
Value type: integer (xs:integer).
When a DTD is specified in the document (DOCTYPE declaration), these properties collect respectively the name of the DTD, its system- or public id, and if provided by the XML parser the contents of the internal subset, if any.
Otherwise these properties are absent.