Extensions for popular Java libraries
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
doc/img
guava
hamcrest
junit
mockito
time
.gitignore
.travis.yml
LICENSE
README.md
RELEASE.md
build.sh
coverity.yml
functions.sh
install_java7_and_java8.sh
pom.xml
travis-settings.xml
update_version.sh
use_jdk_switcher.sh

README.md

java-extended

Maven Central Download Build Status

codecov.io Coverity Scan Build Status Dependency Status

Java Extended is an experimental set of libraries targeting JVM 1.6+

Available versions:

JDK/Guava

JDK and Google's Guava extension library

<dependency>
  <groupId>com.bluecatcode.guava</groupId>
  <artifactId>guava-19.0-extended</artifactId>
  <version>1.1.0</version>
</dependency>

Either

Either represents a value of one of two possible types, much like Optional but with both types definable. Simple use case:

public static Either<Exception, Integer> divide(int x, int y) {
    try {
        return Either.valueOf(x / y);
    } catch (Exception e) {
        return Either.errorOf(e);
    }
}
...
divide(10, 2).orThrow(unwrapToUncheckedException());

More complex use case:

InputStream inputStream = either((CheckedFunction<URL, InputStream, IOException>) URL::openStream)
        .apply(new URL("http://example.com"))
        .orThrow(unwrapToUncheckedException());

Contracts

Contracts can be defined using Checks for recoverable, validation errors and Preconditions, Postconditions, Impossibles for unrecoverable, programming errors, this distinction is very important and manifests itself in different type of Throwable being used, an Exception for the former and an Error for the later.

Recoverable, validation error checking usage cases range from simple:

check(name, isNotNull());

to complex and parametrized:

check(name, isNotnull(), CustomValidationException.class, "Expected valid name, got: '%s'", name);

where isNotNull is a predicate.

Unrecoverable, programming errors checking use cases include Preconditions, Postconditions:

public String doStuff(String input) {
    require(input != null, "Expected non-null input");

    String result = this.service.callStuff(input);
    ensure(result, isAsRequired())

    return result;
}

and Impossibles:

public static void closeQuietly(@WillClose @Nullable Closeable closeable) {
    try {
        close(closeable, true);
    } catch (IOException impossible) {
        impossible(impossible);
    }
}

Exceptions

Exceptions class provides some factory methods, mainly exception and throwable, along with parameters and arguments. Usage example:

throwable(throwableType, parameters(String.class),
          arguments(messageFromNullable(errorMessageTemplate, errorMessageArgs));

Exception hierarchy

Exception Classes

Base exception classes CheckedException and UncheckedException are clearly named with the intention for use with custom exception types for clear class hierarchy.

Special exceptions

  • VoidException is an exception that cannot be thrown ever, an analogue of the Void type
  • WrappedException is an unchecked exception used to wrap checked exceptions in case an checked exception is not permitted or not desired

JUnit

JUnit library extensions

<dependency>
  <groupId>com.bluecatcode.junit</groupId>
  <artifactId>junit-4.12-extended</artifactId>
  <version>1.1.0</version>
</dependency>

Hamcrest

Hamcrest library extensions

<dependency>
  <groupId>com.bluecatcode.hamcrest</groupId>
  <artifactId>hamcrest-1.3-extended</artifactId>
  <version>1.1.0</version>
</dependency>

Mockito

Mockito library extensions

<dependency>
  <groupId>com.bluecatcode.mockito</groupId>
  <artifactId>mockito-1.10.19-extended</artifactId>
  <version>1.1.0</version>
</dependency>

Joda Time

Joda Time library extensions

<dependency>
  <groupId>com.bluecatcode.time</groupId>
  <artifactId>joda-time-2.9.1-extended</artifactId>
  <version>1.1.0</version>
</dependency>

Core (deprecated in version > 1.1.0)

Core Java JDK extensions and backports

Functional Java Check (deprecated in version > 1.0.2)

Functional Java test module (a.k.a. Reduction) library extensions

Build on Ubuntu Linux

To build this project you'll need Oracle Java 7 and 8

There are convinience scripts available:

install_java7_and_java8.sh
use_jdk_switcher.sh
build.sh
update_version.sh

To run a simple build use:

source use_jdk_switcher.sh; mvn install

To run a more comprehensive build:

source use_jdk_switcher.sh; mvn install jacoco:report -Penable-unit-tests,enable-integration-tests,enable-mutation-tests,enable-coverage-tests

Development

Maven

Run single project (module) with dependencies, e.g. guava module with target test:

mvn --projects guava --also-make test

Run single test:

mvn -DfailIfNoTests=false -Dtest=StringsCapitalizeSpec test

Debug surefire:

mvn -Dmaven.surefire.debug test

All together

mvn --projects guava --also-make -DfailIfNoTests=false -Dmaven.surefire.debug -Dtest=StringsCapitalizeSpec test