XQuery Function Documentation

http://exist-db.org/xquery/xmldb

java:org.exist.xquery.functions.xmldb.XMLDBModule

A module for database manipulation functions.

xmldb:authenticate#3

xmldb:authenticate($collection-uri as xs:string, $user-id as xs:string?, $password as xs:string?) as xs:boolean

Check if the user, $user-id, can authenticate against the database collection $collection-uri. The function simply tries to read the collection $collection-uri, using the credentials $user-id and $password. Collection URIs can be specified either as a simple collection path or an XMLDB URI. It returns true if the authentication succeeds, false otherwise.

Parameters:

$collection-uri	The collection URI
$user-id	The user-id
$password	The password

Returns:

xs:boolean : true() on successful authentication, false() otherwise

xmldb:clear-lock#2

xmldb:clear-lock($collection-uri as xs:string, $resource as xs:string) as xs:string

Removes the user lock on the resource $resource in the collection $collection-uri. If no lock is in place, the empty sequence is returned. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:

$collection-uri	The collection URI
$resource	The resource

Returns:

xs:string? : the user id of the previous lock owner, otherwise if not locked the empty sequence

xmldb:collection-available#1

xmldb:collection-available($collection-uri as xs:string) as xs:boolean

Returns true() if the collection $collection-uri exists and is available, otherwise false(). Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:

$collection-uri

The collection URI

Returns:

xs:boolean : true() if the collection exists and is available, false() otherwise

xmldb:copy-collection#2

xmldb:copy-collection($source-collection-uri as xs:string, $target-collection-uri as xs:string) as xs:string

Copy the collection $source-collection-uri to the collection $target-collection-uri.

Parameters:

$source-collection-uri	The source URI
$target-collection-uri	The target URI

Returns:

xs:string : The path to the newly copied collection

xmldb:copy-collection#3

xmldb:copy-collection($source-collection-uri as xs:string, $target-collection-uri as xs:string, $preserve as xs:boolean) as xs:string

Copy the collection $source-collection-uri to the collection $target-collection-uri.

Parameters:

$source-collection-uri	The source URI
$target-collection-uri	The target URI
$preserve	Cause the copy process to preserve the following attributes of each source in the copy: modification time, file mode, user ID, and group ID, as allowed by permissions. Access Control Lists (ACLs) will also be preserved

Returns:

xs:string : The path to the newly copied collection

xmldb:copy-resource#4

xmldb:copy-resource($source-collection-uri as xs:string, $source-resource-name as xs:string, $target-collection-uri as xs:string, $target-resource-name as xs:string?) as xs:string

Copy the resource $source-collection-uri/$source-resource-name to collection $target-collection-uri/$target-resource-name. If the $target-resource-name is omitted, the $source-resource-name will be used.

Parameters:

$source-collection-uri	The source URI
$source-resource-name	The name of the resource to copy
$target-collection-uri	The target URI
$target-resource-name	The name of the resource for the target

Returns:

xs:string : The path to the newly copied resource

xmldb:copy-resource#5

xmldb:copy-resource($source-collection-uri as xs:string, $source-resource-name as xs:string, $target-collection-uri as xs:string, $target-resource-name as xs:string?, $preserve as xs:boolean) as xs:string

Parameters:

$source-collection-uri	The source URI
$source-resource-name	The name of the resource to copy
$target-collection-uri	The target URI
$target-resource-name	The name of the resource for the target
$preserve	Cause the copy process to preserve the following attributes of each source in the copy: modification time, file mode, user ID, and group ID, as allowed by permissions. Access Control Lists (ACLs) will also be preserved

Returns:

xs:string : The path to the newly copied resource

xmldb:create-collection#2

xmldb:create-collection($target-collection-uri as xs:string, $new-collection as xs:string) as xs:string

Create a new collection with name $new-collection as a child of $target-collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.Returns the path to the new collection if successfully created, otherwise the empty sequence.

Parameters:

$target-collection-uri	The target collection URI
$new-collection	The name of the new collection to create

Returns:

xs:string? : the path to the new collection if successfully created, otherwise the empty sequence

xmldb:created#1

xmldb:created($collection-uri as xs:string) as xs:dateTime

Returns the creation date of the collection $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:

$collection-uri

The collection URI

Returns:

xs:dateTime : the creation date

xmldb:created#2

xmldb:created($collection-uri as xs:string, $resource as xs:string) as xs:dateTime

Returns the creation date of the resource $resource in $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:

$collection-uri	The collection URI
$resource	The resource

Returns:

xs:dateTime : the creation date

xmldb:decode#1

xmldb:decode($string as xs:string) as xs:string

Decodes the string $string such that any percent encoded octets will be translated to their decoded UTF-8 representation.

Parameters:

$string

The input string

Returns:

xs:string : the decoded string

xmldb:decode-uri#1

xmldb:decode-uri($uri as xs:anyURI) as xs:string

Decodes the URI $uri such that any percent encoded octets will be translated to their decoded UTF-8 representation.

Parameters:

$uri

The URI

Returns:

xs:string : the decoded $uri as xs:string

xmldb:defragment#1

xmldb:defragment($nodes as node()+) as empty-sequence()

Start a defragmentation run on each document which has a node in $nodes. Fragmentation may occur if nodes are inserted into a document using XQuery update extensions. Please note that defragmenting a document changes its internal structure, so any references to this document will become invalid, in particular, variables pointing to some nodes in the document.

Parameters:

$nodes

The sequence of nodes from the documents to defragment

Returns:

empty-sequence()

xmldb:defragment#2

xmldb:defragment($nodes as node()+, $integer as xs:integer) as empty-sequence()

Start a defragmentation run on each document which has a node in $nodes. Fragmentation may occur if nodes are inserted into a document using XQuery update extensions. The second argument specifies the minimum number of fragmented pages which should be in a document before it is considered for defragmentation. Please note that defragmenting a document changes its internal structure, so any references to this document will become invalid, in particular, variables pointing to some nodes in the document.

Parameters:

$nodes	The sequence of nodes from the documents to defragment
$integer	The minimum number of fragmented pages required before defragmenting

Returns:

empty-sequence()

xmldb:document-has-lock#2

xmldb:document-has-lock($collection-uri as xs:string, $resource as xs:string) as xs:string

Returns the user-id of the user that holds a write lock on the resource $resource in the collection $collection-uri. If no lock is in place, the empty sequence is returned. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:

$collection-uri	The collection URI
$resource	The resource

Returns:

xs:string? : the user id of the lock owner, otherwise if not locked the empty sequence

xmldb:encode#1

xmldb:encode($string as xs:string) as xs:string

Encodes the string $string such that it will be a valid collection or resource path. Provides similar functionality to java's URLEncoder.encode() function, with some enhancements.

Parameters:

$string

The input string

Returns:

xs:string : the URL encoded string

xmldb:encode-uri#1

xmldb:encode-uri($string as xs:string) as xs:anyURI

Encodes the string $string such that it will be a valid collection or resource path. Provides similar functionality to java's URLEncoder.encode() function, with some enhancements. Returns an xs:anyURI object representing a valid XmldbURI

Parameters:

$string

The input string

Returns:

xs:anyURI : the XmldbURI encoded from $string

xmldb:find-last-modified-since#2

xmldb:find-last-modified-since($node-set as node()*, $since as xs:dateTime) as node()

Filters the given node set to only include nodes from resources which were modified since the specified date time.

Parameters:

$node-set	A node set
$since	Date

Returns:

node()* : the filtered node set.

xmldb:find-last-modified-until#2

xmldb:find-last-modified-until($node-set as node()*, $until as xs:dateTime) as node()

Filters the given node set to only include nodes from resources which were modified until the specified date time.

Parameters:

$node-set	A node set
$until	Date

Returns:

node()* : the filtered node set.

xmldb:get-child-collections#1

xmldb:get-child-collections($collection-uri as xs:string) as xs:string

Returns the names of the child collections in the collection $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:

$collection-uri

The collection URI

Returns:

xs:string* : the sequence of child collection names

xmldb:get-child-resources#1

xmldb:get-child-resources($collection-uri as item()) as xs:string

Returns the names of the child resources in collection $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:

$collection-uri

The collection URI

Returns:

xs:string* : the sequence of resource names

xmldb:get-mime-type#1

xmldb:get-mime-type($resource-uri as xs:anyURI) as xs:string

Returns the MIME type if available of the resource $resource-uri, otherwise the empty sequence. Resource URIs can be specified either as a simple collection path, an XMLDB URI or any URI.

Parameters:

$resource-uri

The resource URI

Returns:

xs:string? : the mime-type if available, otherwise the empty sequence

xmldb:last-modified#2

xmldb:last-modified($collection-uri as item(), $resource as xs:string) as xs:dateTime

Returns the last-modification date of resource $resource in collection $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:

$collection-uri	The collection URI
$resource	The resource

Returns:

xs:dateTime? : the last modification date

xmldb:login#3

xmldb:login($collection-uri as xs:string, $user-id as xs:string?, $password as xs:string?) as xs:boolean

Login the user, $user-id, and set it as the owner of the currently executing XQuery. Collection URIs can be specified either as a simple collection path or an XMLDB URI. It returns true if the authentication succeeds, false otherwise. If called from a HTTP context the login is cached for the lifetime of the HTTP session and may be used for any XQuery run in that session. If an HTTP session does not already exist, none will be created.

Parameters:

$collection-uri	The collection URI
$user-id	The user-id
$password	The password

Returns:

xs:boolean : true() on successful authentication and owner elevation, false() otherwise

xmldb:login#4

xmldb:login($collection-uri as xs:string, $user-id as xs:string?, $password as xs:string?, $create-session as xs:boolean?) as xs:boolean

Login the user, $user-id, and set it as the owner of the currently executing XQuery. Collection URIs can be specified either as a simple collection path or an XMLDB URI. It returns true() if the authentication succeeds, false() otherwise. If called from a HTTP context the login is cached for the lifetime of the HTTP session and may be used for any XQueryrun in that session. $create-session specifies whether to create an HTTP session on successful authentication or not. If $create-session is false() or the empty sequence no session will be created if one does not already exist.

Parameters:

$collection-uri	The collection URI
$user-id	The user-id
$password	The password
$create-session	whether to create the session or not on successful authentication, default false()

Returns:

xs:boolean : true() on successful authentication and owner elevation, false() otherwise

xmldb:match-collection#1

xmldb:match-collection($regexp as xs:string) as xs:string

Looks for collection names in the collection index that match the provided regexp

Parameters:

$regexp

The expression to use for matching collection names

Returns:

xs:string* : The names of the collections that match the expression

xmldb:move#2

xmldb:move($source-collection-uri as xs:string, $target-collection-uri as xs:string) as empty-sequence()

Moves the collection $source-collection-uri into the collection $target-collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:

$source-collection-uri	The source collection URI
$target-collection-uri	The target collection URI

Returns:

empty-sequence()

xmldb:move#3

xmldb:move($source-collection-uri as xs:string, $target-collection-uri as xs:string, $resource as xs:string) as empty-sequence()

Moves the resource $resource from the collection $source-collection-uri into collection $target-collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:

$source-collection-uri	The source collection URI
$target-collection-uri	The target collection URI
$resource	The resource

Returns:

empty-sequence()

xmldb:register-database#2

xmldb:register-database($driver as xs:string, $create-db as xs:boolean) as xs:boolean

Registers an XMLDB driver class with the XMLDB Database Manager. This is only required if you want to access a database instance different from the one that executes the XQuery.

Parameters:

$driver	The DB driver
$create-db	The flag to create the db if it does not exist

Returns:

xs:boolean : true() if successfully registered, false() otherwise

xmldb:reindex#1

xmldb:reindex($collection-uri as xs:string) as xs:boolean

Reindex collection $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI. The XQuery owner must have appropriate privileges to do this, e.g. having DBA role.

Parameters:

$collection-uri

The collection URI

Returns:

xs:boolean : true() if successfully reindexed, false() otherwise

xmldb:reindex#2

xmldb:reindex($collection-uri as xs:string, $doc-uri as xs:string) as xs:boolean

Reindex document $doc-uri from $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI. Resource URIs can be specified either as a simple collection path, an XMLDB URI or any URI. The XQuery owner must have appropriate privileges to do this, e.g. having DBA role.

Parameters:

$collection-uri	The collection URI
$doc-uri	The document URI

Returns:

xs:boolean : true() if successfully reindexed, false() otherwise

xmldb:remove#1

xmldb:remove($collection-uri as xs:string) as empty-sequence()

Removes the collection $collection-uri and its contents from the database. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:

$collection-uri

The collection URI

Returns:

empty-sequence()

xmldb:remove#2

xmldb:remove($collection-uri as xs:string, $resource as xs:string) as empty-sequence()

Removes the resource $resource from the collection $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:

$collection-uri	The collection URI
$resource	The resource

Returns:

empty-sequence()

xmldb:rename#2

xmldb:rename($source-collection-uri as xs:string, $new-collection-name as xs:string) as empty-sequence()

Renames the collection $source-collection-uri with new name $new-collection-name. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:

$source-collection-uri	The source collection URI
$new-collection-name	The new collection name

Returns:

empty-sequence()

xmldb:rename#3

xmldb:rename($collection-uri as xs:string, $resource as xs:string, $new-resource-name as xs:string) as empty-sequence()

Renames the resource $resource in collection $collection-uri with new name $new-resource-name. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:

$collection-uri	The collection URI
$resource	The resource
$new-resource-name	The new resource name

Returns:

empty-sequence()

xmldb:set-mime-type#2

xmldb:set-mime-type($resource-uri as xs:anyURI, $mime-type as xs:string?) as empty-sequence()

Set the MIME type of the resource $resource-uri.Resource URIs can be specified either as a simple collection path, an XMLDB URI or any URI.

Parameters:

$resource-uri	The resource URI
$mime-type	The new mime-type, use empty sequence to set default value.

Returns:

empty-sequence()

xmldb:size#2

xmldb:size($collection-uri as xs:string, $resource as xs:string) as xs:long

Returns the estimated size of the resource $resource (in bytes) in the collection $collection-uri. The estimation is based on the number of pages occupied by the resource. If the document is serialized back to a string, its size may be different, since parts of the structural information are stored in compressed form. Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:

$collection-uri	The collection URI
$resource	The resource

Returns:

xs:long : the size of the pages, occupied by the resource, in bytes

xmldb:store#3

xmldb:store($collection-uri as xs:string, $resource-name as xs:string?, $contents as item()) as xs:string

Stores a new resource into the database. The resource is stored in the collection $collection-uri with the name $resource-name. Collection URIs can be specified either as a simple collection path or an XMLDB URI. The contents $contents, is either a node, an xs:string, a Java file object or an xs:anyURI. A node will be serialized to SAX. It becomes the root node of the new document. If $contents is of type xs:anyURI, the resource is loaded from that URI. Returns the path to the new document if successfully stored, otherwise an XPathException is thrown.

Parameters:

$collection-uri	The collection URI
$resource-name	The resource name
$contents	The contents

Returns:

xs:string? : the path to new resource if sucessfully stored, otherwise the emtpty sequence

xmldb:store#4

xmldb:store($collection-uri as xs:string, $resource-name as xs:string?, $contents as item(), $mime-type as xs:string) as xs:string

Parameters:

$collection-uri	The collection URI
$resource-name	The resource name
$contents	The contents
$mime-type	The mime type

Returns:

xs:string? : the path to new resource if sucessfully stored, otherwise the emtpty sequence

xmldb:store-as-binary#3

xmldb:store-as-binary($collection-uri as xs:string, $resource-name as xs:string?, $contents as item()) as xs:string

Parameters:

$collection-uri	The collection URI
$resource-name	The resource name
$contents	The contents

Returns:

xs:string? : the path to new resource if sucessfully stored, otherwise the emtpty sequence

xmldb:store-files-from-pattern#3

xmldb:store-files-from-pattern($collection-uri as xs:string, $directory as xs:string, $pattern as xs:string+) as xs:string

Stores new resources into the database. Resources are read from the server's file system, using file patterns. The function returns a sequence of all document paths added to the db. These can be directly passed to fn:doc() to retrieve the document(s).

Parameters:

$collection-uri	The collection-uri where resources should be stored. Collection URIs can be specified either as a simple collection path or an XMLDB URI.
$directory	The directory in the file system from where the files are read.
$pattern	The file matching pattern. Based on code from Apache's Ant, thus following the same conventions. For example: .xml matches any file ending with .xml in the current directory, /.xml matches files in any directory below the current one

Returns:

xs:string* : the sequence of document paths

xmldb:store-files-from-pattern#4

xmldb:store-files-from-pattern($collection-uri as xs:string, $directory as xs:string, $pattern as xs:string+, $mime-type as xs:string?) as xs:string

Parameters:

$collection-uri	The collection-uri where resources should be stored. Collection URIs can be specified either as a simple collection path or an XMLDB URI.
$directory	The directory in the file system from where the files are read.
$pattern	The file matching pattern. Based on code from Apache's Ant, thus following the same conventions. For example: .xml matches any file ending with .xml in the current directory, /.xml matches files in any directory below the current one
$mime-type	If the mime-type is something other than 'text/xml' or 'application/xml', the resource will be stored as a binary resource.

Returns:

xs:string* : the sequence of document paths

xmldb:store-files-from-pattern#5

xmldb:store-files-from-pattern($collection-uri as xs:string, $directory as xs:string, $pattern as xs:string+, $mime-type as xs:string?, $preserve-structure as xs:boolean) as xs:string

Parameters:

$collection-uri	The collection-uri where resources should be stored. Collection URIs can be specified either as a simple collection path or an XMLDB URI.
$directory	The directory in the file system from where the files are read.
$pattern	The file matching pattern. Based on code from Apache's Ant, thus following the same conventions. For example: .xml matches any file ending with .xml in the current directory, /.xml matches files in any directory below the current one
$mime-type	If the mime-type is something other than 'text/xml' or 'application/xml', the resource will be stored as a binary resource.
$preserve-structure	If preserve-structure is true(), the filesystem directory structure will be mirrored in the collection. Otherwise all the matching resources, including the ones in sub-directories, will be stored in the collection given in the first argument flatly.

Returns:

xs:string* : the sequence of document paths

xmldb:store-files-from-pattern#6

xmldb:store-files-from-pattern($collection-uri as xs:string, $directory as xs:string, $pattern as xs:string+, $mime-type as xs:string?, $preserve-structure as xs:boolean, $exclude as xs:string*) as xs:string

Parameters:

$collection-uri	The collection-uri where resources should be stored. Collection URIs can be specified either as a simple collection path or an XMLDB URI.
$directory	The directory in the file system from where the files are read.
$pattern	The file matching pattern. Based on code from Apache's Ant, thus following the same conventions. For example: .xml matches any file ending with .xml in the current directory, /.xml matches files in any directory below the current one
$mime-type	If the mime-type is something other than 'text/xml' or 'application/xml', the resource will be stored as a binary resource.
$preserve-structure	If preserve-structure is true(), the filesystem directory structure will be mirrored in the collection. Otherwise all the matching resources, including the ones in sub-directories, will be stored in the collection given in the first argument flatly.
$exclude	A sequence of file patterns to exclude

Returns:

xs:string* : the sequence of document paths

xmldb:touch#2

xmldb:touch($collection-uri as xs:string, $resource as xs:string) as xs:boolean

Sets the modification time of a resource to the current system time. If not resource does not exist it is not created.

Parameters:

$collection-uri	The collection URI
$resource	The name of the resource in the collection

Returns:

xs:boolean : true if the modification time was updated, false otherwise.

xmldb:touch#3

xmldb:touch($collection-uri as xs:string, $resource as xs:string, $modification-time as xs:dateTime) as xs:boolean

Sets the modification time of a resource. If not resource does not exist it is not created.

Parameters:

$collection-uri	The collection URI
$resource	The name of the resource in the collection
$modification-time	The modification time to set on the resource

Returns:

xs:boolean : true if the modification time was updated, false otherwise.

xmldb:update#2

xmldb:update($collection-uri as xs:string, $modifications as node()) as xs:integer

Processes an XUpdate request, $modifications, against a collection $collection-uri. Collection URIs can be specified either as a simple collection path or an XMLDB URI.The modifications are passed in a document conforming to the XUpdate specification. http://rx4rdf.liminalzone.org/xupdate-wd.html#N1a32e0The function returns the number of modifications caused by the XUpdate.

Parameters:

$collection-uri	The collection URI
$modifications	The XUpdate modifications to be processed

Returns:

xs:integer : the number of modifications, as xs:integer, caused by the XUpdate

xmldb:xcollection#1

xmldb:xcollection($collection-uris as xs:string+) as node()

Returns the document nodes in the collections $collection-uris non-recursively, i.e. does not include document nodes found in sub-collections. C.f. fn:collection(). Collection URIs can be specified either as a simple collection path or an XMLDB URI.

Parameters:

$collection-uris

The collection URIs

Returns:

node()* : the document nodes from the specified collections excluding sub-collections