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.

  • A Java 6 or later Java compiler is required, and at least the pljava-api jar must be on its class path. (The full pljava.jar would also work, but only pljava-api is required.) The jar must be on the class path in any case in order to compile PL/Java code.
  • 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.