diff --git a/src/data/languages/languageData.ts b/src/data/languages/languageData.ts index 20179f34fa..f413676543 100644 --- a/src/data/languages/languageData.ts +++ b/src/data/languages/languageData.ts @@ -9,8 +9,8 @@ export default { react: '2.16', csharp: '1.2', flutter: '1.2', - java: '1.4', - kotlin: '1.4', + java: '1.6', + kotlin: '1.6', objc: '1.2', php: '1.1', python: '2.1', @@ -25,8 +25,8 @@ export default { react: '2.16', csharp: '1.2', flutter: '1.2', - java: '1.4', - kotlin: '1.4', + java: '1.6', + kotlin: '1.6', objc: '1.2', php: '1.1', python: '2.1', @@ -52,7 +52,7 @@ export default { liveObjects: { javascript: '2.16', swift: '0.2', - java: '1.4', + java: '1.6', }, liveSync: { javascript: '0.4', diff --git a/src/pages/docs/api/realtime-sdk/channels.mdx b/src/pages/docs/api/realtime-sdk/channels.mdx index 08fd44c182..826a4d7fe2 100644 --- a/src/pages/docs/api/realtime-sdk/channels.mdx +++ b/src/pages/docs/api/realtime-sdk/channels.mdx @@ -824,11 +824,17 @@ Failure to retrieve the message history will trigger the `errback` callbacks of - + #### getMessage + `getMessage(serialOrMessage: string | Message): Promise` + + + +`Message getMessage(String serial)` + Retrieves the latest version of a specific message by its serial identifier. Requires the **history** [capability](/docs/auth/capabilities). @@ -836,6 +842,7 @@ See [updating and deleting messages: retrieving the latest version](/docs/messag ##### Parameters + | Parameter | Description | Type | |-----------|-------------|------| | 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) | @@ -843,10 +850,27 @@ See [updating and deleting messages: retrieving the latest version](/docs/messag ##### Returns 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. + + + +| Parameter | Description | Type | +|-----------|-------------|------| +| serial | Serial identifier string of the message to retrieve | `String` | + +##### Returns + +Returns a [`Message`](/docs/api/realtime-sdk/messages) object representing the latest version of the message. + #### updateMessage + `updateMessage(message: Message, operation?: MessageOperation): Promise` + + + +`void updateMessage(Message message, MessageOperation operation, Callback callback)` + 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). @@ -859,13 +883,27 @@ See [updating and deleting messages: updates](/docs/messages/updates-deletes#upd | message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field and the fields to update | [`Message`](/docs/api/realtime-sdk/messages) | | operation | An optional `MessageOperation` object containing metadata about the update operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | + ##### Returns 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. + + + +##### Returns + +Invokes the provided `Callback` with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message on success, or with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object describing the error on failure. + #### deleteMessage + `deleteMessage(message: Message, operation?: MessageOperation): Promise` + + + +`void deleteMessage(Message message, MessageOperation operation, Callback callback)` + 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). @@ -878,13 +916,27 @@ See [updating and deleting messages: deletes](/docs/messages/updates-deletes#del | message | A [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field | [`Message`](/docs/api/realtime-sdk/messages) | | operation | An optional `MessageOperation` object containing metadata about the delete operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | + ##### Returns 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. + + + +##### Returns + +Invokes the provided `Callback` with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message on success, or with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object describing the error on failure. + #### appendMessage + `appendMessage(message: Message, operation?: MessageOperation): Promise` + + + +`void appendMessage(Message message, MessageOperation operation, Callback callback)` + 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). @@ -897,13 +949,27 @@ See [updating and deleting messages: appends](/docs/messages/updates-deletes#app | 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) | | operation | An optional `MessageOperation` object containing metadata about the append operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | + ##### Returns 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. + + + +##### Returns + +Invokes the provided `Callback` with an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message on success, or with an [`ErrorInfo`](/docs/api/realtime-sdk/types#error-info) object describing the error on failure. + #### getMessageVersions + `getMessageVersions(serialOrMessage: string | Message, params?: Record): Promise>` + + + +`PaginatedResult getMessageVersions(String serial, Param[] params)` + 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). @@ -914,11 +980,21 @@ See [updating and deleting messages: message versions](/docs/messages/updates-de | Parameter | Description | Type | |-----------|-------------|------| | serialOrMessage | Either the serial identifier string of the message whose versions are to be retrieved, or a [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field | `string` or [`Message`](/docs/api/realtime-sdk/messages) | -| params | Optional parameters sent as part of the query string | `Record` (optional) | +| params | Optional parameters sent as part of the query string | `Record``Param[]` (optional) | + ##### Returns Returns a promise which, upon success, will be fulfilled with a [`PaginatedResult`](#paginated-result) object containing an array of [`Message`](/docs/api/realtime-sdk/messages) objects representing all versions 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. + + + +##### Returns + +On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an array of [`Message`](#message) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods. + +Failure to retrieve the message versions will raise an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception) + diff --git a/src/pages/docs/api/rest-sdk/channels.mdx b/src/pages/docs/api/rest-sdk/channels.mdx index 8bb9d40423..979af1114d 100644 --- a/src/pages/docs/api/rest-sdk/channels.mdx +++ b/src/pages/docs/api/rest-sdk/channels.mdx @@ -469,7 +469,13 @@ On failure to retrieve message history, the `error` contains an [`ErrorInfo`](#e #### getMessage + `getMessage(serialOrMessage: string | Message): Promise` + + + +`Message getMessage(String serial)` + Retrieves the latest version of a specific message by its serial identifier. Requires the **history** [capability](/docs/auth/capabilities). @@ -477,6 +483,7 @@ See [updating and deleting messages: retrieving the latest version](/docs/messag ##### Parameters + | Parameter | Description | Type | |-----------|-------------|------| | 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) | @@ -484,10 +491,27 @@ See [updating and deleting messages: retrieving the latest version](/docs/messag ##### Returns 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. + + + +| Parameter | Description | Type | +|-----------|-------------|------| +| serial | Serial identifier string of the message to retrieve | `String` | + +##### Returns + +Returns a [`Message`](/docs/api/realtime-sdk/messages) object representing the latest version of the message. + #### updateMessage + `updateMessage(message: Message, operation?: MessageOperation, params?: Record): Promise` + + + +`UpdateDeleteResult updateMessage(Message message, MessageOperation operation)` + 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). @@ -501,13 +525,27 @@ See [updating and deleting messages: updates](/docs/messages/updates-deletes#upd | operation | An optional `MessageOperation` object containing metadata about the update operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | | params | Optional parameters sent as part of the query string | `Record` (optional) | + ##### Returns 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. + + + +##### Returns + +Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. + #### deleteMessage + `deleteMessage(message: Message, operation?: MessageOperation, params?: Record): Promise` + + + +`UpdateDeleteResult deleteMessage(Message message, MessageOperation operation)` + 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). @@ -521,13 +559,27 @@ See [updating and deleting messages: deletes](/docs/messages/updates-deletes#del | operation | An optional `MessageOperation` object containing metadata about the delete operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | | params | Optional parameters sent as part of the query string | `Record` (optional) | + ##### Returns 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. + + + +##### Returns + +Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. + #### appendMessage + `appendMessage(message: Message, operation?: MessageOperation, params?: Record): Promise` + + + +`UpdateDeleteResult appendMessage(Message message, MessageOperation operation)` + 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). @@ -543,13 +595,27 @@ See [updating and deleting messages: appends](/docs/messages/updates-deletes#app | operation | An optional `MessageOperation` object containing metadata about the append operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) | | params | Optional parameters sent as part of the query string | `Record` (optional) | + ##### Returns 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. + + + +##### Returns + +Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message. + #### getMessageVersions + `getMessageVersions(serialOrMessage: string | Message, params?: Record): Promise>` + + + +`PaginatedResult getMessageVersions(String serial, Param[] params)` + 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). @@ -562,9 +628,19 @@ See [updating and deleting messages: versions](/docs/messages/updates-deletes#ve | serialOrMessage | Either the serial identifier string of the message whose versions are to be retrieved, or a [`Message`](/docs/api/realtime-sdk/messages) object containing a populated `serial` field | `string` or [`Message`](/docs/api/realtime-sdk/messages) | | params | Optional parameters sent as part of the query string | `Record` (optional) | + ##### Returns Returns a promise which, upon success, will be fulfilled with a [`PaginatedResult`](#paginated-result) object containing an array of [`Message`](/docs/api/realtime-sdk/messages) objects representing all versions 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. + + + +##### Returns + +On success, the returned [`PaginatedResult`](#paginated-result) encapsulates an array of [`Message`](#message) objects corresponding to the current page of results. [`PaginatedResult`](#paginated-result) supports pagination using [`next`](#paginated-result) and [`first`](#paginated-result) methods. + +Failure to retrieve the message versions will raise an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception) + @@ -986,8 +1062,7 @@ console.log('Last page?: ' + nextPage.isLast()); ```nodejs const paginatedResult = await channel.history(); -conn m,./ 2 -\sole.log('Page 0 item 0:' + paginatedResult.items[0].data); +console.log('Page 0 item 0:' + paginatedResult.items[0].data); const nextPage = await paginatedResult.next(); console.log('Page 1 item 1: ' + nextPage.items[1].data); console.log('Last page?: ' + nextPage.isLast()); diff --git a/src/pages/docs/messages/updates-deletes.mdx b/src/pages/docs/messages/updates-deletes.mdx index 05739cb41a..d8ff65ce60 100644 --- a/src/pages/docs/messages/updates-deletes.mdx +++ b/src/pages/docs/messages/updates-deletes.mdx @@ -122,6 +122,47 @@ channel.publish([.init(name: "message-name", data: "original-data")]) { result, } } ``` + +```java +AblyRealtime realtime = new AblyRealtime("{{API_KEY}}"); +// This assumes there is an 'updates' namespace with a channel rule enabling updates and deletes +Channel channel = realtime.channels.get("updates:example"); + +// Publish the original message and get its serial from the result +CompletableFuture publishFuture = new CompletableFuture<>(); +channel.publish("message-name", "original-data", new Callback() { + @Override + public void onSuccess(PublishResult result) { + publishFuture.complete(result); + } + + @Override + public void onError(ErrorInfo reason) { + publishFuture.completeExceptionally(AblyException.fromErrorInfo(reason)); + } +}); +String serial = publishFuture.get().serials[0]; + +// Publish an update using the serial +Message message = new Message(); +message.data = "updated-data"; +message.serial = serial; +MessageOperation operation = new MessageOperation(); +operation.description = "reason for update"; +CompletableFuture updateFuture = new CompletableFuture<>(); +channel.updateMessage(message, operation, new Callback() { + @Override + public void onSuccess(UpdateDeleteResult result) { + updateFuture.complete(result); + } + + @Override + public void onError(ErrorInfo reason) { + updateFuture.completeExceptionally(AblyException.fromErrorInfo(reason)); + } +}); +updateFuture.get(); +``` #### Returns @@ -250,6 +291,47 @@ channel.publish([.init(name: "message-name", data: "original-data")]) { result, } } ``` + +```java +AblyRealtime realtime = new AblyRealtime("{{API_KEY}}"); +// This assumes there is an 'updates' namespace with a channel rule enabling updates and deletes +Channel channel = realtime.channels.get("updates:example"); + +// Publish the original message and get its serial from the result +CompletableFuture publishFuture = new CompletableFuture<>(); +channel.publish("message-name", "original-data", new Callback() { + @Override + public void onSuccess(PublishResult result) { + publishFuture.complete(result); + } + + @Override + public void onError(ErrorInfo reason) { + publishFuture.completeExceptionally(AblyException.fromErrorInfo(reason)); + } +}); +String serial = publishFuture.get().serials[0]; + +// Publish an update using the serial +Message message = new Message(); +message.data = ""; +message.serial = serial; +MessageOperation operation = new MessageOperation(); +operation.description = "reason for delete"; +CompletableFuture deleteFuture = new CompletableFuture<>(); +channel.deleteMessage(message, operation, new Callback() { + @Override + public void onSuccess(UpdateDeleteResult result) { + deleteFuture.complete(result); + } + + @Override + public void onError(ErrorInfo reason) { + deleteFuture.completeExceptionally(AblyException.fromErrorInfo(reason)); + } +}); +deleteFuture.get(); +``` #### Returns @@ -348,6 +430,56 @@ channel.appendMessage({ serial, data: '!' }); // the message in history now has data: "Hello, World!" ``` +```java +AblyRealtime realtime = new AblyRealtime("{{API_KEY}}"); +// This assumes there is an 'updates' namespace with a channel rule enabling updates and deletes +Channel channel = realtime.channels.get("updates:example"); + +// Publish the original message and get its serial from the result +CompletableFuture publishFuture = new CompletableFuture<>(); +channel.publish("message-name", "Hello", new Callback() { + @Override + public void onSuccess(PublishResult result) { + publishFuture.complete(result); + } + + @Override + public void onError(ErrorInfo reason) { + publishFuture.completeExceptionally(AblyException.fromErrorInfo(reason)); + } +}); +String serial = publishFuture.get().serials[0]; + +// Append to the message a few times (without needing to await each to finish +// before doing the next); the data will be concatenated +Message message1 = new Message(); +message1.data = " , "; +message1.serial = serial; +channel.appendMessage(message1); +Message message2 = new Message(); +message2.data = "World"; +message2.serial = serial; +channel.appendMessage(message2); +Message message3 = new Message(); +message3.data = "!"; +message3.serial = serial; +CompletableFuture appendFuture = new CompletableFuture<>(); +channel.appendMessage(message3, new Callback() { + @Override + public void onSuccess(PublishResult result) { + appendFuture.complete(result); + } + + @Override + public void onError(ErrorInfo reason) { + appendFuture.completeExceptionally(AblyException.fromErrorInfo(reason)); + } +}); +appendFuture.get(); + +// the message in history now has data: "Hello, World!" +``` + ```swift import Ably @@ -467,6 +599,16 @@ channel.getMessageWithSerial(serial) { message, error in } } ``` + +```java +AblyRest rest = new AblyRest("{{API_KEY}}"); +Channel channel = rest.channels.get("updates:example"); + +// Example serial; for example from the `serial` property of a `Message` you previously received +String serial = "0123456789-001@abcdefghij:001"; + +Message message = channel.getMessage(serial); +``` ## Get message versions @@ -511,6 +653,17 @@ channel.getMessageVersions(withSerial: serial) { page, error in } } ``` + +```java +AblyRest rest = new AblyRest("{{API_KEY}}"); +Channel channel = rest.channels.get("updates:example"); + +// Example serial; for example from the `serial` property of a `Message` you previously received +String serial = "0123456789-001@abcdefghij:001"; + +PaginatedResult page = channel.getMessageVersions(serial); +System.out.println("Found " + page.items().length + " versions"); +``` ## Message version structure