Azure Communication Service Common client library for Java - version 1.3.9

Article
12/04/2024

Azure Communication Common contains data structures commonly used for communicating with Azure Communication Services. It is intended to provide cross-cutting concerns, e.g. authentication.

Getting started

Prerequisites

An Azure account with an active subscription. Create an account for free.
Java Development Kit (JDK) version 8 or above.
Apache Maven.
A deployed Communication Services resource.

Include the BOM file

Please include the azure-sdk-bom to your project to take dependency on the General Availability (GA) version of the library. In the following snippet, replace the {bom_version_to_target} placeholder with the version number. To learn more about the BOM, see the AZURE SDK BOM README.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

and then include the direct dependency in the dependencies section without the version tag.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-common</artifactId>
  </dependency>
</dependencies>

Include direct dependency

If you want to take dependency on a particular version of the library that is not present in the BOM, add the direct dependency to your project as follows.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-common</artifactId>
    <version>1.3.9</version>
</dependency>

Key concepts

To work with Azure Communication Services, a resource access key is used for authentication.

Azure Communication Service supports HMAC authentication with resource access key. To apply HMAC authentication, construct CommunicationClientCredential with the access key and instantiate a CommunicationIdentityClient to manage users and tokens.

CommunicationTokenCredential

The CommunicationTokenCredential object is used to authenticate a user with Communication Services, such as Chat or Calling. It optionally provides an auto-refresh mechanism to ensure a continuously stable authentication state during communications.

Depending on your scenario, you may want to initialize the CommunicationTokenCredential with:

a static token (suitable for short-lived clients used to e.g. send one-off Chat messages) or
a callback function that ensures a continuous authentication state (ideal e.g. for long Calling sessions).

The tokens supplied to the CommunicationTokenCredential either through the constructor or via the token refresher callback can be obtained using the Azure Communication Identity library.

Examples

Create a credential with a static token

For short-lived clients, refreshing the token upon expiry is not necessary and CommunicationTokenCredential may be instantiated with a static token.

String token = System.getenv("COMMUNICATION_SERVICES_USER_TOKEN");
CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(token);

Create a credential with proactive refreshing with a callback

Alternatively, for long-lived clients, you can create a CommunicationTokenCredential with a callback to renew tokens if expired. Here we assume that we have a function fetchTokenFromMyServerForUser that makes a network request to retrieve a token string for a user. It's necessary that the fetchTokenFromMyServerForUser function returns a valid token (with an expiration date set in the future) at all times.

Optionally, you can enable proactive token refreshing where a fresh token will be acquired as soon as the previous token approaches expiry. Using this method, your requests are less likely to be blocked to acquire a fresh token:

String token = System.getenv("COMMUNICATION_SERVICES_USER_TOKEN");
CommunicationTokenRefreshOptions tokenRefreshOptions = new CommunicationTokenRefreshOptions(fetchTokenFromMyServerForUser)
    .setRefreshProactively(true)
    .setInitialToken(token);
CommunicationTokenCredential tokenCredential = new CommunicationTokenCredential(tokenRefreshOptions);

Troubleshooting

In progress.

Next steps

Check out other client libraries for Azure communication service

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Share via