Module org.postgresql.pljava
Package org.postgresql.pljava.annotation

Annotation Interface 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 enum 
    Function.Effects
    The volatility category describing the presence or absence of side-effects constraining what the optimizer can safely do with the function.
    static enum 
    Function.OnNullInput
    Whether the function is called even for null input, or known to return null in that case and therefore not called.
    static enum 
    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 enum 
    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 enum 
    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, except as described for out below.

      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.

      If there is exactly one OUT parameter declared, PostgreSQL treats the function as returning that parameter's type, rather than a one-element composite; therefore, the Java method must have the corresponding form (returning the result type directly, or an Iterator of that type, rather than expecting a ResultSet final parameter.

      If a one-element composite type is wanted, PL/Java will allow type="pg_catalog.RECORD" along with a one-element out, and will generate the corresponding declaration in SQL. As of this writing, however, no version of PostgreSQL will accept it.

      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

      Function.OnNullInput 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

      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). 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

      Function.Effects 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

      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.
      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

      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. 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:
      ""