Native Modules

There are a number of restrictions on the functions that can be made available to an XQuery program or XPath expression. Many of these restrictions may be lifted in future versions.

• If a function is implemented by a non-static method, then the class must have a public default constructor. In a future version of XmlPrime we hope to allow an instantiation of a class to be specified in the dynamic context settings.
• Methods cannot take any external state. In a future version we hope to allow extra state information to be passed through to native functions called from an XQuery program or XPath expression.
• Methods called from an XQuery program or XPath expression must be pure (have no side effects). Examples of side effects are writing a message to the console, or saving a result to a file. This is because there is no guarantee of what order user defined functions will be called in, how many times they will be called, or whether they will even be called, and these things will all be affected by query optimization. In a future version of XmlPrime we hope to support impure functions (via XQuery Scripting Extensions).
• Methods called from an XQuery program or XPath expression must be deterministic. That is, when the function is called with the same arguments, it must return the same value. Examples of functions that are not deterministic are a function that returns a random number, or one that reads the contents of the specified file (as the contents may change during evaluation). This is required as optimizations such as common subexpression elimination assume this property. In a future version of XmlPrime we hope to support non-deterministic functions as well.

The parameter and return types of methods exposed to XmlPrime are currently restricted to those that can be converted to XQuery types. Items can be represented by any of the CLR types listed in Mapping Atomic Types to CLR Types.

Sequences of items can be specified as arguments of the following types. The generic parameter must be set to one of the item types specified above.

Native libraries can be annotated via the use of XdmModuleAttributeXdmModuleAttributeXdmModuleAttribute, XdmFunctionAttributeXdmFunctionAttributeXdmFunctionAttribute and XdmTypeAttributeXdmTypeAttributeXdmTypeAttribute.

[XdmType(XmlTypeCode.UntypedAtomic,Quantifier.One)]

The following code demonstrates a module implementing a factorial function:

[XdmModule("http://www.example.org")]
class MyModule
{
    [XdmFunction("factorial")]
    public XPathAtomicValue MyFactorialFunction([XdmType(XmlTypeCode.Integer)] int argument)
    {
        if (argument <= 0)
            return 0;
        
        int factorial = 1;
        for (int i = 1; i <= argument; i++)
            factorial *= i;

        return factorial
    }
}

Note that this class is annotated to export the function factorial in the namespace http://www.example.org. The following code shows how to compile a query that uses this external module to calculate 10 factorial, and write out the result to the console.

XQuerySettings querySettings = new XQuerySettings();
XdmModule module = XdmModule.NativeModule<MyModule>();
querySettings.Libraries.Add(module);

string program = "import module namespace module='http://www.example.org';" + Environment.NewLine +
                 "module:factorial(10)";

XQuery query = XQuery.Compile(program, querySettings);

XPathItem result = query.EvaluateToItem();

Console.WriteLine(result.ToString());