Using URI Resolvers

This section provides information about URI resolvers for documents, modules, and file collections.

Document URI Resolvers

DataDirect XQuery allows an application to specify a custom URI resolver for fn:doc and fn:doc-available. For example, you may want to create a Java class to resolve custom URLs that point to a proprietary repository that stores your XML documents, like an XML database. This type of custom URI resolver is called a document URI resolver.

The document URI resolver must be a Java class that implements the the javax.xml.transform.URIResolver interface and the default constructor. The javax.xml.transform.Source object returned by the URI resolver must be an instance of one of the following interfaces:

javax.xml.transform.stream.StreamSource

javax.xml.transform.sax.SAXSource

javax.xml.transform.dom.DOMSource

javax.xml.transform.stax.StAXSource (for JVM 1.6 only)*

com.ddtek.xquery.StAXSource (a proprietary DataDirect XQuery class for JVMs prior to 1.6)*

* The StAXSource must be created with an XMLStreamReader; it cannot be created with an XMLEventReader.

If you specify a document URI resolver, the rules enforced for URI paths are governed by the syntax specified by your custom URI resolver. See XML Data Sources for the rules enforced for specifying URIs by the default URI resolver.

Library Module URI Resolvers

DataDirect XQuery allows you to customize the mechanism for importing library modules in a query. For example, you may want to create a Java class to resolve custom URLs that point to a repository that stores XQuery modules.

Any custom library module URI resolver must be a Java class that implements the com.ddtek.xquery.ModuleURIResolver interface. In addition, it must return an array of Java StreamSource objects that identify the contents of a module to be imported.

The interface has one method, resolve. You must implement the resolve method to resolve the module with the provided module URI, base URI, and location hints, as follows:

public StreamSource[] resolve (String moduleURI, 
                               String baseURI, 
                               String[] locationHints) 
                      throws TransformerException

moduleURI is the module namespace URI. This parameter cannot be null.

baseURI is the base URI of the module containing the import module declaration or null if no base URI is known.

locationHints is the array of location hints provided in the at clause of the import module declaration. An empty array is specified if no at clause is included in the import module declaration.

The resolve method returns an array of StreamSource objects, each identifying the contents of a module to be imported. Each StreamSource must contain a non-null absolute System ID that is used as the location URI of the imported module. Optionally, the StreamSource can contain an InputStream or Reader representing the text of the module. If a representation of the text of the module is not returned, DataDirect XQuery resolves the module using the specified location URI.

If null is returned, DataDirect XQuery resolves the module using the default module URI resolver.

The following custom library module URI resolver relies on a specific directory to resolve the module. In addition, if a location hint is omitted in the XQuery import statement, DataDirect XQuery uses the default module URI resolver.

import javax.xml.transform.TransformerException; 
import javax.xml.transform.stream.StreamSource; 
import java.io.File; 
import com.ddtek.xquery.ModuleURIResolver; 
 
public class customModuleResolver implements ModuleURIResolver { 
   public StreamSource[] resolve(String moduleURI, String baseURI, String[] 
   locationHint)throws TransformerException { 
     // In this example, the custom behavior is triggered by using 
     // a specific moduleURI 
     if(moduleURI.equals("http://sharedFunctions.company.com")) { 
        File fileSource; 
        // If a locationHint is available, we use it; otherwise, we  
        // load the default module URI resolver. 
        if(locationHint.length > 0) 
           fileSource = new File("c:/sharedFunctions/"+locationHint[0]); 
        else 
           fileSource = new File("c:/sharedFunctions/defaultModule.xquery"); 
        // More than one StreamSource can be returned;  
        // This example only returns one StreamSource. 
        StreamSource streamSources[] = {new StreamSource(fileSource)}; 
        return streamSources; 
     } 
     return null; 
} 
}

The following query only specifies the module file name and relies on customModuleResolver to import the module from the path c:/sharedFunctions/module1.xquery:

import module namespace sharedFunctions = 
   'http://sharedFunctions.company.com' at 'module1.xquery'; 
sharedFunctions:func('a','b')

The following query omits the location hint. In this case, the query relies on customModuleResolver to import a default module (c:/sharedFunctions/defaultModule.xquery):

import module namespace sharedFunctions = 
   'http://sharedFunctions.company.com'; (: no location hint :) 
sharedFunctions:func('a','b')

In the following query, customModuleResolver defaults to the behavior of the built-in DataDirect XQuery module URI resolver (note the different namespace URI for the imported module), which tries to locate module1.xquery relative to the location of the URL of the query:

import module namespace otherFunctions = 'http://other.company.com'  
   at 'module1.xquery'; 
sharedFunctions:func('a','b')

Collection URI Resolvers

DataDirect XQuery allows an application to specify a custom URI resolver for fn:collection. For example, you might want to create a Java class to resolve custom URIs that point to a directory that contains your XML files. This type of custom URI resolver is called a collection URI resolver.

The collection URI resolver must be a Java class that implements the com.ddtek.xquery.CollectionURIResolver interface. The URI resolver returns a java.util.Iterator object, which, in turn, must return objects that implement one of the following interfaces:

javax.xml.transform.stream.StreamSource

javax.xml.transform.sax.SAXSource

javax.xml.transform.dom.DOMSource

javax.xml.transform.stax.StAXSource (for JVM 1.6 only)*

com.ddtek.xquery.StAXSource (a proprietary DataDirect XQuery class for JVMs prior to 1.6)*

* The StAXSource must be created with an XMLStreamReader; it cannot be created with an XMLEventReader.