Module org.postgresql.pljava

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.

Interface Summary

Interface	Description
BaseUDT.PredefinedCategory.Code	Character constants corresponding to the predefined categories, for use in the BaseUDT.category() annotation element.
Operator.SelectivityEstimators	Names of several functions predefined in PostgreSQL for estimating the selectivity of operators in restriction clauses or joins.

Enum Summary

Enum	Description
Aggregate.FinishEffect	Declares the effect of the finish function in a Plan.
BaseUDT.Alignment	The supported alignment constraints for the type's internal representation.
BaseUDT.PredefinedCategory	The type categories that are predefined in PostgreSQL.
BaseUDT.Storage	The supported TOAST strategies for the type's stored representation.
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.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.
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.

Annotation Types Summary

Annotation Type	Description
Aggregate	Declares a PostgreSQL aggregate.
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.
Cast	Declares a PostgreSQL CAST.
Function	Annotates a Java method for which an SQL function declaration should be generated into the deployment descriptor file.
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.
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.