Skip to content
Switch branches/tags

jMolecules – Architectural abstractions for Java

A set of libraries to help developers work with architectural concepts in Java. Goals:

  • Express that a piece of code (a package, class, or method) implements an architectural concept.

  • Make it easy for the human reader to determine what kind of architectural concepts a given piece of code is.

  • Allow tool integration (to do interesting stuff like generating persistence or static architecture analysis to check for validations of the architectural rules.)

Expressing DDD concepts


import org.jmolecules.ddd.annotation.*;

public class BankAccount { /* ... */ }

public class Currency { /* ... */ }

public class Accounts { /* ... */ }

When we take Ubiquitous Language serious, we want names (for classes, methods, etc.) that only contain words from the domain language. That means the titles of the building blocks should not be part of the names. So in a banking domain we don’t want BankAccountEntity, CurrencyVO or even AccountRepository as types. Instead, we want BankAccount, Currency and Accounts – like in the example above.

Still, we want to express that a given class (or other architectural element) is a special building block; i.e. uses a design pattern. jMolecules provide a set of standard annotations for the building blocks known from DDD.

Using a type based model

As an alternative to the above mentioned annotations, jMolecules also provides a set of interfaces, largely based on the ideas presented in John Sullivan’s series "Advancing Enterprise DDD". They allow expressing relationships between the building blocks right within the type system, so that the compiler can help to verify model correctness and the information can also be processed by Java reflection more easily.

  • Identifier — A type to represent types that are supposed to act as identifiers.

  • Identifiable<ID> — Anything that’s exposing an identifier.

  • Entity<T extends AggregateRoot<T, ?>, ID> extends Identifiable<ID> — An entity, declaring to which AggregateRoot it belongs and which identifier it exposes.

  • AggregateRoot<T extends AggregateRoot<T, ID>, ID extends Identifier> extends Entity<T, ID> — an aggregate root being an Entity belonging to itself exposing a dedicated Identifier

  • Association<T extends AggregateRoot<T, ID>, ID extends Identifier> extends Identifiable<ID> — an explicit association to a target AggregateRoot.

This arrangement gives guidance to modeling and allows to easily verify the following rules, potentially via reflection:

  • Enforced, dedicated identifier types per aggregate to avoid identifiers for different aggregates mixed up.

  • AggregateRoot must only refer to Entity instances that were declared to belong to it.

  • AggregateRoots and Entitys must only refer to other AggregateRoots via Association instances.

For automated verification and runtime technology integration see jMolecules Integrations.


  • jmolecules-ddd — annotations and interfaces to express DDD building blocks (value objects, entities, aggregate roots etc.) in code.

  • jmolecules-events — annotations and interfaces to express the concept of events in code.

Expressing architecture

jMolecules provides annotations to mark a package as a layer (or ring):

import org.jmolecules.architecture.layered.*;

package org.acmebank.domain;

package org.acmebank.application;

That way, all classes in the respective package are considered to be part of the annotated layer.

Alternatively, classes can be annotated directly:

import org.jmolecules.architecture.layered.*;

public class BankAccount { /* ... */ }

public class TransferMoney { /* ... */ }

Currently, annotations for Layered and Onion Architecture exist.


  • jmolecules-architecture — annotations to express architectural styles in code.

    • jmolecules-cqrs-architecture — CQRS architecture

      • @Command

      • @CommandDispatcher

      • @CommandHandler

      • @QueryModel

    • jmolecules-layered-architecture — Layered architecture

      • @DomainLayer

      • @ApplicationLayer

      • @InfrastructureLayer

      • @InterfaceLayer

    • jmolecules-onion-architecture — Onion architecture

      • Classic

        • @DomainModelRing

        • @DomainServiceRing

        • @ApplicationServiceRing

        • @InfrastructureRing

      • Simplified (does not separate domain model and services)

        • @DomainRing

        • @ApplicationRing

        • @InfrastructureRing


To use jMolecules in your project just declare a dependency to it. Release binaries are available from the Maven central repository.




repositories {
dependencies {

Tool integration

The jMolecules concepts expressed in code can be used to verify rules that stem from the concepts' definitions, generate documentation or even generate technical code needed to express the concept in a certain target technology.

Verification and documentation

  • jQAssistant plugin — to verify rules applying to the different architectural styles, DDD building blocks, CQRS and events. Also creates PlantUML diagrams from the information available in the codebase.

  • ArchUnit rules — allow to verify relationships between DDD building blocks.

  • Moduliths — supports detection of jMolecules components, DDD building blocks and events for module model and documentation purposes (see blog post for more information).

Runtime technology integration

Developer information

Release instructions

  • mvn release:prepare -DscmReleaseCommitComment="$ticketId - Release version $version." -DscmDevelopmentCommitComment="$ticketId - Prepare next development iteration."

  • mvn release:perform -Dgpg.keyname=$keyname