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.
68 lines
2.5 KiB
Markdown
68 lines
2.5 KiB
Markdown
# 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 = 17` with 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 `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.
|