Editing
This API is currently in beta and available via KeySessionExperimental.
Messages that are published with their editable flag set can be edited by other applications.
The api allows edit requests to be automatically routed to the original publisher of data, which will be provided the current version of the data as well as the edited version.
Edit Request
The following example shows how an application can request an edit.
// the setting is received from a publisher
AutoQuoterSetting setting = ...
// the requesting application wants the turn on the AQ by setting the AqEnabled field to true
setting.setAqEnabled(true);
// the requesting application makes an edit request
// the correlation-id will be provided back through an ack so that the request can be tracked
session.edit("correlation-id", setting);
Edit Acknowledgements
Applications can register a MessageEditAck processor to handle the acknowledgement that comes back as a result of the edit request.
The acknowledgement contains a flag that can be used to determine if the edit was successful and also a message field which will contain details of any potential error or rejection.
The topic id of the acknowledgement will contain a correlation id that was provided when the edit was requested.
session.register(MessageEditAck.class, this::processMessageEditAck);
Processing Edit Requests
Edit requests are automatically routed to the publishing application. Publishing applications must register a MessageEditProcessor as follows if they wish to handle edit requests:
session.registerEditProcessor(<message class type>, <message edit processor>);
e.g.
session.registerEditProcessor(AutoQuoterSetting.class, this::editAutoQuoterSetting);
private void editAutoQuoterSetting(AutoQuoterSetting currentVersion, AutoQuoterSetting newVersion, Audit audit) {
// perform validation...
// record audit information
// publish out a new version of the setting
}
When an edit request is received, it's best practice to validate fields in the new version provided and overlay those into the current version. That ensures that a consistent result and also takes account of possible schema version differences between the publisher and editing application.
Audit information containing the ip address and username is provided so that it may be recorded.
There are variations of the message edit processor depending on the serialization being used. These allow the additional Key Header information to be conveyed for types that don't have header information embedded in them (e.g POJOs and Maps and other types).
| Serialization | Edit Processor |
|---|---|
| SBE | MessageEditProcessor |
| DTO | MessageEditDtoProcessor |
| Java POJO or Map, etc. | MessageEditFlexibleProcessor |
Edit Rejection
In the case that an edit request is to be rejected, the application can signal this intent by throwing an Exception in the edit processor. This will result in an acknowledgement containing the error to be sent to the requesting application.
Edit Concurrency Scenario
Scenario: Application publishes item A¹ and then a further update to that same item A².
In this case, its possible for a subscribing application to receive the first event A¹ and submit an edit request. In this instance, the publisher will have an edit request triggered, however note that the latest version A² will be provided along with the new version from the requesting application.
It's possible to identify this scenario by comparing the inceptionNanoTime timestamps of the current and new data provided in the callback. If these are the same, then the edit request would be for the same version of the data. If they are different, then its likely that the edit was performed against an older version of the data. Applications are free to perform whatever action is necessary, e.g. they are free to accept / reject the edit.