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
    • 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 Detail

      • 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:
        org.postgresql.pljava.annotation.Function.OnNullInput.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:
        org.postgresql.pljava.annotation.Function.Security.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:
        org.postgresql.pljava.annotation.Function.Effects.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:
        org.postgresql.pljava.annotation.Function.Trust.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:
        org.postgresql.pljava.annotation.Function.Parallel.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:
        ""