En esta guía (49 elementos)

Java Code Style

MANDATORY FOR ALL AI AGENTS: When generating Java code for this project, you MUST follow every convention listed below. Java code MUST maintain the same hexagonal architecture boundaries as Kotlin code. Domain and application layers MUST remain framework-free.

This document defines concrete conventions for Java code in this repository. Where not specified, follow the official Google Java Style Guide and Spring Boot recommendations. This guide mirrors the Kotlin Code Style with Java-specific idioms.

Targets

Readability first: prefer clarity over brevity.
Domain purity: domain and use cases are free from framework dependencies.
Deterministic formatting: enforced by tooling (recommend Spotless with google-java-format or Checkstyle).
Kotlin interop: Java code must integrate seamlessly with existing Kotlin code across module boundaries.

Formatting

Max line length: 120. Break method chains and parameter lists sensibly.
Indentation: 4 spaces. No tabs.
Braces: always use braces for control flow, even single-line bodies.
Imports: no wildcard imports (import java.util.* is forbidden). Keep imports sorted: java.*, jakarta.*, then third-party, then project.
Imports: javax.* is forbidden (except JDK packages such as javax.sql, javax.crypto); use jakarta.*.
Annotations: one per line when parameters are present; otherwise inline is acceptable.
Blank lines: one blank line between methods, two blank lines between major sections (fields, constructors, methods).

1
// GOOD - always use braces
2
if (user.isEnabled()) {
3
    return user;
4
}
5

6
// BAD - no braces
7
if (user.isEnabled()) return user;

Kotlin equivalent:

1
// Same rule applies in Kotlin
2
if (user.isEnabled()) {
3
    return user
4
}

Naming

Packages: all lowercase, no underscores (e.g., com.example.platform.domain).
Classes/Interfaces: PascalCase (CreateUserUseCase, UserRepositoryAdapter).
Methods/Variables: lowerCamelCase (createUser, contactEmail).
Constants: UPPER_SNAKE_CASE in static final fields or enum values.
Suffixes follow the hexagonal architecture boundaries:
- Request / Response for REST/GraphQL DTOs.
- Entity for persistence models.
- Mapper for mapping classes.
- Adapter for infrastructure adapters.
- Port for port interfaces.
- UseCase for application use case implementations.
- Command for use case input objects.

`record` vs `class`

When to use `record`

Use record for DTOs, value objects, commands, and simple immutable data carriers. Records provide automatic equals(), hashCode(), toString(), and accessor methods.

1
// DTO - REST request
2
public record CreateUserRequest(
3
    @NotBlank(message = "Username is required")
4
    @Size(min = 3, max = 50, message = "Username must be between 3 and 50 characters")
5
    String username,
6

7
    @NotBlank(message = "Email is required")
8
    @Email(message = "Email must be valid")
9
    String email,
10

11
    @NotBlank(message = "First name is required")
12
    String firstName,
13

14
    @NotBlank(message = "Last name is required")
15
    String lastName,
16

17
    @NotEmpty(message = "At least one role is required")
18
    List<String> roles,
19

20
    boolean enabled
21
) {}
22

23
// Command - application layer
24
public record CreateUserCommand(
25
    UUID organizationId,
26
    String username,
27
    String email,
28
    String firstName,
29
    String lastName,
30
    List<String> roles,
31
    boolean enabled
32
) {}
33

34
// Value object - domain layer
35
public record ContactInfo(
36
    String email,
37
    String phone
38
) {
39
    // Compact constructor for validation
40
    public ContactInfo {
41
        if (email == null || email.isBlank()) {
42
            throw new IllegalArgumentException("Email must not be blank");
43
        }
44
    }
45
}
46

47
// Response DTO
48
public record CreatedUserResponse(
49
    UUID id,
50
    LocalDateTime createdAt
51
) {}

Kotlin equivalent:

1
// In Kotlin, use data class for the same purpose
2
data class CreateUserCommand(
3
    val organizationId: UUID,
4
    val username: String,
5
    val email: String,
6
    val firstName: String,
7
    val lastName: String,
8
    val roles: List<String>,
9
    val enabled: Boolean,
10
)

When to use `class`

Use a regular class for rich domain models with behavior, entities with identity, and objects requiring explicit control over equality, mutability, or lifecycle.

1
// Domain entity with behavior
2
public class Organization {
3

4
    private final UUID id;
5
    private final String name;
6
    private final String contactName;
7
    private final String contactLastName;
8
    private final String contactEmail;
9
    private final String contactPhone;
10
    private final OrganizationStatus status;
11
    private final String logoUrl;
12
    private final String websiteUrl;
13
    private final LocalDateTime createdAt;
14
    private final String createdBy;
15
    private final LocalDateTime updatedAt;
16
    private final String updatedBy;
17

18
    public Organization(UUID id, String name, String contactName,
19
                        String contactLastName, String contactEmail,
20
                        String contactPhone, OrganizationStatus status,
21
                        String logoUrl, String websiteUrl,
22
                        LocalDateTime createdAt, String createdBy,
23
                        LocalDateTime updatedAt, String updatedBy) {
24
        this.id = id;
25
        this.name = name;
26
        this.contactName = contactName;
27
        this.contactLastName = contactLastName;
28
        this.contactEmail = contactEmail;
29
        this.contactPhone = contactPhone;
30
        this.status = status;
31
        this.logoUrl = logoUrl;
32
        this.websiteUrl = websiteUrl;
33
        this.createdAt = createdAt;
34
        this.createdBy = createdBy;
35
        this.updatedAt = updatedAt;
36
        this.updatedBy = updatedBy;
37
    }
38

39
    // Business behavior — returns a new instance, enforces transition rules.
40
    // NEVER expose `setStatus`. Every status change goes through this method.
41
    public Organization transitionTo(OrganizationStatus target) {
42
        if (!status.canTransitionTo(target)) {
43
            throw new IllegalStateException(
44
                "Illegal transition: " + status + " → " + target);
45
        }
46
        return new Organization(
47
            this.id, this.name, this.contactName, this.contactLastName,
48
            this.contactEmail, this.contactPhone, target,
49
            this.logoUrl, this.websiteUrl,
50
            this.createdAt, this.createdBy,
51
            this.updatedAt, this.updatedBy
52
        );
53
    }
54

55
    public boolean isActive() {
56
        return status == OrganizationStatus.ACTIVE;
57
    }
58

59
    // Explicit getters only (no setters)
60
    public UUID getId() { return id; }
61
    public String getName() { return name; }
62
    public OrganizationStatus getStatus() { return status; }
63
    // ... remaining getters
64
}

Kotlin equivalent:

1
// Aggregate root — regular class (NOT data class). data class exposes copy(...)
2
// which lets callers bypass `transitionTo` and the canTransitionTo guard.
3
class Organization private constructor(
4
    val id: UUID,
5
    val name: String,
6
    val contactName: String,
7
    val status: OrganizationStatus,
8
    // ...
9
) {
10
    fun transitionTo(target: OrganizationStatus): Organization {
11
        check(status.canTransitionTo(target)) { "Illegal transition: $status → $target" }
12
        return Organization(id, name, contactName, target /*, ... */)
13
    }
14

15
    fun isActive(): Boolean = status == OrganizationStatus.ACTIVE
16
}

Decision matrix

Use `record` when…	Use `class` when…
Pure data carrier (DTO, command, event)	Rich domain model with business behavior
No mutable state needed	Explicit control over equality/identity
Auto-generated equals/hashCode is fine	Need builder pattern for many optional fields
Fewer than ~10 fields	Entity with lifecycle (creation, state changes)
Cross-layer mapping input/output	Need inheritance or abstract behavior

Immutability

Immutability is a core principle. All domain objects, commands, and DTOs must be immutable.

All fields final. No setters.
Use record for simple cases (automatically final).
Use builder pattern for complex objects with many optional fields.
Use List.of(), Map.of(), Set.of() or Collections.unmodifiableList() for collections.

The next example is a builder pattern demo for assembling immutable objects with many fields, not a domain-entity template. As-shown, User is anemic. For a real aggregate root: keep the builder, but add behavior (activate(), assignRole(...), disable(...)), enforce invariants in build(), and refuse to publish a setter.

1
// GOOD - immutable container assembled via builder
2
public class User {
3

4
    private final UUID id;
5
    private final UUID organizationId;
6
    private final String username;
7
    private final String email;
8
    private final String firstName;
9
    private final String lastName;
10
    private final List<String> roles;
11
    private final boolean enabled;
12

13
    private User(Builder builder) {
14
        this.id = builder.id;
15
        this.organizationId = builder.organizationId;
16
        this.username = builder.username;
17
        this.email = builder.email;
18
        this.firstName = builder.firstName;
19
        this.lastName = builder.lastName;
20
        this.roles = List.copyOf(builder.roles); // defensive copy
21
        this.enabled = builder.enabled;
22
    }
23

24
    public static Builder builder() {
25
        return new Builder();
26
    }
27

28
    // Only getters - no setters
29
    public UUID getId() { return id; }
30
    public List<String> getRoles() { return roles; } // already unmodifiable
31

32
    public static class Builder {
33
        private UUID id;
34
        private UUID organizationId;
35
        private String username;
36
        private String email;
37
        private String firstName;
38
        private String lastName;
39
        private List<String> roles = List.of();
40
        private boolean enabled = true;
41

42
        public Builder id(UUID id) { this.id = id; return this; }
43
        public Builder organizationId(UUID id) { this.organizationId = id; return this; }
44
        public Builder username(String username) { this.username = username; return this; }
45
        public Builder email(String email) { this.email = email; return this; }
46
        public Builder firstName(String fn) { this.firstName = fn; return this; }
47
        public Builder lastName(String ln) { this.lastName = ln; return this; }
48
        public Builder roles(List<String> roles) { this.roles = roles; return this; }
49
        public Builder enabled(boolean enabled) { this.enabled = enabled; return this; }
50

51
        public User build() {
52
            return new User(this);
53
        }
54
    }
55
}

1
// GOOD - immutable collections
2
var users = List.of(user1, user2, user3);
3
var config = Map.of("key1", "value1", "key2", "value2");
4
var tags = Set.of("admin", "active");
5

6
// BAD - mutable collections leaking
7
public List<String> getRoles() {
8
    return this.roles; // if roles is an ArrayList, caller can modify it
9
}
10

11
// GOOD - defensive copy or unmodifiable
12
public List<String> getRoles() {
13
    return Collections.unmodifiableList(this.roles);
14
}

Kotlin equivalent:

1
// Kotlin achieves immutability naturally with val. Use `data class` ONLY if this is a
2
// DTO/payload (e.g. `UserPayload`). For a domain aggregate root, prefer a regular class
3
// with private ctor + factory + behavior (`activate`, `assignRole`, etc.) — see the
4
// "data class vs regular class" rules at the top of this file's companion in
5
// kotlin-code-style.md.
6
data class UserPayload(
7
    val id: UUID,
8
    val organizationId: UUID,
9
    val username: String,
10
    val email: String,
11
    val firstName: String,
12
    val lastName: String,
13
    val roles: List<String> = listOf(),
14
    val enabled: Boolean = true,
15
)

Null Safety

Java lacks built-in null safety, so discipline and annotations are critical.

Rules

Use @NonNull and @Nullable annotations from org.jspecify.annotations on public APIs (JSpecify, the standard adopted by Spring 7 / Boot 3.4+; org.springframework.lang is deprecated).
Use Optional<T> as a return type only. Never use Optional as a method parameter, field, or collection element.
Never return null for collections. Return List.of(), Set.of(), or Map.of() instead.
Never return null for error signaling. Throw domain-specific exceptions or return Optional.
Validate constructor arguments with Objects.requireNonNull() for non-nullable fields.

1
import org.jspecify.annotations.NonNull;
2
import org.jspecify.annotations.Nullable;
3

4
public class UserRepositoryAdapter implements UserRepositoryPort {
5

6
    // GOOD - Optional for return type when value may be absent
7
    @Override
8
    public Optional<User> findById(@NonNull UUID id) {
9
        Objects.requireNonNull(id, "User ID must not be null");
10
        return jdbcRepository.findById(id)
11
            .map(EntityMapper::toDomain);
12
    }
13

14
    // GOOD - never return null for collections
15
    @Override
16
    @NonNull
17
    public List<User> findByOrganizationId(@NonNull UUID organizationId) {
18
        return jdbcRepository.findByOrganizationId(organizationId)
19
            .stream()
20
            .map(EntityMapper::toDomain)
21
            .toList(); // returns empty list if none found, never null
22
    }
23

24
    // BAD - returning null instead of Optional or empty collection
25
    public User findById(UUID id) {
26
        return null; // caller must null-check -- error-prone
27
    }
28
}

1
// GOOD - constructor validation
2
public class Organization {
3

4
    private final UUID id;
5
    private final String name;
6

7
    public Organization(@NonNull UUID id, @NonNull String name) {
8
        this.id = Objects.requireNonNull(id, "Organization ID must not be null");
9
        this.name = Objects.requireNonNull(name, "Organization name must not be null");
10
    }
11
}

Kotlin equivalent:

1
// Kotlin's type system handles nullability natively
2
fun findById(id: UUID): User?             // nullable return
3
fun findByOrganizationId(id: UUID): List<User>  // non-null, may be empty

`@FunctionalInterface`

Use @FunctionalInterface for single-method contracts. This is the Java equivalent of Kotlin’s fun interface.

1
// Application layer - transaction port
2
@FunctionalInterface
3
public interface TransactionPort<R> {
4
    R run(TransactionCallbackPort<R> callback);
5
}
6

7
@FunctionalInterface
8
public interface TransactionCallbackPort<R> {
9
    R call();
10
}

1
// Infrastructure layer - implementation
2
@Component
3
public class JdbcTransaction<R> implements TransactionPort<R> {
4

5
    @Override
6
    @Transactional(propagation = Propagation.REQUIRED, rollbackFor = Exception.class)
7
    public R run(TransactionCallbackPort<R> callback) {
8
        return callback.call();
9
    }
10
}

1
// Use case usage - lambda syntax works because of @FunctionalInterface
2
public class CreateUserUseCase implements CreateUserPort {
3

4
    private final TransactionPort<User> transaction;
5
    private final UserRepositoryPort userRepository;
6
    private final UserPublisherPort userPublisher;
7

8
    public CreateUserUseCase(TransactionPort<User> transaction,
9
                             UserRepositoryPort userRepository,
10
                             UserPublisherPort userPublisher) {
11
        this.transaction = transaction;
12
        this.userRepository = userRepository;
13
        this.userPublisher = userPublisher;
14
    }
15

16
    @Override
17
    public User execute(CreateUserCommand command) {
18
        return transaction.run(() -> {
19
            User user = userRepository.save(CommandMapper.toUser(command));
20
            log.info("Created user with ID: {}", user.getId());
21
            userPublisher.publishCreated(user);
22
            return user;
23
        });
24
    }
25
}

Kotlin equivalent:

1
// Kotlin uses fun interface
2
fun interface TransactionPort<R> {
3
    fun run(callback: TransactionCallbackPort<R>): R
4
}
5

6
// Usage with lambda
7
val result = transaction.run { repository.save(entity) }

When to use `@FunctionalInterface` vs regular interface

Use `@FunctionalInterface` when…	Use regular `interface` when…
Single abstract method	Multiple methods needed
Lambda usage desired (callbacks, strategies)	Complex contract with default methods
Transaction, event, or callback boundaries	Repository ports with multiple operations

Mapper Pattern

Java lacks extension functions, so use static methods in dedicated mapper classes. Each architectural boundary has its own mapper class.

CommandMapper (Application Layer)

Maps commands to domain objects.

1
public final class CommandMapper {
2

3
    private CommandMapper() {
4
        // Utility class - prevent instantiation
5
    }
6

7
    public static User toUser(CreateUserCommand command) {
8
        return User.builder()
9
            .id(UUID.randomUUID())
10
            .organizationId(command.organizationId())
11
            .username(command.username())
12
            .email(command.email())
13
            .firstName(command.firstName())
14
            .lastName(command.lastName())
15
            .roles(List.of())
16
            .enabled(command.enabled())
17
            .build();
18
    }
19
}

Kotlin equivalent:

1
// Kotlin uses extension functions -- more fluent
2
fun CreateUserCommand.toUser(): User = User(
3
    id = UUID.randomUUID(),
4
    organizationId = this.organizationId,
5
    username = this.username,
6
    email = this.email,
7
    firstName = this.firstName,
8
    lastName = this.lastName,
9
    roles = listOf(),
10
    enabled = this.enabled,
11
)

EntityMapper (Infrastructure Layer)

Maps between domain objects and persistence entities.

1
public final class EntityMapper {
2

3
    private EntityMapper() {
4
        // Utility class - prevent instantiation
5
    }
6

7
    // For aggregate roots, prefer a dedicated `User.rehydrate(...)` static factory
8
    // over `User.builder()`. The builder is open-ended and lets infrastructure code
9
    // reconstruct arbitrary states; `rehydrate(...)` is the named, intentional escape
10
    // hatch reserved for the persistence boundary and validates structural invariants.
11
    public static User toDomain(UserEntity entity) {
12
        return User.rehydrate(
13
            entity.getId(),
14
            entity.getOrganizationId(),
15
            entity.getUsername(),
16
            new Email(entity.getEmail()),
17
            entity.getFirstName(),
18
            entity.getLastName(),
19
            entity.getRoles() != null ? List.copyOf(entity.getRoles()) : List.of(),
20
            entity.isEnabled(),
21
            entity.getVersion()
22
        );
23
    }
24

25
    public static UserEntity toEntityForInsert(User user) {
26
        var entity = new UserEntity();
27
        entity.setId(user.getId());
28
        entity.setOrganizationId(user.getOrganizationId());
29
        entity.setUsername(user.getUsername());
30
        entity.setEmail(user.getEmail().value());
31
        entity.setFirstName(user.getFirstName());
32
        entity.setLastName(user.getLastName());
33
        entity.setNew(true); // For Spring Data JDBC Persistable
34
        return entity;
35
    }
36
}

Kotlin equivalent:

1
// Kotlin uses extension functions. Aggregate roots have private ctors,
2
// so the mapper calls a dedicated `rehydrate(...)` factory on the companion.
3
fun UserEntity.toDomain(): User = User.rehydrate(
4
    id             = this.id!!,
5
    organizationId = this.organizationId,
6
    username       = this.username,
7
    email          = Email(this.email),
8
    firstName      = this.firstName,
9
    lastName       = this.lastName,
10
    roles          = this.roles.orEmpty().toList(),
11
    enabled        = this.enabled,
12
    version        = this.version,
13
)
14

15
fun User.toEntityForInsert(): UserEntity = UserEntity().apply {
16
    this.id       = this@toEntityForInsert.id
17
    this.username = this@toEntityForInsert.username
18
    this.email    = this@toEntityForInsert.email.value
19
    this.isNew    = true
20
}

RestMapper (Entry Point Layer)

Maps between REST DTOs and application commands / domain objects.

1
public final class UserRestMapper {
2

3
    private UserRestMapper() {
4
        // Utility class - prevent instantiation
5
    }
6

7
    public static CreateUserCommand toCreateUserCommand(
8
            CreateUserRequest request, UUID organizationId) {
9
        return new CreateUserCommand(
10
            organizationId,
11
            request.username(),
12
            request.email(),
13
            request.firstName(),
14
            request.lastName(),
15
            request.roles(),
16
            request.enabled()
17
        );
18
    }
19

20
    public static CreatedUserResponse toCreatedUserResponse(User user) {
21
        return new CreatedUserResponse(user.getId(), user.getCreatedAt());
22
    }
23

24
    public static UserResponse toUserResponse(User user) {
25
        return new UserResponse(
26
            user.getId(),
27
            user.getOrganizationId(),
28
            user.getUsername(),
29
            user.getEmail(),
30
            user.getFirstName(),
31
            user.getLastName(),
32
            List.of(),
33
            user.isEnabled()
34
        );
35
    }
36
}

Kotlin equivalent:

1
// Kotlin uses extension functions for fluent mapping
2
fun CreateUserRequest.toCreateUserCommand(organizationId: UUID): CreateUserCommand =
3
    CreateUserCommand(
4
        organizationId = organizationId,
5
        username = this.username,
6
        email = this.email,
7
        // ...
8
    )
9

10
fun User.toCreatedUserResponse(): CreatedUserResponse =
11
    CreatedUserResponse(id = this.id, createdAt = this.createdAt)

Mapper rules

Mappers are pure functions: no side effects, no business logic, no I/O.
One mapper class per boundary (CommandMapper, EntityMapper, RestMapper).
All methods are public static. The class is final with a private constructor.
Mapper classes live in a mapper sub-package at each layer.
Never place mapper logic in domain classes, use cases, or controllers.

Error Handling

Domain-specific exceptions

Define exceptions in the domain layer. Never use checked exceptions across layer boundaries.

1
public abstract class DomainException extends RuntimeException {
2

3
    protected DomainException(String message) {
4
        super(message);
5
    }
6

7
    protected DomainException(String message, Throwable cause) {
8
        super(message, cause);
9
    }
10
}
11

12
// domain/src/.../domain/exception/OrganizationNotFoundException.java
13
public class OrganizationNotFoundException extends DomainException {
14

15
    public OrganizationNotFoundException(UUID id) {
16
        super("Organization not found with ID: " + id);
17
    }
18
}
19

20
// domain/src/.../domain/exception/UserAlreadyExistsException.java
21
public class UserAlreadyExistsException extends DomainException {
22

23
    public UserAlreadyExistsException(String email) {
24
        super("User already exists with email: " + email);
25
    }
26
}

Layer rules

Layer	Rule
Domain	Throw `RuntimeException` subclasses. No checked exceptions.
Application	Catch infrastructure failures; translate or propagate domain exceptions.
Infrastructure	Wrap low-level exceptions into domain/application exceptions before throwing.
Entry points	Translate exceptions to HTTP status codes in `@ControllerAdvice`.

1
// Infrastructure adapter - wrap low-level exceptions
2
@Component
3
public class UserRepositoryAdapter implements UserRepositoryPort {
4

5
    @Override
6
    public User save(User user) {
7
        try {
8
            var entity = EntityMapper.toEntityForInsert(user);
9
            var saved = jdbcRepository.save(entity);
10
            return EntityMapper.toDomain(saved);
11
        } catch (DataIntegrityViolationException ex) {
12
            throw new UserAlreadyExistsException(user.getEmail());
13
        }
14
    }
15
}

1
// Entry point - translate to HTTP
2
@RestControllerAdvice
3
public class GlobalExceptionHandler {
4

5
    @ExceptionHandler(OrganizationNotFoundException.class)
6
    public ResponseEntity<ErrorResponse> handleNotFound(OrganizationNotFoundException ex) {
7
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
8
            .body(new ErrorResponse(ex.getMessage()));
9
    }
10

11
    @ExceptionHandler(UserAlreadyExistsException.class)
12
    public ResponseEntity<ErrorResponse> handleConflict(UserAlreadyExistsException ex) {
13
        return ResponseEntity.status(HttpStatus.CONFLICT)
14
            .body(new ErrorResponse(ex.getMessage()));
15
    }
16
}

Kotlin equivalent:

1
// Same pattern applies -- RuntimeException subclasses in domain
2
class OrganizationNotFoundException(id: UUID) :
3
    DomainException("Organization not found with ID: $id")

Logging

Use SLF4J logger per class. Log at boundaries with structured messages.

1
import org.slf4j.Logger;
2
import org.slf4j.LoggerFactory;
3

4
public class CreateUserUseCase implements CreateUserPort {
5

6
    private static final Logger log = LoggerFactory.getLogger(CreateUserUseCase.class);
7

8
    @Override
9
    public User execute(CreateUserCommand command) {
10
        log.debug("Creating user with username: {}", command.username());
11
        return transaction.run(() -> {
12
            User user = userRepository.save(CommandMapper.toUser(command));
13
            log.info("Created user with ID: {}", user.getId());
14

15
            userPublisher.publishCreated(user);
16
            log.info("Published event for user creation: userId={}", user.getId());
17
            return user;
18
        });
19
    }
20
}

Kotlin equivalent:

1
companion object {
2
    private val log = LoggerFactory.getLogger(CreateUserUseCase::class.java)
3
}

Logging rules

Declare logger as private static final Logger log (not logger, not LOG).
Log at layer boundaries: entry points (request/response), use cases (operations), adapters (I/O).
Never log sensitive data (passwords, tokens, PII).
Use parameterized messages ({} placeholders), never string concatenation.
Levels:
- DEBUG - detailed flow, method entry/exit.
- INFO - lifecycle events, successful operations.
- WARN - recoverable issues, fallback paths.
- ERROR - failures that bubble up, unrecoverable errors. Always include the exception.
Include correlation IDs when available.

Validation

Entry points: Bean Validation

Use Jakarta Bean Validation annotations on request DTOs. Validate before mapping to domain types.

1
// Request DTO with validation
2
public record CreateOrganizationRequest(
3
    @NotBlank(message = "Name is required")
4
    @Size(min = 2, max = 100, message = "Name must be between 2 and 100 characters")
5
    String name,
6

7
    @NotBlank(message = "Contact email is required")
8
    @Email(message = "Contact email must be valid")
9
    String contactEmail,
10

11
    @NotBlank(message = "Contact phone is required")
12
    @Pattern(regexp = "^\\+?[0-9]{10,15}$", message = "Phone must be a valid number")
13
    String contactPhone
14
) {}
15

16
// Controller uses @Valid
17
@RestController
18
@RequestMapping("/api/v1/organizations")
19
public class OrganizationController {
20

21
    @PostMapping
22
    public ResponseEntity<CreatedOrganizationResponse> create(
23
            @Valid @RequestBody CreateOrganizationRequest request) {
24
        var command = OrganizationRestMapper.toCommand(request);
25
        var organization = createOrganizationPort.execute(command);
26
        return ResponseEntity.status(HttpStatus.CREATED)
27
            .body(OrganizationRestMapper.toCreatedResponse(organization));
28
    }
29
}

Domain: constructor invariants

Validate business rules inside domain constructors or factory methods. Domain validation must not depend on framework annotations.

1
// Domain validation in constructor
2
public class Organization {
3

4
    public Organization(UUID id, String name, String contactEmail,
5
                        OrganizationStatus status) {
6
        this.id = Objects.requireNonNull(id, "ID must not be null");
7
        if (name == null || name.isBlank()) {
8
            throw new IllegalArgumentException("Organization name must not be blank");
9
        }
10
        if (name.length() > 100) {
11
            throw new IllegalArgumentException(
12
                "Organization name must not exceed 100 characters");
13
        }
14
        this.name = name;
15
        this.contactEmail = Objects.requireNonNull(contactEmail, "Contact email is required");
16
        this.status = Objects.requireNonNull(status, "Status is required");
17
    }
18
}

Kotlin equivalent:

1
// Aggregate root — regular class. `data class` would expose copy(...) that skips
2
// state-transition guards; use it only for DTOs/value objects.
3
class Organization private constructor(
4
    val id: UUID,
5
    val name: String,
6
    val contactEmail: String,
7
    val status: OrganizationStatus,
8
) {
9
    init {
10
        require(name.isNotBlank()) { "Organization name must not be blank" }
11
        require(name.length <= 100) { "Organization name must not exceed 100 characters" }
12
    }
13

14
    companion object {
15
        fun create(id: UUID, name: String, contactEmail: String): Organization =
16
            Organization(id, name, contactEmail, OrganizationStatus.PENDING_APPROVAL)
17
    }
18
}

JSON Serialization

Rules

ALWAYS use JsonMapper.builder() (Jackson 3.x) — it produces an immutable, thread-safe mapper. NEVER use ObjectMapper (deprecated in Jackson 3.x).
Register modules at build time only (JavaTimeModule). No runtime .registerModule() calls.
Standard config: WRITE_DATES_AS_TIMESTAMPS=false, FAIL_ON_UNKNOWN_PROPERTIES=false.

1
JsonMapper jsonMapper = JsonMapper.builder()
2
    .addModule(new JavaTimeModule())
3
    .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
4
    .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
5
    .build();

Anti-Patterns to Avoid

1. Mutable DTOs with setters

1
// BAD - mutable DTO
2
public class CreateUserRequest {
3
    private String username;
4
    private String email;
5

6
    public void setUsername(String username) { this.username = username; }
7
    public void setEmail(String email) { this.email = email; }
8
    public String getUsername() { return username; }
9
    public String getEmail() { return email; }
10
}

1
// GOOD - immutable record
2
public record CreateUserRequest(
3
    @NotBlank String username,
4
    @NotBlank @Email String email
5
) {}

Kotlin equivalent:

1
// Kotlin data class is immutable by default with val
2
data class CreateUserRequest(
3
    val username: String,
4
    val email: String,
5
)

2. Anemic domain models

1
// BAD - anemic model, behavior lives in services
2
public class Organization {
3
    private UUID id;
4
    private String name;
5
    private OrganizationStatus status;
6

7
    // Only getters and setters, no behavior
8
    public void setStatus(OrganizationStatus status) { this.status = status; }
9
    public OrganizationStatus getStatus() { return status; }
10
}
11

12
// Business logic incorrectly placed in a service
13
public class OrganizationService {
14
    public void activate(Organization org) {
15
        if (org.getStatus() != OrganizationStatus.INACTIVE) {
16
            throw new IllegalStateException("...");
17
        }
18
        org.setStatus(OrganizationStatus.ACTIVE); // mutating externally
19
    }
20
}

1
// GOOD - rich domain model, behavior inside the entity
2
public class Organization {
3

4
    private final UUID id;
5
    private final String name;
6
    private final OrganizationStatus status;
7

8
    // Constructor...
9

10
    public Organization activate() {
11
        if (this.status != OrganizationStatus.INACTIVE) {
12
            throw new IllegalStateException("Only inactive organizations can be activated");
13
        }
14
        return new Organization(this.id, this.name, OrganizationStatus.ACTIVE);
15
    }
16

17
    public boolean isActive() {
18
        return status == OrganizationStatus.ACTIVE;
19
    }
20
}

3. Checked exceptions in domain

1
// BAD - checked exception forces callers to handle or declare
2
public class Organization {
3
    public Organization activate() throws InvalidStatusException {
4
        // forces every caller to catch or throw
5
    }
6
}

1
// GOOD - unchecked (RuntimeException) domain exception
2
public class Organization {
3
    public Organization activate() {
4
        if (this.status != OrganizationStatus.INACTIVE) {
5
            throw new InvalidStatusException("Only inactive organizations can be activated");
6
        }
7
        return new Organization(this.id, this.name, OrganizationStatus.ACTIVE);
8
    }
9
}
10

11
// InvalidStatusException extends RuntimeException
12
public class InvalidStatusException extends DomainException {
13
    public InvalidStatusException(String message) {
14
        super(message);
15
    }
16
}

4. Static utility classes with business logic

1
// BAD - business logic in a static utility class
2
public class OrganizationUtils {
3
    public static boolean canActivate(Organization org) {
4
        return org.getStatus() == OrganizationStatus.INACTIVE;
5
    }
6
    public static Organization activate(Organization org) {
7
        // Business logic should not live here
8
    }
9
}

1
// GOOD - behavior belongs in the domain model itself
2
public class Organization {
3
    public boolean canActivate() {
4
        return this.status == OrganizationStatus.INACTIVE;
5
    }
6
    public Organization activate() {
7
        if (!canActivate()) {
8
            throw new InvalidStatusException("Cannot activate organization");
9
        }
10
        return new Organization(this.id, this.name, OrganizationStatus.ACTIVE);
11
    }
12
}

Note: Static mapper utility classes (like CommandMapper, EntityMapper) are acceptable because they only perform structural mapping, not business logic.

5. Field injection with `@Autowired`

1
// BAD - field injection hides dependencies, prevents immutability, breaks testing
2
@Component
3
public class UserRepositoryAdapter implements UserRepositoryPort {
4

5
    @Autowired
6
    private UserJdbcRepository jdbcRepository; // hidden dependency
7

8
    @Autowired
9
    private EntityMapper mapper; // hidden dependency
10
}

1
// GOOD - constructor injection, explicit dependencies, immutable
2
@Component
3
public class UserRepositoryAdapter implements UserRepositoryPort {
4

5
    private final UserJdbcRepository jdbcRepository;
6

7
    public UserRepositoryAdapter(UserJdbcRepository jdbcRepository) {
8
        this.jdbcRepository = jdbcRepository;
9
    }
10
}

Kotlin equivalent:

1
// Kotlin constructor injection is concise by nature
2
@Component
3
class UserRepositoryAdapter(
4
    private val jdbcRepository: UserJdbcRepository,
5
) : UserRepositoryPort { ... }

6. Raw types without generics

1
// BAD - raw types lose type safety
2
List users = repository.findAll();
3
Map config = loadConfig();
4
TransactionPort transaction; // raw generic

1
// GOOD - always parameterize generics
2
List<User> users = repository.findAll();
3
Map<String, String> config = loadConfig();
4
TransactionPort<User> transaction;

7. Returning null instead of Optional or empty collections

1
// BAD - returning null
2
public User findById(UUID id) {
3
    // returns null if not found -- caller may forget to check
4
    return null;
5
}
6

7
public List<User> findByOrganization(UUID orgId) {
8
    if (noResults) {
9
        return null; // forces null checks on callers
10
    }
11
}

1
// GOOD - Optional for single values, empty collection for lists
2
public Optional<User> findById(UUID id) {
3
    return jdbcRepository.findById(id).map(EntityMapper::toDomain);
4
}
5

6
public List<User> findByOrganization(UUID orgId) {
7
    // always returns a list, possibly empty -- never null
8
    return jdbcRepository.findByOrganizationId(orgId)
9
        .stream()
10
        .map(EntityMapper::toDomain)
11
        .toList();
12
}

Kotlin equivalent:

1
// Kotlin uses nullable types for single values
2
fun findById(id: UUID): User?            // explicit nullable
3
fun findByOrganization(orgId: UUID): List<User>  // non-null, possibly empty

8. Using `Object` as type parameter

1
// BAD - loses type safety, requires casting
2
public class GenericRepository {
3
    public Object save(Object entity) {
4
        // what type is this? no compile-time safety
5
        return entity;
6
    }
7
}
8

9
Map<String, Object> response = new HashMap<>(); // untyped values

1
// GOOD - use proper generics
2
public interface RepositoryPort<T> {
3
    T save(T entity);
4
    Optional<T> findById(UUID id);
5
}
6

7
// GOOD - use typed responses
8
public record ApiResponse<T>(
9
    T data,
10
    String message,
11
    int status
12
) {}

Sealed Classes (Java 17+)

Java 17+ supports sealed classes. Use them for closed hierarchies, equivalent to Kotlin sealed classes.

1
// Domain event hierarchy
2
public sealed interface DomainEvent permits UserCreatedEvent, UserEnabledEvent {
3
    UUID eventId();
4
    LocalDateTime occurredAt();
5
}
6

7
public record UserCreatedEvent(
8
    UUID eventId,
9
    LocalDateTime occurredAt,
10
    UUID userId,
11
    String email
12
) implements DomainEvent {}
13

14
public record UserEnabledEvent(
15
    UUID eventId,
16
    LocalDateTime occurredAt,
17
    UUID userId
18
) implements DomainEvent {}
19

20
// Exhaustive pattern matching (Java 17+)
21
public String describeEvent(DomainEvent event) {
22
    return switch (event) {
23
        case UserCreatedEvent e -> "User created: " + e.userId();
24
        case UserEnabledEvent e -> "User enabled: " + e.userId();
25
    };
26
}

Kotlin equivalent:

1
sealed interface DomainEvent {
2
    val eventId: UUID
3
    val occurredAt: LocalDateTime
4
}
5

6
data class UserCreatedEvent(
7
    override val eventId: UUID,
8
    override val occurredAt: LocalDateTime,
9
    val userId: UUID,
10
    val email: String,
11
) : DomainEvent
12

13
// Exhaustive when
14
fun describeEvent(event: DomainEvent): String = when (event) {
15
    is UserCreatedEvent -> "User created: ${event.userId}"
16
    is UserEnabledEvent -> "User enabled: ${event.userId}"
17
}

Verification Checklist

Before submitting Java code, verify every item:

Formatting and structure

Max 120 characters per line
4-space indentation, no tabs
Braces on all control flow blocks
No wildcard imports; imports sorted
Annotations on separate lines when parameterized

Naming

Packages all lowercase
Classes PascalCase with correct suffixes (Request, Response, Entity, Mapper, Adapter, Port, UseCase, Command)
Methods and variables lowerCamelCase
Constants UPPER_SNAKE_CASE in static final fields

Types and immutability

record used for DTOs, commands, value objects, responses
class used for rich domain models with behavior
All fields final (or record components)
No setters on domain objects or DTOs
Collections returned as unmodifiable (List.of(), List.copyOf(), Collections.unmodifiableList())

Null safety

@NonNull / @Nullable annotations on public API boundaries
Optional used only as return type, never as parameter or field
Collections never null – always empty when no elements
Constructor arguments validated with Objects.requireNonNull()

Functional interfaces

@FunctionalInterface on single-method interfaces (TransactionPort, callbacks)
Regular interfaces for multi-method contracts (repository ports)

Mappers

Static methods in final utility classes with private constructors
One mapper class per boundary (CommandMapper, EntityMapper, RestMapper)
No business logic in mappers
Mappers live in mapper sub-packages

Error handling

Domain exceptions extend RuntimeException (unchecked)
No checked exceptions crossing layer boundaries
Infrastructure exceptions wrapped into domain exceptions
Entry points translate exceptions to HTTP responses via @ControllerAdvice

Logging

SLF4J logger per class: private static final Logger log
Parameterized messages with {} placeholders
No sensitive data logged
Logging at layer boundaries

Validation

Bean Validation annotations on entry-point DTOs
Domain invariants validated in constructors or factory methods
No framework annotations in domain or application layers

Architecture boundaries

Domain layer: no Spring, no framework dependencies
Application layer: no framework annotations, depends only on domain
Infrastructure: implements ports, depends on application and domain
Bootstrap: wires beans, no business logic
Constructor injection everywhere (no @Autowired field injection)

Anti-patterns avoided

No mutable DTOs with setters
No anemic domain models
No checked exceptions in domain
No static utility classes with business logic (mappers are structural only)
No field injection with @Autowired
No raw types without generics
No null returns for Optional/collection scenarios
No Object as type parameter where generics apply

Java Code Style

Java Code Style

Targets

Formatting

Naming

record vs class

When to use record

When to use class

Decision matrix

Immutability

Null Safety

Rules

@FunctionalInterface

When to use @FunctionalInterface vs regular interface

Mapper Pattern

CommandMapper (Application Layer)

EntityMapper (Infrastructure Layer)

RestMapper (Entry Point Layer)

Mapper rules

Error Handling

Domain-specific exceptions

Layer rules

Logging

Logging rules

Validation

Entry points: Bean Validation

Domain: constructor invariants

JSON Serialization

Rules

Anti-Patterns to Avoid

1. Mutable DTOs with setters

2. Anemic domain models

3. Checked exceptions in domain

4. Static utility classes with business logic

5. Field injection with @Autowired

6. Raw types without generics

7. Returning null instead of Optional or empty collections

8. Using Object as type parameter

Sealed Classes (Java 17+)

Verification Checklist

Formatting and structure

Naming

Types and immutability

Null safety

Functional interfaces

Mappers

Error handling

Logging

Validation

Architecture boundaries

Anti-patterns avoided

`record` vs `class`

When to use `record`

When to use `class`

`@FunctionalInterface`

When to use `@FunctionalInterface` vs regular interface

5. Field injection with `@Autowired`

8. Using `Object` as type parameter