Some common interfaces for Java

This is a collection of some common interfaces that describe everyday use cases. It is mainly intended for API providers who don't want to redeclare somewhat trivial interfaces all the time.

Overview

This library is hosted in the Maven Central Repository. You can use it with the following coordinates:

<dependency>
	<groupId>net.markenwerk</groupId>
	<artifactId>commons-interfaces</artifactId>
	<version>4.0.2</version>
</dependency>

Consult the description and Javadoc for further information.

Motivation

Some interfaces, especially functional interfaces, are - by their nature - generic enough to describe a very broad field of situation. The Java standard API doesn't provide such interfaces, but some of the standard interfaces are used in a generic way. This is especially true for Runnable, which is used in event queues everywhere, although it has very specific semantics in relation to Thread. On the other hand, it wouldn't be very useful to create new interfaces with a similar signature, particularly because Runnable is already a very concise and descriptive name.

A well chosen, concise and descriptive name reduces the necessity for a bulky method documentation, so even in an Java 8 environment, it may be better to use such interfaces, instead of a generic Function parameters.

Project specific declaration of common interfaces leads to unnecessary duplication and sometimes even the necessity to implement the same basic functionality repeatedly.

Therefore, this library provides a collection of common interfaces that describe everyday situations.

Interfaces

Check

The Check interface should be used by components that perform tests.

A Check must implement the following method:

public boolean test();

A Check should not throw any exceptions.

Predicate

The Predicate interface should be used by components that perform tests on test subjects.

A Predicate must implement the following method:

public boolean test(Subject subject);

A Predicate should not throw any exceptions.

Callback

The Callback interface should be used by components that perform an operation that will eventually yield a result.

A Callback needs to implement the following method:

public void onResult(Callee callee, Result result);

A Callback should not throw any exceptions.

Handler

The Handler interface should be used by components that perform an operation that may encounter some condition and needs to delegate the handling.

A Handler needs to implement the following method:

public void handle(Handler result) throws HandlingException;

A Handler should wrap every exception in an HandlingException.

Processor

The Processor interface should be used by components that perform modifications on some values.

A Processor needs to implement the following method:

public value process(Value value) throws ProcessingException;

A Processor should wrap every exception in an ProcessingException.

Converter

The Converter interface should be used by components that perform conversions on some values.

A Converter needs to implement the following method:

public To convert(From from) throws ConversionException;

A Converter should wrap every exception in an ConversionException.

Translator

The Translator interface should be used by components that perform conversions on some values in both directions. It is an extension of Converter.

A Translator needs to implement the following methods:

public To convert(From from) throws ConversionException;

public To revert(From from) throws ConversionException;

A Translator should wrap every exception in an ConversionException.

Provider

The Provider interface should be used by components that may need a value that may be costly (time-consuming) to produce and don't wan't to enforce its creation prematurely.

A Provider needs to implement the following method:

public Product provide() throws ProvisioningException;

A Provider should wrap every exception in an ProvisioningException.

Producer

The Producer interface should be used when a simple Provider is not sufficient, because it is necessary to obtain contextual (e.g. location-, date-, or language-dependent) values. It acts like a Provider that takes orders and produces corresponding values.

A Producer needs to implement the following method:

public Product produce(Order order) throws ProductionException;

A Producer should wrap every exception in an ProductionException.