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:

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

You can specify a document URI resolver by configuring the DocumentUriResolver property of DDXQDataSource. SeeDDXQDataSource and DDXQJDBCConnection Properties.

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 

The resolve method accepts the following parameters specified in the query:

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.

You can specify a custom library module URI resolver by configuring the ModuleUriResolver property of DDXQDataSource. See DDXQDataSource and DDXQJDBCConnection Properties.

Example: Using a Custom Library 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:

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

Refer to the Javadoc for details about the CollectionURIResolver interface.

You can specify a collection URI resolver by configuring the CollectionUriResolver property of DDXQDataSource. See DDXQDataSource and DDXQJDBCConnection Properties.

See also Querying Multiple Files in a Directory and Querying ZIP, JAR, and MS Office Files.