Module com.darkcollective.relix.function
Package com.darkcollective.relix.function

Interface FunctionLibrary

All Known Implementing Classes:
BuiltinFunctionLibrary
public interface FunctionLibrary
A collection of functions offered to the engine — the unit that is installed, discovered and versioned.

A library is found with ServiceLoader, so an implementation needs a public no-argument constructor and must be declared as a provider both in its module-info and in META-INF/services: a module path reads the first and a class path reads the second, and a library that declares only one of them works in exactly one of the two ways the engine is run.

What a library offers is expressed by which methods it overrides. Both default to offering nothing, so a library of scalar functions never mentions aggregates. 


 public final class GeoFunctions implements FunctionLibrary {
     public String name() { return "acme-geo"; }
     public List<ScalarFunction> scalarFunctions() { return List.of(new Haversine()); }
 }

  • Method Summary

    Modifier and Type
    Method
    Description
    default List<AggregateFunction>
    aggregateFunctions()
    The aggregates this library offers.
    default Optional<String>
    documentation(String docKey)
    This library's documentation for one of its functions, as Markdown.
    String
    name()
    A short identifier for this library, used in diagnostics — including the one that reports two libraries offering the same function name.
    default int
    priority()
    Which library wins when two offer a function of the same name: the higher priority.
    default List<ScalarFunction>
    scalarFunctions()
    The scalar functions this library offers.

  • Method Details

    • name

      String name()
      A short identifier for this library, used in diagnostics — including the one that reports two libraries offering the same function name.
      Returns:
      the library's name; never null or blank

    • priority

      default int priority()
      Which library wins when two offer a function of the same name: the higher priority.

      The default library ships at 0, so a library declaring a higher priority replaces built-in functions it re-declares, and one declaring a lower priority fills gaps without disturbing them. Either way the engine reports the clash rather than resolving it silently.

      Ties are broken by discovery order, which is not something to rely on: two libraries that both want to own a name should differ in priority.

      Returns:
      this library's priority; higher wins

    • scalarFunctions

      default List<ScalarFunction> scalarFunctions()
      The scalar functions this library offers.
      Returns:
      the scalar functions; empty by default

    • aggregateFunctions

      default List<AggregateFunction> aggregateFunctions()
      The aggregates this library offers.
      Returns:
      the aggregates; empty by default

    • documentation

      default Optional<String> documentation(String docKey)
      This library's documentation for one of its functions, as Markdown.

      A library serves its own pages rather than the engine reading them out of it: a module's resources are its own — under JPMS they are not even visible from outside without an explicit opens — and a library that keeps its documentation somewhere other than a resource file (generating it, or fetching it) can still answer.

      The key is the one a signature declares. A library is asked only for keys, and should answer only for keys, that its own functions declare: it is being asked for its page, not for whatever happens to sit at that path.

      Parameters:
      docKey - the documentation key of one of this library's functions
      Returns:
      the Markdown page, or empty when this library has no page under that key