mxaccessgw/docs/style-guides/JavaStyleGuide.md

Java Style Guide

This guide defines Java conventions for the MXAccess Gateway Java client library, CLI, and tests.

Baseline

• Target the Java version defined by the client build, with Java 21 preferred.
• Use Gradle unless the repository standardizes on Maven.
• Apply a formatter such as Spotless or Google Java Format when configured.
• Keep generated protobuf code separate from handwritten wrappers.

Source Documentation

• Maintain the existing documentation style in the file, package, and surrounding component.
• Write comments that include business-specific or domain-specific context when that context is available from the code, surrounding docs, or naming.
• Use Javadoc for public APIs when behavior, parity constraints, or security requirements are not obvious from the signature.
• Avoid comments that restate syntax or control flow.

Packages

• Use lowercase package names under com.dohertylan.mxgateway.
• Keep client library code separate from CLI code.
• Keep generated protobuf classes in a generated package.
• Do not expose implementation-only transport helpers as public API.

Naming

• Use PascalCase for classes, records, interfaces, and enums.
• Use camelCase for methods, fields, parameters, and local variables.
• Use UPPER_SNAKE_CASE for constants.
• Use MXAccess terms consistently: serverHandle, itemHandle, mxStatusProxy, and hResult.

API Design

• Prefer immutable options objects with builders for public configuration.
• Implement AutoCloseable for clients and sessions that own resources.
• Provide async methods with CompletableFuture where useful, but keep a blocking API for simple CLI workflows.
• Expose raw generated protobuf messages where parity tests need them.

Errors

• Use typed exceptions for gateway, authentication, authorization, session, worker, command, and MXAccess failures.
• Preserve raw command replies in command exceptions when available.
• Redact API keys, passwords, and secured write values in toString, logs, and CLI output.

Streaming

• Cancel gRPC calls explicitly when callers stop consuming streams.
• Do not reorder, coalesce, or drop events in client code.
• Avoid unbounded queues in async stream helpers.

Tests

• Use JUnit 5.
• Use in-process gRPC servers for unit tests.
• Keep live gateway tests behind MXGATEWAY_INTEGRATION=1 and JUnit assumptions.