Module org.postgresql.pljava.internal

Package org.postgresql.pljava.internal

Interface Checked<WT,EX extends Throwable>

Type Parameters:

WT - The type this functional interface can be wrapped as by ederWrap(), which may be a corresponding Java functional interface that does not allow checked exceptions.

EX - The checked exception type (or least upper bound of the checked exception types) that the body of this functional interface may throw.

All Known Subinterfaces:

Checked.BiConsumer<T,U,E>, Checked.BooleanConsumer<E>, Checked.BooleanSupplier<E>, Checked.ByteConsumer<E>, Checked.ByteSupplier<E>, Checked.CharConsumer<E>, Checked.CharSupplier<E>, org.postgresql.pljava.internal.Checked.Closing.Trivial<WT,EX>, Checked.Consumer<T,E>, Checked.DoubleConsumer<E>, Checked.DoubleSupplier<E>, Checked.FloatConsumer<E>, Checked.FloatSupplier<E>, Checked.Function<T,R,E>, Checked.IntConsumer<E>, Checked.IntSupplier<E>, Checked.LongConsumer<E>, Checked.LongSupplier<E>, Checked.Predicate<T,E>, Checked.Runnable<E>, Checked.ShortConsumer<E>, Checked.ShortSupplier<E>, Checked.Supplier<T,E>, Checked.ToByteFunction<T,E>, Checked.ToCharFunction<T,E>, Checked.ToDoubleFunction<T,E>, Checked.ToFloatFunction<T,E>, Checked.ToIntFunction<T,E>, Checked.ToLongFunction<T,E>, Checked.ToShortFunction<T,E>

public interface Checked<WT,EX extends Throwable>

Functional interfaces handling checked exceptions.

It would be ideal if the compiler could preserve its union of possible thrown types as the inferred exception type of the functional interface method. Instead, it collapses the union to the nearest common supertype, which is less useful, as it becomes Exception rather quickly if the lambda can throw a few unrelated exceptions. It is still useful for short lambdas that throw only a few related exceptions.

Also, the Java API lacks primitive Consumer/Supplier/Optional types for byte, short, char, float, and some of them for boolean. To allow a more orthogonal API for access to datum values, those are provided here, again supporting checked exceptions. Because these "bonus" types do not have checked-exception-less counterparts in the Java API, they do not strictly need the wrapper methods described next.

For interoperating with Java APIs that require the Java no-checked-exceptions versions of these interfaces, each checked interface here (for which a Java API no-checked version exists) has an ederWrap method that produces the Java no-checked version of the same interface, using a lightweight idiom advanced by Lukas Eder, developer of jOOλ. The checked exception is not wrapped, but simply flown under javac's radar. That idiom is extended here with a corresponding in method to pass the wrapped interface into code that requires it, re-exposing the checked exception type. That makes possible constructions like:

 Stream<String> strs = ...;
 Writer w = ...;
 try {
   Checked.Consumer.use((String s) -> w.write(s)) // throws IOException!
     .in(c -> strs.forEach(c));
 }
 catch ( IOException e ) { ... }

where the Stream.forEach method requires a Java Consumer that declares no checked exceptions.

Such an idiom is, of course, contrary to an SEI CERT coding standard, and likely to produce surprises if the exception will be 'flown' through deep layers of code by others that may contain catch blocks. That said, as a convenience for dealing with checked exceptions and simple Java APIs that cannot accept them, it can be useful as long as the intervening code through which the exception may be 'flown' is simple and short.

The functional interfaces defined here that do not correspond to a Java API no-checked version, while not strictly needing an ederWrap method, have one anyway, a no-op identity function. That avoids arbitrary limits on which ones can participate in the use(...).in(...) idiom.

Static composed() methods are provided here in place of the instance compose or andThen methods in Java's function API, which seem to challenge javac's type inference when exception types are thrown in. A static composed method can substitute for compose or andThen, by ordering the parameters as desired. Likewise, static and and or methods are provided in place of the instance methods on Java's Predicate.

Each functional interface declared here has a static use(...) method that can serve, as a concise alternative to casting, to constrain the type of a lambda expression when the compiler won't infer it.

A variant of AutoCloseable with an exception-type parameter, and some closing methods (inspired by Python, for use with resources that do not already implement AutoCloseable), are also provided.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Checked.AutoCloseable<E extends Exception>	Version of AutoCloseable with an exception-type parameter.
static interface	Checked.BiConsumer<T,U,E extends Throwable>	Like BiConsumer but with a body that can throw checked exceptions.
static interface	Checked.BooleanConsumer<E extends Throwable>	Represents an operation that accepts a single boolean-valued argument and can throw checked exceptions.
static interface	Checked.BooleanSupplier<E extends Throwable>	Like BooleanSupplier but with a body that can throw checked exceptions.
static interface	Checked.ByteConsumer<E extends Throwable>	Represents an operation that accepts a single byte-valued argument and can throw checked exceptions.
static interface	Checked.ByteSupplier<E extends Throwable>	A supplier of byte-valued results, with a body that can throw checked exceptions.
static interface	Checked.CharConsumer<E extends Throwable>	Represents an operation that accepts a single char-valued argument and can throw checked exceptions.
static interface	Checked.CharSupplier<E extends Throwable>	A supplier of char-valued results, with a body that can throw checked exceptions.
static class	Checked.Closing<T,E extends Exception>	A class that can supply a T while also implementing AutoCloseable<E>; suitable for use in a try-with-resources to wrap some value that does not itself implement AutoCloseable.
static interface	Checked.Consumer<T,E extends Throwable>	Like Consumer but with a body that can throw checked exceptions.
static interface	Checked.DoubleConsumer<E extends Throwable>	Like DoubleConsumer but with a body that can throw checked exceptions.
static interface	Checked.DoubleSupplier<E extends Throwable>	Like DoubleSupplier but with a body that can throw checked exceptions.
static interface	Checked.FloatConsumer<E extends Throwable>	Represents an operation that accepts a single float-valued argument and can throw checked exceptions.
static interface	Checked.FloatSupplier<E extends Throwable>	A supplier of float-valued results, with a body that can throw checked exceptions.
static interface	Checked.Function<T,R,E extends Throwable>	Like Function but with a body that can throw checked exceptions.
static interface	Checked.IntConsumer<E extends Throwable>	Like IntConsumer but with a body that can throw checked exceptions.
static interface	Checked.IntSupplier<E extends Throwable>	Like IntSupplier but with a body that can throw checked exceptions.
static interface	Checked.LongConsumer<E extends Throwable>	Like LongConsumer but with a body that can throw checked exceptions.
static interface	Checked.LongSupplier<E extends Throwable>	Like LongSupplier but with a body that can throw checked exceptions.
static class	Checked.OptionalBase	Head of a family of Optional-like types covering the Java primitives that the java.util.Optional... classes do not cover, and whose methods that expect functional interfaces will accept the checked-exception versions declared here.
static class	Checked.OptionalBoolean	A container object which may or may not contain a boolean value.
static class	Checked.OptionalByte	A container object which may or may not contain a byte value.
static class	Checked.OptionalChar	A container object which may or may not contain a char value.
static class	Checked.OptionalFloat	A container object which may or may not contain a float value.
static class	Checked.OptionalShort	A container object which may or may not contain a short value.
static interface	Checked.Predicate<T,E extends Throwable>	Like Predicate but with a body that can throw checked exceptions.
static interface	Checked.Runnable<E extends Throwable>	Like Runnable but with a body that can throw checked exceptions.
static interface	Checked.ShortConsumer<E extends Throwable>	Represents an operation that accepts a single short-valued argument and can throw checked exceptions.
static interface	Checked.ShortSupplier<E extends Throwable>	A supplier of short-valued results, with a body that can throw checked exceptions.
static interface	Checked.Supplier<T,E extends Throwable>	Like Supplier but with a body that can throw checked exceptions.
static interface	Checked.ToByteFunction<T,E extends Throwable>	Represents a function that produces a byte-valued result and can throw checked exceptions.
static interface	Checked.ToCharFunction<T,E extends Throwable>	Represents a function that produces a char-valued result and can throw checked exceptions.
static interface	Checked.ToDoubleFunction<T,E extends Throwable>	Like ToDoubleFunction but with a body that can throw checked exceptions.
static interface	Checked.ToFloatFunction<T,E extends Throwable>	Represents a function that produces a float-valued result and can throw checked exceptions.
static interface	Checked.ToIntFunction<T,E extends Throwable>	Like ToIntFunction but with a body that can throw checked exceptions.
static interface	Checked.ToLongFunction<T,E extends Throwable>	Like ToLongFunction but with a body that can throw checked exceptions.
static interface	Checked.ToShortFunction<T,E extends Throwable>	Represents a function that produces a short-valued result and can throw checked exceptions.

Method Summary

Modifier and Type	Method	Description
static <T, E extends Throwable> Checked.Predicate<T,E>	and(Checked.Predicate<? super T,? extends E> first, Checked.Predicate<? super T,? extends E> after)	Returns a Predicate that is the short-circuiting AND of two others.
static <E extends Exception> Checked.AutoCloseable<E>	closing(Checked.AutoCloseable<E> o)	Returns its argument; shorthand for casting a suitable lambda to AutoCloseable<E>.
static <T, S extends BaseStream<T, S>, E extends Exception> Checked.Closing<S,E>	closing(S stream, Checked.Runnable<E> closer)	Given a stream and a lambda that should be invoked when it is closed, construct a new stream that runs that lambda when closed, and return a Closing instance with the new stream as its payload, which will be closed by the close action.
static <T, E extends Exception> Checked.Closing<T,E>	closing(T payload, Checked.AutoCloseable<E> closer)	Wrap some payload and a 'closer' lambda as a Closing instance that can supply the payload and implements AutoCloseable using the lambda; useful in a try-with-resources when the payload itself does not implement AutoCloseable.
static <T, U, E extends Throwable> Checked.BiConsumer<T,U,E>	composed(Checked.BiConsumer<? super T,? super U,? extends E> first, Checked.BiConsumer<? super T,? super U,? extends E> after)	Returns a BiConsumer that is the composition of two others.
static <T, E extends Throwable> Checked.Consumer<T,E>	composed(Checked.Consumer<? super T,? extends E> first, Checked.Consumer<? super T,? extends E> after)	Returns a Consumer that is the composition of two others.
static <E extends Throwable> Checked.DoubleConsumer<E>	composed(Checked.DoubleConsumer<? extends E> first, Checked.DoubleConsumer<? extends E> after)	Returns a DoubleConsumer that is the composition of two others.
static <T, R, V, E extends Throwable> Checked.Function<T,R,E>	composed(Checked.Function<? super T,? extends V,? extends E> first, Checked.Function<? super V,? extends R,? extends E> after)	Returns a Function that is the composition of two others.
static <E extends Throwable> Checked.IntConsumer<E>	composed(Checked.IntConsumer<? extends E> first, Checked.IntConsumer<? extends E> after)	Returns an IntConsumer that is the composition of two others.
static <E extends Throwable> Checked.LongConsumer<E>	composed(Checked.LongConsumer<? extends E> first, Checked.LongConsumer<? extends E> after)	Returns a LongConsumer that is the composition of two others.
static <E extends Throwable> E	ederThrow(Throwable t)	Throw an exception, unsafely cast to a different exception type, chiefly as used by Lukas Eder to fly a checked exception through a section of code that does not accept it.
WT	ederWrap()	Wraps this Checked functional interfaces as its corresponding Java functional interface WT, which possibly does not allow checked exceptions.
default <RX extends Throwable> void	in(Checked.Consumer<? super WT,RX> c)	Passes this functional interface, wrapped as its wrapper type WT, into a code body that requires that wrapper type, while remembering for the compiler the checked exception type that may, in fact, be thrown.
default <RX extends Throwable> boolean	inBooleanReturning(Checked.Predicate<? super WT,RX> f)	Like in(...) but where the body returns a boolean.
default <RX extends Throwable> byte	inByteReturning(Checked.ToByteFunction<? super WT,RX> f)	Like in(...) but where the body returns a byte.
default <RX extends Throwable> char	inCharReturning(Checked.ToCharFunction<? super WT,RX> f)	Like in(...) but where the body returns a char.
default <RX extends Throwable> double	inDoubleReturning(Checked.ToDoubleFunction<? super WT,RX> f)	Like in(...) but where the body returns a double.
default <RX extends Throwable> float	inFloatReturning(Checked.ToFloatFunction<? super WT,RX> f)	Like in(...) but where the body returns a float.
default <RX extends Throwable> int	inIntReturning(Checked.ToIntFunction<? super WT,RX> f)	Like in(...) but where the body returns an int.
default <RX extends Throwable> long	inLongReturning(Checked.ToLongFunction<? super WT,RX> f)	Like in(...) but where the body returns a long.
default <RT, RX extends Throwable> RT	inReturning(Checked.Function<? super WT,RT,RX> f)	Like in(...) but where the body returns a non-primitive type.
default <RX extends Throwable> short	inShortReturning(Checked.ToShortFunction<? super WT,RX> f)	Like in(...) but where the body returns a short.
static <T, E extends Throwable> Checked.Predicate<T,E>	or(Checked.Predicate<? super T,? extends E> first, Checked.Predicate<? super T,? extends E> after)	Returns a Predicate that is the short-circuiting OR of two others.

Method Details

ederThrow

static <E extends Throwable> E ederThrow(Throwable t)
                                  throws E

Throw an exception, unsafely cast to a different exception type, chiefly as used by Lukas Eder to fly a checked exception through a section of code that does not accept it.

In PL/Java, this method is not intended to be called directly, but used transparently within the in(...) construct, which re-exposes the checked exception type EX to the compiler.

Type Parameters:

E - The throwable type the argument t should be presented as.

Parameters:

t - A throwable.

Throws:

E - The argument t, represented to the compiler as of type E.

ederWrap

WT ederWrap()

Wraps this Checked functional interfaces as its corresponding Java functional interface WT, which possibly does not allow checked exceptions.

Checked exceptions of type EX may still, in reality, be thrown. This method is not intended to be called directly; it is used transparently by in(...), which passes the wrapper type into code that requires it, but re-exposes the original checked exception type to the compiler.

in

default <RX extends Throwable> void in(Checked.Consumer<? super WT,RX> c)
                                throws EX,
RX

Passes this functional interface, wrapped as its wrapper type WT, into a code body that requires that wrapper type, while remembering for the compiler the checked exception type that may, in fact, be thrown.

Type Parameters:

RX - Any exception type that the body, c, detectably can throw.

Parameters:

c - A Consumer to which this instance, wrapped as its corresponding functional interface WT, will be passed.

Throws:

EX - whatever can be thrown by the body of this instance

RX - whatever can be thrown by the body c.

inReturning

default <RT,
RX extends Throwable> RT inReturning(Checked.Function<? super WT,RT,RX> f)
                                           throws EX,
RX

Like in(...) but where the body returns a non-primitive type.

Type Parameters:

RT - Return type of the body f.

RX - Any exception type that the body, f, detectably can throw.

Parameters:

f - A ToDoubleFunction to which this instance, wrapped as its corresponding functional interface WT, will be passed.

Throws:

EX - whatever can be thrown by the body of this instance

RX - whatever can be thrown by the body f.

inDoubleReturning

default <RX extends Throwable> double inDoubleReturning(Checked.ToDoubleFunction<? super WT,RX> f)
                                                 throws EX,
RX

Like in(...) but where the body returns a double.

Type Parameters:

RX - Any exception type that the body, f, detectably can throw.

Parameters:

f - A ToDoubleFunction to which this instance, wrapped as its corresponding functional interface WT, will be passed.

Throws:

EX - whatever can be thrown by the body of this instance

RX - whatever can be thrown by the body f.

inIntReturning

default <RX extends Throwable> int inIntReturning(Checked.ToIntFunction<? super WT,RX> f)
                                           throws EX,
RX

Like in(...) but where the body returns an int.

Type Parameters:

RX - Any exception type that the body, f, detectably can throw.

Parameters:

f - A ToIntFunction to which this instance, wrapped as its corresponding functional interface WT, will be passed.

Throws:

EX - whatever can be thrown by the body of this instance

RX - whatever can be thrown by the body f.

inLongReturning

default <RX extends Throwable> long inLongReturning(Checked.ToLongFunction<? super WT,RX> f)
                                             throws EX,
RX

Like in(...) but where the body returns a long.

Type Parameters:

RX - Any exception type that the body, f, detectably can throw.

Parameters:

f - A ToLongFunction to which this instance, wrapped as its corresponding functional interface WT, will be passed.

Throws:

EX - whatever can be thrown by the body of this instance

RX - whatever can be thrown by the body f.

inBooleanReturning

default <RX extends Throwable> boolean inBooleanReturning(Checked.Predicate<? super WT,RX> f)
                                                   throws EX,
RX

Like in(...) but where the body returns a boolean.

Type Parameters:

RX - Any exception type that the body, f, detectably can throw.

Parameters:

f - A Predicate to which this instance, wrapped as its corresponding functional interface WT, will be passed.

Throws:

EX - whatever can be thrown by the body of this instance

RX - whatever can be thrown by the body f.

inByteReturning

default <RX extends Throwable> byte inByteReturning(Checked.ToByteFunction<? super WT,RX> f)
                                             throws EX,
RX

Like in(...) but where the body returns a byte.

This method is provided for consistency of notation, even though it is not strictly needed because Java has no checked-exception-less counterpart of ToByteFunction.

Type Parameters:

RX - Any exception type that the body, f, detectably can throw.

Parameters:

f - A ToByteFunction to which this instance, wrapped as its corresponding functional interface WT, will be passed.

Throws:

EX - whatever can be thrown by the body of this instance

RX - whatever can be thrown by the body f.

inShortReturning

default <RX extends Throwable> short inShortReturning(Checked.ToShortFunction<? super WT,RX> f)
                                               throws EX,
RX

Like in(...) but where the body returns a short.

This method is provided for consistency of notation, even though it is not strictly needed because Java has no checked-exception-less counterpart of ToShortFunction.

Type Parameters:

RX - Any exception type that the body, f, detectably can throw.

Parameters:

f - A ToShortFunction to which this instance, wrapped as its corresponding functional interface WT, will be passed.

Throws:

EX - whatever can be thrown by the body of this instance

RX - whatever can be thrown by the body f.

inCharReturning

default <RX extends Throwable> char inCharReturning(Checked.ToCharFunction<? super WT,RX> f)
                                             throws EX,
RX

Like in(...) but where the body returns a char.

This method is provided for consistency of notation, even though it is not strictly needed because Java has no checked-exception-less counterpart of ToCharFunction.

Type Parameters:

RX - Any exception type that the body, f, detectably can throw.

Parameters:

f - A ToCharFunction to which this instance, wrapped as its corresponding functional interface WT, will be passed.

Throws:

EX - whatever can be thrown by the body of this instance

RX - whatever can be thrown by the body f.

inFloatReturning

default <RX extends Throwable> float inFloatReturning(Checked.ToFloatFunction<? super WT,RX> f)
                                               throws EX,
RX

Like in(...) but where the body returns a float.

This method is provided for consistency of notation, even though it is not strictly needed because Java has no checked-exception-less counterpart of ToFloatFunction.

Type Parameters:

RX - Any exception type that the body, f, detectably can throw.

Parameters:

f - A ToFloatFunction to which this instance, wrapped as its corresponding functional interface WT, will be passed.

Throws:

EX - whatever can be thrown by the body of this instance

RX - whatever can be thrown by the body f.

and

static <T,
E extends Throwable>
Checked.Predicate<T,E> and(Checked.Predicate<? super T,? extends E> first,
 Checked.Predicate<? super T,? extends E> after)

Returns a Predicate that is the short-circuiting AND of two others.

Type Parameters:

T - Greatest-lower-bound parameter type acceptable to first and after, and the parameter type of the resulting predicate.

E - Least upper bound of the exception types thrown by first and after, representing the exception types thrown by the resulting predicate.

Parameters:

first - The predicate to be tested first.

after - The predicate to be tested next.

or

static <T,
E extends Throwable>
Checked.Predicate<T,E> or(Checked.Predicate<? super T,? extends E> first,
 Checked.Predicate<? super T,? extends E> after)

Returns a Predicate that is the short-circuiting OR of two others.

Type Parameters:

T - Greatest-lower-bound parameter type acceptable to first and after, and the parameter type of the resulting predicate.

E - Least upper bound of the exception types thrown by first and after, representing the exception types thrown by the resulting predicate.

Parameters:

first - The predicate to be tested first.

after - The predicate to be tested next.

composed

static <T,
R,
V,
E extends Throwable>
Checked.Function<T,R,E> composed(Checked.Function<? super T,? extends V,? extends E> first,
 Checked.Function<? super V,? extends R,? extends E> after)

Returns a Function that is the composition of two others.

Type Parameters:

T - Parameter type of the resulting function, and acceptable as parameter of first.

R - Return type of the composed function, subsuming the return type of after.

V - Type subsuming the return type of first, and acceptable as parameter of after.

E - Least upper bound of the exception types thrown by first and after, representing the exception types thrown by the resulting function.

Parameters:

first - The first function to be applied.

after - The function applied to the result of first.

composed

static <T,
U,
E extends Throwable>
Checked.BiConsumer<T,U,E> composed(Checked.BiConsumer<? super T,? super U,? extends E> first,
 Checked.BiConsumer<? super T,? super U,? extends E> after)

Returns a BiConsumer that is the composition of two others.

Type Parameters:

T - First parameter type of the resulting BiConsumer, acceptable as first parameter to both first and after.

U - Second parameter type of the resulting BiConsumer, acceptable as second parameter to both first and after.

E - Least upper bound of the exception types thrown by first and after, representing the exception types thrown by the resulting biconsumer.

Parameters:

first - The first consumer to be applied.

after - The consumer next applied to the same inputs.

composed

static <T,
E extends Throwable>
Checked.Consumer<T,E> composed(Checked.Consumer<? super T,? extends E> first,
 Checked.Consumer<? super T,? extends E> after)

Returns a Consumer that is the composition of two others.

Type Parameters:

T - Parameter type of the resulting Consumer, acceptable as parameter to both first and after.

E - Least upper bound of the exception types thrown by first and after, representing the exception types thrown by the resulting consumer.

Parameters:

first - The first consumer to be applied.

after - The consumer next applied to the same input.

composed

static <E extends Throwable>
Checked.DoubleConsumer<E> composed(Checked.DoubleConsumer<? extends E> first,
 Checked.DoubleConsumer<? extends E> after)

Returns a DoubleConsumer that is the composition of two others.

Type Parameters:

E - Least upper bound of the exception types thrown by first and after, representing the exception types thrown by the resulting consumer.

Parameters:

first - The first consumer to be applied.

after - The consumer next applied to the same input.

composed

static <E extends Throwable> Checked.IntConsumer<E> composed(Checked.IntConsumer<? extends E> first,
 Checked.IntConsumer<? extends E> after)

Returns an IntConsumer that is the composition of two others.

Type Parameters:

E - Least upper bound of the exception types thrown by first and after, representing the exception types thrown by the resulting consumer.

Parameters:

first - The first consumer to be applied.

after - The consumer next applied to the same input.

composed

static <E extends Throwable>
Checked.LongConsumer<E> composed(Checked.LongConsumer<? extends E> first,
 Checked.LongConsumer<? extends E> after)

Returns a LongConsumer that is the composition of two others.

Type Parameters:

E - Least upper bound of the exception types thrown by first and after, representing the exception types thrown by the resulting consumer.

Parameters:

first - The first consumer to be applied.

after - The consumer next applied to the same input.

closing

static <E extends Exception>
Checked.AutoCloseable<E> closing(Checked.AutoCloseable<E> o)

Returns its argument; shorthand for casting a suitable lambda to AutoCloseable<E>.

Where some resource does not itself implement AutoCloseable, an idiom like the following, inspired by Python, can be used in Java 10 or later, and the compiler will infer that it can throw whatever thing.release() can throw:

  try(var ac = closing(() -> { thing.release(); }))
  {
    ...
  }

Pre-Java 10, without var, you have to specify the exception type, but you still get the simple idiom without needing to declare some new interface:

  try(Checked.AutoCloseable<ThingException> ac =
                closing(() -> { thing.release(); }))
  {
    ...
  }

Type Parameters:

E - Least upper bound of exceptions that can be thrown by o

Parameters:

o - Lambda or method reference to serve as the close operation.

closing

static <T,
E extends Exception>
Checked.Closing<T,E> closing(T payload,
 Checked.AutoCloseable<E> closer)

Wrap some payload and a 'closer' lambda as a Closing instance that can supply the payload and implements AutoCloseable using the lambda; useful in a try-with-resources when the payload itself does not implement AutoCloseable.

Type Parameters:

T - Type of the payload.

E - Least upper bound of exceptions that may be thrown at close.

Parameters:

payload - Any object.

closer - Lambda or method reference to serve as the close operation.

closing

static <T,
S extends BaseStream<T,
S>,
E extends Exception>
Checked.Closing<S,E> closing(S stream,
 Checked.Runnable<E> closer)

Given a stream and a lambda that should be invoked when it is closed, construct a new stream that runs that lambda when closed, and return a Closing instance with the new stream as its payload, which will be closed by the close action.

Intended for use in a try-with-resources. Any checked exception throwable by closer will be remembered as throwable by the close method of the returned Closing instance (and therefore will be considered throwable by the try-with-resources in which it is used. Any other code that calls close directly on the returned stream could be surprised by the checked exception, as a stream's close method is not declared to throw any. When used as intended in a try-with-resources, any such surprise is bounded by the scope of that statement.

Type Parameters:

T - Type of the stream elements

S - Type of the stream

E - Least upper bound of exceptions that can be thrown by closer, and the declared throwable type of the close method of the returned Closing instance.

Parameters:

stream - Stream to have closer added as an action on close.

closer - Runnable to be executed when the returned stream is closed.