Annotation Type Operator


@Documented
@Target({METHOD,TYPE})
@Repeatable(Container.class)
@Retention(CLASS)
public @interface Operator
Declares a PostgreSQL OPERATOR.

May annotate a Java method (which should also carry a @Function annotation, making it a PostgreSQL function), or a class or interface (just to have a place to put it when not directly annotating a method).

Author:
Chapman Flack
  • Nested Class Summary

    Nested Classes
    Modifier and Type Class Description
    static interface  Operator.SelectivityEstimators
    Names of several functions predefined in PostgreSQL for estimating the selectivity of operators in restriction clauses or joins.
  • Required Element Summary

    Required Elements
    Modifier and Type Required Element Description
    String[] name
    Name for this operator.
  • Optional Element Summary

    Optional Elements
    Modifier and Type Optional Element Description
    String comment
    A comment to be associated with the operator.
    String[] commutator
    Name of an operator that is the commutator of this one.
    String[] function
    Name of the function backing the operator; may be omitted if this annotation appears on a method.
    boolean hashes
    Whether this operator can be used in computing a hash join.
    String implementor
    The <implementor name> to be used around SQL code generated for this operator.
    String[] join
    Name of a function that can estimate the selectivity of this operator when used in a join.
    String left
    The type of the operator's left operand, if any.
    boolean merges
    Whether this operator can be used in computing a merge join.
    String[] negator
    Name of an operator that is the negator of this one.
    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[] restrict
    Name of a function that can estimate the selectivity of this operator when used in a WHERE clause.
    String right
    The type of the operator's right operand, if any.
    String[] synthetic
    Name of a function to be synthesized by PL/Java based on the method this annotation appears on and this operator's commutator or negator relationship to another operator declared on the same method.
  • Field Summary

    Fields
    Modifier and Type Field Description
    static String SELF
    Distinguished value usable for commutator= to indicate that an operator is its own commutator without having to repeat its schema and name.
    static String TWIN
    Distinguished value usable for commutator= to indicate that an operator's commutator is another operator with the same schema and name, without having to repeat them.
  • Field Details

    • SELF

      static final String SELF
      Distinguished value usable for commutator= to indicate that an operator is its own commutator without having to repeat its schema and name.

      This value strictly declares that the operator is its own commutator, and therefore is only allowed for an operator with two operands of the same type. If the types are different, a commutator with the same name would in fact be a different operator with the operand types exchanged; use TWIN for that.

      See Also:
      Constant Field Values
    • TWIN

      static final String TWIN
      Distinguished value usable for commutator= to indicate that an operator's commutator is another operator with the same schema and name, without having to repeat them.

      This value strictly declares that the commutator is a different operator, and therefore is only allowed for an operator with two operands of different types. As commutators, this operator and its twin will have those operand types in opposite orders, so PostgreSQL overloading will allow them to have the same name.

      This value may also be used with synthetic= to give the synthesized function the same schema and name as the one it is based on; this also is possible only for a function synthesized by commutation where the commuted parameter types differ.

      See Also:
      Constant Field Values
  • Element Details

    • name

      String[] name
      Name for this operator.

      May be specified in explicit {"schema","operatorname"} form, or as a single string that will be leniently parsed as an optionally schema-qualified name. In the explicit form, "" as the schema will make the name explicitly unqualified.

    • left

      String left
      The type of the operator's left operand, if any. Will default to the first parameter type of an associated two-parameter function, or none for an associated one-parameter function.
      Default:
      ""
    • right

      String right
      The type of the operator's right operand, if any. Will default to the second parameter type of an associated two-parameter function, or the parameter type for an associated one-parameter function.
      Default:
      ""
    • function

      String[] function
      Name of the function backing the operator; may be omitted if this annotation appears on a method.

      The function named here must take one parameter of the matching type if only one of left or right is specified, or the left and right types in that order if both are present.

      Default:
      {}
    • synthetic

      String[] synthetic
      Name of a function to be synthesized by PL/Java based on the method this annotation appears on and this operator's commutator or negator relationship to another operator declared on the same method.

      Only allowed in an annotation on a Java method, and where function is not specified.

      The special value TWIN is allowed, to avoid repeating the schema and name when the desired name for the synthesized function is the same as the one it is derived from (which is only possible if the derivation involves commuting the arguments and their types are different, so the two functions can be distinguished by overloading). A typical case would be the twin of a cross-type function like add that is commutative, so using the same name makes sense.

      Default:
      {}
    • commutator

      String[] commutator
      Name of an operator that is the commutator of this one.

      Specified in the same ways as name. The value SELF can be used to avoid repeating the schema and name for the common case of an operator that is its own commutator. The value TWIN can likewise declare that the commutator is the different operator with the same name and schema but the operand types (which must be different) reversed. A typical case would be the twin of a cross-type operator like + that is commutative, so using the same name makes sense.

      Default:
      {}
    • negator

      String[] negator
      Name of an operator that is the negator of this one.

      Specified in the same ways as name.

      Default:
      {}
    • hashes

      boolean hashes
      Whether this operator can be used in computing a hash join.

      Only sensible for a boolean-valued binary operator, which must have a commutator in the same hash index operator family, with the underlying functions marked Function.Effects.IMMUTABLE or Function.Effects.STABLE.

      Default:
      false
    • merges

      boolean merges
      Whether this operator can be used in computing a merge join.

      Only sensible for a boolean-valued binary operator, which must have a commutator also appearing as an equality member in the same btree index operator family, with the underlying functions marked Function.Effects.IMMUTABLE or Function.Effects.STABLE.

      Default:
      false
    • restrict

      String[] restrict
      Name of a function that can estimate the selectivity of this operator when used in a WHERE clause.

      Specified in the same ways as function.

      A custom estimator is a complex undertaking (and, at present, requires a language other than Java), but several predefined ones can be found in Operator.SelectivityEstimators.

      Default:
      {}
    • join

      String[] join
      Name of a function that can estimate the selectivity of this operator when used in a join.

      Specified in the same ways as function.

      A custom estimator is a complex undertaking (and, at present, requires a language other than Java), but several predefined ones can be found in Operator.SelectivityEstimators.

      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 operator. 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 operator. If left to default, and the annotated Java construct has a doc comment, its first sentence will be used. If an empty string is explicitly given, no comment will be set.
      Default:
      ""