@@ -395,12 +395,14 @@ delivered to subscription listeners) map to ably-java interfaces with getters (p
395395` io.ably.lib.liveobjects.message ` ). The ` PublicAPI:: ` prefix is dropped — ably-java exposes them as
396396` ObjectMessage ` / ` ObjectOperation ` .
397397
398- > ** Getter-only, no public constructor.** You obtain an ` ObjectMessage ` only from a subscription event
399- > (` event.getMessage() ` , §8) — there is no public factory. The spec's * explicit* construction-from-wire
400- > (` PublicObjectMessage.fromObjectMessage(source, channel) ` / ` PublicObjectOperation.fromObjectOperation(op) ` ,
401- > ` PAOM3 ` /` PAOOP3 ` , in ` public_object_message.md ` ) is internal in ably-java, so assert the getters on a
402- > message received via ` subscribe ` rather than constructing one; treat a standalone construction-only test
403- > as internal (§13).
398+ > ** Getter-only, no * public* constructor — use the ` buildPublicObjectMessage ` helper.** In normal use you
399+ > obtain an ` ObjectMessage ` from a subscription event (` event.getMessage() ` , §8); there is no public
400+ > factory. The spec's explicit construction-from-wire (`PublicObjectMessage.fromObjectMessage(source,
401+ > channel)` / ` PublicObjectOperation.fromObjectOperation(op)` , ` PAOM3` / ` PAOOP3`, in
402+ > ` public_object_message.md ` ) is ` internal ` to ` :liveobjects ` — but the unit helpers expose it ** by
403+ > reflection** as ` buildPublicObjectMessage(wireJson, channelName) ` (§13). So ` public_object_message.md ` is
404+ > translatable: build the source with the op builders (` buildMapSet(...) ` , ` buildCounterInc(...) ` , …) and
405+ > assert the public getters on the result.
404406
405407` ObjectMessage ` : ` getId() ` , ` getClientId() ` , ` getConnectionId() ` , ` getTimestamp(): Long? ` , `getChannel():
406408String` , ` getOperation(): ObjectOperation` , ` getSerial()` , ` getSerialTimestamp(): Long?` , ` getSiteCode()`,
@@ -499,29 +501,59 @@ Several **unit** specs assert on the **internal CRDT graph**, not the public API
499501- ` realtime_object.md ` — ** mixed** : ` get() ` (` RTO23 ` , incl. the ` 40024 ` /` 90001 ` /` 92008 ` precondition cases)
500502 is public and maps via §2/§12, but ` publish ` / ` publishAndApply ` (` RTO15 ` /` RTO20 ` , marked ` internal ` in the
501503 IDL) and the OBJECT/ACK wire assertions are internal.
502- - ` public_object_message.md ` — ** mixed ** : the ` ObjectMessage ` / ` ObjectOperation ` * getters * are public
503- (assert them on a message received via ` subscribe ` , §11), but the explicit construction-from-wire it tests
504- ( ` fromObjectMessage ` / ` fromObjectOperation ` , ` PAOM3 ` / ` PAOOP3 ` ) has no public factory and is internal .
504+ - ` public_object_message.md ` — ** translatable ** via the ` buildPublicObjectMessage ` helper (below), which
505+ reflectively performs the ` PAOM3 ` / ` PAOOP3 ` construction ( ` WireObjectMessage ` → ` DefaultObjectMessage ` )
506+ that is otherwise ` internal ` . Build the source with the op builders and assert the public getters (§11) .
505507
506508In ably-java these are ** not public** . They live in the ` :liveobjects ` module as ` Default* ` / ` Wire* ` /
507509` ResolvedValue ` / ` Leaf ` / ` MapRef ` / ` CounterRef ` classes (package ` io.ably.lib.liveobjects.* ` ,
508- implementation source set) — and the ` uts ` module currently depends only on ` :java ` (public API) and
509- ` :network-client-core ` , ** not** on ` :liveobjects ` . Consequences when translating:
510-
511- - ** Public-API unit specs** (` path_object*.md ` , ` instance.md ` , ` live_object_subscribe.md ` , and the
512- public-surface parts of ` realtime_object.md ` , ` public_object_message.md ` and ` value_types.md ` ) translate
513- cleanly against the §1–§12 map and compile against ` :java ` . (Note ` path_object.md ` / ` instance.md ` also
514- contain ` compact() ` cases, which are deviations per §4/§5 since ably-java implements only ` compactJson() ` .)
515- - ** Internal-graph unit specs** can't be expressed through the public API. Before translating those, decide
516- with the user whether to (a) add a ` testImplementation(project(":liveobjects")) ` dependency to
517- ` uts/build.gradle.kts ` and target the ` Default* ` /internal classes directly, or (b) translate them inside
518- the ` :liveobjects ` module's own test source set instead, or (c) skip them for the uts module. Flag this
519- rather than forcing a public-API assertion that can't see internal state.
510+ implementation source set). The ` uts ` module keeps them ** off its compile classpath** (it compiles against
511+ ` :java ` only) but now has ` testRuntimeOnly(project(":liveobjects")) ` , so the helpers reach the internal
512+ wire/message classes ** by reflection** at runtime. Consequences when translating:
513+
514+ - ** Public-API unit specs** (` path_object*.md ` , ` instance.md ` , ` live_object_subscribe.md ` ,
515+ ` public_object_message.md ` , and the public-surface parts of ` realtime_object.md ` and ` value_types.md ` )
516+ translate cleanly against the §1–§12 map + the helpers below, and compile against ` :java ` . (Note
517+ ` path_object.md ` / ` instance.md ` also contain ` compact() ` cases, which are deviations per §4/§5 since
518+ ably-java implements only ` compactJson() ` .)
519+ - ** Internal-graph unit specs** (` objects_pool.md ` , ` parent_references.md ` , the internal-state assertions in
520+ ` live_counter.md ` / ` live_map.md ` ) assert on internal CRDT state the public API can't see. Options: (a)
521+ add reflective accessors to the helpers for the ` Default* ` /internal classes (the technique
522+ ` buildPublicObjectMessage ` and ` infra/unit/Utils.kt ` already use), (b) translate them in the
523+ ` :liveobjects ` module's own test source where the types are directly accessible, or (c) skip them. Flag
524+ rather than forcing a public-API assertion that can't reach internal state.
520525- Spec name → ably-java impl (for orientation, not public use): ` InternalLiveMap ` → ` DefaultLiveMap ` ,
521526 ` InternalLiveCounter ` → ` DefaultLiveCounter ` , the public-view impls are ` DefaultPathObject ` /
522527 ` DefaultLiveMapPathObject ` / ` DefaultInstance ` / …, wire form is ` WireObjectMessage ` /
523528 ` WireObjectOperation ` / ` WireObjectState ` etc.
524529
530+ ### Unit-test helpers — ` standard_test_pool.md ` → ` helpers.kt `
531+
532+ Every objects unit spec opens with ` setup_synced_channel ` and constructs protocol/object messages with the
533+ ` build_* ` helpers. These are implemented in
534+ ` uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/helpers.kt ` — ** call them; don't hand-roll the mock
535+ setup or message JSON.**
536+
537+ | Spec helper | ` helpers.kt ` |
538+ | ---| ---|
539+ | ` { client, channel, root, mock_ws } = AWAIT setup_synced_channel("test") ` | ` val (client, channel, root, mockWs) = setupSyncedChannel("test") ` (` suspend ` , returns ` SyncedChannel ` ) |
540+ | ` setup_synced_channel_no_ack(...) ` | ` setupSyncedChannelNoAck(...) ` |
541+ | ` build_object_sync_message ` / ` build_object_message ` / ` build_ack_message ` | ` buildObjectSyncMessage ` / ` buildObjectMessage ` / ` buildAckMessage ` → ` ProtocolMessage ` |
542+ | ` build_counter_inc ` / ` build_map_set ` / ` build_map_remove ` / ` build_map_clear ` / ` build_object_delete ` / ` build_counter_create ` / ` build_map_create ` | same names camelCased → wire ` JsonObject ` |
543+ | ` build_object_state ` / ` build_object_message_with_state ` | ` buildObjectState ` / ` buildObjectMessageWithState ` |
544+ | ` build_public_object_message(msg, channel) ` | ` buildPublicObjectMessage(wireJson, channel) ` (reflective; §11) |
545+ | ` STANDARD_POOL_OBJECTS ` | ` STANDARD_POOL_OBJECTS ` |
546+ | inline ObjectData / map-entry / state fragments | ` dataString ` / ` dataNumber ` / ` dataBoolean ` / ` dataObjectId ` / ` dataBytes ` / ` dataJson ` , ` mapEntry ` , ` mapState ` , ` counterState ` , ` mapCreateOp ` , ` counterCreateOp ` |
547+
548+ ` mock_ws.send_to_client(...) ` is the existing ` mockWs.sendToClient(...) ` (§ mock API in the main skill). The
549+ wire ` action ` / ` semantics ` are integer enum codes — the builders emit the codes for you.
550+
551+ > ** Runtime caveat:** ` setupSyncedChannel ` returns only once ` RealtimeObject.get() ` resolves, which needs
552+ > the ` :liveobjects ` SDK's OBJECT_SYNC processing. Until that lands the helpers ** compile** and the test
553+ > structure is correct, but the setup throws at runtime — i.e. translate-only today, runnable once the SDK
554+ > is implemented. (` buildPublicObjectMessage ` does * not* depend on this — the message/operation layer is
555+ > implemented, so those tests can run now.)
556+
525557---
526558
527559## 14. Worked example <a id =" 14-worked-example " ></a >
0 commit comments