swe-programming-java

Java Stack Coding Standards

Purpose

Progressive disclosure of Java stack coding standards for agents writing Java code.

Coverage: Java language → Spring Framework → Spring Boot (full technology stack)

Usage: Auto-loaded for agents when writing any Java/Spring code. Provides quick reference to idioms, best practices, and antipatterns across the full stack.

---

Java Language Standards

Authoritative Source: docs/explanation/software-engineering/programming-languages/java/README.md

Naming Conventions

Classes and Interfaces: PascalCase

• Classes: UserAccount, PaymentProcessor
• Interfaces: Comparable, Serializable (adjective form preferred)
• Abstract classes: AbstractProcessor, BaseEntity

Methods and Variables: camelCase

• Methods: calculateTotal(), findUserById()
• Variables: userName, totalAmount
• Constants: UPPER_SNAKE_CASE (MAX_RETRIES, DEFAULT_TIMEOUT)

Packages: lowercase with dots

• com.oseplatform.domain.account
• com.oseplatform.infrastructure.persistence

Modern Java Features (Java 17+)

Records: Use for immutable data carriers

public record UserAccount(String id, String name, LocalDateTime createdAt) {}

Sealed Classes: Use for closed type hierarchies

public sealed interface Payment permits CreditCard, BankTransfer {}

Pattern Matching: Use for type-safe casts

if (obj instanceof String s) {
    return s.toUpperCase();
}

Text Blocks: Use for multi-line strings

String json = """
    {
        "name": "value"
    }
    """;

Error Handling

Checked Exceptions: For recoverable errors

• Use for business logic failures
• Document with @throws javadoc

Unchecked Exceptions: For programming errors

• Use for validation failures, illegal state
• Extend RuntimeException

Try-with-resources: Always use for AutoCloseable

try (var reader = Files.newBufferedReader(path)) {
    // Use reader
}

Testing Standards

JUnit 5: Primary testing framework

• @Test for test methods
• @BeforeEach, @AfterEach for setup/teardown
• @ParameterizedTest for data-driven tests

AssertJ: Fluent assertions

assertThat(result)
    .isNotNull()
    .hasSize(3)
    .containsExactly("a", "b", "c");

Mockito: Mocking framework

@Mock
private UserRepository repository;

Security Practices

Input Validation: Always validate external input

• Use Bean Validation annotations (@NotNull, @Size)
• Validate before processing

Sensitive Data: Never log secrets

• Use SensitiveDataFilter for logging
• Clear sensitive data after use

SQL Injection: Use prepared statements

var stmt = connection.prepareStatement("SELECT * FROM users WHERE id = ?");
stmt.setString(1, userId);

Java Comprehensive Documentation

• Java README
• Functional Programming

---

Spring Framework Standards

Authoritative Source: docs/explanation/software-engineering/platform-web/tools/jvm-spring/README.md

Foundation: Builds on Java language standards above.

IoC Container and ApplicationContext

• Use ApplicationContext for production code
• Prefer annotation-based configuration (@Configuration, @Bean)
• Use component scanning with explicit base packages

Dependency Injection Patterns

• Constructor injection (preferred): Use for required dependencies
• Field injection (avoid): Creates testing difficulties
• Setter injection: Use for optional dependencies

Bean Lifecycle and Scopes

• Singleton (default): Stateless services
• Prototype: Stateful objects
• Request/Session: Web-scoped beans
• Use @PostConstruct and @PreDestroy for lifecycle callbacks

AOP Patterns

• Use @Aspect for cross-cutting concerns
• Prefer declarative transactions (@Transactional)
• Apply aspects for logging, security, caching

Data Access

• Use JdbcTemplate for SQL operations
• Prefer Spring Data JPA repositories
• Apply transaction management at service layer
• Use @Transactional for declarative transactions

Web MVC

• Use @RestController for REST APIs
• Apply @RequestMapping for endpoint routing
• Use @Valid for request validation
• Implement @ControllerAdvice for global exception handling

Spring Framework Comprehensive Documentation

Core Patterns:

• Idioms
• Best Practices
• Anti-Patterns

Configuration & Architecture:

• Configuration
• Dependency Injection
• AOP
• Build Configuration

Data & Web:

• Data Access
• Web MVC
• REST APIs

Quality & Operations:

• Security
• Testing
• Performance
• Observability
• Deployment
• Code Quality

Domain & Design:

• DDD Standards
• API Standards
• Concurrency Standards
• Error Handling Standards
• Version Migration

---

Spring Boot Standards

Authoritative Source: docs/explanation/software-engineering/platform-web/tools/jvm-spring-boot/README.md

Foundation: Builds on Spring Framework standards above.

Auto-configuration and Starters

• Use Spring Boot starters for dependency management
• Customize auto-configuration with application.yml properties
• Exclude unnecessary auto-configurations explicitly
• Document custom auto-configurations

Configuration Properties

• Use @ConfigurationProperties for type-safe configuration
• Group related properties in dedicated classes
• Validate configuration with Bean Validation annotations
• Use profiles for environment-specific configuration

REST API Development

• Use @RestController for REST endpoints
• Apply @Valid for request validation
• Implement global exception handling with @ControllerAdvice
• Use HATEOAS for hypermedia-driven APIs
• Document APIs with OpenAPI/Swagger

Spring Boot Data Access

• Use Spring Data JPA repositories
• Prefer derived query methods over @Query
• Apply @Transactional at service layer
• Use @DataJpaTest for repository testing

Spring Boot Security

• Use Spring Security with OAuth2/JWT
• Implement method-level security with @PreAuthorize
• Configure CORS for API access
• Use @AuthenticationPrincipal for user context

Spring Boot Testing

• Use @SpringBootTest for integration tests
• Apply test slices: @WebMvcTest, @DataJpaTest, @JsonTest
• Use TestContainers for external dependencies
• Mock external services with @MockBean

Observability

• Enable Spring Boot Actuator for monitoring
• Expose custom metrics with Micrometer
• Implement custom health indicators
• Use structured logging with Logback

Spring Boot Comprehensive Documentation

Core Patterns:

• Idioms
• Best Practices
• Anti-Patterns

Configuration & Architecture:

• Configuration
• Dependency Injection
• AOP

Data & Web:

• Data Access
• REST APIs
• WebFlux Reactive

Quality & Operations:

• Security
• Testing
• Performance
• Observability
• Deployment

Domain & Design:

• Domain-Driven Design
• Functional Programming
• Version Migration

---

Related Skills

• docs-applying-content-quality
• repo-practicing-trunk-based-development