Java Control Client

com.friendly.qa is the one groupId of every qa-program library. A consumer must bind it to its repositories with Maven’s remote repository filter, so that Maven Central can never serve it. The binding has three parts. One part alone protects nothing.

If the same groupId is bound to several repositories, Maven asks each of them in turn and you see a 404 line from the ones that do not have the artifact. That is expected.

One deadline covers a whole call: connect, headers and body. When it passes, the exchange is cancelled and the call throws UncheckedIOException. A response body larger than 64 MiB is refused while it is read, with the same exception.

A deadline that passes on the client does not undo what the server already did. Two calls are long:

For slow devices or large batches, pass a longer deadline to the three-argument create, or make the batch smaller.

Protocol, connection config, transport, lifecycle and logs. 19 operations.

The device-tree files (.xml) of the configuration directory, and the selection among them. 3 operations, 4 methods: select and clearSelection are two methods over the same endpoint.

select throws IllegalArgumentException before any request for a null or blank name, or a name with / or \. The server drops a directory part and would select another file than the one you named.

While the emulator is initialized or started, the server refuses both select and clearSelection with 400 EMULATOR_NOT_STOPPED. A name that does not end in .xml answers 400 BAD_REQUEST; a file that does not exist answers 400 CONFIG_FILE_NOT_FOUND.

The devices of the running emulator. 18 operations.

startNew creates and starts a stand-alone device. create, createBatch and startNew all store their devices, see create, createBatch and startNew store their devices. startNew and createBatch throw IllegalArgumentException before any request for a template that holds the mask *** in one of the four fixed secrets or as any protocolOptions value, whatever its key, see Secrets read back as ***.

The devices the emulator stores on disk. 4 operations.

LwM2M fleet operations. 2 operations, 3 methods: deregister and deregisterWithDetails are two methods over the same endpoint.

deregister and update answer 409 when there is nothing to act on: NO_RUNNING_LWM2M_DEVICE.

Certificate enrolment (EST) of one device. 4 operations.

On an emulator without EST configured, enroll and reenroll answer 409 with a plain-text body, and options answers 400 for an option the emulator does not know. These answers have no JSON code, so EmulatorApiException.code() is null for them.

start(), stop() and reset() answer 409 NOT_INITIALIZED when nothing is initialized. The typed call throws; a call that ignored the status would not have noticed. stop() on a started session also un-initializes it, so status().initialized() is false afterwards.

updateConfig leaves a null component unchanged, with one exception: a request that omits delaySec sets the delay to 0, because the server applies delaySec whenever it reads >= 0 and an omitted number reads 0. Always start from the current config:

setAutoupdate has the same trap: the booleans autoupdatable, global and randomizeStepType read as false when omitted. Start from autoupdate(…​).toBuilder().

The emulator masks secrets on read: a stored device’s keys and the connection config’s keys and passwords come back as ***. Device parameters are not masked by the emulator at all.

The connection config can be read with config() and sent back unchanged: a masked or omitted secret keeps the stored value.

A stored-device template cannot be sent with the mask in it. The client refuses the mask in these places:

devices().startNew(template) and devices().createBatch(templates) throw IllegalArgumentException before any request is sent, and a batch is refused whole. The message names the component, and in a batch the index of the template; it holds neither the mask nor the client id. A null element of a batch is not checked: it is sent as JSON null and the server’s answer is what you get.

Why the client refuses: the mask is what the server returns instead of a secret, and the client cannot tell a real value *** from a mask that was read back.

What the server would do with the mask differs by place:

The client is deliberately stricter than the server for protocolOptions: it refuses the mask under any key, because the server decides which option keys are secret from its own per-protocol properties, which the client cannot evaluate. A real option value that is the literal *** is therefore refused as well.

To restart a template taken from storedDevices().list(), set its secrets again with toBuilder():

DeviceTemplate.maskedSecret() returns the name of the component that holds the mask, or an empty Optional when the template can be sent as it is.

lwm2m().deregister() deregisters every LwM2M device in the emulator, including one already deregistered. It answers 409 NO_RUNNING_LWM2M_DEVICE only when the emulator holds no LwM2M device. After a first deregister the devices stay in the emulator, so a second call answers 204 and sends nothing to the server.

Inside one emulator process a stored device is also a running one. storedDevices().start(clientId) therefore throws 400 DEVICE_START_FAILED while the device exists in that process, whether running or stopped. It succeeds after the emulator restarts over the same configuration directory.

devices().create(…​), devices().createBatch(…​) and devices().startNew(…​) store the devices they create. session().reset() keeps the stored devices, and session().init() creates every stored device again. A test that creates devices therefore leaves them for the next session. storedDevices().clear() is the clean-up between sessions; devices().delete(clientId) removes one device and its stored entry, see Deleting a device also deletes its stored entry.

devices().delete(clientId) removes the device from the store too. storedDevices().delete(clientId) and clear() remove stored entries only; running devices stay.

The selection made with configFiles().select(…​) stays when you call selectProtocol, also across protocols. It is kept in memory only, so a restart of the emulator clears it. In active(), the property for the protocol’s default file is defaultFile.

Three test classes in the gui test tree (com.friendly.emulator.gui.api.contract) tie the client to the controllers. They run in the emulator build, with no mock of the server.

A developer who adds, renames or removes a controller path, or changes a field of a DTO the client uses, sees one of these classes fail in the gui build. The fix is to change the client in the same commit, or, for a new operation the client does not need, to add it to the not-covered list with a reason.