You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by bu...@apache.org on 2011/10/27 02:01:50 UTC
svn commit: r797528 [6/6] -
/websites/staging/jena/trunk/content/jena/documentation/query/
Added: websites/staging/jena/trunk/content/jena/documentation/query/writing_functions.html
==============================================================================
--- websites/staging/jena/trunk/content/jena/documentation/query/writing_functions.html (added)
+++ websites/staging/jena/trunk/content/jena/documentation/query/writing_functions.html Thu Oct 27 00:01:49 2011
@@ -0,0 +1,284 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+ <link href="/jena/css/jena.css" rel="stylesheet" type="text/css">
+ <title>Apache Jena - ARQ - Writing Filter Functions</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <script src="/jena/js/jquery-1.6.4.min.js" type="text/javascript"></script>
+ <script src="/jena/js/jena-navigation.js" type="text/javascript"></script>
+</head>
+
+<body>
+ <div id="header">
+ <div id="logoblock">
+ <img alt="Apache Jena" src="/jena/images/jena-logo/jena-logo-small.png"/>
+ </div>
+
+ <div id="titleblock">
+ <h1 class="title">Apache Jena</h1>
+ <div id="topmenu" class="tabbar round-10">
+ <ul>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/index.html" id="home_menu">Home</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/help_and_support/index.html">Support</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/getting_started/index.html">Getting started</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/tutorials/index.html">Tutorials</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/documentation/index.html">Documentation</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+
+ <div id="navigation" class="clear">
+ <h1 id="quick_links">Quick links</h1>
+<ul>
+<li><a href="/jena/index.html">Home</a></li>
+<li><a href="/jena/download/index.html">Downloads</a></li>
+<li><a href="/jena/help_and_support/index.html">Help and support</a></li>
+<li><a href="/jena/help_and_support/bugs_and_suggestions.html">Report a bug</a></li>
+<li><a href="/jena/about_jena/roadmap.html">Roadmap</a></li>
+<li><a href="/jena/getting_involved/index.html">Getting involved</a></li>
+<li><a href="/jena/documentation/">Documentation</a></li>
+</ul>
+<h1 id="about_jena">About Jena</h1>
+<ul>
+<li><a href="/jena/index.html">Home</a></li>
+<li><a href="/jena/about_jena/about.html">About Jena</a></li>
+<li><a href="/jena/about_jena/architecture.html">Architecture</a></li>
+<li><a href="/jena/about_jena/roadmap.html">Roadmap</a></li>
+<li><a href="/jena/about_jena/team.html">Project team</a></li>
+</ul>
+<h1 id="download">Download</h1>
+<ul>
+<li><a href="/jena/download/index.html">Downloading Jena</a></li>
+<li><a href="/jena/download/maven.html">Using Maven</a></li>
+<li><a href="/jena/download/osgi.html">Using OSGi</a></li>
+</ul>
+<h1 id="help_and_support">Help and support</h1>
+<ul>
+<li><a href="/jena/help_and_support/index.html">Getting help</a></li>
+<li><a href="/jena/help_and_support/bugs_and_suggestions.html">Bugs and suggestions</a></li>
+</ul>
+<h1 id="getting_started">Getting Started</h1>
+<ul>
+<li><a href="/jena/getting_started/index.html">A first Jena project</a></li>
+<li><a href="/jena/getting_started/rdf_api.html">RDF API overview</a></li>
+<li><a href="/jena/getting_started/sparql.html">Querying RDF with SPARQL</a></li>
+<li><a href="/jena/getting_started/fuseki.html">Serving RDF over HTTP</a></li>
+<li><a href="/jena/getting_started/tell_me_how.html">Tell me how to ...</a></li>
+</ul>
+<h1 id="tutorials">Tutorials</h1>
+<ul>
+<li><a href="/jena/tutorials/index.html">RDF tutorial</a></li>
+<li><a href="/jena/tutorials/sparql.html">SPARQL queries</a></li>
+<li><a href="/jena/tutorials/using_jena_with_eclipse.html">Using Jena with Eclipse</a></li>
+</ul>
+<h1 id="documentation">Documentation</h1>
+<ul>
+<li><a href="/jena/documentation/index.html">Overview</a></li>
+<li><a href="/jena/documentation/javadoc">Javadoc</a></li>
+<li><a href="/jena/documentation/rdf/index.html">RDF</a></li>
+<li><a href="/jena/documentation/query/index.html">SPARQL (ARQ)</a></li>
+<li><a href="/jena/documentation/tdb/index.html">TDB</a></li>
+<li><a href="/jena/documentation/sdb/index.html">SDB</a><ul>
+<li><a href="/jena/documentation/sdb/installation.html">Installation</a></li>
+<li><a href="/jena/documentation/sdb/quickstart.html">Quick start</a></li>
+<li><a href="/jena/documentation/sdb/commands.html">Cmd line</a></li>
+<li><a href="/jena/documentation/sdb/javaapi.html">Java API</a></li>
+<li><a href="/jena/documentation/sdb/configuration.html">Config</a></li>
+<li><a href="/jena/documentation/sdb/databases_supported.html">Databases</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/larq/index.html">LARQ</a></li>
+<li><a href="/jena/documentation/serving_data/index.html">Serving Data</a></li>
+<li><a href="/jena/documentation/ontology/index.html">Ontology</a></li>
+<li><a href="/jena/documentation/inference/index.html">Inference</a></li>
+<li><a href="/jena/documentation/assembler/index.html">Assembler</a><ul>
+<li><a href="/jena/documentation/assembler/assembler-howto.html">Assembler how-to</a></li>
+<li><a href="/jena/documentation/assembler/inside-assemblers.html">Inside assemblers</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/io/index.html">I/O</a><ul>
+<li><a href="/jena/documentation/io/iohowto.html">I/O how-to</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/notes/index.html">Notes</a><ul>
+<li><a href="/jena/documentation/notes/concurrency-howto.html">Concurrency how-to</a></li>
+<li><a href="/jena/documentation/notes/event-handler-howto.html">Event handler how-to</a></li>
+<li><a href="/jena/documentation/notes/file-manager.html">File manager how-to</a></li>
+<li><a href="/jena/documentation/notes/model-factory.html">Model factory how-to</a></li>
+<li><a href="/jena/documentation/notes/rdf-frames.html">RDF frames</a></li>
+<li><a href="/jena/documentation/notes/reification.html">Reification how-to</a></li>
+<li><a href="/jena/documentation/notes/typed-literals.html">Typed literals how-to</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/tools/index.html">Tools</a><ul>
+<li><a href="/jena/documentation/tools/schemagen.html">schemagen</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="getting_involved">Getting Involved</h1>
+<ul>
+<li><a href="/jena/getting_involved/index.html">Contributing to Jena</a></li>
+</ul>
+<h1 id="asf_links">ASF links</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">ARQ - Writing Filter Functions</h1>
+ <p>Applications can add SPARQL functions to the query engine. This is
+done by writing a class implementing the right interface, then
+either registering it or using the fake <code>java:</code> URI scheme to
+dynamically call the function.</p>
+<h2 id="writing_sparql_value_functions">Writing SPARQL Value Functions</h2>
+<p>A SPARQL value function is an extension point of the SPARQL query
+language that allows URI to name a function in the query
+processor.</p>
+<p>In the ARQ engine, code to implement function must implement the
+interface <code>com.hp.hpl.jena.sparql.function.Function</code> although it is
+easier to work with one of the abstract classes for specific
+numbers of arguments like
+<code>com.hp.hpl.jena.sparql.function.FunctionBase1</code> for one argument
+functions. Functions do not have to have a fixed number of
+arguments.</p>
+<p>The abstract class <code>FunctionBase</code>, the superclass of
+<code>FunctionBase1</code> to <code>FunctionBase4</code>, evaluates its arguments and
+calls the implementation code with argument values (if a variable
+was unbound, an error will have been generated)Â </p>
+<p>It is possible to get unevaluated arguments but care must be taken
+not to violate the rules of function evaluation. The standard
+functions that access unevaluated arguments are the logical 'or'
+and logical 'and' operations that back <code>||</code> and <code>&&</code> are special
+forms to allow for the special exception handling rules.</p>
+<p>Normally, function should be a pure evaluation based on it's
+argument. It should not access a graph nor return different values
+for the same arguments (to allow expression optimization). Usually,
+these requirements can be better met with a
+<a href="writing_propfunc.html">property function</a>. Functions can't bind a
+variables; this would be done in a
+<a href="writing_propfunc.html">property function</a> as well.</p>
+<p>Example: (this is the max function in the standard ARQ library):</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">max</span> <span class="n">extends</span> <span class="n">FunctionBase2</span>
+<span class="p">{</span>
+ <span class="n">public</span> <span class="n">max</span><span class="p">()</span> <span class="p">{</span> <span class="n">super</span><span class="p">()</span> <span class="p">;</span> <span class="p">}</span>
+ <span class="n">public</span> <span class="n">NodeValue</span> <span class="nb">exec</span><span class="p">(</span><span class="n">NodeValue</span> <span class="n">nv1</span><span class="p">,</span> <span class="n">NodeValue</span> <span class="n">nv2</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="k">return</span> <span class="n">Functions</span><span class="o">.</span><span class="n">max</span><span class="p">(</span><span class="n">nv1</span><span class="p">,</span> <span class="n">nv2</span><span class="p">)</span> <span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>The function takes two arguments and returns a single value. The
+class NodeValue represents values and supports value-based
+operations. NodeValue value support includes the XSD datatypes,
+xsd:decimal and all it's subtypes like xsd:integer and xsd:byte,
+xsd';double, xsd:float, xsd:boolean, xsd:dateTime and xsd:date.
+Literals with language tags are also treated as values in
+additional "value spaces" determined by the language tag without
+regard to case.</p>
+<p>The <code>Functions</code> class contains the core XML Functions and Operators
+operations. Class NodeFunctions contains the implementations of
+node-centric operations like <code>isLiteral</code> and <code>str</code>.</p>
+<p>If any of the arguments are wrong, then the function should throw
+<code>ExprEvalException</code>.</p>
+<p>Example: calculate the canonical namespace from a URI (calls the
+Jena operation for the actual work):</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">namespace</span> <span class="n">extends</span> <span class="n">FunctionBase1</span>
+<span class="p">{</span>
+ <span class="n">public</span> <span class="n">namespace</span><span class="p">()</span> <span class="p">{</span> <span class="n">super</span><span class="p">()</span> <span class="p">;</span> <span class="p">}</span>
+
+ <span class="n">public</span> <span class="n">NodeValue</span> <span class="nb">exec</span><span class="p">(</span><span class="n">NodeValue</span> <span class="n">v</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="n">Node</span> <span class="n">n</span> <span class="o">=</span> <span class="n">v</span><span class="o">.</span><span class="n">asNode</span><span class="p">()</span> <span class="p">;</span>
+ <span class="k">if</span> <span class="p">(</span> <span class="o">!</span> <span class="n">n</span><span class="o">.</span><span class="n">isURI</span><span class="p">()</span> <span class="p">)</span>
+ <span class="n">throw</span> <span class="k">new</span> <span class="n">ExprEvalException</span><span class="p">(</span><span class="s">"Not a URI: "</span><span class="o">+</span><span class="n">FmtUtils</span><span class="o">.</span><span class="n">stringForNode</span><span class="p">(</span><span class="n">n</span><span class="p">))</span> <span class="p">;</span>
+ <span class="n">String</span> <span class="n">str</span> <span class="o">=</span> <span class="n">n</span><span class="o">.</span><span class="n">getNameSpace</span><span class="p">()</span> <span class="p">;</span>
+ <span class="k">return</span> <span class="n">NodeValue</span><span class="o">.</span><span class="n">makeString</span><span class="p">(</span><span class="n">str</span><span class="p">)</span> <span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>This throws an evaluation exception if it is passed a value that is
+not a URI.</p>
+<p>The standard library, in package
+<code>com.hp.hpl.jena.sparql.function.library</code>, contains many examples.</p>
+<h2 id="registering_functions">Registering Functions</h2>
+<p>The query compiler finds functions based on the functions URI.Â
+There is a global registry of known functions, but any query
+execution can have it's own function registry.</p>
+<p>For each function, there is a function factory associated with the
+URI. A new function instance is created for each use of a function
+in each query execution.</p>
+<div class="codehilite"><pre><span class="sr">//</span> <span class="n">Register</span> <span class="n">with</span> <span class="n">the</span> <span class="n">global</span> <span class="n">registry</span><span class="o">.</span>
+<span class="n">FunctionRegistry</span><span class="o">.</span><span class="n">get</span><span class="p">()</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="s">"http://example.org/function#myFunction"</span><span class="p">,</span> <span class="k">new</span> <span class="n">MyFunctionFactory</span><span class="p">())</span> <span class="p">;</span>
+</pre></div>
+
+
+<p>A common case is registering a specific class for a function
+implementation so there is an addition method that takes a class,
+wraps in a built-in function factory and registers the function
+implementation.</p>
+<div class="codehilite"><pre><span class="sr">//</span> <span class="n">Register</span> <span class="n">with</span> <span class="n">the</span> <span class="n">global</span> <span class="n">registry</span><span class="o">.</span>
+<span class="n">FunctionRegistry</span><span class="o">.</span><span class="n">get</span><span class="p">()</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="s">"http://example.org/function#myFunction"</span><span class="p">,</span> <span class="n">MyFunction</span><span class="o">.</span><span class="n">class</span><span class="p">)</span> <span class="p">;</span>
+</pre></div>
+
+
+<p>Another convenience route to function calling is to use the
+<a href="java-uri.html"><code>java:</code> URI scheme</a>. This dynamically loads the code,
+which must be on the Java classpath. With this scheme, the function
+URI gives the class name. There is automatic registration of a
+wrapper into the function registry. This way, no explicit
+registration step is needed by the application and queries issues
+with the command line tools can load custom functions.</p>
+<div class="codehilite"><pre><span class="n">PREFIX</span> <span class="n">f:</span> <span class="sr"><java:app.myFunctions.></span>
+<span class="o">...</span>
+ <span class="n">FILTER</span> <span class="n">f:myTest</span><span class="p">(?</span><span class="n">x</span><span class="p">,</span> <span class="p">?</span><span class="n">y</span><span class="p">)</span>
+<span class="o">...</span>
+ <span class="n">FILTER</span> <span class="p">(?</span><span class="n">x</span> <span class="o">+</span> <span class="n">f:myIntToXSD</span><span class="p">(?</span><span class="n">y</span><span class="p">))</span>
+<span class="o">...</span>
+</pre></div>
+
+
+<p><a href="index.html">ARQ documentation index</a></p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache Jena, Jena, the Apache Jena project logo,
+ Apache and the Apache feather logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>