jMolecules Documentation

jMolecules is a set of libraries designed to help developers implement domain models in plain Java by explicitly expressing architectural concepts. It aims to keep domain-specific code free from technical dependencies, reduce boilerplate, and enable automatic documentation and architectural validation.

Key capabilities include:

• Expressing DDD concepts: Using annotations or a type-based model to define Value Objects, Entities, and Aggregate Roots.
• Expressing architectural styles: Marking code as part of Layered, Onion, or Hexagonal architectures.
• Tool integration: Enabling automated augmentation (e.g., Spring/JPA integrations) and architectural rule checking (e.g., ArchUnit, jQAssistant).

The type-based model uses interfaces to express relationships between building blocks directly within the Java type system. This allows the compiler to help verify model correctness and makes the information easily accessible via reflection.

Core interfaces include:

• Identifier: Represents types acting as identifiers.
• Identifiable<ID>: Anything exposing an identifier.
• Entity<T extends AggregateRoot<T, ?>, ID>: An entity declaring its parent AggregateRoot and its identifier.
• AggregateRoot<T extends AggregateRoot<T, ID>, ID extends Identifier>: An aggregate root that is also an Entity belonging to itself.
• Association<T extends AggregateRoot<T, ID>, ID extends Identifier>: An explicit association to a target AggregateRoot.

The annotation-based model allows you to use standard annotations to mark building blocks from Domain-Driven Design (DDD). This approach allows you to use clean domain names (e.g., BankAccount instead of BankAccountEntity) while still expressing their architectural role.

Common annotations provided by jmolecules-ddd include:

• @Entity
• @Identity
• @ValueObject
• @Repository

import org.jmolecules.ddd.annotation.*;

@Entity
class BankAccount {

@Identity
    final IBAN iban;

/* ... */

}

@ValueObject
class IBAN { /* ... */ }

@ValueObject
record Currency { /* ... */ }

@Repository
class Accounts { /* ... */ }

To use jMolecules, declare a dependency in your project. It is recommended to use the jmolecules-bom to manage versions across all modules.

Maven

<dependency>
  <groupId>org.jmolecules</groupId>
  <artifactId>jmolecules-ddd</artifactId>
  <version>1.9.0</version>
</dependency>

Gradle

repositories {
  mavenCentral()
}
dependencies {
  implementation("org.jmolecules:jmolecules-ddd:1.9.0")
}

jMolecules is split into several specialized libraries:

• jmolecules-ddd: Annotations and interfaces for DDD building blocks (Value Objects, Entities, etc.).
• jmolecules-events: Annotations and interfaces for expressing events.
• kmolecules-ddd: A Kotlin-based version of jmolecules-ddd to improve Kotlin/Java interoperability with the type-based model.
• jmolecules-architecture: Annotations for architectural styles (Layered, Onion, Hexagonal, CQRS).
• jmolecules-integrations: Provides support for Spring, Data JPA, Data MongoDB, Data JDBC, and Jackson.