Local DAV collections

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.

	Note:
	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.

Table Collections

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:

create table XML_EXAMPLE (
        XE_ID int primary key,
        XE_ENTITY any
)
;

then the URI for accessing all documents stored in XE_ENTITY column and referenced by XE_ID is:

virt://DB.DBA.XML_EXAMPLE.XE_ID.XE_ENTITY

Home path in local DAV collections

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.

Remote DAV collections, WEB collections

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.

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.

	Note:
	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.

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.

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.

Recursive collecting is not supported for WEB collections and table collections.

Rest of optional arguments (encoding, language, dtd_config) are passed to internal XML parser. They are equal to optional argument of xtree_doc() .

Authentication

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:

connection_set ('HTTP_CLI_UID', 'loginhere');
connection_set ('HTTP_CLI_PWD', 'passwordhere');

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:

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://example.com/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://example.com/DAV/home/", ., 1, 2)
        return <res> { document-uri (\044a) }</res>
    }
  </result>', xtree_doc ('<a/>'));
      

uri

collection URI. If the uri is a relative xs:anyURI, it is resolved against the value of the base-URI property from the static context or from base_uri .

base_uri

If uri is an relative URI string, not an absolute one then base_uri is used to make it absolute.

parser_mode

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).

encoding

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.

language

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')

dtd_config

configuration string for DTD validator, default is empty string meaning that DTD validator should be fully disabled. See Configuration Options of the DTD Validator for details.