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.

    • Method Detail

      • ederThrow

        static <E extends Throwable> E ederThrow​(Throwable t)
                                          throws E extends Throwable
        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.
        E extends Throwable
      • 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 extends Throwable,
                                               RX extends Throwable
        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.
        EX extends Throwable
      • inReturning

        default <RT,​RX extends Throwable> RT inReturning​(Checked.Function<? super WT,​RT,​RX> f)
                                                        throws EX extends Throwable,
                                                               RX extends Throwable
        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.
        EX extends Throwable
      • inDoubleReturning

        default <RX extends Throwable> double inDoubleReturning​(Checked.ToDoubleFunction<? super WT,​RX> f)
                                                         throws EX extends Throwable,
                                                                RX extends Throwable
        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.
        EX extends Throwable
      • inIntReturning

        default <RX extends Throwable> int inIntReturning​(Checked.ToIntFunction<? super WT,​RX> f)
                                                   throws EX extends Throwable,
                                                          RX extends Throwable
        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.
        EX extends Throwable
      • inLongReturning

        default <RX extends Throwable> long inLongReturning​(Checked.ToLongFunction<? super WT,​RX> f)
                                                     throws EX extends Throwable,
                                                            RX extends Throwable
        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.
        EX extends Throwable
      • inBooleanReturning

        default <RX extends Throwable> boolean inBooleanReturning​(Checked.Predicate<? super WT,​RX> f)
                                                           throws EX extends Throwable,
                                                                  RX extends Throwable
        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.
        EX extends Throwable
      • inByteReturning

        default <RX extends Throwable> byte inByteReturning​(Checked.ToByteFunction<? super WT,​RX> f)
                                                     throws EX extends Throwable,
                                                            RX extends Throwable
        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.
        EX extends Throwable
      • inShortReturning

        default <RX extends Throwable> short inShortReturning​(Checked.ToShortFunction<? super WT,​RX> f)
                                                       throws EX extends Throwable,
                                                              RX extends Throwable
        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.
        EX extends Throwable
      • inCharReturning

        default <RX extends Throwable> char inCharReturning​(Checked.ToCharFunction<? super WT,​RX> f)
                                                     throws EX extends Throwable,
                                                            RX extends Throwable
        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.
        EX extends Throwable
      • inFloatReturning

        default <RX extends Throwable> float inFloatReturning​(Checked.ToFloatFunction<? super WT,​RX> f)
                                                       throws EX extends Throwable,
                                                              RX extends Throwable
        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.
        EX extends Throwable
      • and

        static <T,​E extends ThrowableChecked.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 ThrowableChecked.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 ThrowableChecked.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.
        V - Type subsuming the return type of first, and acceptable as parameter of after.
        R - Return type of the composed function, subsuming the return type 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 ThrowableChecked.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 ThrowableChecked.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 ThrowableChecked.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 ThrowableChecked.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 ThrowableChecked.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 ExceptionChecked.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 ExceptionChecked.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 ExceptionChecked.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.