fn:docfunction returns an empty sequence if the specified resource is not found. This would be a problem if there was no way of knowing the difference between a resource that could not be found and an XQuery that did not match any results. Fortunately, Oracle's implementation of
fn:doc-availablefunction can be used to test for the availability of the resource. The screen shot shown next (click on it to see larger version) shows use of
fn:doc-availableagainst a URL with
truebecause the resource is found. However, as shown in the screen shot, when I fail to specify the
falseis returned. I also showed trying to use
fn:docagainst this same URL to demonstrate the return of the empty sequence rather than an error message. This behavior is as documented in Using XQuery with Oracle XML DB (Chapter 18 of Oracle XML DB Developer's Guide).
The screen shot specifically demonstrates use of XQLPlus to show use of
fn:doc-available, but this behavior should be the same for all Oracle XQuery implementations.
Had I included the
file:///protocol in the URI to
fn:doc, but with an invalid file location, an error would have been returned as shown in the next screen shot image:
So, Oracle XQuery implementations that are told to look for a file (with the
file:///protocol) and cannot find that file will report an error. On the other hand, if the URL resolves to something other than the file system (such as the default XML DB repository) with a non-valid value, an empty sequence is returned. The function
falsein both cases (file not found and non-file URI with no matching resource). Note that the XQuery implementations can also find documents in the database's XML DB repository and this is why
file:///is not a default (and
C:\cannot be found in the repository).
doc-availableis also recommended before
fn:docthat accesses file system files (with
doc-availablereturns "false" for files that are wrong format (such as binary files or files with encoding other than UTF-8) and for files that are text but not XML. If
fn:docis used directly on the binary files an exception will be thrown with the message "Invalid UTF8 encoding." Likewise, if
fn:docis used directly on a non-XML text file, an exception will be thrown with the message "Start of root element expected." Using
fn:doc-availablein a conditional before using
fn:docin an XQuery script helps avoid these exceptions.
Specification details on fn:doc and fn:doc-available can be found in the XQuery 1.0 and XPath 2.0 Functions and Operators document.