From a7ff58c67ba0256b0335372e2fc04d7338d5ee28 Mon Sep 17 00:00:00 2001 From: Liangying Wei Date: Tue, 2 Nov 2021 17:20:27 +0800 Subject: [PATCH 1/5] Updating service description and minor fixes --- .../azure-messaging-webpubsub/README.md | 40 +++++++++---------- .../src/samples/README.md | 6 ++- 2 files changed, 22 insertions(+), 24 deletions(-) diff --git a/sdk/webpubsub/azure-messaging-webpubsub/README.md b/sdk/webpubsub/azure-messaging-webpubsub/README.md index 108a72aaafc4..5aa015416c6b 100644 --- a/sdk/webpubsub/azure-messaging-webpubsub/README.md +++ b/sdk/webpubsub/azure-messaging-webpubsub/README.md @@ -1,16 +1,16 @@ # Azure Web PubSub service client library for Java -Azure Web PubSub service client library for Java allows sending messages to Web PubSub. Azure Web PubSub service -enables you to build real-time messaging web applications using WebSockets and the publish-subscribe pattern. Any -platform supporting WebSocket APIs can connect to the service easily, e.g. web pages, mobile applications, edge devices, -etc. The service manages the WebSocket connections for you and allows up to 100K concurrent connections. It provides -powerful APIs for you to manage these clients and deliver real-time messages. +[Azure Web PubSub service](https://aka.ms/awps/doc) is an Azure-managed service that helps developers easily build web applications with real-time features and publish-subscribe pattern. Any scenario that requires real-time publish-subscribe messaging between server and clients or among clients can use Azure Web PubSub service. Traditional real-time features that often require polling from server or submitting HTTP requests can also use Azure Web PubSub service. -Any scenario that requires real-time publish-subscribe messaging between server and clients or among clients, can use -Azure Web PubSub service. Traditional real-time features that often require polling from server or submitting HTTP -requests, can also use Azure Web PubSub service. +Use the library to: -[Source code][source_code] | [Product Documentation][product_documentation] | [Samples][samples_readme] +- Send messages to hubs and groups. +- Send messages to particular users and connections. +- Organize users and connections into groups. +- Close connections +- Grant/revoke/check permissions for an existing connection + +[Source code][source_code] | [API reference documentation][api] | [Product Documentation][product_documentation] | [Samples][samples_readme] ## Getting started @@ -56,30 +56,25 @@ WebPubSubServiceClient webPubSubServiceClient = new WebPubSubServiceClientBuilde ## Key concepts +### Connection + +A connection, also known as a client or a client connection, represents an individual WebSocket connection connected to the Web PubSub service. When successfully connected, a unique connection ID is assigned to this connection by the Web PubSub service. + ### Hub -Hub is a logic set of connections. All connections to Web PubSub connect to a specific hub. Messages that are broadcast -to the hub are dispatched to all connections to that hub. For example, hub can be used for different applications, -different applications can share one Azure Web PubSub service by using different hub names. +A hub is a logical concept for a set of client connections. Usually you use one hub for one purpose, for example, a chat hub, or a notification hub. When a client connection is created, it connects to a hub, and during its lifetime, it belongs to that hub. Different applications can share one Azure Web PubSub service by using different hub names. ### Group -Group allow broadcast messages to a subset of connections to the hub. You can add and remove users and connections as -needed. A client can join multiple groups, and a group can contain multiple clients. +A group is a subset of connections to the hub. You can add a client connection to a group, or remove the client connection from the group, anytime you want. For example, when a client joins a chat room, or when a client leaves the chat room, this chat room can be considered to be a group. A client can join multiple groups, and a group can contain multiple clients. ### User -Connections to Web PubSub can belong to one user. A user might have multiple connections, for example when a single user -is connected across multiple devices or multiple browser tabs. - -### Connection - -Connections, represented by a connection id, represent an individual websocket connection to the Web PubSub service. -Connection id is always unique. +Connections to Web PubSub can belong to one user. A user might have multiple connections, for example when a single user is connected across multiple devices or multiple browser tabs. ### Message -A message is either an UTF-8 encoded string or raw binary data. +When the client is connected, it can send messages to the upstream application, or receive messages from the upstream application, through the WebSocket connection. ## Examples @@ -164,5 +159,6 @@ comments. [coc]: https://opensource.microsoft.com/codeofconduct/ [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ [coc_contact]: mailto:opencode@microsoft.com +[api]: https://aka.ms/awps/sdk/java ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Fwebpubsub%2Fazure-messaging-webpubsub%2FREADME.png) diff --git a/sdk/webpubsub/azure-messaging-webpubsub/src/samples/README.md b/sdk/webpubsub/azure-messaging-webpubsub/src/samples/README.md index 2b94153dbce9..bf6354630e2e 100644 --- a/sdk/webpubsub/azure-messaging-webpubsub/src/samples/README.md +++ b/sdk/webpubsub/azure-messaging-webpubsub/src/samples/README.md @@ -21,13 +21,14 @@ Getting started explained in detail [here][SDK_README_GETTING_STARTED]. ## Examples The following sections provide several code snippets covering some of the most common configuration service tasks, including: -## Troubleshooting -Troubleshooting steps can be found [here][SDK_README_TROUBLESHOOTING]. - [Broadcasting a message][broadcast_sample] - [Send a message to a user or connection][direct_sample] - [Manage groups][manage_group_sample] - [A simple chat client][simple_chat_client] +- [More advanced samples][advanced_samples] +## Troubleshooting +Troubleshooting steps can be found [here][SDK_README_TROUBLESHOOTING]. ## Next steps See [Next steps][SDK_README_NEXT_STEPS]. @@ -47,5 +48,6 @@ This project welcomes contributions and suggestions. Find [more contributing][SD [direct_sample]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/webpubsub/azure-messaging-webpubsub/src/samples/java/com/azure/messaging/webpubsub/DirectMessageSample.java [manage_group_sample]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/webpubsub/azure-messaging-webpubsub/src/samples/java/com/azure/messaging/webpubsub/ManagingGroupsSample.java [simple_chat_sample]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/webpubsub/azure-messaging-webpubsub/src/samples/java/com/azure/messaging/webpubsub/SimpleChatClient.java +[advanced_samples]: https://github.com/Azure/azure-webpubsub/tree/main/samples/java ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Fwebpubsub%2Fazure-messaging-webpubsub%2FREADME.png) From 576baf3d152a0c547428738021ec6ced11d52b4b Mon Sep 17 00:00:00 2001 From: "Liangying.Wei" Date: Tue, 2 Nov 2021 23:14:55 +0800 Subject: [PATCH 2/5] Update README.md --- sdk/webpubsub/azure-messaging-webpubsub/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sdk/webpubsub/azure-messaging-webpubsub/README.md b/sdk/webpubsub/azure-messaging-webpubsub/README.md index 5aa015416c6b..fea9540d4335 100644 --- a/sdk/webpubsub/azure-messaging-webpubsub/README.md +++ b/sdk/webpubsub/azure-messaging-webpubsub/README.md @@ -2,13 +2,13 @@ [Azure Web PubSub service](https://aka.ms/awps/doc) is an Azure-managed service that helps developers easily build web applications with real-time features and publish-subscribe pattern. Any scenario that requires real-time publish-subscribe messaging between server and clients or among clients can use Azure Web PubSub service. Traditional real-time features that often require polling from server or submitting HTTP requests can also use Azure Web PubSub service. -Use the library to: +This library can be used to do the following actions. Details about the terms used here are described in [Key concepts](#key-concepts) section. -- Send messages to hubs and groups. +- Send messages to hubs and groups. - Send messages to particular users and connections. - Organize users and connections into groups. - Close connections -- Grant/revoke/check permissions for an existing connection +- Grant, revoke, and check permissions for an existing connection [Source code][source_code] | [API reference documentation][api] | [Product Documentation][product_documentation] | [Samples][samples_readme] From 83cf22db76429c0ad95ad831c7b1058bb4bce0f3 Mon Sep 17 00:00:00 2001 From: "Liangying.Wei" Date: Tue, 2 Nov 2021 23:51:00 +0800 Subject: [PATCH 3/5] Avoid using client as client is a preserved term --- sdk/webpubsub/azure-messaging-webpubsub/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/webpubsub/azure-messaging-webpubsub/README.md b/sdk/webpubsub/azure-messaging-webpubsub/README.md index fea9540d4335..ebdae84e5269 100644 --- a/sdk/webpubsub/azure-messaging-webpubsub/README.md +++ b/sdk/webpubsub/azure-messaging-webpubsub/README.md @@ -33,7 +33,7 @@ This library can be used to do the following actions. Details about the terms us [//]: # ({x-version-update-end}) -### Create a Web PubSub client using connection string +### Create a `WebPubSubServiceClient` using connection string ```java @@ -43,7 +43,7 @@ WebPubSubServiceClient webPubSubServiceClient = new WebPubSubServiceClientBuilde .buildClient(); ``` -### Create a Web PubSub client using access key +### Create a `WebPubSubServiceClient` using access key ```java From 6cb9e53dd0e7d0f6b63a57a77407b96f59385c16 Mon Sep 17 00:00:00 2001 From: "Liangying.Wei" Date: Wed, 3 Nov 2021 13:37:54 +0800 Subject: [PATCH 4/5] Update README.md --- sdk/webpubsub/azure-messaging-webpubsub/README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/sdk/webpubsub/azure-messaging-webpubsub/README.md b/sdk/webpubsub/azure-messaging-webpubsub/README.md index ebdae84e5269..3f425c1a0d3d 100644 --- a/sdk/webpubsub/azure-messaging-webpubsub/README.md +++ b/sdk/webpubsub/azure-messaging-webpubsub/README.md @@ -2,14 +2,18 @@ [Azure Web PubSub service](https://aka.ms/awps/doc) is an Azure-managed service that helps developers easily build web applications with real-time features and publish-subscribe pattern. Any scenario that requires real-time publish-subscribe messaging between server and clients or among clients can use Azure Web PubSub service. Traditional real-time features that often require polling from server or submitting HTTP requests can also use Azure Web PubSub service. -This library can be used to do the following actions. Details about the terms used here are described in [Key concepts](#key-concepts) section. +You can use this library in your app server side to manage the WebSocket client connections, as shown in below diagram: +![overflow](https://user-images.githubusercontent.com/668244/140014067-25a00959-04dc-47e8-ac25-6957bd0a71ce.png) + +Use this library to: - Send messages to hubs and groups. - Send messages to particular users and connections. - Organize users and connections into groups. - Close connections - Grant, revoke, and check permissions for an existing connection + [Source code][source_code] | [API reference documentation][api] | [Product Documentation][product_documentation] | [Samples][samples_readme] ## Getting started From 53aedfe8f9b5d781a484e6cb1f81ce2b3fe85f17 Mon Sep 17 00:00:00 2001 From: "Liangying.Wei" Date: Wed, 3 Nov 2021 14:10:33 +0800 Subject: [PATCH 5/5] Update README.md --- sdk/webpubsub/azure-messaging-webpubsub/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/sdk/webpubsub/azure-messaging-webpubsub/README.md b/sdk/webpubsub/azure-messaging-webpubsub/README.md index 3f425c1a0d3d..5923f85cc45e 100644 --- a/sdk/webpubsub/azure-messaging-webpubsub/README.md +++ b/sdk/webpubsub/azure-messaging-webpubsub/README.md @@ -13,6 +13,7 @@ Use this library to: - Close connections - Grant, revoke, and check permissions for an existing connection +Details about the terms used here are described in [Key concepts](#key-concepts) section. [Source code][source_code] | [API reference documentation][api] | [Product Documentation][product_documentation] | [Samples][samples_readme]