- All Implemented Interfaces:
SlotTester.Visible
- Direct Known Subclasses:
Adapter.As
,Adapter.Container
,Adapter.Primitive
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 Datum
s. An adapter class
should avoid leaking a Datum
to other code.
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
A lightweight unchecked exception used to wrap checked ones (oftenSQLException
) in settings where checked ones are a bother.static class
Abstract supertype of array adapters.static final class
Builder to derive properly-typed array adapters of various dimensionalities, first obtained from anAdapter.ArrayProto
.static interface
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
Abstract superclass of primitiveboolean
adapters.static class
Abstract superclass of signed and unsigned primitivebyte
adapters.static class
Abstract superclass of primitivechar
adapters.static class
Abstract superclass of primitivedouble
adapters.static class
Abstract superclass of primitivefloat
adapters.static class
Abstract superclass of signed and unsigned primitiveint
adapters.static class
Abstract superclass of signed and unsigned primitivelong
adapters.static class
Abstract superclass of signed and unsigned primitiveshort
adapters.protected static class
A class that is returned by theconfigure
method, intended for use during anAdapter
subclass's static initialization, and must be supplied to the constructor when instances of the class are created.static class
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
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 suppliedContract
and returning whatever that returns.static final class
A permission allowing the creation of a leafAdapter
.static class
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 suppliedContract
and returning whatever that returns.static class
Specification of a service supplied by the internals module for certain operations, such as specially instantiating array adapters based onArrayBuilder
s constructed here.protected static enum
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 TypeMethodDescriptionboolean
Method that anAdapter
may override to indicate whether it is capable of fetching a given PostgreSQL attribute.boolean
Method that a leafAdapter
must implement to indicate whether it is capable of fetching a given PostgreSQL type.abstract boolean
Method that anAdapter
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 anAdapter
subclass, producing aConfiguration
object that must be passed to the constructor when creating an instance.topType()
The full genericType
this Adapter presents to Java.static Type
A static method to indicate the type returned by a givenAdapter
subclass, based only on the type information recorded for it by the Java compiler.toString()
static Type
A static method to indicate the "under" type expected by a givenAdapter
subclass that is intended for composition over another adapter, based only on the type information recorded for it by the Java compiler.
-
Method Details
-
toString
-
canFetch
Method that a leafAdapter
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
Method that anAdapter
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 anAdapter
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
A static method to indicate the type returned by a givenAdapter
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 theClass
object for the actual primitive type, not the boxed type. -
topType
The full genericType
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
A static method to indicate the "under" type expected by a givenAdapter
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
Method that must be called in static initialization of anAdapter
subclass, producing aConfiguration
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 theAdapter.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.
-