Module org.postgresql.pljava

Package org.postgresql.pljava.adt

package org.postgresql.pljava.adt
Package containing functional interfaces that document and present PostgreSQL data types abstractly, but clearly enough for faithful mapping.

Interfaces in this package are meant to occupy a level between a PL/Java Adapter (responsible for PostgreSQL internal details that properly remain encapsulated) and some intended Java representation class (which may encapsulate details of its own).

Example

Suppose an application would like to manipulate a PostgreSQL TIME WITH TIME ZONE in the form of a Java OffsetTime instance.

The application selects a PL/Java Adapter that handles the PostgreSQL TIME WITH TIME ZONE type and presents it via the functional interface Datetime.TimeTZ in this package.

The application can instantiate that Adapter with some implementation (possibly just a lambda) of that functional interface, which will construct an OffsetTime instance. That Adapter instance now maps TIME WITH TIME ZONE to OffsetTime, as desired.

The PostgreSQL internal details are handled by the Adapter. The internal details of OffsetTime are OffsetTime's business. In between those two sits the Datetime.TimeTZ interface in this package, with its one simple role: it presents the value in a clear, documented form as consisting of:

  • microseconds since midnight, and
  • a time zone offset in seconds west of the prime meridian

It serves as a contract for the Adapter and as a clear starting point for constructing the wanted Java representation.

It is important that the interfaces here serve as documentation as well as code, as it turns out that OffsetTime expects its time zone offsets to be positive east of the prime meridian, so a sign flip is needed. Interfaces in this package must be documented with enough detail to allow a developer to make correct use of the exposed values.

The division of labor between what is exposed in these interfaces and what is encapsulated within Adapters calls for a judgment of which details are semantically significant. If PostgreSQL somehow changes the internal details needed to retrieve a timetz value, it should be the Adapter's job to make that transparent. If PostgreSQL ever changes the fact that a timetz is microseconds since midnight with seconds-west as a zone offset, that would require versioning the corresponding interface here; it is something a developer would need to know.

Reference implementations

A few simple reference implementations (including the timetz-as-OffsetTime used as the example) can also be found in this package, and Adapter instances using them are available, so an application would not really have to follow the steps of the example to obtain one.
Author:
Chapman Flack
  • Class
    Description
    Array
    Container for functional interfaces presenting a PostgreSQL array.
    Array.AsFlatList<E>
    A contract whereby an array is returned flattened into a Java list, with no attention to its specified dimensionality or index bounds.
    Bitstring
    Container for abstract-type functional interfaces in PostgreSQL's BITSTRING type category.
    Bitstring.Bit<T>
    The BIT and VARBIT types' PostgreSQL semantics: the number of bits, and the sequence of bytes they're packed into.
    Bitstring.Bit.Modifier<T>
    Functional interface to obtain information from the PostgreSQL type modifier applied to the type.
    Datetime
    Container for abstract-type functional interfaces in PostgreSQL's DATETIME type category.
    Datetime.Date<T>
    The DATE type's PostgreSQL semantics: a signed number of days since the "Postgres epoch".
    Datetime.Date.AsLocalDate
    A reference implementation that maps to LocalDate.
    Datetime.Time<T>
    The TIME type's PostgreSQL semantics: microseconds since midnight.
    Datetime.Time.AsLocalTime
    A reference implementation that maps to LocalTime.
    Datetime.Time.Modifier<T>
    Functional interface to obtain information from the PostgreSQL type modifier applied to the type.
    Datetime.Timestamp<T>
    The TIMESTAMP type's PostgreSQL semantics: microseconds since midnight of the PostgreSQL epoch, without an assumed time zone.
    Datetime.Timestamp.AsLocalDateTime
    A reference implementation that maps to LocalDateTime.
    Datetime.Timestamp.Modifier<T>
    Functional interface to obtain information from the PostgreSQL type modifier applied to the type.
    Datetime.TimestampTZ<T>
    The TIMESTAMPTZ type's PostgreSQL semantics: microseconds since midnight UTC of the PostgreSQL epoch.
    Datetime.TimestampTZ.AsOffsetDateTime
    A reference implementation that maps to OffsetDateTime.
    Datetime.TimestampTZ.Modifier<T>
    Functional interface to obtain information from the PostgreSQL type modifier applied to the type.
    Datetime.TimeTZ<T>
    The TIMETZ type's PostgreSQL semantics: microseconds since midnight, accompanied by a time zone offset expressed in seconds.
    Datetime.TimeTZ.AsOffsetTime
    A reference implementation that maps to OffsetTime.
    Datetime.TimeTZ.Modifier<T>
    Functional interface to obtain information from the PostgreSQL type modifier applied to the type.
    Geometric
    Container for abstract-type functional interfaces in PostgreSQL's GEOMETRIC type category.
    Geometric.Box<T,I>
    The BOX type's PostgreSQL semantics: two corner points.
    Geometric.Circle<T,I>
    The CIRCLE type's PostgreSQL semantics: center point and radius.
    Geometric.Line<T>
    The LINE type's PostgreSQL semantics: coefficients of its general equation Ax+By+C=0.
    Geometric.LSeg<T,I>
    The LSEG type's PostgreSQL semantics: two endpoints.
    Geometric.Path<T,I>
    The PATH type's PostgreSQL semantics: vertex points and whether closed.
    Geometric.Point<T>
    The POINT type's PostgreSQL semantics: a pair of float8 coordinates.
    Geometric.Polygon<T,I1,I2>
    The POLYGON type's PostgreSQL semantics: vertex points and a bounding box.
    Internal
    Container for abstract-type functional interfaces, not quite exactly corresponding to PostgreSQL's INTERNAL category; there are some fairly "internal" types that ended up in the USER category too, for whatever reason.
    Internal.Tid<T>
    The tid type's PostgreSQL semantics: a block ID and a row index within that block.
    Money<T>
    The MONEY type's PostgreSQL semantics: an integer value, whose scaling, display format, and currency are all determined by a user-settable configuration setting.
    Network
    Container for abstract-type functional interfaces in PostgreSQL's NETWORK type category (and MAC addresses, which, for arcane reasons, are not in that category).
    Network.Inet<T>
    The INET and CIDR types' PostgreSQL semantics: the family (INET or INET6), the number of network prefix bits, and the address bytes in network byte order.
    Network.MAC<T>
    The macaddr and macaddr8 types' PostgreSQL semantics: a byte array (6 or 8 bytes, respectively)., of which byte 0 is the one appearing first in the text representation (and stored in the member named a of the C struct).
    Numeric<T>
    The NUMERIC type's PostgreSQL semantics: a sign (or indication that the value is NaN, + infinity, or - infinity), a display scale, a weight, and zero or more base-ten-thousand digits.
    Numeric.AsBigDecimal
    A reference implementation that maps to BigDecimal (but cannot represent all possible values).
    Numeric.Kind
    Label to distinguish positive, negative, and three kinds of special values.
    Numeric.Modifier<T>
    Functional interface to obtain information from the PostgreSQL type modifier applied to the type.
    Timespan
    Container for abstract-type functional interfaces in PostgreSQL's TIMESPAN type category (which, at present, includes the single type INTERVAL).
    Timespan.Interval<T>
    The INTERVAL type's PostgreSQL semantics: separate microseconds, days, and months components, independently signed.
    Timespan.Interval.Field
     
    Timespan.Interval.Modifier<T>
    Functional interface to obtain information from the PostgreSQL type modifier applied to the type.