Function

Function.java

/**
 * <p>This is the extension point for 17.6 (Extensible Value Testing) of the SPARQL spec.</p>
 *
 * <p>For implementations of Function to be visible to the query parser and engine, they must be registered
 * via the JDK {@link java.util.ServiceLoader}.  Create a file called
 * {@code com.complexible.stardog.plan.filter.functions.Function} in the {@code META-INF/services} directory.
 * The contents of this file should be all of the *fully-qualified* class names for the custom Functions.  Then
 * if a jar containing the {@code META-INF/services} directory and the implementations for the Functions is
 * included on the classpath, Stardog will pick up the implementations on startup.</p>
 *
 * To use the example from the SPARQL spec, if the Function is used in a query
 * {@code aGeo:distance(?axLoc, ?ayLoc, ?bxLoc, ?byLoc) }, its signature is as follows:
 *
 * <pre>
 * {code
 *      xsd:double   aGeo:distance (numeric x1, numeric y1, numeric x2, numeric y2)
 * }
 * </pre>
 *
 * When {@code evaluate} is called, it will be provided four {@link Value values} via the {@link ValueSolution},
 * which are the current values for the parameters, {@code x1}, {@code y1}, {@code x2}, and {@code y2}.
 *
 * @author	Michael Grove
 * @since	0.1
 * @version	3.0
 *
 * @see     FunctionRegistry
 * @see     <a href="http://www.w3.org/TR/2012/PR-sparql11-query-20121108/#extensionFunctions">Extension Functions</a>
 */
public interface Function extends Expression {

	/**
	 * Return the string that uniquely identifies this {@code Expression}, which should be a fully qualified URI.  This
	 * URI is what is used to reference this {@code Expression} in a SPARQL query.
	 *
	 * @return the URI
	 */
	public String getName();

	/**
	 * Return all the strings that uniquely identifies this {@code Expression}. A function may have different names
	 * in different namespaces.
	 *
	 * @return all aliases of this {@code Expression}
	 *
	 * @see #getName()
	 */
	public List<String> getNames();

	/**
	 * Initialize this function.
	 *
	 * In the case of a pure function, this is a no-op. However, in some cases, a function needs to keep some global state
	 * during query execution for it to work correctly.  {@code initialize} should prepare the function for
	 * execution by either clearing or otherwise preparing it's state for (re)execution.
	 */
	public void initialize();

	/**
	 * {@inheritDoc}
	 */
	@Override
	public Function copy();
}