Annotation Type 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. If those function declarations will depend on the existence of this type, or the type must refer to the functions (as it must for typeModifierInput or typeModifierOutput functions, for example), appropriate provides/requires labels must be used in their @Function annotations and this annotation, to make the order come out right.

  • Nested Class Summary

    Nested Classes
    Modifier and Type Class Description
    static class  BaseUDT.Alignment
    The supported alignment constraints for the type's internal representation.
    static class  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 a provides label, and this annotation must refer to it by that name and include the label in requires 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 a provides label, and this annotation must refer to it by that name and include the label in requires 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.
      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

      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

      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.
      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