Skip to content

Commit 0940436

Browse files
ttypicttypic
committed
[AIT-304] feat: Mutable messages ably-java
1 parent b3a3ecf commit 0940436

3 files changed

Lines changed: 289 additions & 2 deletions

File tree

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

Lines changed: 77 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -824,29 +824,53 @@ 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)`
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+
860+
##### Returns
861+
862+
Returns a [`Message`](/docs/api/realtime-sdk/messages) object representing the latest version of the message.
863+
</If>
846864

847865
#### updateMessage
848866

867+
<If lang="javascript,nodejs">
849868
`updateMessage(message: Message, operation?: MessageOperation): Promise<UpdateDeleteResult>`
869+
</If>
870+
871+
<If lang="java">
872+
`void updateMessage(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback)`
873+
</If>
850874

851875
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).
852876

@@ -859,13 +883,27 @@ See [updating and deleting messages: updates](/docs/messages/updates-deletes#upd
859883
| 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) |
860884
| operation | An optional `MessageOperation` object containing metadata about the update operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) |
861885

886+
<If lang="javascript,nodejs">
862887
##### Returns
863888

864889
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.
890+
</If>
891+
892+
<If lang="java">
893+
##### Returns
894+
895+
Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message.
896+
</If>
865897

866898
#### deleteMessage
867899

900+
<If lang="javascript,nodejs">
868901
`deleteMessage(message: Message, operation?: MessageOperation): Promise<UpdateDeleteResult>`
902+
</If>
903+
904+
<If lang="java">
905+
`void deleteMessage(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback)`
906+
</If>
869907

870908
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).
871909

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

919+
<If lang="javascript,nodejs">
881920
##### Returns
882921

883922
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.
923+
</If>
924+
925+
<If lang="java">
926+
##### Returns
927+
928+
Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message.
929+
</If>
884930

885931
#### appendMessage
886932

933+
<If lang="javascript,nodejs">
887934
`appendMessage(message: Message, operation?: MessageOperation): Promise<UpdateDeleteResult>`
935+
</If>
936+
937+
<If lang="java">
938+
`void appendMessage(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback)`
939+
</If>
888940

889941
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).
890942

@@ -897,13 +949,27 @@ See [updating and deleting messages: appends](/docs/messages/updates-deletes#app
897949
| 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) |
898950
| operation | An optional `MessageOperation` object containing metadata about the append operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) |
899951

952+
<If lang="javascript,nodejs">
900953
##### Returns
901954

902955
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.
956+
</If>
957+
958+
<If lang="java">
959+
##### Returns
960+
961+
Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message.
962+
</If>
903963

904964
#### getMessageVersions
905965

966+
<If lang="javascript,nodejs">
906967
`getMessageVersions(serialOrMessage: string | Message, params?: Record<string, any>): Promise<PaginatedResult<Message>>`
968+
</If>
969+
970+
<If lang="java">
971+
`PaginatedResult<Message> getMessageVersions(String serial, Param[] params)`
972+
</If>
907973

908974
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).
909975

@@ -916,9 +982,19 @@ See [updating and deleting messages: message versions](/docs/messages/updates-de
916982
| 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) |
917983
| params | Optional parameters sent as part of the query string | `Record<string, any>` (optional) |
918984

985+
<If lang="javascript,nodejs">
919986
##### Returns
920987

921988
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.
989+
</If>
990+
991+
<If lang="java">
992+
#### Returns
993+
994+
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.
995+
996+
Failure to retrieve the message versions will raise an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception)
997+
</If>
922998

923999
</If>
9241000

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

Lines changed: 77 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -469,25 +469,49 @@ 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)`
478+
</If>
473479

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

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

478484
##### Parameters
479485

486+
<If lang="javascript,nodejs">
480487
| Parameter | Description | Type |
481488
|-----------|-------------|------|
482489
| 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) |
483490

484491
##### Returns
485492

486493
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.
494+
</If>
495+
496+
<If lang="java">
497+
| Parameter | Description | Type |
498+
|-----------|-------------|------|
499+
| serial | Serial identifier string of the message to retrieve | `string` |
500+
501+
##### Returns
502+
503+
Returns a [`Message`](/docs/api/realtime-sdk/messages) object representing the latest version of the message.
504+
</If>
487505

488506
#### updateMessage <a id="update-message" />
489507

490-
`updateMessage(message: Message, operation?: MessageOperation, params?: Record<string, any>): Promise<UpdateDeleteResult>`
508+
<If lang="javascript,nodejs">
509+
`updateMessage(message: Message, operation?: MessageOperation, params?: Record<string, any>): Promise<UpdateDeleteResult>
510+
</If>
511+
512+
<If lang="java">
513+
`UpdateDeleteResult updateMessage(Message message, MessageOperation operation)`
514+
</If>
491515

492516
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).
493517

@@ -501,13 +525,27 @@ See [updating and deleting messages: updates](/docs/messages/updates-deletes#upd
501525
| operation | An optional `MessageOperation` object containing metadata about the update operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) |
502526
| params | Optional parameters sent as part of the query string | `Record<string, any>` (optional) |
503527

528+
<If lang="javascript,nodejs">
504529
##### Returns
505530

506531
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.
532+
</If>
533+
534+
<If lang="java">
535+
##### Returns
536+
537+
Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message.
538+
</If>
507539

508540
#### deleteMessage
509541

542+
<If lang="javascript,nodejs">
510543
`deleteMessage(message: Message, operation?: MessageOperation, params?: Record<string, any>): Promise<UpdateDeleteResult>`
544+
</If>
545+
546+
<If lang="java">
547+
`UpdateDeleteResult deleteMessage(Message message, MessageOperation operation)`
548+
</If>
511549

512550
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).
513551

@@ -521,13 +559,27 @@ See [updating and deleting messages: deletes](/docs/messages/updates-deletes#del
521559
| operation | An optional `MessageOperation` object containing metadata about the delete operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) |
522560
| params | Optional parameters sent as part of the query string | `Record<string, any>` (optional) |
523561

562+
<If lang="javascript,nodejs">
524563
##### Returns
525564

526565
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.
566+
</If>
567+
568+
<If lang="java">
569+
##### Returns
570+
571+
Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message.
572+
</If>
527573

528574
#### appendMessage
529575

576+
<If lang="javascript,nodejs">
530577
`appendMessage(message: Message, operation?: MessageOperation, params?: Record<string, any>): Promise<UpdateDeleteResult>`
578+
</If>
579+
580+
<If lang="java">
581+
`UpdateDeleteResult appendMessage(Message message, MessageOperation operation)`
582+
</If>
531583

532584
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).
533585

@@ -543,13 +595,27 @@ See [updating and deleting messages: appends](/docs/messages/updates-deletes#app
543595
| operation | An optional `MessageOperation` object containing metadata about the append operation. Can include `clientId`, `description`, and `metadata` fields | `MessageOperation` (optional) |
544596
| params | Optional parameters sent as part of the query string | `Record<string, any>` (optional) |
545597

598+
<If lang="javascript,nodejs">
546599
##### Returns
547600

548601
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.
602+
</If>
603+
604+
<If lang="java">
605+
##### Returns
606+
607+
Returns an [`UpdateDeleteResult`](/docs/api/realtime-sdk/types#update-delete-result) object containing the new version of the message.
608+
</If>
549609

550610
#### getMessageVersions
551611

612+
<If lang="javascript,nodejs">
552613
`getMessageVersions(serialOrMessage: string | Message, params?: Record<string, any>): Promise<PaginatedResult<Message>>`
614+
</If>
615+
616+
<If lang="java">
617+
`PaginatedResult<Message> getMessageVersions(String serial, Param[] params)`
618+
</If>
553619

554620
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).
555621

@@ -562,9 +628,19 @@ See [updating and deleting messages: versions](/docs/messages/updates-deletes#ve
562628
| 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) |
563629
| params | Optional parameters sent as part of the query string | `Record<string, any>` (optional) |
564630

631+
<If lang="javascript,nodejs">
565632
##### Returns
566633

567634
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.
635+
</If>
636+
637+
<If lang="java">
638+
#### Returns
639+
640+
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.
641+
642+
Failure to retrieve the message versions will raise an [`AblyException`](/docs/api/realtime-sdk/types#ably-exception)
643+
</If>
568644

569645
</If>
570646

0 commit comments

Comments
 (0)