Module com.machinezoo.noexception
Package com.machinezoo.noexception

Class Exceptions

  • public final class Exceptions
extends Object
    Static methods for creating predefined exception handlers. Custom exception handlers can be created by inheriting from ExceptionHandler and CheckedExceptionHandler.

    Typical usage: Exceptions.silence().get(() -> my_throwing_lambda).orElse(fallback)

    Usage with checked exceptions: Exceptions.silence().run(Exceptions.sneak().runnable(() -> my_throwing_lambda))

    See Also:
    NoException tutorial

    • Method Detail

      • propagate

        public static ExceptionHandler propagate()
        Returns ExceptionHandler that propagates (lets through) all exceptions. This exception handler is equivalent to having no exception handler at all. It is useful when switching among several exception handlers at runtime.
        Returns:
        propagating exception handler

      • ignore

        @Deprecated
public static ExceptionHandler ignore()
        Deprecated.
        Use propagate() instead.
        Returns ExceptionHandler that lets all exceptions through. This is an old deprecated alias for propagate().
        Returns:
        pass-through exception handler

      • log

        @Deprecated
public static ExceptionHandler log()
        Deprecated.
        Use SLF4J extension instead.
        Returns ExceptionHandler that writes all exceptions to common logger. Logs are written to SLF4J logger named after this class. This handler is convenient and a suitable default choice, but the single shared logger can make logs harder to filter. Use log(Logger) to specify custom logger where filtering is important.

        Typical usage: Exceptions.log().run(() -> my_throwing_lambda)

        No exceptions are allowed through, not even Errors. If InterruptedException is caught, Thread.interrupt() is called.

        Returns:
        logging exception handler
        See Also:
        log(Logger)

      • log

        @Deprecated
public static ExceptionHandler log​(org.slf4j.Logger logger,
                                   String message)
        Deprecated.
        Use SLF4J extension instead.
        Creates ExceptionHandler that writes all exceptions to the specified logger with the specified message. If you just need to specify custom logger, use log(Logger). This overload allows for differentiating or explanatory message. If the message is expensive to construct, use log(Logger, Supplier) method.

        Typical usage: Exceptions.log(logger, "Failed to do X.").run(() -> my_throwing_lambda)

        No exceptions are allowed through, not even Errors. If InterruptedException is caught, Thread.interrupt() is called.

        Parameters:
        logger - where all exceptions are logged
        message - introduces every exception in the log
        Returns:
        exception handler with custom logger and message
        Throws:
        NullPointerException - if logger or message is null
        See Also:
        log(Logger), log(Logger, Supplier)

      • log

        @Deprecated
public static ExceptionHandler log​(org.slf4j.Logger logger,
                                   Supplier<String> message)
        Deprecated.
        Use SLF4J extension instead.
        Creates ExceptionHandler that writes all exceptions to the specified logger with lazily evaluated message. If the message does not need lazy evaluation, use the log(Logger, String) method. This overload constructs expensive messages lazily only when exception is caught. If message throws, the exception is logged and fallback message is used to log the original exception.

        Typical usage: Exceptions.log(logger, () -> "Exception in " + this).run(() -> my_throwing_lambda)

        No exceptions are allowed through, not even Errors. If InterruptedException is caught, Thread.interrupt() is called.

        Parameters:
        logger - where all exceptions are logged
        message - a Supplier that is lazily evaluated to generate log message
        Returns:
        exception handler with custom logger and lazily evaluated message
        Throws:
        NullPointerException - if logger or message is null
        See Also:
        log(Logger, String)

      • silence

        public static ExceptionHandler silence()
        Returns ExceptionHandler that silently ignores all exceptions. This handler is useful when some code is known to produce junk exceptions. Most application code should use logging or counting handler instead.

        Typical usage: Exceptions.silence().run(() -> my_throwing_lambda)

        No exceptions are allowed through, not even Errors. If InterruptedException is caught, Thread.interrupt() is called.

        Returns:
        exception handler that ignores all exceptions

      • sneak

        public static CheckedExceptionHandler sneak()
        Returns CheckedExceptionHandler that lets through checked exceptions without declaring them. All exceptions are allowed through unmodified, including checked ones, even though no checked exceptions are declared.

        Typical usage: Exceptions.sneak().run(() -> my_throwing_lambda)

        This is the recommended CheckedExceptionHandler, because it does not obfuscate the original exception in any way. Use wrap() if using sneaky exceptions is not possible or not desirable.

        Sneaky throw is implemented using a neat trick with type erasure that persuades java compiler to tolerate throwing undeclared checked exception from specially crafted generic method. The trick is safe. It is legal java code and JVMs do not mind it. It is just considered dirty by some developers.

        Returns:
        exception handler that lets checked exceptions through
        See Also:
        wrap()

      • wrap

        public static CheckedExceptionHandler wrap​(Function<Exception,​RuntimeException> wrapper)
        Creates CheckedExceptionHandler that applies custom wrapper to checked exceptions. Unchecked exceptions are passed through unmodified. Checked exceptions are passed to wrapper and the resulting unchecked exception is thrown. Use sneak() to avoid wrapping and wrap() to use standard wrapper.

        Typical usage: Exceptions.wrap(MyWrapperException::new).run(() -> my_throwing_lambda)

        If InterruptedException is caught, Thread.interrupt() is called before invoking the wrapper.

        Parameters:
        wrapper - method converting checked exception into an unchecked one, often just exception constructor reference
        Returns:
        exception handler with custom exception transform
        Throws:
        NullPointerException - if wrapper is null
        See Also:
        sneak(), wrap()