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

Annotation Interface BaseUDT

@Target(TYPE) @Retention(CLASS) @Documented public @interface BaseUDT
Annotation on a PL/Java class to form a User Defined Type that will become a new PostgreSQL base type.

A class marked with this annotation must implement SQLData, and will use the methods of that interface to map between its own state and an internal form that PostgreSQL will store. For that to work, it must also have a public, no-argument constructor.

It must also have a public, static parse(String value, String typeName) method, and the ubiquitous Java toString method, which will be used to map between its own state and an externally-usable, text representation. Note that, while it may inherit some sort of toString method from a superclass, there is a special requirement on toString for a class that will be a base UDT: the method must produce exactly what the parse method can parse.

A type will be created in SQL with the name and, if specified, schema from this annotation. If not specified, the type will be created with no explicit schema qualification (that is, it will go into whatever schema heads the search_path at the time the commands are executed), and the name will be the simple name of the annotated class.

Four functions will be declared in SQL, corresponding to the parse, toString, readSQL, and writeSQL methods of the class. By default, the SQL names given to them will use the schema, if any, given here for the class, with the names based on the type name given or defaulted here, with _in, _out, _recv, and _send suffixed, respectively. All of those defaults (and other properties of the functions) can be individually adjusted by adding @Function annotations on a method's declaration in this class.

Other static methods in the class may be exported as SQL functions by marking them with @Function in the usual way, and will not have any special treatment on account of being in a UDT class. Those function declarations will be correctly ordered before or after this type's, in common cases such as when this type appears in their signatures, or the type must refer to the functions (as it must for typeModifierInput or typeModifierOutput functions, for example). In a case that the automatic ordering does not handle correctly, appropriate provides/requires labels can be used in the @Function annotations and this annotation, to make the order come out right.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    BaseUDT.Alignment
    The supported alignment constraints for the type's internal representation.
    static enum 
    BaseUDT.PredefinedCategory
    The type categories that are predefined in PostgreSQL.
    static enum 
    BaseUDT.Storage
    The supported TOAST strategies for the type's stored representation.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    BaseUDT.Alignment
    alignment
    Alignment constraint for the type in memory.
    String
    analyze
    Name, possibly schema-qualified, of a function to gather custom statistics for this type.
    char
    category
    A category for this type, influencing PostgreSQL's choices for implicit type conversion.
    boolean
    collatable
    If true, indicates that column definitions or expressions of this type may carry a COLLATE clause.
    String
    comment
    A comment to be associated with the type.
    String
    defaultValue
    A default value for attributes declared to be of this type.
    char
    delimiter
    Delimiter character to be used between elements when the generic array routines output an array with this new type as its element type.
    String
    element
    Name, possibly schema-qualified, of an existing type to be accessible by subscripting this new type as if it were an array (only with zero-based indexing instead of one-based).
    String
    implementor
    The <implementor name> to be used around SQL code generated for this type (and for its in/out/recv/send functions, if not overridden for them).
    int
    internalLength
    Length of the type's internal representation, positive for a fixed length.
    String
    like
    Name, possibly schema-qualified, of another SQL type whose internalLength, passedByValue, alignment, and storage properties are used for this type, as a shorthand alternative to spelling them all out.
    String
    name
    Name of the new type in SQL, if it is not to be the simple name of the class.
    boolean
    passedByValue
    If true, indicates that the contents are passed by value rather than by reference, only possible for fixed-length types no wider than the PostgreSQL Datum.
    boolean
    preferred
    Whether this type is to be "preferred" in its category(), for implicit type conversion purposes.
    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.
    String
    schema
    Schema in which the new type (and, by default, its input/output/send/receive functions) should be declared.
    BaseUDT.Storage
    storage
    The TOAST strategy for the type's stored representation.
    String
    typeModifierInput
    Name, possibly schema-qualified, of a function to parse type-modifier strings for this type.
    String
    typeModifierOutput
    Name, possibly schema-qualified, of a function to format internal type-modifier codes for display.

  • Element Details

    • name

      String name
      Name of the new type in SQL, if it is not to be the simple name of the class. By default, the class name will be used, subject to PostgreSQL's normal case-folding and case-insensitive matching.
      Default:
      ""

    • schema

      String schema
      Schema in which the new type (and, by default, its input/output/send/receive functions) should be declared. If not given, the names will not be schema qualified, and will be created in the schema at the head of the search_path at creation time.
      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 type (and for its in/out/recv/send functions, if 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 type. If left to default, and the Java class has a doc comment, its first sentence will be used. If an empty string is explicitly given, no comment will be set.
      Default:
      ""

    • typeModifierInput

      String typeModifierInput
      Name, possibly schema-qualified, of a function to parse type-modifier strings for this type. Such a function may be implemented in any language as long as it can accept a single cstring[] parameter and return a single non-negative int4. A static Java method may be used, following the conventions for a normal PL/Java function.

      Even if the method is defined on the UDT class marked by this annotation, it is not automatically found or used. It will need its own Function annotation giving it a name, and this annotation must refer to it by that name to ensure the SQL is generated in the right order.

      Default:
      ""

    • typeModifierOutput

      String typeModifierOutput
      Name, possibly schema-qualified, of a function to format internal type-modifier codes for display. If it is not provided, PostgreSQL will simply display numeric modifier codes in parentheses following a type name. Such a function may be implemented in any language as long as it can accept a single int4 parameter and return a cstring (not a cstring[], as you might expect by analogy to typeModifierInput). A static Java method may be used, following the conventions for a normal PL/Java function.

      Even if the method is defined on the UDT class marked by this annotation, it is not automatically found or used. It will need its own Function annotation giving it a name, and this annotation must refer to it by that name to ensure the SQL is generated in the right order.

      Default:
      ""

    • analyze

      String analyze
      Name, possibly schema-qualified, of a function to gather custom statistics for this type. It must be implemented in a language allowing a parameter of type internal, and return a boolean. The details of the necessary API are in vacuum.h.

      Even if the method is defined on the UDT class marked by this annotation, it is not automatically found or used. It will need its own Function annotation giving it a name, and this annotation must refer to it by that name to ensure the SQL is generated in the right order.

      Default:
      ""

    • internalLength

      int internalLength
      Length of the type's internal representation, positive for a fixed length. VARIABLE is assumed if this is omitted.
      Default:
      -1

    • passedByValue

      boolean passedByValue
      If true, indicates that the contents are passed by value rather than by reference, only possible for fixed-length types no wider than the PostgreSQL Datum.
      Default:
      false

    • alignment

      BaseUDT.Alignment alignment
      Alignment constraint for the type in memory. INT4 is the default and, for variable-length types, also the minimum (variable-length types begin with an INT4 header).
      Default:
      INT4

    • storage

      BaseUDT.Storage storage
      The TOAST strategy for the type's stored representation. Only PLAIN is applicable to fixed-length types.
      Default:
      PLAIN

    • like

      String like
      Name, possibly schema-qualified, of another SQL type whose internalLength, passedByValue, alignment, and storage properties are used for this type, as a shorthand alternative to spelling them all out.
      Default:
      ""

    • category

      char category
      A category for this type, influencing PostgreSQL's choices for implicit type conversion. This must be a single character, which PostgreSQL calls "simple ASCII" and really forces to be in [ -~], that is, space to tilde, inclusive.

      The upper-case ASCII letters are reserved for PostgreSQL's predefined categories, which can be found in the PredefinedCategory enumeration. The default is PredefinedCategory.Code.USER.

      Default:
      'U'

    • preferred

      boolean preferred
      Whether this type is to be "preferred" in its category(), for implicit type conversion purposes. Setting true without careful thought can cause perplexing behaviors.
      Default:
      false

    • defaultValue

      String defaultValue
      A default value for attributes declared to be of this type. The value given here will be placed in the CREATE TYPE command as a properly-quoted string literal, which must be convertible to a value of the type (using the parse function of the class this annotation marks).
      Default:
      ""

    • element

      String element
      Name, possibly schema-qualified, of an existing type to be accessible by subscripting this new type as if it were an array (only with zero-based indexing instead of one-based). Reports from anyone who has seen this functionality actually work are welcome.
      Default:
      ""

    • delimiter

      char delimiter
      Delimiter character to be used between elements when the generic array routines output an array with this new type as its element type.
      Default:
      ','

    • collatable

      boolean collatable
      If true, indicates that column definitions or expressions of this type may carry a COLLATE clause. What is actually done with that information is up to functions that operate on the new type; nothing happens automatically.
      Default:
      false