Annotation Type Function


@Documented
@Target(METHOD)
@Retention(CLASS)
public @interface Function
Annotates a Java method for which an SQL function declaration should be generated into the deployment descriptor file.
Author:
Thomas Hallgren - pre-Java6 version, Chapman Flack (Purdue Mathematics) - update to Java6, add trust, cost, rows, settings, leakproof, provide/require
  • Nested Class Summary

    Nested Classes
    Modifier and Type Class Description
    static class  Function.Effects
    The volatility category describing the presence or absence of side-effects constraining what the optimizer can safely do with the function.
    static class  Function.OnNullInput
    Whether the function is called even for null input, or known to return null in that case and therefore not called.
    static class  Function.Parallel
    Whether the function is unsafe to use in any parallel query plan at all, or avoids certain operations and can appear in such a plan but must be executed only in the parallel group leader, or avoids an even larger set of operations and is safe to execute anywhere in a parallel plan.
    static class  Function.Security
    Whether the function executes with the same identity and permissions as the role that has invoked it (the usual case), or with the rights of the role that defined it (such as to offer controlled access to data the invoker would otherwise have no access to).
    static class  Function.Trust
    Whether the function only needs limited capabilities and can run in the "trusted" language sandbox, or has to be unsandboxed and run in an "untrusted" language instance.
  • Optional Element Summary

    Optional Elements
    Modifier and Type Optional Element Description
    String comment
    A comment to be associated with the SQL function.
    int cost
    Estimated cost in units of cpu_operator_cost.
    Function.Effects effects
    What the query optimizer is allowed to assume about this function.
    String implementor
    The <implementor name> to be used around SQL code generated for this function (and for its triggers, if any, and not overridden for them).
    String language
    The name of the PostgreSQL procedural language to which this function should be declared, as an alternative to specifying trust.
    boolean leakproof
    Whether the function can be safely pushed inside the evaluation of views created with the security_barrier option. This should only be set true on a function known not to leak data under any circumstances (even, for example, throwing errors for certain parameter values and not others).
    String name
    The name of the function.
    Function.OnNullInput onNullInput
    Defines what should happen when input to the function is null.
    String[] out
    The result column names and types of a composite-returning function.
    Function.Parallel parallel
    Whether the function is UNSAFE to use in any parallel query plan at all (the default), or avoids all disqualifying operations and so is SAFE to execute anywhere in a parallel plan, or, by avoiding some such operations, may appear in parallel plans but RESTRICTED to execute only on the parallel group leader.
    String[] provides
    One or more arbitrary labels that will be considered 'provided' by the object carrying this annotation.
    String[] requires
    One or more arbitrary labels that will be considered 'required' by the object carrying this annotation.
    int rows
    Estimated number of rows returned (only for functions returning set).
    String schema
    The name of the schema if any.
    Function.Security security
    Whether the function will run with the security credentials of the invoker (the usual case) or with those of its definer (the special case for a function that needs to access objects with the authority of the user who declared it).
    String[] settings
    Configuration parameter overrides to apply during execution of the function, reverting afterward to the former setting.
    Trigger[] triggers
    The Triggers that will call this function (if any).
    Function.Trust trust
    Whether the function will run in the SANDBOXED ("trusted") version of the language, or requires UNSANDBOXED access and must be defined in the "untrusted" language instance.
    String type
    The element type in case the annotated function returns a ResultSetProvider, or can be used to specify the return type of any function if the compiler hasn't inferred it correctly.
    boolean variadic
    Whether PostgreSQL should gather trailing arguments into an array that will be bound to the last (non-output) Java parameter (which must have an array type).
  • Element Details

    • type

      String type
      The element type in case the annotated function returns a ResultSetProvider, or can be used to specify the return type of any function if the compiler hasn't inferred it correctly.

      Only one of type or out may appear.

      Default:
      ""
    • out

      String[] out
      The result column names and types of a composite-returning function.

      This is for a function defining its own one-off composite type (declared with OUT parameters). If the function returns some composite type known to the catalog, simply use type and the name of that type.

      Each element is a name and a type specification, separated by whitespace. An element that begins with whitespace declares an output column with no name, only a type. The name is an ordinary SQL identifier; if it would be quoted in SQL, naturally each double-quote must be represented as \" in Java.

      Default:
      {}
    • name

      String name
      The name of the function. This is optional. The default is to use the name of the annotated method.
      Default:
      ""
    • schema

      String schema
      The name of the schema if any.
      Default:
      ""
    • variadic

      boolean variadic
      Whether PostgreSQL should gather trailing arguments into an array that will be bound to the last (non-output) Java parameter (which must have an array type). Appeared in PostgreSQL 8.4.
      Default:
      false
    • cost

      int cost
      Estimated cost in units of cpu_operator_cost.

      If left unspecified (-1) the backend's default will apply.

      Default:
      -1
    • rows

      int rows
      Estimated number of rows returned (only for functions returning set).

      If left unspecified (-1) the backend's default will apply.

      Default:
      -1
    • onNullInput

      Defines what should happen when input to the function is null. RETURNS_NULL means that if any parameter value is null, Postgres will use null as the return value without even calling the function. CALLED means the function is called in all cases, and must do its own checks for null parameters and determine what to return.
      Default:
      CALLED
    • security

      Whether the function will run with the security credentials of the invoker (the usual case) or with those of its definer (the special case for a function that needs to access objects with the authority of the user who declared it). Security.DEFINER functions must be coded and declared carefully; see at least Writing SECURITY DEFINER Functions Safely in the PostgreSQL docs, and the settings() element of this annotation.
      Default:
      INVOKER
    • effects

      What the query optimizer is allowed to assume about this function.

      IMMUTABLE describes a pure function whose return will always be the same for the same parameter values, with no side effects and no dependency on anything in the environment. STABLE describes a function that has no side effects and can be assumed to produce the same result for the same parameters during any one table scan. VOLATILE (the default) describes a function with side effects or about whose result the optimizer cannot make any safe assumptions.

      Default:
      VOLATILE
    • trust

      Whether the function will run in the SANDBOXED ("trusted") version of the language, or requires UNSANDBOXED access and must be defined in the "untrusted" language instance.
      Default:
      SANDBOXED
    • language

      String language
      The name of the PostgreSQL procedural language to which this function should be declared, as an alternative to specifying trust.

      Ordinarily, PL/Java installs two procedural languages, java and javau, and a function is declared in one or the other by giving trust the value SANDBOXED or UNSANDBOXED, respectively. It is possible to declare other named procedural languages sharing PL/Java's handler functions, and assign customized permissions to them in pljava.policy. A function can be declared in the specific language named with this element.

      It is an error to specify both language and trust in the same annotation.

      Default:
      ""
    • parallel

      Whether the function is UNSAFE to use in any parallel query plan at all (the default), or avoids all disqualifying operations and so is SAFE to execute anywhere in a parallel plan, or, by avoiding some such operations, may appear in parallel plans but RESTRICTED to execute only on the parallel group leader. The operations that must be considered are set out in Parallel Labeling for Functions and Aggregates in the PostgreSQL docs.

      For much more on the practicalities of parallel query and PL/Java, please see the users' guide.

      Appeared in PostgreSQL 9.6.

      Default:
      UNSAFE
    • leakproof

      boolean leakproof
      Whether the function can be safely pushed inside the evaluation of views created with the security_barrier option. This should only be set true on a function known not to leak data under any circumstances (even, for example, throwing errors for certain parameter values and not others). Appeared in PostgreSQL 9.2.
      Default:
      false
    • settings

      String[] settings
      Configuration parameter overrides to apply during execution of the function, reverting afterward to the former setting. Suggested for, e.g., applying a trusted search_path during execution of a SECURITY DEFINER function. Each string will simply be injected into the generated CREATE FUNCTION command after a SET token, and so should have the forms
      configuration_parameter {=|TO} somevalue or
      configuration_parameter FROM CURRENT. The latter will ensure that the function executes with the same setting for configuration_parameter that was in effect when the function was created.

      Appeared in PostgreSQL 8.3.

      Default:
      {}
    • triggers

      Trigger[] triggers
      The Triggers that will call this function (if any).
      Default:
      {}
    • provides

      String[] provides
      One or more arbitrary labels that will be considered 'provided' by the object carrying this annotation. The deployment descriptor will be generated in such an order that other objects that 'require' labels 'provided' by this come later in the output for install actions, and earlier for remove actions.
      Default:
      {}
    • requires

      String[] requires
      One or more arbitrary labels that will be considered 'required' by the object carrying this annotation. The deployment descriptor will be generated in such an order that other objects that 'provide' labels 'required' by this come earlier in the output for install actions, and later for remove actions.
      Default:
      {}
    • implementor

      String implementor
      The <implementor name> to be used around SQL code generated for this function (and for its triggers, if any, and not overridden for them). Defaults to PostgreSQL. Set explicitly to "" to emit code not wrapped in an <implementor block>.
      Default:
      ""
    • comment

      String comment
      A comment to be associated with the SQL function. If left to default, and the Java function has a doc comment, its first sentence will be used. If an empty string is explicitly given, no comment will be set.
      Default:
      ""