Editing

info

This API is currently in beta and available via KeySessionExperimental.

Messages published with the editable flag set can be edited by other applications.

Editing is a request and response flow. A requester sends an edited payload for a message it has received. The platform routes that request back to the application that owns the data. The owner validates it, then accepts or rejects the request. The response is routed back to the requesting application.

Requesting an Edit

A requester edits a message it has already received. The original KeyMessage identifies the topic being edited.

Edit request syntax

session.edit().dto(tag, originalMessage, edited, listener, timeout);

Method Argument	Description
tag	Requester supplied correlation id. It is returned to EditListener callbacks so the application can match the response to a request that it made.
originalMessage	The KeyMessage being edited. Its topic and metadata identify the published item and allow the edit to be routed to the owning application.
edited	The edited payload.
listener	Callback for the edit outcome, such as accepted or rejected.
timeout	Per-request timeout for receiving an edit response.

Submit a DTO edit request

KeyMessage<SettingDto> originalMessage = ...;

AqSettingDto edited = originalMessage.payload();
edited.aqEnabled(true);

long tag = 1001L;
Duration timeout = Duration.ofSeconds(5);

EditListener listener = new EditListener() {
  @Override
  public void onSuccess(long tag) {
    log.info("Edit accepted: {}", tag);
  }

  @Override
  public void onFailure(long tag, String reason) {
    log.warn("Edit rejected: {}, {}", tag, reason);
  }
};

session.edit().dto(tag, originalMessage, edited, listener, timeout);

Processing Edit Requests

The owner application must register an edit processor for the message type before the session is started.

Register an edit processor

session.editRouting().dto(SettingDto.class, this::editSetting);

The edit processor receives:

Method Argument	Description
current	The trusted current message from the publication cache.
edited	The requester supplied payload. Treat this as input that must be validated.
audit	Requester audit information, including IP address and username.

Edit processor

private EditResult editSetting(
    KeyMessage<SettingDto> current,
    SettingDto edited,
    Audit audit) {

  AqSettingDto currentValue = current.payload();

  if (!isValidEdit(currentValue, edited)) {
    return EditResult.fail("Invalid setting");
  }

  publishUpdatedSetting(edited);
  return EditResult.accept();
}

Returning EditResult.accept() sends a successful edit response. It does not automatically republish the edited payload; the owner application should apply and publish the accepted change before returning.

Edit Rejection

Return EditResult.fail("message") when an edit request should be rejected. The failure message is sent back to the requesting application.

Unhandled exceptions are also converted into failed edit responses.

Edit Types

There are edit methods for each message type:

Message Type	Request Method	Routing Method
SBE	edit().sbe(...)	editRouting().sbe(...)
DTO	edit().dto(...)	editRouting().dto(...)
Flexible	edit().flexible(...)	editRouting().flexible(...)
Custom	edit().custom(...)	editRouting().custom(...)
Raw	edit().raw(...)	editRouting().raw(...)

info

Edit Concurrency Scenario: A subscriber may receive item A1 and submit an edit request. By the time the owner receives the edit request, it may already have published A2 for the same topic. In this case, the edit processor would receive A2 as current, alongside the requester supplied edited payload.