Module org.postgresql.pljava

Package org.postgresql.pljava.annotation

package org.postgresql.pljava.annotation
Annotations for use in Java code to generate the SQLJ Deployment Descriptor automatically.

To define functions or types in PL/Java requires more than one step. The Java code must be written, compiled to a jar, and made available to the PostgreSQL server. Before the server can use the objects in the jar, the corresponding PostgreSQL declarations of functions/types/triggers/operators, and so on, must be made in SQL. This often lengthy SQL script (and the version that undoes it when uninstalling the jar) can be written in a prescribed form and stored inside the jar itself as an "SQLJ Deployment Descriptor", and processed automatically when the jar is installed in or removed from the backend.

To write the deployment descriptor by hand can be tedious and error-prone, as it must largely duplicate the method and type declarations in the Java code, but using SQL's syntax and types in place of Java's. Instead, when the annotations in this package are used in the Java code, the Java compiler itself will generate a deployment descriptor file, ready to include with the compiled classes to make a complete SQLJ jar.

Automatic descriptor generation requires attention to a few things.

  • The pljava-api jar must be on the Java compiler's class path. (All but the simplest PL/Java functions probably refer to some class in PL/Java's API anyway, in which case the jar would already have to be on the class path.)
  • When recompiling after changing only a few sources, it is possible the Java compiler will only process a subset of the source files containing annotations. If so, it may generate an incomplete deployment descriptor, and a clean build may be required to ensure the complete descriptor is written.
  • Additional options are available when invoking the Java compiler, and can be specified with -Aoption=value on the command line:
    ddr.output
    The file name to be used for the generated deployment descriptor. If not specified, the file will be named pljava.ddr and found in the top directory of the tree where the compiled class files are written.
    ddr.name.trusted
    The language name that will be used to declare methods that are annotated to have Function.Trust.SANDBOXED behavior. If not specified, the name java will be used. It must match the name used for the "trusted" language declaration when PL/Java was installed.
    ddr.name.untrusted
    The language name that will be used to declare methods that are annotated to have Function.Trust.UNSANDBOXED behavior. If not specified, the name javaU will be used. It must match the name used for the "untrusted" language declaration when PL/Java was installed.
    ddr.implementor
    The identifier (defaulting to PostgreSQL if not specified here) that will be used in the <implementor block>s wrapping any SQL generated from elements that do not specify their own. If this is set to a single hyphen (-), elements that specify no implementor will produce plain <SQL statement>s not wrapped in <implementor block>s.
    ddr.reproducible
    When true (the default), SQL statements are written to the deployment descriptor in an order meant to be consistent across successive compilations of the same sources. This option is further discussed below.
  • The deployment descriptor may contain statements that cannot succeed if placed in the wrong order, and to keep a manually-edited script in a workable order while adding and modifying code can be difficult. Most of the annotations in this package accept arbitrary requires and provides strings, which can be used to control the order of statements in the generated descriptor. The strings given for requires and provides have no meaning to the compiler, except that it will make sure not to write anything that requires some string X into the generated script before whatever provides it.
  • There can be multiple ways to order the statements in the deployment descriptor to satisfy the given provides and requires relationships. While the compiler will always write the descriptor in an order that satisfies those relationships, when the ddr.reproducible option is false, the precise order may differ between successive compilations of the same sources, which should not affect successful loading and unloading of the jar with install_jar and remove_jar. In testing, this can help to confirm that all of the needed provides and requires relationships have been declared. When the ddr.reproducible option is true, the order of statements in the deployment descriptor will be one of the possible orders, chosen arbitrarily but consistently between multiple compilations as long as the sources are unchanged. This can be helpful in software distribution when reproducible output is wanted.
  • Class
    Description
    Aggregate
    Declares a PostgreSQL aggregate.
    Aggregate.FinishEffect
    Declares the effect of the finish function in a Plan.
    Aggregate.Plan
    Specifies one "plan" for evaluating the aggregate; one must always be specified (as plan), and a second may be specified (as movingPlan).
    BaseUDT
    Annotation on a PL/Java class to form a User Defined Type that will become a new PostgreSQL base type.
    BaseUDT.Alignment
    The supported alignment constraints for the type's internal representation.
    BaseUDT.PredefinedCategory
    The type categories that are predefined in PostgreSQL.
    BaseUDT.PredefinedCategory.Code
    Character constants corresponding to the predefined categories, for use in the BaseUDT.category() annotation element.
    BaseUDT.Storage
    The supported TOAST strategies for the type's stored representation.
    Cast
    Declares a PostgreSQL CAST.
    Cast.Application
    When this cast can be applied: only in explicit form, when used in assignment context, or implicitly whenever needed.
    Cast.Path
    A known conversion path when a dedicated function is not supplied: BINARY for two types that are known to have the same internal representation, or INOUT to invoke the first type's text-output function followed by the second type's text-input function.
    Function
    Annotates a Java method for which an SQL function declaration should be generated into the deployment descriptor file.
    Function.Effects
    The volatility category describing the presence or absence of side-effects constraining what the optimizer can safely do with the function.
    Function.OnNullInput
    Whether the function is called even for null input, or known to return null in that case and therefore not called.
    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.
    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).
    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.
    MappedUDT
    Annotation on a PL/Java class that will either map an existing PostgreSQL type (provided its internal storage form is well understood), or create and map a new PostgreSQL composite type (a/k/a "structured type" in the standards).
    Operator
    Declares a PostgreSQL OPERATOR.
    Operator.SelectivityEstimators
    Names of several functions predefined in PostgreSQL for estimating the selectivity of operators in restriction clauses or joins.
    SQLAction
    Annotation that supplies verbatim commands to be copied into the deployment descriptor.
    SQLActions
    Container for multiple SQLAction annotations (in case it is convenient to hang more than one on a given program element).
    SQLType
    Optionally annotates a Java method parameter, to supply an explicit SQL type for use in the SQL function declaration in place of the automatically mapped type, and/or to supply an SQL default value.
    Trigger
    Annotation, only used in @Function(triggers=...), to specify what trigger(s) the function will be called for.
    Trigger.Called
    Whether the trigger is invoked before or after the specified event.
    Trigger.Constraint
    Deferrability (only applies to constraint triggers).
    Trigger.Event
    Types of event that can occasion a trigger.
    Trigger.Scope
    Whether the trigger will occur only once for a statement of interest, or once for each row affected by the statement.