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

Class Adapter<T,U>

java.lang.Object
org.postgresql.pljava.Adapter<T,U>
All Implemented Interfaces:
SlotTester.Visible
Direct Known Subclasses:
Adapter.As, Adapter.Container, Adapter.Primitive
public abstract class Adapter<T,U> extends Object implements SlotTester.Visible
Base for classes that implement data types over raw PostgreSQL datums.

A PL/Java data type adapter is a concrete subclass of this class that knows the structure of one or more PostgreSQL data types and can convert between their raw Datum form and an appropriate Java class or primitive type for use in PL/Java code. It will use the Via... enum declared here (to indicate how it will access the PostgreSQL Datum), and extend an As... abstract class declared here (to indicate the supported Java reference or primitive type).

An adapter should be stateless and thread-safe. There should be no need to instantiate more than one instance of an adapter for a given type mapping.

An adapter has a "top" type T, indicating the type it will present to client code, and an "under" type U, which client code can generally wildcard and ignore; an implementing class that can be composed over another adapter uses U to indicate what that "under" adapter's "top" type must be. The Java compiler records enough information for both parameters to allow PL/Java to reconstruct the type relationships in a stack of composed adapters.

An implementing leaf adapter (which will work directly on PostgreSQL Datum rather than being composed over another adapter) can declare Void for U by convention. An adapter meant to be composed over another, where the "under" adapter has a primitive type, can declare the primitive type's boxed counterpart as U.

For a primitive-typed adapter, the "top" type is implicit in the class name AsLong, AsInt, and so on, and the "under" type follows as the parameter U. For ease of reading, the type parameters of the two-parameter classes like As<T,U> are also in that order, T first.

The precise meaning of the "top" type T depends on whether an adapter is an instance of As<T,U> or of Primitive<T,U>. In the As case, the top type is a reference type and is given by T directly. In the primitive case, T is the boxed counterpart of the actual top type.

To preserve type safety, only recognized "leaf" adapters (those registered to configure with a non-null via) will be able to manipulate raw Datums. An adapter class should avoid leaking a Datum to other code.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Adapter.AdapterException
    A lightweight unchecked exception used to wrap checked ones (often SQLException) in settings where checked ones are a bother.
    static class 
    Adapter.Array<T>
    Abstract supertype of array adapters.
    static final class 
    Adapter.ArrayBuilder<TA,TI>
    Builder to derive properly-typed array adapters of various dimensionalities, first obtained from an Adapter.ArrayProto.
    static interface 
    Adapter.ArrayProto<TA>
    Mixin allowing properly-typed array adapters of various dimensionalities to be derived from an adapter for the array component type.
    static class 
    Adapter.As<T,U>
    Superclass for adapters that fetch something and return it as a reference type T.
    static class 
    Adapter.AsBoolean<U>
    Abstract superclass of primitive boolean adapters.
    static class 
    Adapter.AsByte<U>
    Abstract superclass of signed and unsigned primitive byte adapters.
    static class 
    Adapter.AsChar<U>
    Abstract superclass of primitive char adapters.
    static class 
    Adapter.AsDouble<U>
    Abstract superclass of primitive double adapters.
    static class 
    Adapter.AsFloat<U>
    Abstract superclass of primitive float adapters.
    static class 
    Adapter.AsInt<U>
    Abstract superclass of signed and unsigned primitive int adapters.
    static class 
    Adapter.AsLong<U>
    Abstract superclass of signed and unsigned primitive long adapters.
    static class 
    Adapter.AsShort<U>
    Abstract superclass of signed and unsigned primitive short adapters.
    protected static class 
    Adapter.Configuration
    A class that is returned by the configure method, intended for use during an Adapter subclass's static initialization, and must be supplied to the constructor when instances of the class are created.
    static class 
    Adapter.Container
    Provided to serve as a superclass for a 'container' class that is used to group several related adapters without being instantiable as an adapter itself.
    static interface 
    Adapter.Contract<T>
    A marker interface to be extended by functional interfaces that serve as ADT contracts.
    static interface 
    Adapter.Dispenser<T,U extends Adapter.Contract<T>>
    Functional interface able to dispense one instance of an ADT by passing its constituent values to a supplied Contract and returning whatever that returns.
    static final class 
    Adapter.Opaque
    An Adapter that reports it can be used on any type, but cannot fetch anything.
    static final class 
    Adapter.Permission
    A permission allowing the creation of a leaf Adapter.
    static class 
    Adapter.Primitive<T,U,TA>
    Ancestor class for adapters that fetch something and return it as a Java primitive type.
    static interface 
    Adapter.PullDispenser<T,U extends Adapter.Contract<T>>
    Functional interface able to dispense multiple instances of an ADT identified by a zero-based index, passing the its constituent values to a supplied Contract and returning whatever that returns.
    static class 
    Adapter.Service
    Specification of a service supplied by the internals module for certain operations, such as specially instantiating array adapters based on ArrayBuilders constructed here.
    protected static enum 
    Adapter.Via
    Specifies, for a leaf adapter (one not composed over a lower adapter), the form in which the value fetched from PostgreSQL will be presented to it (or how it will produce a value to be stored to PostgreSQL).

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    canFetch(Attribute attr)
    Method that an Adapter may override to indicate whether it is capable of fetching a given PostgreSQL attribute.
    boolean
    canFetch(RegType pgType)
    Method that a leaf Adapter must implement to indicate whether it is capable of fetching a given PostgreSQL type.
    abstract boolean
    canFetchNull()
    Method that an Adapter must implement to indicate whether it is capable of returning some usable representation of SQL null values.
    protected static Adapter.Configuration
    configure(Class<? extends Adapter> cls, Adapter.Via via)
    Method that must be called in static initialization of an Adapter subclass, producing a Configuration object that must be passed to the constructor when creating an instance.
    Type
    topType()
    The full generic Type this Adapter presents to Java.
    static Type
    topType(Class<? extends Adapter> cls)
    A static method to indicate the type returned by a given Adapter subclass, based only on the type information recorded for it by the Java compiler.
    String
    toString()
     
    static Type
    underType(Class<? extends Adapter> cls)
    A static method to indicate the "under" type expected by a given Adapter subclass that is intended for composition over another adapter, based only on the type information recorded for it by the Java compiler.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Method Details

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • canFetch

      public boolean canFetch(RegType pgType)
      Method that a leaf Adapter must implement to indicate whether it is capable of fetching a given PostgreSQL type.

      In a composing adapter, this default implementation delegates to the adapter beneath.

      Throws:
      UnsupportedOperationException - if called in a leaf adapter

    • canFetch

      public boolean canFetch(Attribute attr)
      Method that an Adapter may override to indicate whether it is capable of fetching a given PostgreSQL attribute.

      If not overridden, this implementation delegates to the adapter beneath, if composed; in a leaf adapter, it delegates to canFetch for the attribute's declared PostgreSQL type.

    • canFetchNull

      public abstract boolean canFetchNull()
      Method that an Adapter must implement to indicate whether it is capable of returning some usable representation of SQL null values.

      An Adapter that cannot should only be used with values that are known never to be null; it will throw an exception if asked to fetch a value that is null.

      An adapter usable with null values can be formed by composing, for example, an adapter producing Optional over an adapter that cannot fetch nulls.

    • topType

      public static Type topType(Class<? extends Adapter> cls)
      A static method to indicate the type returned by a given Adapter subclass, based only on the type information recorded for it by the Java compiler.

      The type returned could contain free type variables that may be given concrete values when the instance topType method is called on a particular instance of the class.

      When cls is a subclass of Primitive, this method returns the Class object for the actual primitive type, not the boxed type.

    • topType

      public Type topType()
      The full generic Type this Adapter presents to Java.

      Unlike the static method, this instance method, on an adapter formed by composition, returns the actual type obtained by unifying the "under" adapter's top type with the top adapter's "under" type, then making the indicated substitutions in the top adapter's "top" type.

      Likewise, for an adapter constructed with an array contract and an adapter for the element type, the element adapter's "top" type is unified with the contract's element type, and this method returns the contract's result type with the same substitutions made.

    • underType

      public static Type underType(Class<? extends Adapter> cls)
      A static method to indicate the "under" type expected by a given Adapter subclass that is intended for composition over another adapter, based only on the type information recorded for it by the Java compiler.

      The type returned could contain free type variables.

    • configure

      protected static Adapter.Configuration configure(Class<? extends Adapter> cls, Adapter.Via via)
      Method that must be called in static initialization of an Adapter subclass, producing a Configuration object that must be passed to the constructor when creating an instance.

      If the adapter class is in a named module, its containing package must be exported to at least org.postgresql.pljava.

      When a leaf adapter (one that does not compose over some other adapter, but acts directly on PostgreSQL datums) is configured, the necessary Permission is checked.

      Parameters:
      cls - The Adapter subclass being configured.
      via - null for a composing (non-leaf) adapter; otherwise a value of the Adapter.Via enumeration, indicating how the underlying PostgreSQL datum will be presented to the adapter.
      Throws:
      SecurityException - if the class being configured represents a leaf adapter and the necessary permission is not held.