Skip to content

Commit bcbe1e9

Browse files
ttypicttypic
committed
[AIT-304] feat: Mutable messages ably-java
1 parent 14b7498 commit bcbe1e9

3 files changed

Lines changed: 209 additions & 2 deletions

File tree

‎src/pages/docs/api/realtime-sdk/channels.mdx‎

Lines changed: 43 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -824,29 +824,49 @@ Failure to retrieve the message history will trigger the `errback` callbacks of
824824

825825
</If>
826826

827-
<If lang="javascript,nodejs">
827+
<If lang="javascript,nodejs,java">
828828

829829
#### getMessage
830830

831+
<If lang="javascript,nodejs">
831832
`getMessage(serialOrMessage: string | Message): Promise<Message>`
833+
</If>
834+
835+
<If lang="java">
836+
`Message getMessage(String serial)` or `void getMessageAsync(Message message, Callback<Message> callback)`
837+
</If>
832838

833839
Retrieves the latest version of a specific message by its serial identifier. Requires the **history** [capability](/docs/auth/capabilities).
834840

835841
See [updating and deleting messages: retrieving the latest version](/docs/messages/updates-deletes#get) for more information.
836842

837843
##### Parameters
838844

845+
<If lang="javascript,nodejs">
839846
| Parameter | Description | Type |
840847
|-----------|-------------|------|
841848
| serialOrMessage | Either the serial identifier string of the message to retrieve, or a [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field | `string` or [`Message`](/docs/api/realtime-sdk/messages) |
842849

843850
##### Returns
844851

845852
Returns a promise which, upon success, will be fulfilled with a [`Message`](/docs/api/realtime-sdk/messages) object representing the latest version of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error.
853+
</If>
854+
855+
<If lang="java">
856+
| Parameter | Description | Type |
857+
|-----------|-------------|------|
858+
| serial | Serial identifier string of the message to retrieve | `string` |
859+
</If>
846860

847861
#### updateMessage
848862

863+
<If lang="javascript,nodejs">
849864
`updateMessage(message: Message, operation?: MessageOperation): Promise<UpdateDeleteResult>`
865+
</If>
866+
867+
<If lang="java">
868+
`void updateMessage(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback)`
869+
</If>
850870

851871
Publishes an update to an existing message with shallow mixin semantics. Non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Requires the **message-update-own** or **message-update-any** [capability](/docs/auth/capabilities).
852872

@@ -865,7 +885,13 @@ Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteR
865885

866886
#### deleteMessage
867887

888+
<If lang="javascript,nodejs">
868889
`deleteMessage(message: Message, operation?: MessageOperation): Promise<UpdateDeleteResult>`
890+
</If>
891+
892+
<If lang="java">
893+
`void deleteMessage(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback)`
894+
</If>
869895

870896
Marks a message as deleted by publishing an update with an action of `MESSAGE_DELETE`. This does not remove the message from the server, and the full message history remains accessible. Uses shallow mixin semantics: non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Requires the **message-delete-own** or **message-delete-any** [capability](/docs/auth/capabilities).
871897

@@ -878,13 +904,21 @@ See [updating and deleting messages: deletes](/docs/messages/updates-deletes#del
878904
| message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field | [`Message`](/docs/api/realtime-sdk/messages) |
879905
| operation | An optional `MessageOperation` object containing metadata about the delete operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) |
880906

907+
<If lang="javascript,nodejs">
881908
##### Returns
882909

883910
Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error.
911+
</If>
884912

885913
#### appendMessage
886914

915+
<If lang="javascript,nodejs">
887916
`appendMessage(message: Message, operation?: MessageOperation): Promise<UpdateDeleteResult>`
917+
</If>
918+
919+
<If lang="java">
920+
`void appendMessage(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback)`
921+
</If>
888922

889923
Appends data to an existing message. The supplied `data` field is appended to the previous message's data, while all other fields (`name`, `extras`) replace the previous values if provided. Requires the **message-update-own** or **message-update-any** [capability](/docs/auth/capabilities).
890924

@@ -897,13 +931,21 @@ See [updating and deleting messages: appends](/docs/messages/updates-deletes#app
897931
| message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field and the data to append | [`Message`](/docs/api/realtime-sdk/messages) |
898932
| operation | An optional `MessageOperation` object containing metadata about the append operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) |
899933

934+
<If lang="javascript,nodejs">
900935
##### Returns
901936

902937
Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object which explains the error.
938+
</If>
903939

904940
#### getMessageVersions
905941

942+
<If lang="javascript,nodejs">
906943
`getMessageVersions(serialOrMessage: string | Message, params?: Record<string, any>): Promise<PaginatedResult<Message>>`
944+
</If>
945+
946+
<If lang="java">
947+
`Message getMessageVersions(String serial, Param[] params)` or `void getMessageVersionsAsync(String serial, Param[] params, Callback<AsyncPaginatedResult<Message>> callback)`
948+
</If>
907949

908950
Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. Requires the **history** [capability](/docs/auth/capabilities).
909951

‎src/pages/docs/api/rest-sdk/channels.mdx‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -469,7 +469,13 @@ On failure to retrieve message history, the `error` contains an [`ErrorInfo`](#e
469469

470470
#### getMessage <a id="get-message" />
471471

472+
<If lang="javascript,nodejs">
472473
`getMessage(serialOrMessage: string | Message): Promise<Message>`
474+
</If>
475+
476+
<If lang="java">
477+
`Message getMessage(String serial)` or `void getMessageAsync(String serial, Callback<Message> callback)`
478+
</If>
473479

474480
Retrieves the latest version of a specific message by its serial identifier. Requires the **history** [capability](/docs/auth/capabilities).
475481

@@ -487,7 +493,13 @@ Returns a promise which, upon success, will be fulfilled with a [`Message`](/doc
487493

488494
#### updateMessage <a id="update-message" />
489495

490-
`updateMessage(message: Message, operation?: MessageOperation, params?: Record<string, any>): Promise<UpdateDeleteResult>`
496+
<If lang="javascript,nodejs">
497+
`updateMessage(message: Message, operation?: MessageOperation, params?: Record<string, any>): Promise<UpdateDeleteResult>
498+
</If>
499+
500+
<If lang="java">
501+
`UpdateDeleteResult updateMessage(Message message, MessageOperation operation)` or `void updateMessageAsync(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback)`
502+
</If>
491503

492504
Publishes an update to an existing message with shallow mixin semantics. Non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Requires the **message-update-own** or **message-update-any** [capability](/docs/auth/capabilities).
493505

@@ -507,7 +519,13 @@ Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteR
507519

508520
#### deleteMessage
509521

522+
<If lang="javascript,nodejs">
510523
`deleteMessage(message: Message, operation?: MessageOperation, params?: Record<string, any>): Promise<UpdateDeleteResult>`
524+
</If>
525+
526+
<If lang="java">
527+
`UpdateDeleteResult deleteMessage(Message message, MessageOperation operation)` or `void deleteMessageAsync(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback)`
528+
</If>
511529

512530
Marks a message as deleted by publishing an update with an action of `MESSAGE_DELETE`. This does not remove the message from the server, and the full message history remains accessible. Uses shallow mixin semantics: non-null `name`, `data`, and `extras` fields in the provided message will replace the corresponding fields in the existing message, while null fields will be left unchanged. Requires the **message-delete-own** or **message-delete-any** [capability](/docs/auth/capabilities).
513531

@@ -527,7 +545,13 @@ Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteR
527545

528546
#### appendMessage
529547

548+
<If lang="javascript,nodejs">
530549
`appendMessage(message: Message, operation?: MessageOperation, params?: Record<string, any>): Promise<UpdateDeleteResult>`
550+
</If>
551+
552+
<If lang="java">
553+
`UpdateDeleteResult appendMessage(Message message, MessageOperation operation)` or `void appendMessageAsync(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback)`
554+
</If>
531555

532556
Appends data to an existing message. The supplied `data` field is appended to the previous message's data, while all other fields (`name`, `extras`) replace the previous values if provided. Requires the **message-update-own** or **message-update-any** [capability](/docs/auth/capabilities).
533557

@@ -549,7 +573,13 @@ Returns a promise which, upon success, will be fulfilled with an [`UpdateDeleteR
549573

550574
#### getMessageVersions
551575

576+
<If lang="javascript,nodejs">
552577
`getMessageVersions(serialOrMessage: string | Message, params?: Record<string, any>): Promise<PaginatedResult<Message>>`
578+
</If>
579+
580+
<If lang="java">
581+
`PaginatedResult<Message> getMessageVersions(String serial, Param[] params)` or `void getMessageVersionsAsync(String serial, Param[] params, Callback<AsyncPaginatedResult<Message>> callback)`
582+
</If>
553583

554584
Retrieves all historical versions of a specific message, ordered by version. This includes the original message and all subsequent updates or delete operations. Requires the **history** [capability](/docs/auth/capabilities).
555585

‎src/pages/docs/messages/updates-deletes.mdx‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,47 @@ await channel.updateMessage(
8888
{ description: 'reason for update' }
8989
);
9090
```
91+
92+
```java
93+
AblyRealtime realtime = new AblyRealtime("{{API_KEY}}");
94+
// This assumes there is an 'updates' namespace with a channel rule enabling updates and deletes
95+
Channel channel = realtime.channels.get("updates:example");
96+
97+
// Publish the original message and get its serial from the result
98+
CompletableFuture<PublishResult> publishFuture = new CompletableFuture<>();
99+
channel.publish("message-name", "original-data", new Callback<PublishResult>() {
100+
@Override
101+
public void onSuccess(PublishResult result) {
102+
publishFuture.complete(result);
103+
}
104+
105+
@Override
106+
public void onError(ErrorInfo reason) {
107+
publishFuture.completeExceptionally(AblyException.fromErrorInfo(reason));
108+
}
109+
});
110+
String serial = publishFuture.get().serials[0];
111+
112+
// Publish an update using the serial
113+
Message message = new Message();
114+
message.data = "updated-data";
115+
message.serial = serial;
116+
MessageOperation operation = new MessageOperation();
117+
operation.description = "reason for update";
118+
CompletableFuture<UpdateDeleteResult> updateFuture = new CompletableFuture<>();
119+
channel.updateMessage(message, operation, new Callback<UpdateDeleteResult>() {
120+
@Override
121+
public void onSuccess(UpdateDeleteResult result) {
122+
updateFuture.complete(result);
123+
}
124+
125+
@Override
126+
public void onError(ErrorInfo reason) {
127+
updateFuture.completeExceptionally(AblyException.fromErrorInfo(reason));
128+
}
129+
});
130+
updateFuture.get();
131+
```
91132
</Code>
92133

93134
#### Returns
@@ -182,6 +223,47 @@ await channel.deleteMessage(
182223
{ description: 'reason for delete' }
183224
);
184225
```
226+
227+
```java
228+
AblyRealtime realtime = new AblyRealtime("{{API_KEY}}");
229+
// This assumes there is an 'updates' namespace with a channel rule enabling updates and deletes
230+
Channel channel = realtime.channels.get("updates:example");
231+
232+
// Publish the original message and get its serial from the result
233+
CompletableFuture<PublishResult> publishFuture = new CompletableFuture<>();
234+
channel.publish("message-name", "original-data", new Callback<PublishResult>() {
235+
@Override
236+
public void onSuccess(PublishResult result) {
237+
publishFuture.complete(result);
238+
}
239+
240+
@Override
241+
public void onError(ErrorInfo reason) {
242+
publishFuture.completeExceptionally(AblyException.fromErrorInfo(reason));
243+
}
244+
});
245+
String serial = publishFuture.get().serials[0];
246+
247+
// Publish an update using the serial
248+
Message message = new Message();
249+
message.data = "";
250+
message.serial = serial;
251+
MessageOperation operation = new MessageOperation();
252+
operation.description = "reason for delete";
253+
CompletableFuture<UpdateDeleteResult> deleteFuture = new CompletableFuture<>();
254+
channel.deleteMessage(message, operation, new Callback<UpdateDeleteResult>() {
255+
@Override
256+
public void onSuccess(UpdateDeleteResult result) {
257+
deleteFuture.complete(result);
258+
}
259+
260+
@Override
261+
public void onError(ErrorInfo reason) {
262+
deleteFuture.completeExceptionally(AblyException.fromErrorInfo(reason));
263+
}
264+
});
265+
deleteFuture.get();
266+
```
185267
</Code>
186268

187269
#### Returns
@@ -277,6 +359,44 @@ channel.appendMessage({ serial, data: ', ' });
277359
channel.appendMessage({ serial, data: 'World' });
278360
channel.appendMessage({ serial, data: '!' });
279361
362+
// the message in history now has data: "Hello, World!"
363+
```
364+
365+
```java
366+
AblyRealtime realtime = new AblyRealtime("{{API_KEY}}");
367+
// This assumes there is an 'updates' namespace with a channel rule enabling updates and deletes
368+
Channel channel = realtime.channels.get("updates:example");
369+
370+
// Publish the original message and get its serial from the result
371+
CompletableFuture<PublishResult> publishFuture = new CompletableFuture<>();
372+
channel.publish("message-name", "Hello", new Callback<PublishResult>() {
373+
@Override
374+
public void onSuccess(PublishResult result) {
375+
publishFuture.complete(result);
376+
}
377+
378+
@Override
379+
public void onError(ErrorInfo reason) {
380+
publishFuture.completeExceptionally(AblyException.fromErrorInfo(reason));
381+
}
382+
});
383+
String serial = publishFuture.get().serials[0];
384+
385+
// Append to the message a few times (without needing to await each to finish
386+
// before doing the next); the data will be concatenated
387+
Message message1 = new Message();
388+
message1.data = " , ";
389+
message1.serial = serial;
390+
channel.appendMessage(message1);
391+
Message message2 = new Message();
392+
message2.data = "World";
393+
message2.serial = serial;
394+
channel.appendMessage(message2);
395+
Message message3 = new Message();
396+
message3.data = "!";
397+
message3.serial = serial;
398+
channel.appendMessage(message3);
399+
280400
// the message in history now has data: "Hello, World!"
281401
```
282402
</Code>
@@ -342,6 +462,13 @@ const channel = rest.channels.get('updates:example');
342462
// message for a serial you have stored or passed around
343463
const message = await channel.getMessage(msg);
344464
```
465+
466+
```java
467+
AblyRest rest = new AblyRest("{{API_KEY}}");
468+
Channel channel = rest.channels.get("updates:example");
469+
470+
Message message = channel.getMessage(serial);
471+
```
345472
</Code>
346473

347474
## Get message versions <a id="versions"/>
@@ -366,6 +493,14 @@ const channel = rest.channels.get('updates:example');
366493
const page = await channel.getMessageVersions(msg);
367494
console.log(`Found ${page.items.length} versions`);
368495
```
496+
497+
```java
498+
AblyRest rest = new AblyRest("{{API_KEY}}");
499+
Channel channel = rest.channels.get("updates:example");
500+
501+
PaginatedResult<Message> page = channel.getMessageVersions(serial);
502+
System.out.println("Found " + page.items().length + " versions");
503+
```
369504
</Code>
370505

371506
## Message version structure <a id="version-structure"/>

0 commit comments

Comments
 (0)