GitHub Copilot ChatGPT Claude Codex CLI Cursor opencode Skill Text

azure-messaging-webpubsub-java

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.

Ciza · 0 points · 16 views 1 listing impressions 0 install-command copies
Download microsoft-skills-.github_plugins_azure-sdk-java_skills_azure-messaging-webpubsub-java-e58528d.zip · 6 KB

Install

skills CLI npx skills add https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-java/skills/azure-messaging-webpubsub-java
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install microsoft-skills@llmmart
Git git clone https://github.com/microsoft/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole microsoft/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Azure Web PubSub SDK for Java

Build real-time web applications using the Azure Web PubSub SDK for Java.

Installation

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.5.0</version>
</dependency>

Client Creation

With Connection String

import com.azure.messaging.webpubsub.WebPubSubServiceClient;
import com.azure.messaging.webpubsub.WebPubSubServiceClientBuilder;

WebPubSubServiceClient client = new WebPubSubServiceClientBuilder()
    .connectionString("<connection-string>")
    .hub("chat")
    .buildClient();

With Access Key

import com.azure.core.credential.AzureKeyCredential;

WebPubSubServiceClient client = new WebPubSubServiceClientBuilder()
    .credential(new AzureKeyCredential("<access-key>"))
    .endpoint("<endpoint>")
    .hub("chat")
    .buildClient();

With DefaultAzureCredential

import com.azure.core.credential.TokenCredential;
import com.azure.identity.AzureIdentityEnvVars;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.identity.ManagedIdentityCredentialBuilder;

// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
TokenCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();
// Or use a specific credential directly in production:
// See https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable#credential-classes
// TokenCredential credential = new ManagedIdentityCredentialBuilder().build();

WebPubSubServiceClient client = new WebPubSubServiceClientBuilder()
    .credential(credential)
    .endpoint("<endpoint>")
    .hub("chat")
    .buildClient();

Async Client

import com.azure.messaging.webpubsub.WebPubSubServiceAsyncClient;

WebPubSubServiceAsyncClient asyncClient = new WebPubSubServiceClientBuilder()
    .connectionString("<connection-string>")
    .hub("chat")
    .buildAsyncClient();

Key Concepts

  • Hub: Logical isolation unit for connections
  • Group: Subset of connections within a hub
  • Connection: Individual WebSocket client connection
  • User: Entity that can have multiple connections

Core Patterns

Send to All Connections

import com.azure.messaging.webpubsub.models.WebPubSubContentType;

// Send text message
client.sendToAll("Hello everyone!", WebPubSubContentType.TEXT_PLAIN);

// Send JSON
String jsonMessage = "{\"type\": \"notification\", \"message\": \"New update!\"}";
client.sendToAll(jsonMessage, WebPubSubContentType.APPLICATION_JSON);

Send to All with Filter

import com.azure.core.http.rest.RequestOptions;
import com.azure.core.util.BinaryData;

BinaryData message = BinaryData.fromString("Hello filtered users!");

// Filter by userId
client.sendToAllWithResponse(
    message,
    WebPubSubContentType.TEXT_PLAIN,
    message.getLength(),
    new RequestOptions().addQueryParam("filter", "userId ne 'user1'"));

// Filter by groups
client.sendToAllWithResponse(
    message,
    WebPubSubContentType.TEXT_PLAIN,
    message.getLength(),
    new RequestOptions().addQueryParam("filter", "'GroupA' in groups and not('GroupB' in groups)"));

Send to Group

// Send to all connections in a group
client.sendToGroup("java-developers", "Hello Java devs!", WebPubSubContentType.TEXT_PLAIN);

// Send JSON to group
String json = "{\"event\": \"update\", \"data\": {\"version\": \"2.0\"}}";
client.sendToGroup("subscribers", json, WebPubSubContentType.APPLICATION_JSON);

Send to Specific Connection

// Send to a specific connection by ID
client.sendToConnection("connectionId123", "Private message", WebPubSubContentType.TEXT_PLAIN);

Send to User

// Send to all connections for a specific user
client.sendToUser("andy", "Hello Andy!", WebPubSubContentType.TEXT_PLAIN);

Manage Groups

// Add connection to group
client.addConnectionToGroup("premium-users", "connectionId123");

// Remove connection from group
client.removeConnectionFromGroup("premium-users", "connectionId123");

// Add user to group (all their connections)
client.addUserToGroup("admin-group", "userId456");

// Remove user from group
client.removeUserFromGroup("admin-group", "userId456");

// Check if user is in group
boolean exists = client.userExistsInGroup("admin-group", "userId456");

Manage Connections

// Check if connection exists
boolean connected = client.connectionExists("connectionId123");

// Close a connection
client.closeConnection("connectionId123");

// Close with reason
client.closeConnection("connectionId123", "Session expired");

// Check if user exists (has any connections)
boolean userOnline = client.userExists("userId456");

// Close all connections for a user
client.closeUserConnections("userId456");

// Close all connections in a group
client.closeGroupConnections("inactive-group");

Generate Client Access Token

import com.azure.messaging.webpubsub.models.GetClientAccessTokenOptions;
import com.azure.messaging.webpubsub.models.WebPubSubClientAccessToken;

// Basic token
WebPubSubClientAccessToken token = client.getClientAccessToken(
    new GetClientAccessTokenOptions());
System.out.println("URL: " + token.getUrl());

// With user ID
WebPubSubClientAccessToken userToken = client.getClientAccessToken(
    new GetClientAccessTokenOptions().setUserId("user123"));

// With roles (permissions)
WebPubSubClientAccessToken roleToken = client.getClientAccessToken(
    new GetClientAccessTokenOptions()
        .setUserId("user123")
        .addRole("webpubsub.joinLeaveGroup")
        .addRole("webpubsub.sendToGroup"));

// With groups to join on connect
WebPubSubClientAccessToken groupToken = client.getClientAccessToken(
    new GetClientAccessTokenOptions()
        .setUserId("user123")
        .addGroup("announcements")
        .addGroup("updates"));

// With custom expiration
WebPubSubClientAccessToken expToken = client.getClientAccessToken(
    new GetClientAccessTokenOptions()
        .setUserId("user123")
        .setExpiresAfter(Duration.ofHours(2)));

Grant/Revoke Permissions

import com.azure.messaging.webpubsub.models.WebPubSubPermission;

// Grant permission to send to a group
client.grantPermission(
    WebPubSubPermission.SEND_TO_GROUP,
    "connectionId123",
    new RequestOptions().addQueryParam("targetName", "chat-room"));

// Revoke permission
client.revokePermission(
    WebPubSubPermission.SEND_TO_GROUP,
    "connectionId123",
    new RequestOptions().addQueryParam("targetName", "chat-room"));

// Check permission
boolean hasPermission = client.checkPermission(
    WebPubSubPermission.SEND_TO_GROUP,
    "connectionId123",
    new RequestOptions().addQueryParam("targetName", "chat-room"));

Async Operations

asyncClient.sendToAll("Async message!", WebPubSubContentType.TEXT_PLAIN)
    .subscribe(
        unused -> System.out.println("Message sent"),
        error -> System.err.println("Error: " + error.getMessage())
    );

asyncClient.sendToGroup("developers", "Group message", WebPubSubContentType.TEXT_PLAIN)
    .doOnSuccess(v -> System.out.println("Sent to group"))
    .doOnError(e -> System.err.println("Failed: " + e))
    .subscribe();

Error Handling

import com.azure.core.exception.HttpResponseException;

try {
    client.sendToConnection("invalid-id", "test", WebPubSubContentType.TEXT_PLAIN);
} catch (HttpResponseException e) {
    System.out.println("Status: " + e.getResponse().getStatusCode());
    System.out.println("Error: " + e.getMessage());
}

Environment Variables

WEB_PUBSUB_CONNECTION_STRING=Endpoint=https://<resource>.webpubsub.azure.com;AccessKey=...  # Alternative to Entra ID auth
WEB_PUBSUB_ENDPOINT=https://<resource>.webpubsub.azure.com  # Required for AzureKeyCredential or TokenCredential auth
WEB_PUBSUB_ACCESS_KEY=<your-access-key>  # Only required for AzureKeyCredential auth
AZURE_TOKEN_CREDENTIALS=prod  # Required only if DefaultAzureCredential is used in production

Client Roles

Role Permission
webpubsub.joinLeaveGroup Join/leave any group
webpubsub.sendToGroup Send to any group
webpubsub.joinLeaveGroup.<group> Join/leave specific group
webpubsub.sendToGroup.<group> Send to specific group

Best Practices

  1. Use Groups: Organize connections into groups for targeted messaging
  2. User IDs: Associate connections with user IDs for user-level messaging
  3. Token Expiration: Set appropriate token expiration for security
  4. Roles: Grant minimal required permissions via roles
  5. Hub Isolation: Use separate hubs for different application features
  6. Connection Management: Clean up inactive connections

Trigger Phrases

  • "Web PubSub Java"
  • "WebSocket messaging Azure"
  • "real-time push notifications"
  • "server-sent events"
  • "chat application backend"
  • "live updates broadcasting"
Files (skills)
  • references
    • examples.md 13 KB
      Loading…
  • SKILL.md 9.3 KB
    ---
    name: azure-messaging-webpubsub-java
    description: 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.
    license: MIT
    metadata:
      author: Microsoft
      version: "1.0.0"
      package: com.azure:azure-messaging-webpubsub
    ---
    
    # Azure Web PubSub SDK for Java
    
    Build real-time web applications using the Azure Web PubSub SDK for Java.
    
    ## Installation
    
    ```xml
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-messaging-webpubsub</artifactId>
        <version>1.5.0</version>
    </dependency>
    ```
    
    ## Client Creation
    
    ### With Connection String
    
    ```java
    import com.azure.messaging.webpubsub.WebPubSubServiceClient;
    import com.azure.messaging.webpubsub.WebPubSubServiceClientBuilder;
    
    WebPubSubServiceClient client = new WebPubSubServiceClientBuilder()
        .connectionString("<connection-string>")
        .hub("chat")
        .buildClient();
    ```
    
    ### With Access Key
    
    ```java
    import com.azure.core.credential.AzureKeyCredential;
    
    WebPubSubServiceClient client = new WebPubSubServiceClientBuilder()
        .credential(new AzureKeyCredential("<access-key>"))
        .endpoint("<endpoint>")
        .hub("chat")
        .buildClient();
    ```
    
    ### With DefaultAzureCredential
    
    ```java
    import com.azure.core.credential.TokenCredential;
    import com.azure.identity.AzureIdentityEnvVars;
    import com.azure.identity.DefaultAzureCredentialBuilder;
    import com.azure.identity.ManagedIdentityCredentialBuilder;
    
    // Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
    TokenCredential credential = new DefaultAzureCredentialBuilder()
        .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
        .build();
    // Or use a specific credential directly in production:
    // See https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable#credential-classes
    // TokenCredential credential = new ManagedIdentityCredentialBuilder().build();
    
    WebPubSubServiceClient client = new WebPubSubServiceClientBuilder()
        .credential(credential)
        .endpoint("<endpoint>")
        .hub("chat")
        .buildClient();
    ```
    
    ### Async Client
    
    ```java
    import com.azure.messaging.webpubsub.WebPubSubServiceAsyncClient;
    
    WebPubSubServiceAsyncClient asyncClient = new WebPubSubServiceClientBuilder()
        .connectionString("<connection-string>")
        .hub("chat")
        .buildAsyncClient();
    ```
    
    ## Key Concepts
    
    - **Hub**: Logical isolation unit for connections
    - **Group**: Subset of connections within a hub
    - **Connection**: Individual WebSocket client connection
    - **User**: Entity that can have multiple connections
    
    ## Core Patterns
    
    ### Send to All Connections
    
    ```java
    import com.azure.messaging.webpubsub.models.WebPubSubContentType;
    
    // Send text message
    client.sendToAll("Hello everyone!", WebPubSubContentType.TEXT_PLAIN);
    
    // Send JSON
    String jsonMessage = "{\"type\": \"notification\", \"message\": \"New update!\"}";
    client.sendToAll(jsonMessage, WebPubSubContentType.APPLICATION_JSON);
    ```
    
    ### Send to All with Filter
    
    ```java
    import com.azure.core.http.rest.RequestOptions;
    import com.azure.core.util.BinaryData;
    
    BinaryData message = BinaryData.fromString("Hello filtered users!");
    
    // Filter by userId
    client.sendToAllWithResponse(
        message,
        WebPubSubContentType.TEXT_PLAIN,
        message.getLength(),
        new RequestOptions().addQueryParam("filter", "userId ne 'user1'"));
    
    // Filter by groups
    client.sendToAllWithResponse(
        message,
        WebPubSubContentType.TEXT_PLAIN,
        message.getLength(),
        new RequestOptions().addQueryParam("filter", "'GroupA' in groups and not('GroupB' in groups)"));
    ```
    
    ### Send to Group
    
    ```java
    // Send to all connections in a group
    client.sendToGroup("java-developers", "Hello Java devs!", WebPubSubContentType.TEXT_PLAIN);
    
    // Send JSON to group
    String json = "{\"event\": \"update\", \"data\": {\"version\": \"2.0\"}}";
    client.sendToGroup("subscribers", json, WebPubSubContentType.APPLICATION_JSON);
    ```
    
    ### Send to Specific Connection
    
    ```java
    // Send to a specific connection by ID
    client.sendToConnection("connectionId123", "Private message", WebPubSubContentType.TEXT_PLAIN);
    ```
    
    ### Send to User
    
    ```java
    // Send to all connections for a specific user
    client.sendToUser("andy", "Hello Andy!", WebPubSubContentType.TEXT_PLAIN);
    ```
    
    ### Manage Groups
    
    ```java
    // Add connection to group
    client.addConnectionToGroup("premium-users", "connectionId123");
    
    // Remove connection from group
    client.removeConnectionFromGroup("premium-users", "connectionId123");
    
    // Add user to group (all their connections)
    client.addUserToGroup("admin-group", "userId456");
    
    // Remove user from group
    client.removeUserFromGroup("admin-group", "userId456");
    
    // Check if user is in group
    boolean exists = client.userExistsInGroup("admin-group", "userId456");
    ```
    
    ### Manage Connections
    
    ```java
    // Check if connection exists
    boolean connected = client.connectionExists("connectionId123");
    
    // Close a connection
    client.closeConnection("connectionId123");
    
    // Close with reason
    client.closeConnection("connectionId123", "Session expired");
    
    // Check if user exists (has any connections)
    boolean userOnline = client.userExists("userId456");
    
    // Close all connections for a user
    client.closeUserConnections("userId456");
    
    // Close all connections in a group
    client.closeGroupConnections("inactive-group");
    ```
    
    ### Generate Client Access Token
    
    ```java
    import com.azure.messaging.webpubsub.models.GetClientAccessTokenOptions;
    import com.azure.messaging.webpubsub.models.WebPubSubClientAccessToken;
    
    // Basic token
    WebPubSubClientAccessToken token = client.getClientAccessToken(
        new GetClientAccessTokenOptions());
    System.out.println("URL: " + token.getUrl());
    
    // With user ID
    WebPubSubClientAccessToken userToken = client.getClientAccessToken(
        new GetClientAccessTokenOptions().setUserId("user123"));
    
    // With roles (permissions)
    WebPubSubClientAccessToken roleToken = client.getClientAccessToken(
        new GetClientAccessTokenOptions()
            .setUserId("user123")
            .addRole("webpubsub.joinLeaveGroup")
            .addRole("webpubsub.sendToGroup"));
    
    // With groups to join on connect
    WebPubSubClientAccessToken groupToken = client.getClientAccessToken(
        new GetClientAccessTokenOptions()
            .setUserId("user123")
            .addGroup("announcements")
            .addGroup("updates"));
    
    // With custom expiration
    WebPubSubClientAccessToken expToken = client.getClientAccessToken(
        new GetClientAccessTokenOptions()
            .setUserId("user123")
            .setExpiresAfter(Duration.ofHours(2)));
    ```
    
    ### Grant/Revoke Permissions
    
    ```java
    import com.azure.messaging.webpubsub.models.WebPubSubPermission;
    
    // Grant permission to send to a group
    client.grantPermission(
        WebPubSubPermission.SEND_TO_GROUP,
        "connectionId123",
        new RequestOptions().addQueryParam("targetName", "chat-room"));
    
    // Revoke permission
    client.revokePermission(
        WebPubSubPermission.SEND_TO_GROUP,
        "connectionId123",
        new RequestOptions().addQueryParam("targetName", "chat-room"));
    
    // Check permission
    boolean hasPermission = client.checkPermission(
        WebPubSubPermission.SEND_TO_GROUP,
        "connectionId123",
        new RequestOptions().addQueryParam("targetName", "chat-room"));
    ```
    
    ### Async Operations
    
    ```java
    asyncClient.sendToAll("Async message!", WebPubSubContentType.TEXT_PLAIN)
        .subscribe(
            unused -> System.out.println("Message sent"),
            error -> System.err.println("Error: " + error.getMessage())
        );
    
    asyncClient.sendToGroup("developers", "Group message", WebPubSubContentType.TEXT_PLAIN)
        .doOnSuccess(v -> System.out.println("Sent to group"))
        .doOnError(e -> System.err.println("Failed: " + e))
        .subscribe();
    ```
    
    ## Error Handling
    
    ```java
    import com.azure.core.exception.HttpResponseException;
    
    try {
        client.sendToConnection("invalid-id", "test", WebPubSubContentType.TEXT_PLAIN);
    } catch (HttpResponseException e) {
        System.out.println("Status: " + e.getResponse().getStatusCode());
        System.out.println("Error: " + e.getMessage());
    }
    ```
    
    ## Environment Variables
    
    ```bash
    WEB_PUBSUB_CONNECTION_STRING=Endpoint=https://<resource>.webpubsub.azure.com;AccessKey=...  # Alternative to Entra ID auth
    WEB_PUBSUB_ENDPOINT=https://<resource>.webpubsub.azure.com  # Required for AzureKeyCredential or TokenCredential auth
    WEB_PUBSUB_ACCESS_KEY=<your-access-key>  # Only required for AzureKeyCredential auth
    AZURE_TOKEN_CREDENTIALS=prod  # Required only if DefaultAzureCredential is used in production
    ```
    
    ## Client Roles
    
    | Role | Permission |
    |------|------------|
    | `webpubsub.joinLeaveGroup` | Join/leave any group |
    | `webpubsub.sendToGroup` | Send to any group |
    | `webpubsub.joinLeaveGroup.<group>` | Join/leave specific group |
    | `webpubsub.sendToGroup.<group>` | Send to specific group |
    
    ## Best Practices
    
    1. **Use Groups**: Organize connections into groups for targeted messaging
    2. **User IDs**: Associate connections with user IDs for user-level messaging
    3. **Token Expiration**: Set appropriate token expiration for security
    4. **Roles**: Grant minimal required permissions via roles
    5. **Hub Isolation**: Use separate hubs for different application features
    6. **Connection Management**: Clean up inactive connections
    
    ## Trigger Phrases
    
    - "Web PubSub Java"
    - "WebSocket messaging Azure"
    - "real-time push notifications"
    - "server-sent events"
    - "chat application backend"
    - "live updates broadcasting"
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.