Writing your own collection finder

The CollectionFinder interface enables you to define a mapping from a collection URI to a set of resources (which can be arbitrary XDM values: they are not restricted to be XML documents).

The details differ between Java and .NET:

• On Java, the CollectionFinder is a functional interface, so you can either write a class that implements the interface, or you can supply an implementation directly as a lambda expression. It accepts a URI as input (supplied as a string), and returns an instance of ResourceCollection.

  You can either reuse the existing implementations of ResourceCollection (such as CatalogCollection, DirectoryCollection, JarCollection, and ExplicitCollection), or you can write your own. You can also of course subclass the existing collection classes. The ResourceCollection object provides two key methods that you need to implement: getResources(), which returns a sequence of Resource objects, and getResourceURIs(), which returns a sequence of URIs. These are invoked by the fn:collection() and fn:uri-collection() functions respectively.

  Again, you can either reuse existing implementations of Resource (such as XmlResource, JSONResource, UnparsedTextResource, BinaryResource, and MetadataResource), or you can create your own, perhaps by subclassing. The key method that the Resource object must provide is getItem() which returns the resource in the form of an XDM item. It is good practice to delay any extensive work such as parsing until the getItem() method is called: this reduces the memory footprint, and enables parallel evaluation of multiple threads (Saxon-EE only).

  For example, a CollectionFinder written to handle collection URIs using the scheme name "sql" might be supplied as:

  config.setCollectionFinder((context, uri) -> uri.startsWith('sql:') ? sqlCollection(uri) : new StandardCollectionFinder().findCollection(context, uri) )

  where sqlCollection(uri) returns some user-defined implementation of ResourceCollection, perhaps one that retrieves XML documents from a relational database.

• On .NET, the CollectionFinder is a delegate so you will typically implement it directly as a lambda expression. It accepts a URI as input (supplied as a string), and returns an instance of IEnumerable<IResource>.

  You can either reuse the existing implementations of IResource, or you can write your own. The key method that the IResource object must provide is GetItem() which returns the resource in the form of an XDM item. It is good practice to delay any extensive work such as parsing until the GetItem() method is called: this reduces the memory footprint, and enables parallel evaluation of multiple threads.

  For example, a CollectionFinder written to handle collection URIs using the scheme name "sql" might be supplied as:

  processor.CollectionFinder = uri => uri.startsWith('sql:') ? sqlCollection(uri) : new StandardCollectionFinder().findCollection(context, uri) )

  where sqlCollection(uri) returns some user-defined implementation of IEnumerable<IResource>, perhaps one that retrieves XML documents from a relational database.