USAGE.md

UniJ: Usage

← back to UniJ README

Table of Contents:

• Implementation (for End Users)
• User API (for Library Providers)
• Service API (for Custom Binding Providers)

Note: UniJ resides in Maven Central.

Implementation (for End Users)

An end user can provide UniJ implementation in two ways:

• basic: through a single dependency on a UniJ bundle

• complex: through three dependencies:

  1. on the User API (optional if already provided by a library)
  2. on a Collection factory API binding
  3. on a miscellaneous API binding

In all cases, the end user may also need to add certain external dependencies.

Basic Implementation Usage (Bundles)

Gradle (Kotlin DSL)

implementation(group = "pl.tlinkowski.unij", name = "pl.tlinkowski.unij.bundle.{B}", version = "x.y.z")

Gradle (Groovy DSL)

implementation group: 'pl.tlinkowski.unij', name: 'pl.tlinkowski.unij.bundle.{B}', version: 'x.y.z'

Maven

<dependency>
  <groupId>pl.tlinkowski.unij</groupId>
  <artifactId>pl.tlinkowski.unij.bundle.{B}</artifactId>
  <version>x.y.z</version>
</dependency>

JPMS (module-info.java)

requires pl.tlinkowski.unij.bundle.{B};

where {B} can be one of: jdk8, jdk11, guava_jdk8, or eclipse_jdk8 (see Bundles for details).

Complex Implementation Usage (API + Bindings)

Gradle (Kotlin DSL)

implementation(group = "pl.tlinkowski.unij", name = "pl.tlinkowski.unij.api", version = "x.y.z")
implementation(group = "pl.tlinkowski.unij", name = "pl.tlinkowski.unij.service.collect.{C}", version = "x.y.z")
implementation(group = "pl.tlinkowski.unij", name = "pl.tlinkowski.unij.service.misc.{M}", version = "x.y.z")

Gradle (Groovy DSL)

implementation group: 'pl.tlinkowski.unij', name: 'pl.tlinkowski.unij.api', version: 'x.y.z'
implementation group: 'pl.tlinkowski.unij', name: 'pl.tlinkowski.unij.service.collect.{C}', version: 'x.y.z'
implementation group: 'pl.tlinkowski.unij', name: 'pl.tlinkowski.unij.service.misc.{M}', version: 'x.y.z'

Maven

<dependency>
  <groupId>pl.tlinkowski.unij</groupId>
  <artifactId>pl.tlinkowski.unij.api</artifactId>
  <version>x.y.z</version>
</dependency>
<dependency>
  <groupId>pl.tlinkowski.unij</groupId>
  <artifactId>pl.tlinkowski.unij.service.collect.{C}</artifactId>
  <version>x.y.z</version>
</dependency>
<dependency>
  <groupId>pl.tlinkowski.unij</groupId>
  <artifactId>pl.tlinkowski.unij.service.misc.{M}</artifactId>
  <version>x.y.z</version>
</dependency>

JPMS (module-info.java)

requires pl.tlinkowski.unij.api;
requires pl.tlinkowski.unij.service.collect.{C};
requires pl.tlinkowski.unij.service.misc.{M};

where:

• {C} can be one of: jdk8, jdk10, guava, or eclipse (see Collection Factory API Bindings for details)

• {M} can be either jdk8 or jdk11 (see Miscellaneous API Bindings for details)

Note that, instead of any of the predefined bindings mentioned above, you can create and depend on a custom binding.

External Dependencies (for End Users)

SLF4J

UniJ User API has an implementation dependency on SLF4J API to let you have insight into which implementation it chooses for each of its Service API interfaces.

As a result, if you use UniJ as an end user, you should also add a runtimeOnly dependency on one of SLF4J bindings. Otherwise, you'll see the following message at runtime:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".

SLF4J: Defaulting to no-operation (NOP) logger implementation

SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

Guava / Eclipse Collections

The dependencies on Guava and Eclipse Collections (present only in modules with guava and eclipse in their name, respectively) are compileOnly dependencies.

Thanks to this, dependency on UniJ won't affect the version of Guava / Eclipse Collections you want to use, since you have to declare this dependency explicitly.

Depending on your use case, do the following:

• if you want to use Guava / Eclipse Collections implicitly (= access to Collection implementations through UniJ only):

  • add a runtimeOnly dependency on Guava / Eclipse Collections

• if you want to use Guava / Eclipse Collections explicitly (= access to the entire API of the library):

  • (non-transitive) add an implementation dependency + requires entry to module-info.java
  • (transitive) add an api dependency + requires transitive entry to module-info.java

Minimal supported versions are:

• Guava: 23.2
• Eclipse Collections: 9.0.0

User API (for Library Providers)

A library provider can use UniJ User API in two ways:

• non-transitive: so that only the library provider can program to the User API (the end user needs to be instructed to choose the UniJ implementation as per Implementation Usage)

• transitive: so that both the library provider and the end user can program to the User API (the end user still needs to be instructed to choose the UniJ implementation as per Implementation Usage)

Non-Transitive Usage of User API

Gradle (Kotlin DSL)

implementation(group = "pl.tlinkowski.unij", name = "pl.tlinkowski.unij.api", version = "x.y.z")

Gradle (Groovy DSL)

implementation group: 'pl.tlinkowski.unij', name: 'pl.tlinkowski.unij.api', version: 'x.y.z'

JPMS (module-info.java)

requires pl.tlinkowski.unij.api;

Transitive Usage of User API

Gradle (Kotlin DSL)

api(group = "pl.tlinkowski.unij", name = "pl.tlinkowski.unij.api", version = "x.y.z")

Gradle (Groovy DSL)

api group: 'pl.tlinkowski.unij', name: 'pl.tlinkowski.unij.api', version: 'x.y.z'

Maven

<dependency>
  <groupId>pl.tlinkowski.unij</groupId>
  <artifactId>pl.tlinkowski.unij.api</artifactId>
  <version>x.y.z</version>
</dependency>

JPMS (module-info.java)

requires transitive pl.tlinkowski.unij.api;

Service API (for Custom Binding Providers)

UniJ Service API should be used only in the rare case that you need to create a custom UniJ binding.

Gradle (Kotlin DSL)

implementation(group = "pl.tlinkowski.unij", name = "pl.tlinkowski.unij.service.api", version = "x.y.z")
testImplementation(group = "pl.tlinkowski.unij", name = "pl.tlinkowski.unij.test", version = "x.y.z")

Gradle (Groovy DSL)

implementation group: 'pl.tlinkowski.unij', name: 'pl.tlinkowski.unij.service.api', version: 'x.y.z'
testImplementation group: 'pl.tlinkowski.unij', name: 'pl.tlinkowski.unij.test', version: 'x.y.z'

Maven

<dependency>
  <groupId>pl.tlinkowski.unij</groupId>
  <artifactId>pl.tlinkowski.unij.service.api</artifactId>
  <version>x.y.z</version>
</dependency>
<dependency>
  <groupId>pl.tlinkowski.unij</groupId>
  <artifactId>pl.tlinkowski.unij.test</artifactId>
  <version>x.y.z</version>
  <scope>test</scope>
</dependency>

JPMS (module-info.java)

requires pl.tlinkowski.unij.service.api;

---

← back to UniJ README