Sofiar/cherrypicker

sdk/communication/azure-communication-phonenumbers/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 ### Features Added
 
+- Adds support for the Browse Available Phone Numbers and Reservations APIs
+  - This adds an alternate way to search and purchase phone numbers that allows customers to select which phone numbers they want to reserve and purchase.
+- Adds support for automated purchases of phone numbers from countries requiring a Do Not Resell agreement.
+  - For more information, refer to: https://learn.microsoft.com/azure/communication-services/concepts/numbers/sub-eligibility-number-capability
+- API version `2025-04-01` is the default.
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/communication/azure-communication-phonenumbers/README.md

@@ -6,16 +6,18 @@ Purchased phone numbers can come with many capabilities, depending on the countr
 
 [Source code][source] | [Package (Maven)][package] | [API reference documentation][api_documentation]
 | [Product documentation][product_docs]
+
 ## Getting started
 
 ### Prerequisites
 
-- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
-- [Java Development Kit (JDK)](https://learn.microsoft.com/java/azure/jdk/?view=azure-java-stable) version 8 or above.
-- [Apache Maven](https://maven.apache.org/download.cgi).
-- A deployed Communication Services resource. You can use the [Azure Portal](https://learn.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp) or the [Azure PowerShell](https://learn.microsoft.com/powershell/module/az.communication/new-azcommunicationservice) to set it up.
+-   An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
+-   [Java Development Kit (JDK)](https://learn.microsoft.com/java/azure/jdk/?view=azure-java-stable) version 8 or above.
+-   [Apache Maven](https://maven.apache.org/download.cgi).
+-   A deployed Communication Services resource. You can use the [Azure Portal](https://learn.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp) or the [Azure PowerShell](https://learn.microsoft.com/powershell/module/az.communication/new-azcommunicationservice) to set it up.
 
 ### Include the package
+
 #### 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.
@@ -34,6 +36,7 @@ To learn more about the BOM, see the [AZURE SDK BOM README](https://github.com/A
     </dependencies>
 </dependencyManagement>
 ```
+
 and then include the direct dependency in the dependencies section without the version tag.
 
 ```xml
@@ -46,11 +49,12 @@ and then include the direct dependency in the dependencies section without the v
 ```
 
 #### 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.
 
+[//]: # "{x-version-update-start;com.azure:azure-communication-phonenumbers;current}"
 
-[//]: # ({x-version-update-start;com.azure:azure-communication-phonenumbers;current})
 ```xml
 <dependency>
   <groupId>com.azure</groupId>
@@ -70,6 +74,7 @@ The `direct routing` feature enables connecting your existing telephony infrastr
 The configuration is managed using the `SipRoutingClient`, which provides methods for setting up SIP trunks and voice routing rules, in order to properly handle calls for your telephony subnet.
 
 ### Initializing Client
+
 Clients can be initialized using the Azure Active Directory Authentication.
 
 ```java readme-sample-createPhoneNumberClientWithAAD
@@ -131,6 +136,7 @@ SipRoutingClient sipRoutingClient = new SipRoutingClientBuilder()
     .httpClient(httpClient)
     .buildClient();
 ```
+
 Alternatively, you can provide the entire connection string using the connectionString() function of the client instead of providing the endpoint and access key.
 
 ### Phone numbers client
@@ -145,6 +151,14 @@ Phone numbers can be searched through the search creation API by providing an ar
 
 Phone numbers can also be released using the release API.
 
+#### Browsing and reserving phone numbers
+
+The Browse and Reservations APIs provide an alternate way to acquire phone numbers via a shopping-cart-like experience. This is achieved by splitting the search operation, which finds and reserves numbers using a single LRO, into two separate synchronous steps, Browse and Reservation.
+
+The browse operation retrieves a random sample of phone numbers that are available for purchase for a given country, with optional filtering criteria to narrow down results. The returned phone numbers are not reserved for any customer.
+
+Reservations represent a collection of phone numbers that are locked by a specific customer and are awaiting purchase. They have an expiration time of 15 minutes after the last modification or 2 hours from creation time. A reservation can include numbers from different countries, in contrast with the Search operation. Customers can Create, Retrieve, Modify (by adding and removing numbers), Delete, and Purchase reservations. Purchasing a reservation is an LRO.
+
 ### SIP routing client
 
 Direct routing feature allows connecting customer-provided telephony infrastructure to Azure Communication Resources. In order to setup routing configuration properly, customer needs to supply the SIP trunk configuration and SIP routing rules for calls. SIP routing client provides the necessary interface for setting this configuration.
@@ -157,6 +171,7 @@ Once a route is matched, the call is routed to the first trunk in the route's tr
 ### PhoneNumbersClient
 
 #### Get Purchased Phone Number
+
 Gets the specified purchased phone number.
 
 ```java readme-sample-getPurchasedPhoneNumber
@@ -166,6 +181,7 @@ System.out.println("Phone Number Country Code: " + phoneNumber.getCountryCode())
 ```
 
 #### Get All Purchased Phone Numbers
+
 Lists all the purchased phone numbers.
 
 ```java readme-sample-listPhoneNumbers
@@ -175,11 +191,36 @@ System.out.println("Phone Number Value: " + phoneNumber.getPhoneNumber());
 System.out.println("Phone Number Country Code: " + phoneNumber.getCountryCode());
 ```
 
+### Browse and reserve available phone numbers
+
+Use the Browse and Reservations API to reserve a phone number
+
+```java readme-sample-browseAndReservePhoneNumbers
+PhoneNumbersClient phoneNumberClient = createPhoneNumberClient();
+String reservationId = UUID.randomUUID().toString();
+
+BrowsePhoneNumbersOptions browseRequest = new BrowsePhoneNumbersOptions("US", PhoneNumberType.TOLL_FREE)
+        .setAssignmentType(PhoneNumberAssignmentType.APPLICATION)
+        .setCapabilities(new PhoneNumberCapabilities().setCalling(PhoneNumberCapabilityType.INBOUND_OUTBOUND)
+                .setSms(PhoneNumberCapabilityType.INBOUND_OUTBOUND));
+
+PhoneNumbersBrowseResult result = phoneNumberClient.browseAvailableNumbers(browseRequest);
+
+List<AvailablePhoneNumber> numbersToAdd = new ArrayList<>();
+
+numbersToAdd.add(result.getPhoneNumbers().get(0));
+
+PhoneNumbersReservation reservationResponse = phoneNumberClient.createOrUpdateReservation(
+        new CreateOrUpdateReservationOptions(reservationId).setPhoneNumbersToAdd(numbersToAdd));
+System.out.println("Reservation ID: " + reservationResponse.getId());
+```
+
 ### Long Running Operations
 
 The Phone Number Client supports a variety of long-running operations that allow indefinite polling time to the functions listed down below.
 
 #### Search for Available Phone Numbers
+
 Search for available phone numbers by providing the area code, assignment type, phone number capabilities, phone number type, and quantity. The result of the search can then be used to purchase the numbers. Note that for the toll-free phone number type, providing the area code is optional.
 
 ```java readme-sample-searchAvailablePhoneNumbers
@@ -204,6 +245,7 @@ if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
 ```
 
 #### Purchase Phone Numbers
+
 The result of searching for phone numbers is a `PhoneNumberSearchResult`. This can be used to get the numbers' details and purchase numbers by passing in the `searchId` to the purchase number API.
 
 ```java readme-sample-purchasePhoneNumbers
@@ -212,7 +254,18 @@ PollResponse<PhoneNumberOperation> purchaseResponse =
 System.out.println("Purchase phone numbers is complete: " + purchaseResponse.getStatus());
 ```
 
+#### Purchase Phone Number Reservation
+
+Begin the purchas of a reservation
+
+```java readme-sample-purchaseReservation
+PollResponse<PhoneNumberOperation> purchaseResponse =
+    phoneNumberClient.beginReservationPurchase(reservationId, Context.NONE).waitForCompletion();
+System.out.println("Purchase reservation is complete: " + purchaseResponse.getStatus());
+```
+
 #### Release Phone Number
+
 Releases a purchased phone number.
 
 ```java readme-sample-releasePhoneNumber
@@ -222,11 +275,13 @@ System.out.println("Release phone number is complete: " + releaseResponse.getSta
 ```
 
 #### Updating Phone Number Capabilities
+
 Updates Phone Number Capabilities for Calling and SMS to one of:
-- `PhoneNumberCapabilityValue.NONE`
-- `PhoneNumberCapabilityValue.INBOUND`
-- `PhoneNumberCapabilityValue.OUTBOUND`
-- `PhoneNumberCapabilityValue.INBOUND_OUTBOUND`
+
+-   `PhoneNumberCapabilityValue.NONE`
+-   `PhoneNumberCapabilityValue.INBOUND`
+-   `PhoneNumberCapabilityValue.OUTBOUND`
+-   `PhoneNumberCapabilityValue.INBOUND_OUTBOUND`
 
 ```java readme-sample-updatePhoneNumberCapabilities
 PhoneNumberCapabilities capabilities = new PhoneNumberCapabilities();
@@ -311,7 +366,6 @@ When you submit a pull request, a CLA-bot will automatically determine whether y
 
 This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [[email protected]][coc_contact] with any additional questions or comments.
 
-
 ## Troubleshooting
 
 In progress.
@@ -321,6 +375,7 @@ In progress.
 Check out other client libraries for Azure communication service
 
 <!-- LINKS -->
+
 [cla]: https://cla.microsoft.com
 [coc]: https://opensource.microsoft.com/codeofconduct/
 [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
@@ -329,7 +384,3 @@ Check out other client libraries for Azure communication service
 [package]: https://central.sonatype.com/artifact/com.azure/azure-communication-phonenumbers
 [api_documentation]: https://aka.ms/java-docs
 [source]: https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/communication/azure-communication-phonenumbers/src
-
-
-
-

sdk/communication/azure-communication-phonenumbers/assets.json

@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "java",
   "TagPrefix": "java/communication/azure-communication-phonenumbers",
-  "Tag": "java/communication/azure-communication-phonenumbers_2dd73df054"
+  "Tag": "java/communication/azure-communication-phonenumbers_ac7d2e0f8b"
 }

sdk/communication/azure-communication-phonenumbers/spotbugs-exclude.xml

@@ -37,4 +37,10 @@
       <Class name="com.azure.communication.phonenumbers.siprouting.models.SipTrunkRoute" />
     </Or>
   </Match>
+  <Match>
+    <Bug pattern="EI_EXPOSE_STATIC_REP2" />
+    <Or>
+      <Class name="com.azure.communication.phonenumbers.implementation.accesshelpers.PhoneNumbersReservationAccessHelper" />
+    </Or>
+  </Match>
 </FindBugsFilter>