From 5ec6d58e3f8d3814aa8cce0f2c215bf772f2f871 Mon Sep 17 00:00:00 2001 From: Peter Maguire Date: Mon, 9 May 2022 16:04:10 +0100 Subject: [PATCH 01/12] Batch operations spec points --- .../features.textile | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index 4d9b671590..139ca9c188 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -1516,6 +1516,7 @@ class Realtime: auth: Auth // RTC4 push: Push device() => io LocalDevice + batch: BatchOperations channels: Channels // RTC3, RTS1 clientId: String? // proxy for RSA7 connection: Connection // RTC2 @@ -1662,6 +1663,34 @@ class RealtimeChannel: unsubscribe(String, (Message) ->) // RTL8a setOptions(options: ChannelOptions) => io // RTL16 +class BatchOperations: + publish([Channel], [Message]) => BatchPublishResult + publish(Channel, [Message]) => BatchPublishResult + publish([Channel], Message) => BatchPublishResult + getPresence([Channel]) => BatchPresenceResult + +class BatchPublishResult: + error: ErrorInfo? + responses: []BatchPublishResponse? + +class BatchPublishResponse: + channel: String + messageId: String? + error: ErrorInfo? + +class BatchPresenceResult: + error: ErrorInfo? + responses: []BatchPresenceResponse? + +class BatchPresenceResponse + channel: String + presence: []BatchPresence + +class BatchPresence: + clientId: string + action: string? + error: ErrorInfo? + class PushChannel: subscribeDevice() => io // RSH7a subscribeClient() => io // RSH7b From 57aed769c503d742e00967feb9008331d7999dbd Mon Sep 17 00:00:00 2001 From: Peter Maguire Date: Mon, 9 May 2022 16:43:27 +0100 Subject: [PATCH 02/12] some headings --- .../features.textile | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index 139ca9c188..87225973b5 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -1336,6 +1336,25 @@ h4. ChannelProperties * @(CP2)@ The attributes of @ChannelProperties@ consist of: ** @(CP2a)@ @attachSerial@ string - contains the last @channelSerial@ received in an @ATTACHED@ @ProtocolMesage@ for the channel, see "RTL15a":#RTL15a + +h4. BatchPublishResult +* @(BPS1)@ the error object is populated if an error is returned from the API, and left undefined if not +* @(BPS2)@ an array of @BatchPublishResponse@ objects. undefined if the request failed completely + + +h4. BatchPublishResponse +* @(BPR1)@ + + +h4. BatchPresenceResult + + +h4. BatchPresenceResponse + + +h4. BatchPresence + + h3(#options). Option types h4. ClientOptions From f4ba9fdcf1c711443dad43cb3e2b3c222bcde114 Mon Sep 17 00:00:00 2001 From: Peter Maguire Date: Mon, 9 May 2022 16:43:27 +0100 Subject: [PATCH 03/12] Batch operations spec points --- .../features.textile | 57 +++++++++++++------ 1 file changed, 40 insertions(+), 17 deletions(-) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index 139ca9c188..1c711e8931 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -1336,6 +1336,33 @@ h4. ChannelProperties * @(CP2)@ The attributes of @ChannelProperties@ consist of: ** @(CP2a)@ @attachSerial@ string - contains the last @channelSerial@ received in an @ATTACHED@ @ProtocolMesage@ for the channel, see "RTL15a":#RTL15a +h4. BatchResult +* @(BPA1)@ Contains the results from the batch operation +* @(BPA2)@ @BatchResult@ has the following attributes: +** @(BPA2a)@ @responses@ is an array of batch response objects. undefined if the request failed completely (e.g. for an invalid key) +** @(BPA2b)@ @error@ is an @ErrorInfo@ object which is populated if one or more batch publish requests failed + +h4. BatchPublishResponse +* @(BPB1)@ Contains information for each batch publish request within a @BatchResult@ +* @(BPB2)@ @BatchPublishResponse@ has the following attributes: +** (@BPB2a)@ @channel@ is the channel name which this publish request was directed to +** (@BPB2b)@ @messageId@ contains the resultant message ID, if the request succeeds and is undefined if @error@ is present +** (@BPB2c)@ @error@ contains an @ErrorInfo@ object if this publish request failed, and is undefined if it succeeded + +h4. BatchPresenceResponse +* @(BPD1)@ Contains information for each batch presence request within a @BatchResult@ +* @(BPD2)@ @BatchPresenceResponse@ contains the following attributes: +** @(BPD2a)@ @channel@ is the channel name which this presence request +** @(BPD2b)@ @presence@ is an array of presence data for the @channel@ + +h4. BatchPresence +* @(BPE1)@ Is a partial @PresenceMessage@ object containing @clientId@ and @action@, or @error@ if the presence failed +* @(PBE2)@ @BatchPresence@ contains the following attributes: +** @(PBE2a)@ @clientId@ - identical to #TP3c +** @(PBE2a)@ @action@ - identical to #TP3b - undefined if @error@ is present +** @(PBE2a)@ @error@ - an @ErrorInfo@ object representing the failure reason for this channel - undefined if @action@ is present + + h3(#options). Option types h4. ClientOptions @@ -1664,27 +1691,23 @@ class RealtimeChannel: setOptions(options: ChannelOptions) => io // RTL16 class BatchOperations: - publish([Channel], [Message]) => BatchPublishResult - publish(Channel, [Message]) => BatchPublishResult - publish([Channel], Message) => BatchPublishResult - getPresence([Channel]) => BatchPresenceResult + publish([Channel], [Message]) => BatchResult + publish(Channel, [Message]) => BatchResult + publish([Channel], Message) => BatchResult + getPresence([Channel]) => BatchResult -class BatchPublishResult: - error: ErrorInfo? - responses: []BatchPublishResponse? +class BatchResult: + error: ErrorInfo? // BPA2b + responses: []T? // BPA2a class BatchPublishResponse: - channel: String - messageId: String? - error: ErrorInfo? - -class BatchPresenceResult: - error: ErrorInfo? - responses: []BatchPresenceResponse? + channel: String // BPB2a + messageId: String? // BPB2b + error: ErrorInfo? // BPB2c -class BatchPresenceResponse - channel: String - presence: []BatchPresence +class BatchPresenceResponse: + channel: String // BPD2a + presence: []BatchPresence // PBD2b class BatchPresence: clientId: string From 5708b1d3768ef36f5b36c1b369da4c081d562f90 Mon Sep 17 00:00:00 2001 From: Peter Maguire Date: Tue, 10 May 2022 15:52:56 +0100 Subject: [PATCH 04/12] add batch operations heading for the rest client --- .../features.textile | 20 ++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index 1c711e8931..5a6df193cd 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -17,6 +17,7 @@ jump_to: - Presence#rest-presence - Encryption#rest-encryption - Forwards compatibility#rest-compatibility + - Batch Operations#batch-operations Realtime client library: - RealtimeClient - Connection#realtime-connection @@ -337,6 +338,14 @@ h3(#rest-encryption). Encryption h3(#rest-compatibility). Forwards compatibility * @(RSF1)@ The library must apply the "robustness principle":https://en.wikipedia.org/wiki/Robustness_principle in its processing of requests and responses with the Ably system. In particular, deserialization of Messages and related types, and associated enums, must be tolerant to unrecognised attributes or enum values. Such unrecognised values must be ignored. +h3(#batch-operations). Batch Operations +* @(BO1)@ The batch operations functions must use the REST endpoints in Batch Mode, sending a single request containing all specified data +* @(BO2)@ Batch operations must be able to be performed for the following: +** @(BO2a)@ Publishing messages against one or more channels with one or more messages +*** @(B02a1)@ Functions should be provided to pass either an array or a single object for both Message and Channel +** @(BO2b)@ Retrieving the presence data for one or more channels +* @(BO3)@ When all passed arrays contain a single object, the underlying request is functionally identical to it's non-batch equivalent, but the returned result should be a @BatchResponse@ object. + h2(#realtime). Realtime client library features The Ably Realtime client libraries establish and maintain a persistent connection to Ably and provide methods to publish and subscribe to messages over a low latency realtime connection. @@ -1518,6 +1527,7 @@ class Rest: constructor(ClientOptions) // RSC1 auth: Auth // RSC5 push: Push + batch: BatchOperations // BO1 device() => io LocalDevice channels: Channels // RSN1 request( @@ -1543,7 +1553,6 @@ class Realtime: auth: Auth // RTC4 push: Push device() => io LocalDevice - batch: BatchOperations channels: Channels // RTC3, RTS1 clientId: String? // proxy for RSA7 connection: Connection // RTC2 @@ -1678,6 +1687,7 @@ class RealtimeChannel: end: Time api-default now(), // RTL10a direction: .Backwards | .Forwards api-default .Backwards, // RTL10a limit: int api-default 100, // RTL10a + limit: int api-default 100, // RTL10a untilAttach: Bool default false // RTL10b ) => io PaginatedResult // RSL2a publish(Message) => io // RTL6i @@ -1691,10 +1701,10 @@ class RealtimeChannel: setOptions(options: ChannelOptions) => io // RTL16 class BatchOperations: - publish([Channel], [Message]) => BatchResult - publish(Channel, [Message]) => BatchResult - publish([Channel], Message) => BatchResult - getPresence([Channel]) => BatchResult + publish([Channel], [Message]) => BatchResult // BO2a + publish(Channel, [Message]) => BatchResult // BO2a + publish([Channel], Message) => BatchResult // BO2a + getPresence([Channel]) => BatchResult // BO2b class BatchResult: error: ErrorInfo? // BPA2b From 9943b893770ba4f28846687dbd0d46754e04953a Mon Sep 17 00:00:00 2001 From: Peter Maguire Date: Tue, 10 May 2022 16:03:04 +0100 Subject: [PATCH 05/12] fix duplicates --- content/client-lib-development-guide/features.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index 9e022a569c..4de9e00acd 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -1402,8 +1402,8 @@ h4. BatchPresence * @(BPE1)@ Is a partial @PresenceMessage@ object containing @clientId@ and @action@, or @error@ if the presence failed * @(PBE2)@ @BatchPresence@ contains the following attributes: ** @(PBE2a)@ @clientId@ - identical to #TP3c -** @(PBE2a)@ @action@ - identical to #TP3b - undefined if @error@ is present -** @(PBE2a)@ @error@ - an @ErrorInfo@ object representing the failure reason for this channel - undefined if @action@ is present +** @(PBE2b)@ @action@ - identical to #TP3b - undefined if @error@ is present +** @(PBE2c)@ @error@ - an @ErrorInfo@ object representing the failure reason for this channel - undefined if @action@ is present h3(#options). Option types From e1d3090a526241aafb3571668d0c4c3dbee09dcd Mon Sep 17 00:00:00 2001 From: Peter Maguire Date: Wed, 11 May 2022 10:07:43 +0100 Subject: [PATCH 06/12] Update content/client-lib-development-guide/features.textile Co-authored-by: Owen Pearson <48608556+owenpearson@users.noreply.github.com> --- content/client-lib-development-guide/features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index 4de9e00acd..b1abe63f22 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -346,7 +346,7 @@ h3(#batch-operations). Batch Operations ** @(BO2a)@ Publishing messages against one or more channels with one or more messages *** @(B02a1)@ Functions should be provided to pass either an array or a single object for both Message and Channel ** @(BO2b)@ Retrieving the presence data for one or more channels -* @(BO3)@ When all passed arrays contain a single object, the underlying request is functionally identical to it's non-batch equivalent, but the returned result should be a @BatchResponse@ object. +* @(BO3)@ When all passed arrays contain a single object, the underlying request is functionally identical to its non-batch equivalent, but the returned result should be a @BatchResponse@ object. h2(#realtime). Realtime client library features From 2cdba4a3cc09efeb703bacc864b0e1f6489e068a Mon Sep 17 00:00:00 2001 From: Peter Maguire Date: Wed, 11 May 2022 10:20:39 +0100 Subject: [PATCH 07/12] suggested changes --- .../features.textile | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index b1abe63f22..04f6660350 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -343,9 +343,9 @@ h3(#rest-compatibility). Forwards compatibility h3(#batch-operations). Batch Operations * @(BO1)@ The batch operations functions must use the REST endpoints in Batch Mode, sending a single request containing all specified data * @(BO2)@ Batch operations must be able to be performed for the following: -** @(BO2a)@ Publishing messages against one or more channels with one or more messages -*** @(B02a1)@ Functions should be provided to pass either an array or a single object for both Message and Channel -** @(BO2b)@ Retrieving the presence data for one or more channels +** @(BO2a)@ @BatchOperations::publish@ publishes messages against one or more channels with one or more messages +*** @(B02a1)@ Functions should be provided to pass either an array or a single object for both Message and Channel ID +** @(BO2b)@ @BatchOperations::getPresence@ retrieves the presence data for one or more channels * @(BO3)@ When all passed arrays contain a single object, the underlying request is functionally identical to its non-batch equivalent, but the returned result should be a @BatchResponse@ object. h2(#realtime). Realtime client library features @@ -1357,7 +1357,7 @@ h4. ChannelDetails h4. ChannelStatus -* @(CHS1)@ @ChannelStatus@ is a type that contains status and occupancy for a channel +* @(CHS1)@ @ChannelStatus@ is a type that contains status and occupancy for a channel * @(CHS2)@ The attributes of @ChannelStatus@ consist of: ** @(CHS2a)@ @isActive@ boolean - represents if the channel is active ** @(CHS2b)@ @occupancy@ @ChannelOccupancy@ - occupancy is an object containing the metrics for the channel @@ -1370,13 +1370,13 @@ h4. ChannelOccupancy h4. ChannelMetrics -* @(CHM1)@ @ChannelMetrics@ is a type that contains the count of publishers and subscribers, connections and presenceConnections, presenceMembers and presenceSubscribers +* @(CHM1)@ @ChannelMetrics@ is a type that contains the count of publishers and subscribers, connections and presenceConnections, presenceMembers and presenceSubscribers * @(CHM2)@ The attributes of @ChannelMetrics@ consist of: ** @(CHM2a)@ @connections@ integer - the total number of connections to the channel ** @(CHM2b)@ @presenceConnections@ integer - the total number of presence connections to the channel ** @(CHM2c)@ @presenceMembers@ integer - the total number of presence members for the channel ** @(CHM2d)@ @presenceSubscribers@ integer - the total number of presence subscribers for the channel -** @(CHM2e)@ @publishers@ integer - the total number of publishers to the channel +** @(CHM2e)@ @publishers@ integer - the total number of publishers to the channel ** @(CHM2f)@ @subscribers@ integer - the total number of subscribers to the channel h4. BatchResult @@ -1722,7 +1722,6 @@ class RealtimeChannel: end: Time api-default now(), // RTL10a direction: .Backwards | .Forwards api-default .Backwards, // RTL10a limit: int api-default 100, // RTL10a - limit: int api-default 100, // RTL10a untilAttach: Bool default false // RTL10b ) => io PaginatedResult // RSL2a publish(Message) => io // RTL6i @@ -1736,10 +1735,10 @@ class RealtimeChannel: setOptions(options: ChannelOptions) => io // RTL16 class BatchOperations: - publish([Channel], [Message]) => BatchResult // BO2a - publish(Channel, [Message]) => BatchResult // BO2a - publish([Channel], Message) => BatchResult // BO2a - getPresence([Channel]) => BatchResult // BO2b + publish([String], [Message]) => BatchResult // BO2a + publish(String, [Message]) => BatchResult // BO2a + publish([String], Message) => BatchResult // BO2a + getPresence([String]) => BatchResult // BO2b class BatchResult: error: ErrorInfo? // BPA2b From 859971218fb5ea2cf83a84586812ea050125e6ed Mon Sep 17 00:00:00 2001 From: Peter Maguire Date: Wed, 11 May 2022 10:30:33 +0100 Subject: [PATCH 08/12] BatchSpec publishing --- content/client-lib-development-guide/features.textile | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index 04f6660350..6c0dee1a96 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -344,7 +344,7 @@ h3(#batch-operations). Batch Operations * @(BO1)@ The batch operations functions must use the REST endpoints in Batch Mode, sending a single request containing all specified data * @(BO2)@ Batch operations must be able to be performed for the following: ** @(BO2a)@ @BatchOperations::publish@ publishes messages against one or more channels with one or more messages -*** @(B02a1)@ Functions should be provided to pass either an array or a single object for both Message and Channel ID +*** @(B02a1)@ Functions should be provided to pass either an array or a single object for both Message and Channel ID, or an array of @BatchSpec@ objects ** @(BO2b)@ @BatchOperations::getPresence@ retrieves the presence data for one or more channels * @(BO3)@ When all passed arrays contain a single object, the underlying request is functionally identical to its non-batch equivalent, but the returned result should be a @BatchResponse@ object. @@ -1738,6 +1738,7 @@ class BatchOperations: publish([String], [Message]) => BatchResult // BO2a publish(String, [Message]) => BatchResult // BO2a publish([String], Message) => BatchResult // BO2a + publish([BatchSpec]) => BatchResult // BO2a getPresence([String]) => BatchResult // BO2b class BatchResult: @@ -1765,6 +1766,10 @@ class PushChannel: unsubscribeClient() => io // RSH7d listSubscriptions() => io PaginatedResult // RSH7e +class BatchSpec: + channels: [String] + messages: [Message] + enum ChannelState: INITIALIZED ATTACHING From b0ec9971e2189521e4273e37457231f99c8b6fcd Mon Sep 17 00:00:00 2001 From: Peter Maguire Date: Wed, 11 May 2022 12:19:22 +0100 Subject: [PATCH 09/12] replace references to 'undefined' with 'null' --- content/client-lib-development-guide/features.textile | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index 6c0dee1a96..e278d3f590 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -1382,15 +1382,15 @@ h4. ChannelMetrics h4. BatchResult * @(BPA1)@ Contains the results from the batch operation * @(BPA2)@ @BatchResult@ has the following attributes: -** @(BPA2a)@ @responses@ is an array of batch response objects. undefined if the request failed completely (e.g. for an invalid key) +** @(BPA2a)@ @responses@ is an array of batch response objects. null if the request failed completely (e.g. for an invalid key) ** @(BPA2b)@ @error@ is an @ErrorInfo@ object which is populated if one or more batch publish requests failed h4. BatchPublishResponse * @(BPB1)@ Contains information for each batch publish request within a @BatchResult@ * @(BPB2)@ @BatchPublishResponse@ has the following attributes: ** (@BPB2a)@ @channel@ is the channel name which this publish request was directed to -** (@BPB2b)@ @messageId@ contains the resultant message ID, if the request succeeds and is undefined if @error@ is present -** (@BPB2c)@ @error@ contains an @ErrorInfo@ object if this publish request failed, and is undefined if it succeeded +** (@BPB2b)@ @messageId@ contains the resultant message ID, if the request succeeds and is null if @error@ is present +** (@BPB2c)@ @error@ contains an @ErrorInfo@ object if this publish request failed, and is null if it succeeded h4. BatchPresenceResponse * @(BPD1)@ Contains information for each batch presence request within a @BatchResult@ @@ -1402,8 +1402,8 @@ h4. BatchPresence * @(BPE1)@ Is a partial @PresenceMessage@ object containing @clientId@ and @action@, or @error@ if the presence failed * @(PBE2)@ @BatchPresence@ contains the following attributes: ** @(PBE2a)@ @clientId@ - identical to #TP3c -** @(PBE2b)@ @action@ - identical to #TP3b - undefined if @error@ is present -** @(PBE2c)@ @error@ - an @ErrorInfo@ object representing the failure reason for this channel - undefined if @action@ is present +** @(PBE2b)@ @action@ - identical to #TP3b - null if @error@ is present +** @(PBE2c)@ @error@ - an @ErrorInfo@ object representing the failure reason for this channel - null if @action@ is present h3(#options). Option types From 1e1ded87b7b3c1cc7219e46f0aac1828736be373 Mon Sep 17 00:00:00 2001 From: Peter Maguire Date: Wed, 11 May 2022 12:23:31 +0100 Subject: [PATCH 10/12] remove shorthand publish functions --- content/client-lib-development-guide/features.textile | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index e278d3f590..84f2e0d420 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -344,7 +344,7 @@ h3(#batch-operations). Batch Operations * @(BO1)@ The batch operations functions must use the REST endpoints in Batch Mode, sending a single request containing all specified data * @(BO2)@ Batch operations must be able to be performed for the following: ** @(BO2a)@ @BatchOperations::publish@ publishes messages against one or more channels with one or more messages -*** @(B02a1)@ Functions should be provided to pass either an array or a single object for both Message and Channel ID, or an array of @BatchSpec@ objects +*** @(B02a1)@ Functions should be provided to pass either an array or a single @BatchSpec@ object. In languages where function overloading is not possible, an array is preferred. ** @(BO2b)@ @BatchOperations::getPresence@ retrieves the presence data for one or more channels * @(BO3)@ When all passed arrays contain a single object, the underlying request is functionally identical to its non-batch equivalent, but the returned result should be a @BatchResponse@ object. @@ -1735,10 +1735,8 @@ class RealtimeChannel: setOptions(options: ChannelOptions) => io // RTL16 class BatchOperations: - publish([String], [Message]) => BatchResult // BO2a - publish(String, [Message]) => BatchResult // BO2a - publish([String], Message) => BatchResult // BO2a publish([BatchSpec]) => BatchResult // BO2a + publish(BatchSpec) => BatchResult // BO2a getPresence([String]) => BatchResult // BO2b class BatchResult: From 16917a8ad3742064e320d9a7ff38bb14fedbcd08 Mon Sep 17 00:00:00 2001 From: Peter Maguire Date: Wed, 11 May 2022 13:45:00 +0100 Subject: [PATCH 11/12] Update content/client-lib-development-guide/features.textile Co-authored-by: Rosie Hamilton --- content/client-lib-development-guide/features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index 84f2e0d420..f67386d452 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -346,7 +346,7 @@ h3(#batch-operations). Batch Operations ** @(BO2a)@ @BatchOperations::publish@ publishes messages against one or more channels with one or more messages *** @(B02a1)@ Functions should be provided to pass either an array or a single @BatchSpec@ object. In languages where function overloading is not possible, an array is preferred. ** @(BO2b)@ @BatchOperations::getPresence@ retrieves the presence data for one or more channels -* @(BO3)@ When all passed arrays contain a single object, the underlying request is functionally identical to its non-batch equivalent, but the returned result should be a @BatchResponse@ object. +* @(BO3)@ When a batch operation only contains one batch, the underlying request is functionally identical to its non-batch equivalent, but the returned result should be a @BatchResponse@ object. h2(#realtime). Realtime client library features From 32d50b884ad38bc61d7e6fab1320c3f360fa7a35 Mon Sep 17 00:00:00 2001 From: Peter Maguire Date: Thu, 12 May 2022 16:28:23 +0100 Subject: [PATCH 12/12] clarify the purpose of BatchResult.error --- content/client-lib-development-guide/features.textile | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index 84f2e0d420..8c828d3eff 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -1382,8 +1382,9 @@ h4. ChannelMetrics h4. BatchResult * @(BPA1)@ Contains the results from the batch operation * @(BPA2)@ @BatchResult@ has the following attributes: -** @(BPA2a)@ @responses@ is an array of batch response objects. null if the request failed completely (e.g. for an invalid key) -** @(BPA2b)@ @error@ is an @ErrorInfo@ object which is populated if one or more batch publish requests failed +** @(BPA2a)@ @responses@ is an array of batch response objects. +** @(BPA2b)@ @error@ is an @ErrorInfo@ object which is populated if one or more batch publish requests failed. +*** @(BPA2b1)@ This error should only be set if it relates to a partial success. All fatal errors should be handled via language appropriate error handling. h4. BatchPublishResponse * @(BPB1)@ Contains information for each batch publish request within a @BatchResult@