# 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.zb.mom.ww.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.