Module org.apache.jena.arq
Package org.apache.jena.sparql.function.user

Class UserDefinedFunctionFactory

java.lang.Object
org.apache.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 Details

    • 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:
      SSE_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)
      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:
      QueryParseException - 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