Class UserDefinedFunctionFactory

  • All Implemented Interfaces:
    FunctionFactory

    public class UserDefinedFunctionFactory
    extends java.lang.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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(java.lang.String uri, java.lang.String expr, java.util.List<Var> args)
      Adds a function
      void add​(java.lang.String uri, Expr e, java.util.List<Var> args)
      Adds a function
      void clear()
      Clears all function definitions
      Function create​(java.lang.String uri)
      Creates a function for the given URI
      UserDefinedFunctionDefinition get​(java.lang.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​(java.lang.String uri)
      Gets whether a function with the given URI has been registered
      void remove​(java.lang.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​(java.lang.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​(java.lang.String uri,
                        Expr e,
                        java.util.List<Var> args)
        Adds a function
        Parameters:
        uri - URI
        e - Expression
        args - Arguments
      • add

        public void add​(java.lang.String uri,
                        java.lang.String expr,
                        java.util.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​(java.lang.String uri)
        Removes a function definition
        Parameters:
        uri - URI
        Throws:
        java.util.NoSuchElementException - Thrown if a function with the given URI does not exist
      • get

        public UserDefinedFunctionDefinition get​(java.lang.String uri)
        Gets the definition of the function (if registered)
        Parameters:
        uri - URI
        Returns:
        Function Definition if registered, null otherwise
      • isRegistered

        public boolean isRegistered​(java.lang.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