Unexceptional

A small cohesive module, leveraging Java 8 functional capabilities to remove most of the boiler-plate of handling checked exceptions.

Example - Deserialization

Without Unexceptional, 7 lines and 8 branches:

	@SuppressWarnings("unchecked")
	public static <T> T deserialize(byte[] serialized, Class<T> type)
	{
		ByteArrayInputStream bais = new ByteArrayInputStream(serialized);
		try(ObjectInputStream ois = new ObjectInputStream(bais)) {
			return (T) ois.readObject();
		} catch(IOException ioe) {
			throw new UncheckedIOException(ioe);
		} catch(ClassNotFoundException cnfe) {
			throw new RuntimeException(cnfe);
		}
	}

With Unexceptional, 2 lines and 0 branches:

	@SuppressWarnings("unchecked")
	public static <T> T deserialize(byte[] serialized, Class<T> type)
	{
		ByteArrayInputStream bais = new ByteArrayInputStream(serialized);
		return (T) closeAfterApplying(ObjectInputStream::new, bais, ObjectInputStream::readObject);
	}

Example - File list

Without Unexceptional, 4 lines:

	List<Path> fileListVanilla(Path targetDir)
	{
		try {
			return Files.list(targetDir)
					.collect(toList());
		} catch (IOException e) {
			throw new UncheckedIOException(e);
		}
	}

With Unexceptional, 1 line:

	List<Path> fileList(Path targetDir)
	{
		return Exceptional.apply(Files::list, targetDir)
				.collect(toList());
	}

Example - new URI from String

Without Unexceptional, 4 lines:

	public static URI toUriVanilla(String ʊri)
	{
		try {
			return new URI(ʊri);
		} catch (URISyntaxException e) {
			throw new SomeArbitraryRuntimeException(e);
		}
	}

With Unexceptional, 1 line:

	public static URI toUri(String ʊri)
	{
		return Exceptional.uri(ʊri);
	}

Example - Free Port Finder

Without Unexceptional, 4 lines and 8 branches:

	public static int findFreePortVanilla()
	{
		try(ServerSocket socket = new ServerSocket(0)) {
			return socket.getLocalPort();
		} catch(IOException e) {
			throw new UncheckedIOException(e);
		}
	}

With Unexceptional, 1 line and 0 branches:

	public static int findFreePort()
	{
		return closeAfterApplying(ServerSocket::new, 0, ServerSocket::getLocalPort);
	}

Example - Serialization

Without Unexceptional, 6 lines and 8 branches:

	public static byte[] serialize(Object object)
	{
		ByteArrayOutputStream baos = new ByteArrayOutputStream();
		try(ObjectOutputStream oos = new ObjectOutputStream(baos)) {
			oos.writeObject(object);
			return baos.toByteArray();
		} catch(IOException ioe) {
			throw new UncheckedIOException(ioe);
		}
	}

With Unexceptional, 3 lines and 0 branches:

	public static byte[] serialize(Object object)
	{
		ByteArrayOutputStream baos = new ByteArrayOutputStream();
		closeAfterAccepting(ObjectOutputStream::new, baos, object, ObjectOutputStream::writeObject);
		return baos.toByteArray();
	}

Example - File read all bytes

Without Unexceptional, 4 lines:

	public byte[] readAllBytesVanilla(Path file)
	{
		try {
			return Files.readAllBytes(file);
		} catch(IOException e) {
			throw new UncheckedIOException(e);
		}
	}

With Unexceptional, 1 line:

	public byte[] readAllBytes(Path file)
	{
		return Exceptional.apply(Files::readAllBytes, file);
	}

‹ ›

What’s inside?

Types equivalent to those found in java.util.function but with checked methods (declaring Throwable)
A small family of unchecked exceptions; reflective operation, security, interrupt, etc.
Static helper Exceptional:
- Convert checked method handles to java.util.functional interfaces
- Invoke checked functional types without try-catch
- Dirty compiler trick; throwing a checked exception as unchecked
- Factories for some common types where the constructor declares a checked exception (e.g. java.net.URI, java.net.URL)
- Convert checked exceptions to unchecked equivalents
- Swallow exceptions (accepts throwables, but only swallows exceptions - errors are rethrown)
- Unwrap reflective exceptions
Static helper Closing:
- Concise IO stream usage (re-read as terse one-liner), condenses create-operate-close - arguably laconic over expressive
- Does all the dirty work for I-don’t-care-but-IOExceptions-on-AutoCloseable-are-destroying-my-branch-coverage
Simple mirror EmeticStream:
- wraps java.util.stream.Stream providing equivalent methods taking checked functional types (terminates immediately on exception)

Usage

The intended use of this library is to make code more concise by removing the need to handle checked exceptions. It should really only be used for the impossible (logically we know this cannot occur) or fatal (unrecoverable, cannot degrade with grace, game over) cases.

Please use responsibly; first consider if a raised exception can actually be handled, and if not, then could it be propagated with a more contextual type/message? Be considerate to readers of logs, unlucky users and your future self.

Brief note on `try-with-resources` branch coverage

A nice side effect is the removal of, potential but often unrealistic, branches; a typical try-with-resources block for IO streams typically result in 8 branches - the causes of which are often misunderstood (see this old StackOverflow post - I’ve added a rambling answer with more detail).

Migration from versions 0.* to 1.*

What changed

A generic type parameter was added to the functional types for the Throwable on method declarations; so:

    interface CheckedFunction<T, R> {
       public abstract R apply(T t) throws Throwable;
    }

Has become:

    interface CheckedFunction<T, R, E extends Throwable> {
       public abstract R apply(T t) throws E;
    }

Why

This allows users to declare specific subtypes of Throwable, and therefore supported cases where the consumer of a checked functional type demanded matching of specific exception type e.g. AutoCloseable’s close() method declares that it throws Exception. Previously you could assign the autocloseable::close handle to a checked functional type, but not the other way round.

Upgrade path

For existing code, currently dependent on v0.y,z, the impact is nonexistent if the only use is Exceptional or EmeticStream. Otherwise, where using the checked equivalents of java.util.function.*, then appending a wildcard type parameter of <?> is sufficient (this will set the new type parameter to the upper bound of Throwable which is equivalent to the unparameterised form of v0.y.z).
Deprecated methods (such as Exceptional.closing(...)) have been removed, their alternatives are documented in previous versions.

Unexceptional
/ʌnɪkˈsɛpʃ(ə)n(ə)l,ʌnɛkˈsɛpʃ(ə)n(ə)l/
adjective: not out of the ordinary; usual.
synonyms: ordinary, average, typical, common, everyday, run-of-the-mill, middle-of-the-road, stock, mediocre, so-so, pedestrian, unremarkable, undistinguished, indifferent, unimpressive.

Emetic
/ɪˈmɛtɪk/
adjective: (of a substance) causing vomiting.

What’s inside?

Usage

Brief note on try-with-resources branch coverage

Migration from versions 0.* to 1.*

What changed

Why

Upgrade path

Brief note on `try-with-resources` branch coverage