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 routes the request to the owning application, and its application sequence number identifies the exact published version being edited.
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, int statusCode, String reason) {
    EditStatus status = EditStatus.fromCode(statusCode);
    log.warn("Edit rejected: tag={}, statusCode={}, status={}, reason={}", tag, statusCode, status, 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. Before invoking the processor, the api verifies that the application sequence number from the original message still matches the owner's current version. This prevents an edit intended for an older version from being applied to newer data.

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.

Failure Status Codes

Failure responses include an informational integer status code. Known codes are defined by EditStatus:

An edit processor can return a known status with EditResult.fail(EditStatus, message) or an application-defined integer with EditResult.fail(statusCode, message). EditResult.fail(message) uses UNKNOWN.

EditListener.onFailure receives the raw integer. Use EditStatus.fromCode(statusCode) to resolve a known value. Note that applications may use their own custom defined status codes.

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. If the owner publishes A2 for the same topic before processing that request, the application sequence numbers no longer match. The api rejects the request with APPLICATION_SEQUENCE_NUMBER_MISMATCH and does not invoke the edit processor, ensuring that an edit based on A1 cannot be applied to A2.