com.hp.hpl.jena.sparql.function.user
Class UserDefinedFunctionFactory

java.lang.Object
  com.hp.hpl.jena.sparql.function.user.UserDefinedFunctionFactory

All Implemented Interfaces:

FunctionFactory

public class UserDefinedFunctionFactory
extends Object
implements FunctionFactory

A function factory for managing user defined functions aka function macros.

User defined functions provide a simple mechanism for a user to inject custom functions into SPARQL processing without the need to write any code. These functions essentially act as macros/aliases for another SPARQL expression and serve as a means to aid users in simplifying their SPARQL queries.

For example we can define a square function like so:

 List<Var> args = new ArrayList<Var>(Var.alloc("x"));
 UserDefinedFunctionFactory.getFactory().add("http://example/square", "?x * ?x", args);
 

We can then use this in queries like so:

 SELECT (<http://example/square>(3) AS ?ThreeSquared) { }
 

Internally the call to the square function is translated into its equivalent SPARQL expression and executed in that form.

User defined functions may rely on each other but this has some risks, therefore the default behaviour is to not preserve these dependencies but rather to expand the function definitions to give the resulting expression associated with a function. Please see getPreserveDependencies() for more information on this.

Method Summary

void	add(String uri, Expr e, List<Var> args) Adds a function
void	add(String uri, String expr, List<Var> args) Adds a function
void	clear() Clears all function definitions
Function	create(String uri) Creates a function for the given URI
UserDefinedFunctionDefinition	get(String uri) Gets the definition of the function (if registered)
static UserDefinedFunctionFactory	getFactory() Gets the static instance of the factory
boolean	getPreserveDependencies() Gets whether user defined functions may preserve dependencies on each other (default false)
boolean	isRegistered(String uri) Gets whether a function with the given URI has been registered
void	remove(String uri) Removes a function definition
void	setPreserveDependencies(boolean allow) Sets whether user functions may explicitly depend on each other, see getPreserveDependencies() for explanation of this behavior

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getFactory

public static UserDefinedFunctionFactory getFactory()

Gets the static instance of the factory

Returns:

Function Factory

getPreserveDependencies

public boolean getPreserveDependencies()

Gets whether user defined functions may preserve dependencies on each other (default false)

When this is disabled (as it is by default) function definitions are fully expanded at registration time. So if you add a function that references an existing user defined function it will be expanded to include the resulting expression rather than left with a reference to another function. This protects the user from depending on other functions whose definitions are later removed or changed.

However it may sometimes be desirable to have dependencies preserved in which case this option may be disabled with the corresponding setPreserveDependencies(boolean) setter

Returns:

Whether explicit dependencies are allowed

setPreserveDependencies

public void setPreserveDependencies(boolean allow)

Sets whether user functions may explicitly depend on each other, see getPreserveDependencies() for explanation of this behavior

Parameters:

allow - Whether to preserve dependencies

create

public Function create(String uri)

Creates a function for the given URI

Specified by:

create in interface FunctionFactory

Parameters:

uri - URI

Returns:

Function

Throws:

ExprBuildException - Thrown if the given URI is not a known function

add

public void add(String uri,
                Expr e,
                List<Var> args)

Adds a function

Parameters:

uri - URI

e - Expression

args - Arguments

add

public void add(String uri,
                String expr,
                List<Var> args)
         throws ParseException

Adds a function

This method will build the expression to use based on the expression string given, strings must match the SPARQL expression syntax e.g.

 (?x * ?y) + 5
 

Parameters:

uri - URI

expr - Expression String (in SPARQL syntax)

args - Arguments

Throws:

ParseException - Thrown if the expression string is not valid syntax

remove

public void remove(String uri)

Removes a function definition

Parameters:

uri - URI

Throws:

NoSuchElementException - Thrown if a function with the given URI does not exist

get

public UserDefinedFunctionDefinition get(String uri)

Gets the definition of the function (if registered)

Parameters:

uri - URI

Returns:

Function Definition if registered, null otherwise

isRegistered

public boolean isRegistered(String uri)

Gets whether a function with the given URI has been registered

Parameters:

uri - URI

Returns:

True if registered, false otherwise

clear

public void clear()

Clears all function definitions