Azure Messaging Webpubsub Java

1---
2name: azure-messaging-webpubsub-java
3description: Build real-time web applications with Azure Web PubSub SDK for Java. Use when implementing WebSocket-based messaging, live updates, chat applications, or server-to-client push notifications.
4package: com.azure:azure-messaging-webpubsub
5---
6 
7# Azure Web PubSub SDK for Java
8 
9Build real-time web applications using the Azure Web PubSub SDK for Java.
10 
11## Installation
12 
13```xml
14<dependency>
15    <groupId>com.azure</groupId>
16    <artifactId>azure-messaging-webpubsub</artifactId>
17    <version>1.5.0</version>
18</dependency>
19```
20 
21## Client Creation
22 
23### With Connection String
24 
25```java
26import com.azure.messaging.webpubsub.WebPubSubServiceClient;
27import com.azure.messaging.webpubsub.WebPubSubServiceClientBuilder;
28 
29WebPubSubServiceClient client = new WebPubSubServiceClientBuilder()
30    .connectionString("<connection-string>")
31    .hub("chat")
32    .buildClient();
33```
34 
35### With Access Key
36 
37```java
38import com.azure.core.credential.AzureKeyCredential;
39 
40WebPubSubServiceClient client = new WebPubSubServiceClientBuilder()
41    .credential(new AzureKeyCredential("<access-key>"))
42    .endpoint("<endpoint>")
43    .hub("chat")
44    .buildClient();
45```
46 
47### With DefaultAzureCredential
48 
49```java
50import com.azure.identity.DefaultAzureCredentialBuilder;
51 
52WebPubSubServiceClient client = new WebPubSubServiceClientBuilder()
53    .credential(new DefaultAzureCredentialBuilder().build())
54    .endpoint("<endpoint>")
55    .hub("chat")
56    .buildClient();
57```
58 
59### Async Client
60 
61```java
62import com.azure.messaging.webpubsub.WebPubSubServiceAsyncClient;
63 
64WebPubSubServiceAsyncClient asyncClient = new WebPubSubServiceClientBuilder()
65    .connectionString("<connection-string>")
66    .hub("chat")
67    .buildAsyncClient();
68```
69 
70## Key Concepts
71 
72- **Hub**: Logical isolation unit for connections
73- **Group**: Subset of connections within a hub
74- **Connection**: Individual WebSocket client connection
75- **User**: Entity that can have multiple connections
76 
77## Core Patterns
78 
79### Send to All Connections
80 
81```java
82import com.azure.messaging.webpubsub.models.WebPubSubContentType;
83 
84// Send text message
85client.sendToAll("Hello everyone!", WebPubSubContentType.TEXT_PLAIN);
86 
87// Send JSON
88String jsonMessage = "{\"type\": \"notification\", \"message\": \"New update!\"}";
89client.sendToAll(jsonMessage, WebPubSubContentType.APPLICATION_JSON);
90```
91 
92### Send to All with Filter
93 
94```java
95import com.azure.core.http.rest.RequestOptions;
96import com.azure.core.util.BinaryData;
97 
98BinaryData message = BinaryData.fromString("Hello filtered users!");
99 
100// Filter by userId
101client.sendToAllWithResponse(
102    message,
103    WebPubSubContentType.TEXT_PLAIN,
104    message.getLength(),
105    new RequestOptions().addQueryParam("filter", "userId ne 'user1'"));
106 
107// Filter by groups
108client.sendToAllWithResponse(
109    message,
110    WebPubSubContentType.TEXT_PLAIN,
111    message.getLength(),
112    new RequestOptions().addQueryParam("filter", "'GroupA' in groups and not('GroupB' in groups)"));
113```
114 
115### Send to Group
116 
117```java
118// Send to all connections in a group
119client.sendToGroup("java-developers", "Hello Java devs!", WebPubSubContentType.TEXT_PLAIN);
120 
121// Send JSON to group
122String json = "{\"event\": \"update\", \"data\": {\"version\": \"2.0\"}}";
123client.sendToGroup("subscribers", json, WebPubSubContentType.APPLICATION_JSON);
124```
125 
126### Send to Specific Connection
127 
128```java
129// Send to a specific connection by ID
130client.sendToConnection("connectionId123", "Private message", WebPubSubContentType.TEXT_PLAIN);
131```
132 
133### Send to User
134 
135```java
136// Send to all connections for a specific user
137client.sendToUser("andy", "Hello Andy!", WebPubSubContentType.TEXT_PLAIN);
138```
139 
140### Manage Groups
141 
142```java
143// Add connection to group
144client.addConnectionToGroup("premium-users", "connectionId123");
145 
146// Remove connection from group
147client.removeConnectionFromGroup("premium-users", "connectionId123");
148 
149// Add user to group (all their connections)
150client.addUserToGroup("admin-group", "userId456");
151 
152// Remove user from group
153client.removeUserFromGroup("admin-group", "userId456");
154 
155// Check if user is in group
156boolean exists = client.userExistsInGroup("admin-group", "userId456");
157```
158 
159### Manage Connections
160 
161```java
162// Check if connection exists
163boolean connected = client.connectionExists("connectionId123");
164 
165// Close a connection
166client.closeConnection("connectionId123");
167 
168// Close with reason
169client.closeConnection("connectionId123", "Session expired");
170 
171// Check if user exists (has any connections)
172boolean userOnline = client.userExists("userId456");
173 
174// Close all connections for a user
175client.closeUserConnections("userId456");
176 
177// Close all connections in a group
178client.closeGroupConnections("inactive-group");
179```
180 
181### Generate Client Access Token
182 
183```java
184import com.azure.messaging.webpubsub.models.GetClientAccessTokenOptions;
185import com.azure.messaging.webpubsub.models.WebPubSubClientAccessToken;
186 
187// Basic token
188WebPubSubClientAccessToken token = client.getClientAccessToken(
189    new GetClientAccessTokenOptions());
190System.out.println("URL: " + token.getUrl());
191 
192// With user ID
193WebPubSubClientAccessToken userToken = client.getClientAccessToken(
194    new GetClientAccessTokenOptions().setUserId("user123"));
195 
196// With roles (permissions)
197WebPubSubClientAccessToken roleToken = client.getClientAccessToken(
198    new GetClientAccessTokenOptions()
199        .setUserId("user123")
200        .addRole("webpubsub.joinLeaveGroup")
201        .addRole("webpubsub.sendToGroup"));
202 
203// With groups to join on connect
204WebPubSubClientAccessToken groupToken = client.getClientAccessToken(
205    new GetClientAccessTokenOptions()
206        .setUserId("user123")
207        .addGroup("announcements")
208        .addGroup("updates"));
209 
210// With custom expiration
211WebPubSubClientAccessToken expToken = client.getClientAccessToken(
212    new GetClientAccessTokenOptions()
213        .setUserId("user123")
214        .setExpiresAfter(Duration.ofHours(2)));
215```
216 
217### Grant/Revoke Permissions
218 
219```java
220import com.azure.messaging.webpubsub.models.WebPubSubPermission;
221 
222// Grant permission to send to a group
223client.grantPermission(
224    WebPubSubPermission.SEND_TO_GROUP,
225    "connectionId123",
226    new RequestOptions().addQueryParam("targetName", "chat-room"));
227 
228// Revoke permission
229client.revokePermission(
230    WebPubSubPermission.SEND_TO_GROUP,
231    "connectionId123",
232    new RequestOptions().addQueryParam("targetName", "chat-room"));
233 
234// Check permission
235boolean hasPermission = client.checkPermission(
236    WebPubSubPermission.SEND_TO_GROUP,
237    "connectionId123",
238    new RequestOptions().addQueryParam("targetName", "chat-room"));
239```
240 
241### Async Operations
242 
243```java
244asyncClient.sendToAll("Async message!", WebPubSubContentType.TEXT_PLAIN)
245    .subscribe(
246        unused -> System.out.println("Message sent"),
247        error -> System.err.println("Error: " + error.getMessage())
248    );
249 
250asyncClient.sendToGroup("developers", "Group message", WebPubSubContentType.TEXT_PLAIN)
251    .doOnSuccess(v -> System.out.println("Sent to group"))
252    .doOnError(e -> System.err.println("Failed: " + e))
253    .subscribe();
254```
255 
256## Error Handling
257 
258```java
259import com.azure.core.exception.HttpResponseException;
260 
261try {
262    client.sendToConnection("invalid-id", "test", WebPubSubContentType.TEXT_PLAIN);
263} catch (HttpResponseException e) {
264    System.out.println("Status: " + e.getResponse().getStatusCode());
265    System.out.println("Error: " + e.getMessage());
266}
267```
268 
269## Environment Variables
270 
271```bash
272WEB_PUBSUB_CONNECTION_STRING=Endpoint=https://<resource>.webpubsub.azure.com;AccessKey=...
273WEB_PUBSUB_ENDPOINT=https://<resource>.webpubsub.azure.com
274WEB_PUBSUB_ACCESS_KEY=<your-access-key>
275```
276 
277## Client Roles
278 
279| Role | Permission |
280|------|------------|
281| `webpubsub.joinLeaveGroup` | Join/leave any group |
282| `webpubsub.sendToGroup` | Send to any group |
283| `webpubsub.joinLeaveGroup.<group>` | Join/leave specific group |
284| `webpubsub.sendToGroup.<group>` | Send to specific group |
285 
286## Best Practices
287 
2881. **Use Groups**: Organize connections into groups for targeted messaging
2892. **User IDs**: Associate connections with user IDs for user-level messaging
2903. **Token Expiration**: Set appropriate token expiration for security
2914. **Roles**: Grant minimal required permissions via roles
2925. **Hub Isolation**: Use separate hubs for different application features
2936. **Connection Management**: Clean up inactive connections
294 
295## Trigger Phrases
296 
297- "Web PubSub Java"
298- "WebSocket messaging Azure"
299- "real-time push notifications"
300- "server-sent events"
301- "chat application backend"
302- "live updates broadcasting"
303