:toc:
= jMolecules – Architectural abstractions for Java
A set of libraries to help developers implement domain models in distraction-free, plain old Java.
== Ideas behind jMolecules
== Goals
== Use Case: Express DDD concepts
Example: A banking domain.
=== Using the Annotation-Based Model
import org.jmolecules.ddd.annotation.*;
@Entity class BankAccount {
@Identity
final IBAN iban;
/* ... */
}
@ValueObject class IBAN { /* ... */ }
@ValueObject record Currency { /* ... */ }
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 the 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 https://scabl.blogspot.com/p/advancing-enterprise-ddd.html["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:
AggregateRoot
must only refer to Entity
instances that were declared to belong to it.AggregateRoot
s and Entity
s must only refer to other AggregateRoots
via Association
instances.For automated verification and runtime technology integration see https://github.com/xmolecules/jmolecules-integrations#jmoleculestechnology-integrations[jMolecules Integrations].
=== Available Libraries
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.kmolecules-ddd
] -- Kotlin-based flavor of jmolecules-ddd
to mitigate Kotlin/Java interop issues for the type based model.== Use Case: Expressing architectural concepts
jMolecules provides annotations to describe higher-level architectural concepts following the styles of Layered, Onion, and Hexagonal Architectures.
They allow you to mark an entire package as a layer, ring, or one containing ports and adapters.
These would appear in the package-info.java
file for each package that you want to annotate, e.g.:
package-info.java
for Domain layer:@DomainLayer package org.acmebank.domain;
package-info.java
for Application layer:@ApplicationLayer package org.acmebank.application;
That way, all classes in the respective package are considered to be part of the annotated layer, ring, or considered a port / adapter.
Alternatively, classes can be annotated directly:
import org.jmolecules.architecture.layered.*;
@DomainLayer @Entity public class BankAccount { /* ... */ }
Currently, annotations for Layered, Onion, and Hexagonal Architecture exist.
=== Available Libraries
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@DomainModelRing
@DomainServiceRing
@ApplicationServiceRing
@InfrastructureRing
@DomainRing
@ApplicationRing
@InfrastructureRing
jmolecules-hexagonal-architecture
] -- Hexagonal architecture@Application
@(Primary|Secondary)Adapter
@(Primary|Secondary)Port
== Use Case: Generate Technical Boilerplate Code
The jMolecules annotations and interfaces can be used to generate technical code needed to express the concept in a certain target technology.
=== Available Libraries
== Use Case: Verify and Document Architecture
The jMolecules concepts expressed in code can be used to verify rules that stem from the concepts' definitions and generate documentation.
=== Available Libraries
== Installation To use jMolecules in your project just declare a dependency to it. Release binaries are available from the Maven central repository. To avoid having to declare all versions explicitly, we recommend using the https://github.com/xmolecules/jmolecules-bom[`jmolecules-bom`] in your dependency management section.
=== Maven
=== Gradle
== Developer information
=== Release instructions
mvn release:prepare -DscmReleaseCommitComment="$ticketId - Release version $version." -DscmDevelopmentCommitComment="$ticketId - Prepare next development iteration."
mvn release:perform -Dgpg.keyname=$keyname