jMolecules

https://github.com/xmolecules/jmolecules
Admin
jMolecules is a set of libraries that help developers implement domain models in Java using...
Tokens:29,601
Snippets:278
Trust Score:7.2
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### BankAccountRepository implementation example

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-types.md

Example of extending the Repository interface for a specific aggregate.

```java
import org.jmolecules.ddd.types.Repository;

public interface BankAccountRepository extends Repository<BankAccount, BankAccountId> {
    // business API, e.g. Optional<BankAccount> findById(BankAccountId id);
}
```

--------------------------------

### BoundedContext Usage Example

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-annotations.md

Example of applying @BoundedContext to a package via package-info.java.

```java
// package-info.java
@BoundedContext(id = "payments", name = "Payments", description = "Money movement")
package com.acme.payments;
```

--------------------------------

### Association.pointsTo usage example

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-types.md

Example usage of the pointsTo method to verify an association target.

```java
if (ref.pointsTo(loadedAccount)) {
    // ...
}
```

--------------------------------

### SecondaryPort Usage Example

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-hexagonal-architecture.md

An example of applying the @SecondaryPort annotation to a repository interface.

```java
@SecondaryPort
public interface BankAccountRepository {
    BankAccount save(BankAccount account);
}
```

--------------------------------

### forId usage example

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-types.md

Example of using Association.forId to create an association from an identifier.

```java
Association<BankAccount, BankAccountId> ref = Association.forId(new BankAccountId(42));
```

--------------------------------

### Implement a Repository interface

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-annotations.md

Example of using the @Repository annotation on a domain repository interface.

```java
import org.jmolecules.ddd.annotation.Repository;

@Repository
interface BankAccountRepository {
    Optional<BankAccount> findByIban(IBAN iban);
}
```

--------------------------------

### PrimaryPort Usage Example

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-hexagonal-architecture.md

An example of applying the @PrimaryPort annotation to a use case interface.

```java
@PrimaryPort
public interface TransferMoneyUseCase {
    void transfer(BankAccountId source, BankAccountId target, Amount amount);
}
```

--------------------------------

### @Port usage example

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-hexagonal-architecture.md

Shows how to apply @Port to an interface, using the name attribute to identify the port.

```java
@Port(name = "AccountLookup")
public interface AccountLookup {
    Optional<BankAccount> findByIban(IBAN iban);
}
```

--------------------------------

### forAggregate usage example

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-types.md

Example of using Association.forAggregate to create an association from a repository-fetched aggregate.

```java
import org.jmolecules.ddd.types.AggregateRoot;
import org.jmolecules.ddd.types.Association;

BankAccount account = repository.findBy(new BankAccountId(1));
Association<BankAccount, BankAccountId> ref = Association.forAggregate(account);
```

--------------------------------

### Implement an @Adapter annotated class

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-hexagonal-architecture.md

Example of applying the @Adapter annotation to a repository implementation.

```java
@Adapter(name = "JpaAccountRepository", description = "JPA implementation of the bank account repository")
public class JpaAccountRepository implements BankAccountRepository { /* ... */ }
```

--------------------------------

### Identity usage example

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/kmolecules-ddd.md

Example of using @Identity on a constructor property within an @AggregateRoot class.

```kotlin
import org.jmolecules.ddd.annotation.AggregateRoot
import org.jmolecules.ddd.annotation.Identity

@AggregateRoot
class BankAccount(@Identity val iban: IBAN)
```

--------------------------------

### Apply @Application to a package

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-hexagonal-architecture.md

Example of applying the @Application annotation to a package using package-info.java.

```java
// package-info.java
@Application
package com.acme.bank.application;
```

--------------------------------

### BankAccount implementing AggregateRoot

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-types.md

Example implementation of an aggregate root. BankAccount implements AggregateRoot<BankAccount, BankAccountId> and provides the required getId() method.

```java
public class BankAccount implements AggregateRoot<BankAccount, BankAccountId> {

    private final BankAccountId id;

    public BankAccount(BankAccountId id) {
        this.id = id;
    }

    @Override
    public BankAccountId getId() {
        return id;
    }
}
```

--------------------------------

### Association Usage Example

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-annotations.md

Example of using @Association on a field to reference an aggregate by identity.

```java
import org.jmolecules.ddd.annotation.Association;

class Transfer {

    @Association(aggregateType = BankAccount.class)
    private BankAccountId sourceAccount;
}
```

--------------------------------

### pointsTo usage example

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-types.md

Example of using pointsTo to check if an association points to a specific identifier.

```java
if (ref.pointsTo(accountId)) {
    // ...
}
```

--------------------------------

### DomainEventPublisher Usage Example

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-events.md

Example of applying the DomainEventPublisher annotation to a method to publish an external event.

```java
import org.jmolecules.event.annotation.DomainEventPublisher;

@DomainEventPublisher(publishes = "bank.MoneyTransferred", type = DomainEventPublisher.PublisherType.EXTERNAL)
void publish(MoneyTransferred event) { /* ... */ }
```

--------------------------------

### Association usage example

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/kmolecules-ddd.md

Example of using the @Association annotation on a property, specifying the aggregate type.

```kotlin
import org.jmolecules.ddd.annotation.Association

class Transfer {

    @Association(aggregateType = BankAccount::class)
    lateinit var sourceAccount: BankAccountId
}
```

--------------------------------

### pointsToSameAggregateAs usage example

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-types.md

Example of using pointsToSameAggregateAs to compare two associations pointing to the same identifier.

```java
Association<BankAccount, BankAccountId> a = Association.forId(new BankAccountId(7));
Association<BankAccount, BankAccountId> b = Association.forId(new BankAccountId(7));
boolean same = a.pointsToSameAggregateAs(b); // true
```

--------------------------------

### Apply @Module to a package

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-annotations.md

Example of applying the @Module annotation within a package-info.java file to define module metadata.

```java
// package-info.java
@Module(name = "Accounts", description = "Account lifecycle")
package com.acme.bank.account;
```

--------------------------------

### Usage of @Command annotation

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-cqrs-architecture.md

Shows how to apply the @Command annotation to a record, specifying the namespace and name attributes. This example uses a banking domain with a TransferMoney command.

```java
import org.jmolecules.architecture.cqrs.Command;

@Command(namespace = "banking", name = "TransferMoney")
public record TransferMoney(BankAccountId source, BankAccountId target, Amount amount) {}
```

--------------------------------

### Implement a domain event handler

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-events.md

Example of a class using @DomainEventHandler to process a specific domain event.

```java
import org.jmolecules.event.annotation.DomainEventHandler;

class TransferListener {

    @DomainEventHandler
    void on(MoneyTransferred event) {
        // react to the event
    }
}
```

--------------------------------

### SecondaryAdapter usage example

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-hexagonal-architecture.md

Shows a typical usage of @SecondaryAdapter on a Spring component that implements an AccountEventPublisher interface.

```java
@SecondaryAdapter
@Component
public class KafkaAccountEventPublisher implements AccountEventPublisher { /* ... */ }
```

--------------------------------

### Implement Identifiable

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-types.md

Example of implementing the Identifiable interface. The class must provide the getId() method returning the identifier.

```java
public class BankAccount implements Identifiable<BankAccountId> {

    private final BankAccountId id;

    @Override
    public BankAccountId getId() {
        return id;
    }
}
```

--------------------------------

### Implement a @PrimaryAdapter annotated controller

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-hexagonal-architecture.md

Example of using @PrimaryAdapter on a Spring RestController to handle incoming requests.

```java
@PrimaryAdapter
@RestController
public class TransferController {

    private final TransferMoneyUseCase useCase;

    public TransferController(TransferMoneyUseCase useCase) {
        this.useCase = useCase;
    }

    @PostMapping("/transfers")
    void transfer(@RequestBody TransferMoney command) {
        useCase.transfer(command.source(), command.target(), command.amount());
    }
}
```

--------------------------------

### Externalized Usage Example

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-events.md

Example of applying the Externalized annotation to a domain event record.

```java
import org.jmolecules.event.annotation.DomainEvent;
import org.jmolecules.event.annotation.Externalized;

@DomainEvent
@Externalized(target = "account-changed")
public record AccountClosed(BankAccountId id) {}
```

--------------------------------

### Express DDD building blocks with jMolecules annotations

Source: https://github.com/xmolecules/jmolecules/blob/main/readme.adoc

Use these annotations to mark DDD building blocks in a domain model. The example shows @Entity, @Identity, @ValueObject, and @Repository applied to banking types. Prefer domain-language names like BankAccount, Currency, and Accounts over technical suffixes such as Entity or VO.

```java
import org.jmolecules.ddd.annotation.*;

@Entity
class BankAccount {

    @Identity
    final IBAN iban;

    /* ... */

}

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

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

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

--------------------------------

### Usage of @CommandDispatcher annotation

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-cqrs-architecture.md

Shows how to apply the @CommandDispatcher annotation to a method, specifying the dispatches attribute with the command's namespace and name. This example defines a dispatch method in a CommandBus class.

```java
import org.jmolecules.architecture.cqrs.CommandDispatcher;

public class CommandBus {

    @CommandDispatcher(dispatches = "banking.TransferMoney")
    public void dispatch(Command command) { /* ... */ }
}
```

--------------------------------

### Implement Identifier with a record

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-types.md

Example of implementing the Identifier interface with a record. The compiler uses this type in the generic bounds of AggregateRoot, Entity, Association, and Repository.

```java
import org.jmolecules.ddd.types.Identifier;

public record BankAccountId(long value) implements Identifier {}
```

--------------------------------

### Basic usage - declaring a custom stereotype

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jstereotype.md

Shows how to declare a team-specific stereotype using @Stereotype with a name and priority. The example includes the necessary imports and meta-annotations for a custom annotation.

```java
import org.jmolecules.stereotype.Stereotype;

@Stereotype(name = "Use Case", priority = 50)
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface UseCase {}
```

--------------------------------

### Deprecated alias annotation declaration (Command.java)

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-cqrs-architecture.md

Example of the declaration structure of a deprecated alias annotation, as found in annotation/Command.java line 44. It is meta-annotated with the canonical @org.jmolecules.architecture.cqrs.Command and is deprecated. Use the canonical package for new code; this alias is only for migration.

```java
@org.jmolecules.architecture.cqrs.Command
@Deprecated
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Command {
    String namespace() default "";
    String name() default "";
}
```

--------------------------------

### Release Project via Maven

Source: https://github.com/xmolecules/jmolecules/blob/main/readme.adoc

Commands to prepare and perform a release using the Maven release plugin.

```bash
mvn release:prepare -DscmReleaseCommitComment="$ticketId - Release version $version." -DscmDevelopmentCommitComment="$ticketId - Prepare next development iteration."
mvn release:perform -Dgpg.keyname=$keyname
```

--------------------------------

### Package-level Marking via package-info.java

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-onion-architecture.md

Demonstrates how to apply onion architecture annotations at the package level.

```java
// package-info.java (classical)
@DomainModelRing
package org.acmebank.domain;

// package-info.java (simplified)
@DomainRing
package org.acmebank.domain;
```

--------------------------------

### Repository interface

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/kmolecules-ddd.md

Marker interface for repository components.

```kotlin
@Stereotype
interface Repository<T : AggregateRoot<T, ID>, ID : Identifier>
```

--------------------------------

### Class-level Marking

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-onion-architecture.md

Demonstrates how to apply onion architecture annotations to individual classes.

```java
import org.jmolecules.architecture.onion.classical.DomainModelRing;
import org.jmolecules.architecture.onion.classical.DomainServiceRing;
import org.jmolecules.architecture.onion.classical.ApplicationServiceRing;
import org.jmolecules.architecture.onion.classical.InfrastructureRing;

@DomainModelRing
class BankAccount { /* ... */ }

@DomainServiceRing
class MoneyTransfer { /* ... */ }

@ApplicationServiceRing
class TransferApplicationService { /* ... */ }

@InfrastructureRing
class JpaBankAccountRepository { /* ... */ }
```

--------------------------------

### Apply @DomainEvent to a record

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-events.md

Example of using the @DomainEvent annotation on a Java record to define a domain event with a specific namespace and name.

```java
import org.jmolecules.event.annotation.DomainEvent;

@DomainEvent(namespace = "bank", name = "MoneyTransferred")
public record MoneyTransferred(BankAccountId target, Amount amount) {}
```

--------------------------------

### Classical ApplicationServiceRing Annotation

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-onion-architecture.md

Defines the ApplicationServiceRing annotation for the classical onion architecture variant.

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.PACKAGE, ElementType.TYPE })
@Documented
@Stereotype
public @interface ApplicationServiceRing {}
```

--------------------------------

### Entity interface

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/kmolecules-ddd.md

Interface for domain entities, extending Identifiable.

```kotlin
@Stereotype
interface Entity<T : AggregateRoot<T, *>, ID> : Identifiable<ID>
```

--------------------------------

### Identifier interface

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/kmolecules-ddd.md

The base interface for domain identifiers.

```kotlin
@Stereotype
interface Identifier
```

--------------------------------

### Implement ValueObject with a record

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-types.md

Shows a concrete value object implementation using a Java record. The record implements the ValueObject interface and is immutable by design.

```java
import org.jmolecules.ddd.types.ValueObject;

public record Currency(String code) implements ValueObject {}
```

--------------------------------

### Classical DomainServiceRing Annotation

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-onion-architecture.md

Defines the DomainServiceRing annotation for the classical onion architecture variant.

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.PACKAGE, ElementType.TYPE })
@Documented
@Stereotype
public @interface DomainServiceRing {}
```

--------------------------------

### Use the Factory annotation

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-annotations.md

Apply the @Factory annotation to a class that encapsulates the creation logic for domain objects.

```java
import org.jmolecules.ddd.annotation.Factory;

@Factory
class BankAccounts {
    BankAccount openAccount(IBAN iban, Customer customer) { /* ... */ }
}
```

--------------------------------

### Implement DomainEvent in a record

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-events.md

Implementing the DomainEvent interface allows the type system and reflection-based tooling to recognize the event.

```java
import org.jmolecules.event.types.DomainEvent;

public record FundsWithdrawn(BankAccountId accountId, Amount amount) implements DomainEvent {}
```

--------------------------------

### Simplified ApplicationRing Annotation

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-onion-architecture.md

Defines the ApplicationRing annotation for the simplified onion architecture variant.

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.PACKAGE, ElementType.TYPE })
@Documented
@Stereotype
public @interface ApplicationRing {}
```

--------------------------------

### ApplicationLayer annotation declaration

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-layered-architecture.md

Marks a package or type as part of the application layer. Annotating a package-info.java marks the whole package. No attributes.

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.PACKAGE, ElementType.TYPE })
@Documented
@Stereotype
public @interface ApplicationLayer {}
```

--------------------------------

### DomainLayer annotation declaration

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-layered-architecture.md

Marks a package or type as part of the domain layer. Annotating a package-info.java marks the whole package. No attributes.

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.PACKAGE, ElementType.TYPE })
@Documented
@Stereotype
public @interface DomainLayer {}
```

--------------------------------

### @interface Module

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-annotations.md

Identifies a DDD module. Provides attributes for id, name, value, and description to describe the module.

```APIDOC
## @interface Module

### Description
Identifies a DDD module. Same attribute contract as `BoundedContext`, applied to package-level organization of the domain model.

### Declaration
```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.PACKAGE, ElementType.ANNOTATION_TYPE })
@Documented
@Stereotype(priority = 0)
public @interface Module {

	String id() default "";
	String name() default "";
	String value() default "";
	String description() default "";
}
```

### Attributes
| Attribute | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `id` | `String` | no | `""` | Stable identifier; derived from the annotated element (usually a package) if empty; tooling may resolve name/description via resource bundle keys such as `com.acme.myapp.module._name` and `…module_description`. |
| `name` | `String` | no | `""` | Human-readable name; overridable via `id()`; wins against `value()`. |
| `value` | `String` | no | `""` | Alias of `name()`. |
| `description` | `String` | no | `""` | Human-readable description; overridable via `id()`. |

### Usage Example
```java
// package-info.java
@Module(name = "Accounts", description = "Account lifecycle")
package com.acme.bank.account;
```
```

--------------------------------

### Package-level layer marking with package-info.java

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-layered-architecture.md

Package-level marking via package-info.java. All classes in the package are considered part of the domain layer.

```java
// package-info.java
@DomainLayer
package org.acmebank.domain;
```

--------------------------------

### Simplified DomainRing Annotation

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-onion-architecture.md

Defines the DomainRing annotation for the simplified onion architecture variant.

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.PACKAGE, ElementType.TYPE })
@Documented
@Stereotype
public @interface DomainRing {}
```

--------------------------------

### SimpleAssociation implementation

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-types.md

Package-private implementation of Association used by Association.forId(...) and Association.forAggregate(...). The constructor throws IllegalArgumentException for a null supplier, and getId() resolves the identifier lazily on each call. equals() requires the same class and compares identifiers; hashCode() delegates to getId().hashCode().

```java
class SimpleAssociation<T extends AggregateRoot<T, ID>, ID extends Identifier> implements Association<T, ID> {

	private final Supplier<ID> identifier;

	SimpleAssociation(Supplier<ID> identifier) {
		if (identifier == null) {
			throw new IllegalArgumentException("Identifier must not be null!");
		}
		this.identifier = identifier;
	}

	@Override
	public ID getId() {
		return identifier.get();
	}

	@Override
	public String toString() {
		return getId().toString();
	}

	@Override
	public boolean equals(Object obj) {
		if (obj == this) { return true; }
		if (obj == null || !obj.getClass().equals(this.getClass())) { return false; }
		return ((Association<?, ?>) obj).getId().equals(identifier.get());
	}

	@Override
	public int hashCode() {
		return getId().hashCode();
	}
}
```

--------------------------------

### Using attributes to group and rank stereotypes

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jstereotype.md

Demonstrates using the id, name, groups, priority, and inherited attributes of @Stereotype to define a custom stereotype with full metadata.

```java
@Stereotype(
    id = "com.acme.stereotypes.APPLICATION_SERVICE",
    name = "Application Service",
    groups = { "application", "services" },
    priority = 10,
    inherited = true
)
public @interface ApplicationService {}
```

--------------------------------

### Repository annotation class definition

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/kmolecules-ddd.md

Kotlin annotation class for marking repositories. Targets classes only.

```kotlin
@Retention
@MustBeDocumented
@Target(AnnotationTarget.CLASS)
@Stereotype
annotation class Repository
```

--------------------------------

### InfrastructureLayer annotation declaration

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-layered-architecture.md

Marks a package or type as part of the infrastructure layer. Annotating a package-info.java marks the whole package. No attributes.

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.PACKAGE, ElementType.TYPE })
@Documented
@Stereotype
public @interface InfrastructureLayer {}
```

--------------------------------

### Service annotation class definition

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/kmolecules-ddd.md

Kotlin annotation class for marking services. Targets classes only.

```kotlin
@Retention
@MustBeDocumented
@Target(AnnotationTarget.CLASS)
@Stereotype
annotation class Service
```

--------------------------------

### Guard against null identifiers and aggregates

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/errors.md

Demonstrates implementing manual null guards at the call site before invoking Association factory methods to prevent potential runtime issues.

```java
import org.jmolecules.ddd.types.Association;

void safeAssociate(BankAccount account, BankAccountId id) {

    // Guard at the call site instead of catching:
    if (id == null) {
        throw new IllegalArgumentException("Identifier must not be null!");
    }

    Association<BankAccount, BankAccountId> association = Association.forId(id);

    if (account == null) {
        throw new IllegalArgumentException("Aggregate must not be null!");
    }

    association = Association.forAggregate(account);
}
```

--------------------------------

### Annotate Application layer in package-info.java

Source: https://github.com/xmolecules/jmolecules/blob/main/readme.adoc

Place this in package-info.java to mark a package as the Application layer. All classes in the package are then considered part of that layer. Use the layered architecture annotations from jMolecules.

```java
@ApplicationLayer
package org.acmebank.application;

import org.jmolecules.architecture.layered.*;
```

--------------------------------

### Using @AggregateRoot on a class

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-annotations.md

Shows how to apply the @AggregateRoot annotation to a class. The class represents the root entity of an aggregate and is expected to own the invariants.

```java
import org.jmolecules.ddd.annotation.AggregateRoot;

@AggregateRoot
public class BankAccount {
    // invariant-owning root entity
}
```

--------------------------------

### SecondaryAdapter annotation definition

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-hexagonal-architecture.md

Defines the @SecondaryAdapter annotation with attributes name and description. It is meta-annotated with @Adapter and @Stereotype(priority = 200).

```java
@Adapter
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.PACKAGE, ElementType.TYPE })
@Documented
@Stereotype(priority = 200)
public @interface SecondaryAdapter {

	String name() default "";
	String description() default "";
}
```

--------------------------------

### Classical InfrastructureRing Annotation

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-onion-architecture.md

Defines the InfrastructureRing annotation for the classical onion architecture variant.

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.PACKAGE, ElementType.TYPE })
@Documented
@Stereotype
public @interface InfrastructureRing {}
```

--------------------------------

### Annotate Domain layer in package-info.java

Source: https://github.com/xmolecules/jmolecules/blob/main/readme.adoc

Place this in package-info.java to mark a package as the Domain layer. All classes in the package are then considered part of that layer. Use the layered architecture annotations from jMolecules.

```java
@DomainLayer
package org.acmebank.domain;

import org.jmolecules.architecture.layered.*;
```

--------------------------------

### Applying a custom stereotype to a component

Source: https://github.com/xmolecules/jmolecules/wiki/The-Stereotype-Metamodel

Shows how an application component can be assigned the custom stereotype either by annotating it or by implementing the stereotype interface. The comment indicates that either approach can be used.

```java
@com.acme.example.stereotypes.MyCustomStereotype // <- either or …
class MyApplicationComponent implements MyCustomStereotype { … }
```

--------------------------------

### Classical DomainModelRing Annotation

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-onion-architecture.md

Defines the DomainModelRing annotation for the classical onion architecture variant.

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.PACKAGE, ElementType.TYPE })
@Documented
@Stereotype
public @interface DomainModelRing {}
```

--------------------------------

### ValueObject interface

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/kmolecules-ddd.md

Marker interface for value objects.

```kotlin
@Stereotype
interface ValueObject
```

--------------------------------

### Declare Gradle Dependency

Source: https://github.com/xmolecules/jmolecules/blob/main/readme.adoc

Add the jMolecules DDD dependency to your Gradle build file.

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

--------------------------------

### InterfaceLayer annotation declaration

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-layered-architecture.md

Marks a package or type as part of the interface layer. Annotating a package-info.java marks the whole package. No attributes.

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.PACKAGE, ElementType.TYPE })
@Documented
@Stereotype
public @interface InterfaceLayer {}
```

--------------------------------

### SimpleAssociation class

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/kmolecules-ddd.md

A public implementation of Association that resolves the identifier lazily using a lambda.

```kotlin
class SimpleAssociation<T : AggregateRoot<T, ID>, ID : Identifier>(private val identifier: () -> ID) :
        Association<T, ID> {

    override val id: ID
        get() = identifier()

    override fun equals(other: Any?): Boolean {
        if (this === other) return true
        if (javaClass != other?.javaClass) return false

        other as SimpleAssociation<*, *>

        return id == other.id
    }

    override fun hashCode(): Int = id.hashCode()

    override fun toString(): String = id.toString()
}
```

--------------------------------

### Factory annotation class definition

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/kmolecules-ddd.md

Kotlin annotation class for marking factories. Targets classes only.

```kotlin
@Retention
@MustBeDocumented
@Target(AnnotationTarget.CLASS)
@Stereotype
annotation class Factory
```

--------------------------------

### pointsToSameAggregateAs implementation

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/api-reference/jmolecules-ddd-types.md

Implementation of the default method pointsToSameAggregateAs. Throws IllegalArgumentException if the other association is null. Compares only the target identifiers, not type equality.

```java
default boolean pointsToSameAggregateAs(Association<?, ID> other) {

	if (other == null) {
		throw new IllegalArgumentException("Other association must not be null!");
	}

	return getId().equals(other.getId());
}
```

--------------------------------

### Catch IllegalArgumentException for Association creation

Source: https://github.com/xmolecules/jmolecules/blob/main/_autodocs/errors.md

Shows the standard try-catch pattern for handling IllegalArgumentException when attempting to create an Association with a null identifier.

```java
import org.jmolecules.ddd.types.Association;

// Catching the exact documented condition:

try {
    Association.forId(null);
} catch (IllegalArgumentException e) {
    // e.getMessage() == "Identifier must not be null!"
    // the association was not created
}
```

--------------------------------

### Annotate Classes with Architectural Layers

Source: https://github.com/xmolecules/jmolecules/blob/main/readme.adoc

Use @DomainLayer and @ApplicationLayer to explicitly mark classes within a layered architecture.

```java
import org.jmolecules.architecture.layered.*;

@DomainLayer
@Entity
public class BankAccount { /* ... */ }

@ApplicationLayer
@Service
public class TransferMoney { /* ... */ }
```
Tokens:
Raw