Pure logic is easy to compose.
Side effects are hard to compose.

The goal is not to eliminate all side effects.
The goal is to isolate, name, sequence, and test them deliberately.

Mendesain Java components dengan pure core dan explicit effect boundaries sehingga business reasoning, tests, composition, dan API evolution tetap stabil.

Side-effect boundary design:
  ├─ identify side effects
  ├─ classify effect types
  ├─ isolate pure transformations
  ├─ pass time/randomness explicitly
  ├─ separate query from command
  ├─ avoid mutation leaks
  ├─ design deterministic validators/rules
  ├─ make IO boundaries explicit
  ├─ keep domain logic framework-free
  ├─ test pure logic without mocks
  ├─ test effect shell with contracts
  └─ avoid fake functional style

Mapper that writes database
Validator that calls remote service unexpectedly
Predicate that logs/audits/publishes
Supplier that hides network IO
Domain method that reads current time directly
Record that exposes mutable list
Static global state in business rules
Tests full of mocks for simple calculations

Writing database row
Publishing message
Calling remote API
Writing file
Logging
Updating metric
Reading current time
Generating random number
Reading environment variable
Mutating object passed as parameter
Mutating static/global state
Throwing exception for expected branch
Starting thread
Acquiring lock

public static BigDecimal calculatePenalty(BigDecimal principal, BigDecimal rate) {
    return principal.multiply(rate);
}

public BigDecimal calculatePenalty(BigDecimal principal, BigDecimal rate) {
    auditRepository.save(new AuditEntry("calculatePenalty"));
    return principal.multiply(rate);
}

public boolean expired(Deadline deadline) {
    return Instant.now().isAfter(deadline.value());
}

public boolean expired(Deadline deadline, Instant now) {
    return now.isAfter(deadline.value());
}

public final class DeadlineService {
    private final Clock clock;

    public DeadlineService(Clock clock) {
        this.clock = Objects.requireNonNull(clock);
    }

    public boolean expired(Deadline deadline) {
        return deadline.expiredAt(clock.instant());
    }
}

Put business decisions in pure core.
Put IO, time, randomness, persistence, messaging, and framework concerns in shell.

records/value objects
calculators
validators
policies
state transition functions
decision functions
mapping that does not call IO

HTTP controllers
message listeners
repositories
gateways
transaction orchestration
security context reading
clock/uuid/random source
audit/event publishing
logging/metrics/tracing

same input => same output
can test without mocks
can compose safely
can cache if needed
can run in any order if independent
can replay in tests
can document easily

output may depend on hidden state
order matters
retry can duplicate effects
tests need fixtures/mocks
failure semantics more complex
composition can surprise users

DB transaction boundaries
remote API failure
duplicate event publish
time-dependent rules
security context assumptions
hidden mutation
partial success

The more externally visible or irreversible the effect is, the closer it should be to the shell.

public List<Violation> validate(CaseCommand command, List<Violation> violations) {
    if (command.caseId() == null) {
        violations.add(new Violation("caseId", "required"));
    }
    return violations;
}

caller-owned list is mutated
result depends on initial list state
same validator cannot be safely reused without discipline
composition order may leak through shared collection

public ValidationReport validate(CaseCommand command) {
    if (command.caseId() == null) {
        return ValidationReport.failed("caseId", "required");
    }
    return ValidationReport.ok();
}

public ValidationReport validateAll(CaseCommand command, List<CaseValidator> validators) {
    ValidationReport report = ValidationReport.ok();
    for (CaseValidator validator : validators) {
        report = report.merge(validator.validate(command));
    }
    return report;
}

public ValidationReport validateAll(CaseCommand command, List<CaseValidator> validators) {
    List<Violation> violations = new ArrayList<>();
    for (CaseValidator validator : validators) {
        violations.addAll(validator.validate(command).violations());
    }
    return new ValidationReport(List.copyOf(violations));
}

Local mutation is an implementation detail.
Shared mutation is an API contract risk.

public record ValidationReport(List<Violation> violations) {}

public record ValidationReport(List<Violation> violations) {
    public ValidationReport {
        violations = List.copyOf(violations);
    }
}

At API boundaries, copy mutable inputs unless ownership transfer is explicitly documented.

public EligibilityDecision evaluate(CaseFile file) {
    if (file.deadline().isBefore(Instant.now())) {
        return EligibilityDecision.denied("DEADLINE_EXPIRED");
    }
    return EligibilityDecision.allowed();
}

public EligibilityDecision evaluate(CaseFile file, Instant now) {
    if (file.deadline().isBefore(now)) {
        return EligibilityDecision.denied("DEADLINE_EXPIRED");
    }
    return EligibilityDecision.allowed();
}

public final class CaseEligibilityService {
    private final Clock clock;
    private final CaseEligibilityPolicy policy;

    public CaseEligibilityService(Clock clock, CaseEligibilityPolicy policy) {
        this.clock = Objects.requireNonNull(clock);
        this.policy = Objects.requireNonNull(policy);
    }

    public EligibilityDecision evaluate(CaseFile file) {
        return policy.evaluate(file, clock.instant());
    }
}

@Test
void deniesWhenDeadlineExpired() {
    Instant now = Instant.parse("2026-06-30T10:00:00Z");
    CaseFile file = new CaseFile(Instant.parse("2026-06-30T09:59:59Z"));

    EligibilityDecision decision = policy.evaluate(file, now);

    assertEquals(EligibilityDecision.denied("DEADLINE_EXPIRED"), decision);
}

public CaseId newCaseId() {
    return new CaseId(UUID.randomUUID().toString());
}

@FunctionalInterface
public interface IdGenerator<T> {
    T nextId();
}

public final class UuidCaseIdGenerator implements IdGenerator<CaseId> {
    @Override
    public CaseId nextId() {
        return new CaseId(UUID.randomUUID().toString());
    }
}

public final class CaseFactory {
    private final IdGenerator<CaseId> idGenerator;
    private final Clock clock;

    public CaseFactory(IdGenerator<CaseId> idGenerator, Clock clock) {
        this.idGenerator = Objects.requireNonNull(idGenerator);
        this.clock = Objects.requireNonNull(clock);
    }

    public CaseFile open(NewCaseRequest request) {
        return new CaseFile(
            idGenerator.nextId(),
            request.subject(),
            clock.instant(),
            CaseStatus.OPEN
        );
    }
}

Randomness is an input source. Treat it like dependency, not invisible magic.

public CaseFile findCase(CaseId id) {
    CaseFile file = repository.find(id);
    auditRepository.save(new AuditEntry("case viewed"));
    return file;
}

public CaseFile viewCase(CaseId id, Actor actor) {
    CaseFile file = repository.find(id);
    auditRepository.save(AuditEntry.caseViewed(id, actor.id(), clock.instant()));
    return file;
}

public CaseFile findCase(CaseId id) {
    return repository.find(id);
}

public void recordCaseViewed(CaseId id, Actor actor) {
    auditRepository.save(AuditEntry.caseViewed(id, actor.id(), clock.instant()));
}

A method that writes should not look like a harmless query unless the write is a documented part of the query semantics.

public interface Validator<T> {
    ValidationReport validate(T value);
}

Validator<CaseCommand> requireReason = command ->
    command.reason() == null || command.reason().isBlank()
        ? ValidationReport.failed("reason", "required")
        : ValidationReport.ok();

Validator<CaseCommand> caseMustExist = command ->
    repository.exists(command.caseId())
        ? ValidationReport.ok()
        : ValidationReport.failed("caseId", "case does not exist");

public interface CaseExistencePolicy {
    ValidationReport evaluate(CaseCommand command);
}

public ValidationReport validateCaseReference(CaseCommand command, Set<CaseId> existingCaseIds) {
    return existingCaseIds.contains(new CaseId(command.caseId()))
        ? ValidationReport.ok()
        : ValidationReport.failed("caseId", "case does not exist");
}

Set<CaseId> existing = caseRepository.findExistingIds(List.of(command.caseId()));
ValidationReport report = validator.validateCaseReference(command, existing);

If validation performs IO, name and place it as policy/check boundary, not simple validator.

public CaseDto toDto(CaseFile file) {
    accessLogRepository.save(...);
    return new CaseDto(...);
}

CaseDto dto = mapper.toDto(file);
auditSink.record(AuditEvent.caseViewed(file.id(), actor.id()));

public CaseDto viewCase(CaseId id, Actor actor) {
    CaseFile file = repository.get(id);
    auditSink.record(AuditEvent.caseViewed(id, actor.id(), clock.instant()));
    return mapper.toDto(file);
}

A mapper maps.
An auditor audits.
An orchestrator decides order.

Function<String, String> trim = String::trim;
Function<String, String> upper = s -> s.toUpperCase(Locale.ROOT);

Consumer<CaseFile> log = file -> logger.info("case {}", file.id());
Consumer<CaseFile> publish = file -> publisher.publish(CaseViewed.of(file.id()));

Consumer<CaseFile> effect = log.andThen(publish);

If log succeeds and publish fails, should operation fail?
If publish succeeds and log fails, should operation fail?
If retry happens, can duplicate publish occur?
Is log part of business outcome or diagnostics only?

Do not compose irreversible effects casually with Consumer.andThen unless failure semantics are acceptable and documented.

public interface CaseRepository {
    Optional<CaseFile> findById(CaseId id);
    void save(CaseFile file);
}

public interface CaseEventPublisher {
    void publish(CaseEvent event);
}

public interface AuditSink {
    void record(AuditEvent event);
}

public final class ApproveCaseService {
    private final CaseRepository repository;
    private final CaseApprovalPolicy policy;
    private final CaseEventPublisher publisher;
    private final AuditSink auditSink;
    private final Clock clock;

    public ApproveCaseService(
        CaseRepository repository,
        CaseApprovalPolicy policy,
        CaseEventPublisher publisher,
        AuditSink auditSink,
        Clock clock
    ) {
        this.repository = Objects.requireNonNull(repository);
        this.policy = Objects.requireNonNull(policy);
        this.publisher = Objects.requireNonNull(publisher);
        this.auditSink = Objects.requireNonNull(auditSink);
        this.clock = Objects.requireNonNull(clock);
    }

    public ApprovalResult approve(ApproveCaseCommand command, Actor actor) {
        CaseFile file = repository.findById(command.caseId())
            .orElseThrow(() -> new CaseNotFoundException(command.caseId()));

        ApprovalDecision decision = policy.decide(file, actor, clock.instant());
        if (decision instanceof ApprovalDecision.Denied denied) {
            return ApprovalResult.denied(denied.reason());
        }

        CaseFile approved = file.approve(actor.id(), clock.instant());
        repository.save(approved);
        publisher.publish(CaseEvent.approved(approved.id()));
        auditSink.record(AuditEvent.caseApproved(approved.id(), actor.id()));

        return ApprovalResult.approved(approved.id());
    }
}

public interface CaseApprovalPolicy {
    ApprovalDecision decide(CaseFile file, Actor actor, Instant now);
}

public final class CaseApprovalRules {
    public ApprovalDecision decide(CaseFile file, Actor actor, Instant now) {
        if (!file.isOpen()) {
            return ApprovalDecision.denied("CASE_NOT_OPEN");
        }
        if (!actor.hasPermission("CASE_APPROVE")) {
            return ApprovalDecision.denied("MISSING_PERMISSION");
        }
        if (file.deadline().isBefore(now)) {
            return ApprovalDecision.denied("DEADLINE_EXPIRED");
        }
        return ApprovalDecision.allowed();
    }
}

no hidden mutable state
no IO
no clock read inside
same input => same output

public final class CaseApprovalApplicationService {
    private final CaseRepository repository;
    private final CaseApprovalRules rules;
    private final Clock clock;

    // coordinates effects
}

Functional core is about determinism, not syntax.

public Money add(Money other) {
    Objects.requireNonNull(other, "other must not be null");
    if (!currency.equals(other.currency)) {
        throw new IllegalArgumentException("currency mismatch");
    }
    return new Money(amount.add(other.amount), currency);
}

public void approve(CaseFile file) throws CaseNotEligibleException {
    if (!file.isEligible()) {
        throw new CaseNotEligibleException(...);
    }
}

public ApprovalDecision decide(CaseFile file) {
    if (!file.isEligible()) {
        return ApprovalDecision.denied("NOT_ELIGIBLE");
    }
    return ApprovalDecision.allowed();
}

invalid programmer input
broken invariant
unexpected infrastructure failure
contract violation
unrecoverable adapter failure

validation failed
authorization denied
business rule rejected
not eligible
conflict expected by workflow

repository.save(approved);
publisher.publish(CaseEvent.approved(approved.id()));

Effectful methods should reveal whether they are safe to retry.
Commands should carry idempotency keys when duplicate execution matters.
Pure functions do not need idempotency keys because they do not cause external effects.

public record ApproveCaseCommand(
    CaseId caseId,
    String reason,
    IdempotencyKey idempotencyKey
) {}

public interface CaseCommandStore {
    boolean alreadyProcessed(IdempotencyKey key);
    void markProcessed(IdempotencyKey key, ApprovalResult result);
}

Once an API performs externally visible writes, retry semantics are part of the contract.

Supplier<ExchangeRate> rate = exchangeRateClient::latestRate;

public PriceCalculator(Supplier<ExchangeRate> exchangeRateSupplier) { ... }

called per calculation or once?
may throw?
should be cached?
must be thread-safe?
can block?

public interface ExchangeRateProvider {
    ExchangeRate currentRate(Currency from, Currency to);
}

Supplier is fine for simple deferred values.
For effectful retrieval, prefer named provider/gateway interface.

com.acme.caseapproval
  ├─ api
  │   ├─ ApproveCaseCommand.java
  │   └─ ApprovalResult.java
  ├─ domain
  │   ├─ CaseFile.java
  │   ├─ CaseApprovalRules.java
  │   └─ ApprovalDecision.java
  ├─ application
  │   └─ ApproveCaseService.java
  ├─ port
  │   ├─ CaseRepository.java
  │   ├─ CaseEventPublisher.java
  │   └─ AuditSink.java
  └─ adapter
      ├─ JdbcCaseRepository.java
      ├─ KafkaCaseEventPublisher.java
      └─ StructuredAuditSink.java

domain should not depend on adapter
port should not depend on adapter
domain rules should not read database directly
application coordinates effects
adapter implements effects

@Test
void approvalDeniedWhenCaseClosed() {
    CaseApprovalRules rules = new CaseApprovalRules();
    CaseFile closed = CaseFile.closed(new CaseId("C-1"));
    Actor actor = Actor.withPermission("CASE_APPROVE");
    Instant now = Instant.parse("2026-06-30T10:00:00Z");

    ApprovalDecision decision = rules.decide(closed, actor, now);

    assertEquals(ApprovalDecision.denied("CASE_NOT_OPEN"), decision);
}

@Test
void approvePersistsPublishesAndAuditsWhenAllowed() {
    InMemoryCaseRepository repository = new InMemoryCaseRepository();
    RecordingPublisher publisher = new RecordingPublisher();
    RecordingAuditSink audit = new RecordingAuditSink();
    Clock clock = Clock.fixed(Instant.parse("2026-06-30T10:00:00Z"), ZoneOffset.UTC);

    ApproveCaseService service = new ApproveCaseService(
        repository,
        new CaseApprovalRules(),
        publisher,
        audit,
        clock
    );

    repository.save(CaseFile.open(new CaseId("C-1")));

    ApprovalResult result = service.approve(
        new ApproveCaseCommand(new CaseId("C-1"), "valid reason"),
        Actor.withPermission("CASE_APPROVE")
    );

    assertTrue(result.approved());
    assertEquals(1, publisher.events().size());
    assertEquals(1, audit.events().size());
}

public ApprovalResult approve(String caseId, String actorId) {
    CaseFile file = repository.find(caseId);

    if (!securityContext.currentUser().id().equals(actorId)) {
        logger.warn("actor mismatch");
        return ApprovalResult.denied("ACTOR_MISMATCH");
    }

    if (file.deadline().isBefore(Instant.now())) {
        auditRepository.save(new AuditEntry(caseId, "deadline expired"));
        return ApprovalResult.denied("DEADLINE_EXPIRED");
    }

    file.setStatus("APPROVED");
    file.setApprovedAt(Instant.now());
    repository.save(file);
    eventBus.publish(new CaseApprovedEvent(caseId));
    return ApprovalResult.approved(caseId);
}

stringly typed status
hidden security context
direct time access twice
mutation of entity state
business rule mixed with audit/repository/event bus
hard to test without mocks
hard to replay deterministically

public final class CaseApprovalPolicy {
    public ApprovalDecision decide(CaseFile file, Actor actor, Instant now) {
        if (!actor.hasPermission("CASE_APPROVE")) {
            return ApprovalDecision.denied("MISSING_PERMISSION");
        }
        if (file.deadline().isBefore(now)) {
            return ApprovalDecision.denied("DEADLINE_EXPIRED");
        }
        return ApprovalDecision.allowed();
    }
}

public record CaseFile(
    CaseId id,
    CaseStatus status,
    Instant deadline,
    Instant approvedAt
) {
    public CaseFile approve(Instant approvedAt) {
        if (status != CaseStatus.OPEN) {
            throw new IllegalStateException("Only OPEN case can be approved");
        }
        return new CaseFile(id, CaseStatus.APPROVED, deadline, approvedAt);
    }
}

public ApprovalResult approve(ApproveCaseCommand command, Actor actor) {
    Instant now = clock.instant();
    CaseFile file = repository.get(command.caseId());

    ApprovalDecision decision = policy.decide(file, actor, now);
    if (decision instanceof ApprovalDecision.Denied denied) {
        auditSink.record(AuditEvent.approvalDenied(file.id(), actor.id(), denied.code(), now));
        return ApprovalResult.denied(denied.code());
    }

    CaseFile approved = file.approve(now);
    repository.save(approved);
    publisher.publish(CaseEvent.approved(approved.id(), now));
    auditSink.record(AuditEvent.caseApproved(approved.id(), actor.id(), now));

    return ApprovalResult.approved(approved.id());
}

policy is pure
clock read once
effects are visible
state transition is explicit
expected denial is result, not exception

public final class CaseDraft {
    private final List<Attachment> attachments = new ArrayList<>();

    public void addAttachment(Attachment attachment) {
        attachments.add(Objects.requireNonNull(attachment));
    }
}

object owns the state
invariants are preserved
state is not shared unsafely
method name signals command
lifecycle is controlled

Mutation is acceptable when ownership is clear.
Mutation is dangerous when ownership is shared or hidden behind query-like names.

client.request()
    .withHeader("X", "Y")
    .body(payload)
    .send();

pipeline
    .validate(command)
    .audit()
    .approve();

ApprovalPlan plan = approvalPlanner.plan(command, actor);
ApprovalResult result = approvalExecutor.execute(plan);

ApprovalResult result = approvalFlow
    .forCommand(command)
    .as(actor)
    .execute();

A fluent chain should distinguish configuration/building from execution/effects.

/**
 * Normalizes the command without performing IO or mutating the supplied command.
 *
 * @param command command to normalize, must not be null
 * @return normalized command, never null
 */
CaseCommand normalize(CaseCommand command);

/**
 * Publishes the event to the configured external event channel.
 *
 * <p>This method may block and may throw EventPublishException if the event
 * cannot be accepted by the underlying channel. Implementations should be
 * idempotent with respect to eventId when possible.</p>
 */
void publish(CaseEvent event);

Does it perform IO?
Can it block?
Can it mutate input?
Can it throw?
Is it retry-safe?
Is it thread-safe?
When is supplied behavior invoked?
Does it cache results?

1. Does method name reveal whether it is query or command?
2. Does business logic read time/randomness directly?
3. Does mapper/validator/predicate perform IO?
4. Does any function mutate caller-owned collection/object?
5. Are mutable inputs copied at boundaries?
6. Are expected business failures represented as result objects?
7. Are effect ordering and retry semantics clear?
8. Are side effects near shell/application layer?
9. Can pure rules be tested without mocks?
10. Are effectful ports named by domain capability?
11. Does fluent API clearly separate build from execute?
12. Are Supplier/Consumer uses hiding expensive or irreversible behavior?

Function<Command, Command> f = command -> {
    repository.save(command);
    return command;
};

return deadline.isBefore(Instant.now());

record Report(List<String> lines) {}

boolean allowed = policy.allowed(actor, command);

audit.andThen(publish).andThen(save).accept(event);

Cari 3 method yang membaca Instant.now(), UUID.randomUUID(), atau System.getenv() di tengah business logic.
Refactor agar time/randomness/config menjadi dependency atau explicit input.

Ambil validator yang return boolean.
Ubah menjadi ValidationReport dengan diagnostics.
Pastikan validator pure.

Ambil mapper yang punya side effect.
Pisahkan mapper dan auditor/publisher.
Buat orchestrator yang menentukan order.

Review satu fluent API.
Tandai method mana yang hanya konfigurasi dan mana yang mengeksekusi side effect.
Rename jika ambiguous.

Buat package boundary:
  - domain pure
  - port effect interface
  - application orchestration
  - adapter implementation
Pastikan dependency direction tidak bocor.

Keep business decisions pure when practical.
Move IO/time/randomness to explicit boundaries.
Prefer result objects for expected domain outcomes.
Do not hide writes inside mappers, validators, predicates, or suppliers.
Copy mutable inputs at API boundaries.
Make effect order and retry semantics visible.
Use application services as orchestration shells.

Composition is easy when behavior is deterministic.
Boundary design is the discipline that keeps it deterministic.