Joseph Doherty
10534ec906
TST-27: docs/GatewayConfiguration.md's ShowTagValues row no longer says "Reserved" — it now states what false (default) does (DashboardEventBroadcaster blanks tag values from a deep-cloned MxEvent before the SignalR events-hub mirror), the security relevance (no per-session hub ACL yet, so this redaction is the only thing between a low-trust Viewer and other sessions' tag values), and the honest scope limit (does not cover /browse). WRK-26 (discharges IPC-29): docs/MxAccessWorkerInstanceDesign.md's "Outbound Queues" section rewritten from the stale five-level priority list to the two-class Control/Event scheduler actually shipped, with the collapsed- decision rationale, and the overflow paragraph rewritten to the implemented fail-fast. docs/WorkerFrameProtocol.md gained a "Write Scheduling And Sequencing" section describing HEAD truthfully: WRK-23's peek-stamp-commit sequencing is live, WRK-25's event-batch flush coalescing is not (the drain loop still awaits each event write individually), and WRK-22's cancellation tombstone is not yet defined (noted as pending, not documented as shipped). CLI-42: clients/rust/README.md and docs/ClientPackaging.md document the vendored Rust proto layout matching build.rs — repo-path-first resolution falling back to clients/rust/protos/, the check-codegen.ps1 Check 3 refresh rule, and why cargo package/publish run without --no-verify. CLI-43: docs/style-guides/JavaStyleGuide.md now says Java 17 (Ignition 8.3 baseline), mirroring CLI-12's wording, matching the shipped build.gradle. IPC-28: docs/Grpc.md's exception-mapping prose gained CommandTooLarge -> ResourceExhausted, and the Invoke section gained the oversized-payload sentence, cross-referencing GatewayConfiguration.md's headroom rule. Tracking: TST-27, WRK-26, CLI-42, CLI-43, IPC-28 flipped to Done and IPC-29 marked discharged-by-WRK-26 in 00-tracking.md and the 20/30/50/60 domain registers, with a 2026-08-07 change-log entry. Doc-only change; no source, proto, or test edits.
2.5 KiB
2.5 KiB
Java Style Guide
This guide defines Java conventions for the MXAccess Gateway Java client library, CLI, and tests.
Baseline
- Target Java 17 (the Ignition 8.3 baseline; the client build enforces
options.release = 17with a Gradle toolchain 17). Code must compile and run on 17; newer JDKs may host the build. - 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
PascalCasefor classes, records, interfaces, and enums. - Use
camelCasefor methods, fields, parameters, and local variables. - Use
UPPER_SNAKE_CASEfor constants. - Use MXAccess terms consistently:
serverHandle,itemHandle,mxStatusProxy, andhResult.
API Design
- Prefer immutable options objects with builders for public configuration.
- Implement
AutoCloseablefor clients and sessions that own resources. - Provide async methods with
CompletableFuturewhere 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=1and JUnit assumptions.