README.md

Plume

Plume is an encapsulation of the best available JVM libraries to get a project up and running quickly.

Key concepts:

• Plume has few main principles/dependencies: configuration via Config and dependency injection via Guice or Dagger.
• Plume is the glue made with Config and Guice/Dagger to make popular open source libraries work together: Jersey, QueryDsl, HikariCP, etc.
• Plume is lightweight and modular.

A concrete example of how Plume works is the Plume Mail module:

• It provides the Simple Java Mail dependency
• This module exposes 50 lines of code via the MailerProvider class:
  • In the constructor, it populates the config object from Simple Mail Java using Config
  • The MailerProvider class implements the javax.inject.Provider interface to expose the Simple Mail Java Mailer object.

In this way, it is easy to replace most of the components suggested by Plume. The only "strong" requirement is to provide dependency injection objects using javax.inject.

Plume is maintained by Coreoz and licensed under Apache License 2.0.

Maintenance

In developing Plume, we strive to keep the project and its dependencies as small and lightweight as possible. Making Plume lightweight helps reduce the complexity of the system and the risk of security issues. This means that Plume will help projects have the lowest maintenance and evolution costs.

In addition:

• Coreoz has been maintaining Plume since 2016 and providing migration guides for each release. This is not going to change anytime soon.
• Plume sources are published to Maven Central: so they will always be available one way or another.

Demo

Sample projects can be found here: https://github.com/Coreoz/Plume-showcase.

Getting started

The best way to get started is to use a Maven archetype for Plume.

Plume requires at least Java 11.

Dependency injection

If you are not familiar with the dependency injection concept, read the Guice Motivation Guice.

Dependency injection takes a central place in Plume. Indeed, all modules provided by Plume contain injectable objects. To use these injectables objects, the default choice is Guice: it is really easy to use.

If you are already familiar with Guice, you may want to have a look at Dagger which enables to detect dependency injection problems at compile time. To use Dagger the annotation processor should be enabled in your IDE: https://immutables.github.io/apt.html. However, note that Dagger may be more difficult to use than Guice.

In Plume documentation, examples use Guice modules. Most of the time there is a corresponding Dagger module to each Guice module. For example, the corresponding Dagger module for GuiceConfModule is DaggerConfModule.

Plume core modules

General modules

Plume Base Dependencies

Reference all libraries versions used by Plume. It will help you avoid dependency conflicts in your pom.xml file.

Plume Conf

This module is based on the Config library and handles the application configuration.

Plume Jersey

Enables to build REST web-services with Jersey and expose the documentation with Swagger.

This module can be used with Plume Jersey monitoring to quickly setup application monitoring exposure.

Plume Services

Common services that are often needed in projects or libraries.

Plume Mail

Expose a Mailer object from Simple Java Mail through a Config configuration.

Plume Scheduler

Enables to easily execute recurring tasks/jobs through Wisp Scheduler.

Database modules

Plume Database

Basic utilities to pool SQL connections with HikariCP and manage transactions.

Plume Querydsl

Integration with Querydsl for SQL only (no JPA :).

Plume Querydsl Codegen

Code generation for Querydsl for SQL only.

Plume Database test

Use Flyway to help you make integration tests with a database.

Plume ecosystem

• Maven archetype for Plume helps to create a project using Jersey/Grizzly, QueryDsl, HikariCP, Flyway. The generated project includes sample unit and integration tests. It also includes some basic configuration for Gitlab and Github CI.
• Plume Admin and Plume File libraries allow you to quickly create an admin area and upload files, respectively.
• Plume Dependencies is a Maven BOM project to unify dependencies between Plume, Plume Admin and Plume File libraries.

Other Libraries to use with Plume

If you need an HTTP client in a Plume application, a good choice is to use:

• OkHttp,
• or Retrofit if you need to query a standard REST API.

Upgrades

Upgrade from 3.x to 4.x

See upgrade instructions in the release details.

Upgrade from 2.x to 3.x

See upgrade instructions in the release details.

Upgrade from 1.x to 2.x

See upgrade instructions in the release details.