<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head profile="http://internetalchemy.org/2003/02/profile">
<link rel="foaf" type="application/rdf+xml" title="FOAF" href="http://www.openlinksw.com/dataspace/uda/about.rdf" />
<link rel="schema.dc" href="http://purl.org/dc/elements/1.1/" />
<meta name="dc.title" content="Function: fn:collection - Virtuoso Functions Guide" />
<meta name="dc.subject" content="Function: fn:collection - Virtuoso Functions Guide" />
<meta name="dc.creator" content="OpenLink Software Documentation Team ; " />
<meta name="dc.copyright" content="OpenLink Software, 1999 - 2009" />
<link rel="top" href="index.html" title="OpenLink Virtuoso Universal Server: Documentation" />
<link rel="search" href="/doc/adv_search.vspx" title="Search OpenLink Virtuoso Universal Server: Documentation" />
<link rel="parent" href="functions.html" title="Chapter Contents" />
<link rel="prev" href="appendixa.html" title="Appendix" />
<link rel="next" href="functions.html#.html" title="" />
<link rel="shortcut icon" href="../images/misc/favicon.ico" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="doc.css" />
<link rel="stylesheet" type="text/css" href="/doc/translation.css" />
<title>Function: fn:collection - Virtuoso Functions Guide</title>
<meta http-equiv="Content-Type" content="text/xhtml; charset=UTF-8" />
<meta name="author" content="OpenLink Software Documentation Team ; " />
<meta name="copyright" content="OpenLink Software, 1999 - 2009" />
<meta name="keywords" content="" />
<meta name="GENERATOR" content="OpenLink XSLT Team" />
</head>
<body>
<div id="header">
<a name="xpf_collection" />
<img src="../images/misc/logo.jpg" alt="" />
<h1>22. Virtuoso Functions Guide - fn:collection</h1>
</div>
<div id="navbartop">
<div>
<a class="link" href="functions.html">Chapter Contents</a> | <a class="link" href="xpf_ceiling.html" title="ceiling">Prev</a> | <a class="link" href="xpf_concat.html" title="concat">Next</a>
</div>
</div>
<div id="currenttoc">
<form method="post" action="/doc/adv_search.vspx">
<div class="search">Keyword Search: <br />
<input type="text" name="q" /> <input type="submit" name="go" value="Go" />
</div>
</form>
<div>
<a href="http://www.openlinksw.com/">www.openlinksw.com</a>
</div>
<div>
<a href="http://docs.openlinksw.com/">docs.openlinksw.com</a>
</div>
<br />
<div>
<a href="index.html">Book Home</a>
</div>
<br />
<div>
<a href="contents.html">Contents</a>
</div>
<div>
<a href="preface.html">Preface</a>
</div>
<br />
<div>
<a class="selected" href="functions.html">Virtuoso Functions Guide</a>
</div>
<br />
<div>
<a href="functions.html#admin">Administration</a>
</div>
<div>
<a href="functions.html#aggr">Aggregate Functions</a>
</div>
<div>
<a href="functions.html#array">Array Manipulation</a>
</div>
<div>
<a href="functions.html#bpel">BPEL APIs</a>
</div>
<div>
<a href="functions.html#backup">Backup</a>
</div>
<div>
<a href="functions.html#compression">Compression</a>
</div>
<div>
<a href="functions.html#cursors">Cursor</a>
</div>
<div>
<a href="functions.html#time">Date & Time Manipulation</a>
</div>
<div>
<a href="functions.html#debug">Debug</a>
</div>
<div>
<a href="functions.html#dict">Dictionary Manipulation</a>
</div>
<div>
<a href="functions.html#encoding">Encoding & Decoding</a>
</div>
<div>
<a href="functions.html#file">File Manipulation</a>
</div>
<div>
<a href="functions.html#ft">Free Text</a>
</div>
<div>
<a href="functions.html#hash">Hashing / Cryptographic</a>
</div>
<div>
<a href="functions.html#ldap">LDAP</a>
</div>
<div>
<a href="functions.html#localization">Locale</a>
</div>
<div>
<a href="functions.html#mail">Mail</a>
</div>
<div>
<a href="functions.html#misc">Miscellaneous</a>
</div>
<div>
<a href="functions.html#number">Number</a>
</div>
<div>
<a href="functions.html#phrz">Phrases</a>
</div>
<div>
<a href="functions.html#rdf">RDF data</a>
</div>
<div>
<a href="functions.html#rmt">Remote SQL Data Source</a>
</div>
<div>
<a href="functions.html#repl">Replication</a>
</div>
<div>
<a href="functions.html#soap">SOAP</a>
</div>
<div>
<a href="functions.html#sql">SQL</a>
</div>
<div>
<a href="functions.html#string">String</a>
</div>
<div>
<a href="functions.html#txn">Transaction</a>
</div>
<div>
<a href="functions.html#type">Type Mapping</a>
</div>
<div>
<a href="functions.html#uddi">UDDI</a>
</div>
<div>
<a href="functions.html#udt">User Defined Types & The CLR</a>
</div>
<div>
<a href="functions.html#vad">VAD</a>
</div>
<div>
<a href="functions.html#jvmpl">Virtuoso Java PL API</a>
</div>
<div>
<a href="functions.html#bif">Virtuoso Server Extension Interface (VSEI)</a>
</div>
<div>
<a href="functions.html#ws">Web & Internet</a>
</div>
<div>
<a href="functions.html#xml">XML</a>
</div>
<div>
<a class="selected" href="functions.html#XPATH">XPATH & XQUERY</a>
</div>
<div class="selected">
<div>
<a href="xpf_and.html">and</a>
</div>
<div>
<a href="xpf_append.html">append</a>
</div>
<div>
<a href="xpf_assign.html">assign</a>
</div>
<div>
<a href="xpf_avg.html">avg</a>
</div>
<div>
<a href="xpf_boolean.html">boolean</a>
</div>
<div>
<a href="xpf_ceiling.html">ceiling</a>
</div>
<div>
<a href="xpf_concat.html">concat</a>
</div>
<div>
<a href="xpf_contains.html">contains</a>
</div>
<div>
<a href="xpf_count.html">count</a>
</div>
<div>
<a href="xpf_create_attribute.html">create-attribute</a>
</div>
<div>
<a href="xpf_create_comment.html">create-comment</a>
</div>
<div>
<a href="xpf_create_element.html">create-element</a>
</div>
<div>
<a href="xpf_create_pi.html">create-pi</a>
</div>
<div>
<a href="xpf_current.html">current</a>
</div>
<div>
<a href="xpf_distinct.html">distinct</a>
</div>
<div>
<a href="xpf_doc.html">doc</a>
</div>
<div>
<a href="xpf_document.html">document</a>
</div>
<div>
<a href="xpf_document_literal.html">document-literal</a>
</div>
<div>
<a href="xpf_empty.html">empty</a>
</div>
<div>
<a href="xpf_ends_with.html">ends-with</a>
</div>
<div>
<a href="xpf_every.html">every</a>
</div>
<div>
<a href="xpf_except.html">except</a>
</div>
<div>
<a href="xpf_false.html">false</a>
</div>
<div>
<a href="xpf_filter.html">filter</a>
</div>
<div>
<a href="xpf_floor.html">floor</a>
</div>
<div>
<a class="selected" href="xpf_collection.html">fn:collection</a>
</div>
<div>
<a href="xpf_for.html">for</a>
</div>
<div>
<a href="xpf_format_number.html">format-number</a>
</div>
<div>
<a href="xpf_function_available.html">function-available</a>
</div>
<div>
<a href="xpf_generate_id.html">generate-id</a>
</div>
<div>
<a href="xpf_id.html">id</a>
</div>
<div>
<a href="xpf_if.html">if</a>
</div>
<div>
<a href="xpf_intersect.html">intersect</a>
</div>
<div>
<a href="xpf_is_after.html">is_after()</a>
</div>
<div>
<a href="xpf_is_before.html">is_before()</a>
</div>
<div>
<a href="xpf_key.html">key</a>
</div>
<div>
<a href="xpf_lang.html">lang</a>
</div>
<div>
<a href="xpf_last.html">last</a>
</div>
<div>
<a href="xpf_let.html">let</a>
</div>
<div>
<a href="xpf_list.html">list()</a>
</div>
<div>
<a href="xpf_local_name.html">local-name</a>
</div>
<div>
<a href="xpf_max.html">max</a>
</div>
<div>
<a href="xpf_min.html">min</a>
</div>
<div>
<a href="xpf_name.html">name</a>
</div>
<div>
<a href="xpf_namespace_uri.html">namespace-uri</a>
</div>
<div>
<a href="xpf_normalize_space.html">normalize-space</a>
</div>
<div>
<a href="xpf_not.html">not</a>
</div>
<div>
<a href="xpf_number.html">number</a>
</div>
<div>
<a href="xpf_or.html">or</a>
</div>
<div>
<a href="xpf_position.html">position</a>
</div>
<div>
<a href="xpf_processXQuery.html">processxquery</a>
</div>
<div>
<a href="xpf_processXSLT.html">processxslt</a>
</div>
<div>
<a href="xpf_processXSQL.html">processxsql</a>
</div>
<div>
<a href="xpf_progn.html">progn()</a>
</div>
<div>
<a href="xpf_replace.html">replace()</a>
</div>
<div>
<a href="xpf_round.html">round</a>
</div>
<div>
<a href="xpf_serialize.html">serialize</a>
</div>
<div>
<a href="xpf_shallow.html">shallow</a>
</div>
<div>
<a href="xpf_some.html">some</a>
</div>
<div>
<a href="xpf_starts_with.html">starts-with</a>
</div>
<div>
<a href="xpf_string.html">string</a>
</div>
<div>
<a href="xpf_string_length.html">string-length</a>
</div>
<div>
<a href="xpf_substring.html">substring</a>
</div>
<div>
<a href="xpf_substring_after.html">substring-after</a>
</div>
<div>
<a href="xpf_substring_before.html">substring-before</a>
</div>
<div>
<a href="xpf_sum.html">sum</a>
</div>
<div>
<a href="xpf_system_property.html">system-property</a>
</div>
<div>
<a href="xpf_text_contains.html">text_contains()</a>
</div>
<div>
<a href="xpf_translate.html">translate</a>
</div>
<div>
<a href="xpf_true.html">true</a>
</div>
<div>
<a href="xpf_tuple.html">tuple()</a>
</div>
<div>
<a href="xpf_union.html">union</a>
</div>
<div>
<a href="xpf_unordered.html">unordered</a>
</div>
<div>
<a href="xpf_unparsed_entity_uri.html">unparsed-entity-uri</a>
</div>
<div>
<a href="xpf_urlify.html">urlify</a>
</div>
<div>
<a href="xpf_xmlview.html">xmlview</a>
</div>
</div>
<br />
<div>
<a href="functionidx.html">Functions Index</a>
</div>
<br />
</div>
<div id="text">
<h2>fn:collection</h2>
<div class="refpurpose">Returns parsed documents contained in given collections.</div>
<div class="funcsynopsis">
<span class="funcdef">node()* <span class="function">fn:collection</span>
</span>
(<span class="paramdefoptional">[<span class="optional">uri</span> anyURI]</span>,
<span class="paramdefoptional">[<span class="optional">base_uri</span> string]</span>,
<span class="paramdefoptional">[<span class="optional">recursive_mode</span> int]</span>,
<span class="paramdefoptional">[<span class="optional">parser_mode</span> int]</span>,
<span class="paramdefoptional">[<span class="optional">encoding</span> string]</span>,
<span class="paramdefoptional">[<span class="optional">language</span> string]</span>,
<span class="paramdefoptional">[<span class="optional">dtd_config</span> string]</span>);
</div>
<div class="refsect1">
<div class="refsect1title">Description</div>
<p>
This function takes one or more collection URI's and returns the parsed documents contained in these collections as a sequence. </p>
<p>
If no uri is specified, the function returns the sequence of the nodes in the default collection in the dynamic context. The default collection is a home DAV collection. If user does not have default DAV collection, an error is signalled.</p>
<div class="refsect2">
<span class="refsect2title">Local DAV collections – </span>
Local DAV collections can be accessed either by providing "http://local.virt/DAV/" or "http://localhost:PORT/" URI. The "http://local.virt/DAV/" can be used even if the local http server is not enabled.
The "http://localhost:PORT" URI is less efficient and takes the data over HTTP, so "http://local.virt/DAV/" is preferred.
<div class="note">
<div class="notetitle">Note:</div>
<p>
When using http://local.virt/DAV/ URI the effective account calling fn:collection must have read access to the resources in question as defined by DAV permissions. For the http mode of access, the server may request authentication, which the function will supply from the dynamic context, see below.
</p>
</div>
</div>
<div class="refsect2">
<span class="refsect2title">Table Collections – </span>
fn:collection specially recognizes URI's which beginning with "virt://". Such a URI relates to a local table, the content of a specified column is returned as the collection (table collection). The URI contains three parts: table name, id column name, xml content column name. For instance, if the table definition is:
<div>
<pre class="screen">
create table XML_EXAMPLE (
XE_ID int primary key,
XE_ENTITY any
)
;
</pre>
</div>
then the URI for accessing all documents stored in XE_ENTITY column and referenced by XE_ID is:
<div>
<pre class="screen">
virt://DB.DBA.XML_EXAMPLE.XE_ID.XE_ENTITY
</pre>
</div>
</div>
<div class="refsect2">
<span class="refsect2title">Home path in local DAV collections – </span>
fn:collection also supports UNIX style home paths. If URI begins with ~ the next term will treated as user name and is will be substituted by path to home DAV collection. For instance, ~john/test/test2/ can be parsed as http://local.virt/DAV/home/john/test/test2 URI.
</div>
<div class="refsect2">
<span class="refsect2title">Remote DAV collections, WEB collections – </span>
Any other URI which begins with "http://" refers to remote DAV
collections. The function uses the PROPFIND DAV method to get
the list of documents contained in the collection. If the
remote server does not support this method the function tries
to do a HTML GET with the uri and returns all documents
referenced from the result (WEB collection). In this case the
function makes two http requests.
</div>
<div class="refsect2">
When a web page is scanned for document reference by fn:collection it searches <a href=...> tags and returns downloaded and parsed documents referenced in href. If href contains relative reference it is resolved using web page address as base uri.
<div class="note">
<div class="notetitle">Note:</div>
<p>
There is no way to narrow set of resolved references on HTML web page. So, fn:collection call over remote server which does not support PROPFIND method can be very expensive. The engine tries to download all documents referenced on the page, even it does not relates to the collection.
</p>
</div>
</div>
<div class="refsect2">
In this release fn:collection does not support any collections except DAV collections, WEB collections, table collections.
The collection function returns parsed documents. If the collection in question contains non xml documents the function will fail. In order to skip such documents html mode can be set by parser_mode argument.
</div>
<p>
The recursive_mode arguments sets the mode for processing sub-collection. If recursive_mode is set to 0 all sub-collections are ignored. fn:collection collects documents recursively if the argument is set to 1. The recursive mode is the default.
</p>
<p>
Recursive collecting is not supported for WEB collections and table collections.
</p>
<p>
Rest of optional arguments (encoding, language, dtd_config) are passed to internal XML parser. They are equal to optional argument of <a href="">xtree_doc()</a>.
</p>
<div class="refsect2">
<span class="refsect2title">Authentication – </span>
Remote DAV and WEB collections may need authentication information. fn:collection supports two ways of providing authentication information. First one is to provide user name and password by setting appropriate connection variables:
<div>
<pre class="screen">
connection_set ('HTTP_CLI_UID', 'loginhere');
connection_set ('HTTP_CLI_PWD', 'passwordhere');
</pre>
</div>
it can be used if fn:collection collects documents from source which demands only one username and password.
If the remote collection references documents from different sources which need different authentication information then instead of providing single username/password pair the authentication callback function can be used. The engine gets (if HTTP_CLI_UID is not set to NULL) name of the callback function from HTTPAuthManager connection variable. The function must take URI of the resource as argument and return array of username and password for the resource. For instance, here is an example of authentication function which allows to get needed credentials for two home DAV collections:
<div>
<pre class="screen">
create procedure DB.DBA.AUTHINFO (in _uri varchar)
{
if (_uri like 'http://localhost%/DAV/home/john/%')
return vector ('john', 'cat!filt_NY');
else if (_uri like 'http://localhost%/DAV/home/sam/%')
return vector ('sam', 'doggy1913');
return vector (null, null);
}
;
connection_set ('HTTPAuthManager', 'DB.DBA.AUTHINFO');
select xquery_eval ('
<result> John's test cases:
{
for \044a in collection ("http://localhost:8080/DAV/home/john/test-cases/", ., 1, 2)
return <res> { document-uri (\044a) }</res>
}
</result>', xtree_doc ('<a/>'));
select xquery_eval ('
<result> All test cases:
{
for \044a in collection ("http://localhost:8080/DAV/home/", ., 1, 2)
return <res> { document-uri (\044a) }</res>
}
</result>', xtree_doc ('<a/>'));
</pre>
</div>
</div>
</div>
<div class="refsect1">
<div class="refsect1title">Parameters</div>
<div class="refsect2">
<span class="refsect2title">uri – </span>
collection URI. If the <span class="computeroutput">uri</span> is a relative xs:anyURI, it is resolved against the value of the base-URI property from the static context or from <span class="computeroutput">base_uri</span>. </div>
<div class="refsect2">
<span class="refsect2title">base_uri – </span>
If <span class="computeroutput">uri</span> is an relative URI string, not an absolute one then <span class="computeroutput">base_uri</span> is used to make it absolute.
</div>
<div class="refsect2">
<span class="refsect2title">parser_mode – </span>
Sets the mode for parsing documents in collection (0 - XML parser mode, 1 - HTML parser mode, 2 - 'dirty HTML' mode (with quiet recovery after any syntax error).</div>
<div class="refsect2">
<span class="refsect2title">encoding – </span>
string with content encoding type of <document>; valid are 'ASCII', 'ISO',
'UTF8', 'ISO8859-1', 'LATIN-1' etc., defaults are 'UTF-8' for XML mode and 'LATIN-1' for
HTML mode.</div>
<div class="refsect2">
<span class="refsect2title">language – </span>
string with language tag of content of <document>; valid names are listed in
IETF RFC 1766, default is 'x-any' (it means 'mix of words from various human languages')</div>
<div class="refsect2">
<span class="refsect2title">dtd_config – </span>
configuration string for DTD validator, default is empty string meaning that DTD
validator should be fully disabled.
See <a href="xmlschema.html#dtd_config">Configuration Options of the DTD Validator</a> for details.</div>
</div>
<div class="refsect1">
<div class="refsect1title">Return Types</div>
<p>node*</p>
</div>
<div class="refsect1">
<div class="refsect1title">Examples</div>
<a name="xpf_ex1_collection" />
<div class="example">
<p>Example of using remote DAV collection:</p>
<div>
<pre class="screen">
<result>
{ for $a in fn:collection ( "http://www.somdavservice.com:8081/DAV/test1/" )
return
{ $a/value/text() }
}
</result></pre>
</div>
</div>
<a name="xpf_ex2_collection" />
<div class="example">
<p>Example of using relative URI:</p>
<div>
<pre class="screen">
xquery_eval('
<pre>
{ for \044n in fn:collection("/docs", ., 2)
return (document-get-uri(\044n), " - ", name (\044n/*[1]), "\n")
}
</pre> ', xtree_doc ('<stub/>', 0, 'http://www.somdavservice.com:8081/') );
</pre>
</div>
</div>
<a name="xpf_ex3_collection" />
<div class="example">
<p>Example of using default collection:</p>
<div>
<pre class="screen">
xquery_eval('
<div>
{ for \044anchor in fn:collection()//a
return { \044anchor }
}
</div> ', xtree_doc ('<stub/>') );
</pre>
</div>
</div>
</div>
<div class="refsect1">
<div class="refsect1title">See Also</div>
<p>
<a href="xpf_document.html">document()</a>
</p>
<p>
<a href="xpf_doc.html">doc()</a>
</p>
<p>
<a href="fn_xtree_doc.html">xtree_doc()</a>
</p>
<p>
<a href="fn_xml_uri_get.html">xml_uri_get()</a>
</p>
</div>
</div>
<div id="footer">
<div>Copyright© 1999 - 2009 OpenLink Software All rights reserved.</div>
<div id="validation">
<a href="http://validator.w3.org/check/referer">
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" />
</a>
<a href="http://jigsaw.w3.org/css-validator/">
<img src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" height="31" width="88" />
</a>
</div>
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
71d40963b505df4524269198e237b3e3
>
files
>
1023
