[CommunicationIdentifier] Added support for rawId ⟷ CommunicationIden…

…tifier conversion (#28997)

* updated api to include raw id

* CommunicationIdentifier generation from raw ID

* adding test cases

* overriding equal and hashcode

* reverting test changes

* test cases for chat identifier

* revert test changes for chat

* raw id can not be changed after manual set

* fix code review comments

* removing override hashCode

* Update CHANGELOG.md

* Remove breaking changes tag from changelog

* Revert "removing override hashCode"

This reverts commit f093447.

* fix java doc

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

@@ -12,6 +12,10 @@
 
 ## 1.1.4 (2022-06-07)
 
+### Features Added
+
+- Added `String getRawId()` and `static CommunicationIdentifier fromRawId(String rawId)` to `CommunicationIdentifier` to translate between a `CommunicationIdentifier` and its underlying canonical rawId representation. Developers can now use the rawId as an encoded format for identifiers to store in their databases or as stable keys in general.
+
 ### Other Changes
 
 #### Dependency Updates

sdk/communication/azure-communication-common/src/main/java/com/azure/communication/common/CommunicationIdentifier.java

@@ -2,8 +2,81 @@
 // Licensed under the MIT License.
 package com.azure.communication.common;
 
+import com.azure.core.util.CoreUtils;
+
 /**
  * Common communication identifier for Communication Services
  */
 public abstract class CommunicationIdentifier {
+    /**
+     * encoded format for identifiers to store in databases or as stable keys in general.
+     */
+    protected String rawId;
+
+    /**
+     * When storing rawIds, use this function to restore the identifier that was encoded in the rawId.
+     *
+     * @param rawId raw id.
+     * @return CommunicationIdentifier
+     * @throws IllegalArgumentException raw id is null or empty.
+     */
+    public static CommunicationIdentifier fromRawId(String rawId) {
+        if (CoreUtils.isNullOrEmpty(rawId)) {
+            throw new IllegalArgumentException("The parameter [rawId] cannot be null to empty.");
+        }
+
+        if (rawId.startsWith("4:")) {
+            return new PhoneNumberIdentifier("+" + rawId.substring("4:".length()));
+        }
+        final String[] segments = rawId.split(":");
+        if (segments.length < 3) {
+            return new UnknownIdentifier(rawId);
+        }
+
+        final String prefix = segments[0] + ":" + segments[1] + ":";
+        final String suffix = rawId.substring(prefix.length());
+
+        if ("8:teamsvisitor:".equals(prefix)) {
+            return new MicrosoftTeamsUserIdentifier(suffix, true);
+        } else if ("8:orgid:".equals(prefix)) {
+            return new MicrosoftTeamsUserIdentifier(suffix, false);
+        } else if ("8:dod:".equals(prefix)) {
+            return new MicrosoftTeamsUserIdentifier(suffix, false).setCloudEnvironment(CommunicationCloudEnvironment.DOD);
+        } else if ("8:gcch:".equals(prefix)) {
+            return new MicrosoftTeamsUserIdentifier(suffix, false).setCloudEnvironment(CommunicationCloudEnvironment.GCCH);
+        } else if ("8:acs:".equals(prefix) || "8:spool:".equals(prefix) || "8:dod-acs:".equals(prefix) || "8:gcch-acs:".equals(prefix)) {
+            return new CommunicationUserIdentifier(rawId);
+        }
+
+        return new UnknownIdentifier(rawId);
+    }
+
+    /**
+     * Returns the rawId for a given CommunicationIdentifier.
+     * You can use the rawId for encoding the identifier and then use it as a key in a database.
+     *
+     * @return raw id
+     */
+    public String getRawId() {
+        return rawId;
+    }
+
+    @Override
+    public boolean equals(Object that) {
+        if (this == that) {
+            return true;
+        }
+
+        if (!(that instanceof CommunicationIdentifier)) {
+            return false;
+        }
+
+        CommunicationIdentifier thatId = (CommunicationIdentifier) that;
+        return this.getRawId().equals(thatId.getRawId());
+    }
+
+    @Override
+    public int hashCode() {
+        return getRawId().hashCode();
+    }
 }

sdk/communication/azure-communication-common/src/main/java/com/azure/communication/common/CommunicationUserIdentifier.java

@@ -22,10 +22,12 @@ public CommunicationUserIdentifier(String id) {
             throw new IllegalArgumentException("The initialization parameter [id] cannot be null or empty.");
         }
         this.id = id;
+        this.rawId = id;
     }
 
     /**
      * Get id of the communication user.
+     *
      * @return id of the communication user.
      */
     public String getId() {
@@ -42,11 +44,11 @@ public boolean equals(Object that) {
             return false;
         }
 
-        return ((CommunicationUserIdentifier) that).getId().equals(id);
+        return ((CommunicationUserIdentifier) that).getRawId().equals(getRawId());
     }
 
     @Override
     public int hashCode() {
-        return getId().hashCode();
+        return getRawId().hashCode();
     }
 }

sdk/communication/azure-communication-common/src/main/java/com/azure/communication/common/MicrosoftTeamsUserIdentifier.java

@@ -12,9 +12,9 @@ public final class MicrosoftTeamsUserIdentifier extends CommunicationIdentifier
 
     private final String userId;
     private final boolean isAnonymous;
-    private CommunicationCloudEnvironment cloudEnvironment = CommunicationCloudEnvironment.PUBLIC;
+    private boolean rawIdSet = false;
 
-    private String rawId;
+    private CommunicationCloudEnvironment cloudEnvironment = CommunicationCloudEnvironment.PUBLIC;
 
     /**
      * Creates a MicrosoftTeamsUserIdentifier object
@@ -23,21 +23,22 @@ public final class MicrosoftTeamsUserIdentifier extends CommunicationIdentifier
      * @param isAnonymous set this to true if the user is anonymous,
      *                    for example when joining a meeting with a share link
      * @throws IllegalArgumentException thrown if userId parameter fail the validation.
-    */
+     */
     public MicrosoftTeamsUserIdentifier(String userId, boolean isAnonymous) {
         if (CoreUtils.isNullOrEmpty(userId)) {
             throw new IllegalArgumentException("The initialization parameter [userId] cannot be null or empty.");
         }
         this.userId = userId;
         this.isAnonymous = isAnonymous;
+        generateRawId();
     }
 
     /**
      * Creates a MicrosoftTeamsUserIdentifier object
      *
      * @param userId Id of the Microsoft Teams user. If the user isn't anonymous, the id is the Azure AD object id of the user.
      * @throws IllegalArgumentException thrown if userId parameter fail the validation.
-    */
+     */
     public MicrosoftTeamsUserIdentifier(String userId) {
         this(userId, false);
     }
@@ -57,39 +58,36 @@ public boolean isAnonymous() {
         return this.isAnonymous;
     }
 
-    /**
-     * Set cloud environment of the Teams user identifier
-     * @param cloudEnvironment the cloud environment in which this identifier is created
-     * @return this object
-     */
-    public MicrosoftTeamsUserIdentifier setCloudEnvironment(CommunicationCloudEnvironment cloudEnvironment) {
-        this.cloudEnvironment = cloudEnvironment;
-        return this;
-    }
-
     /**
      * Get cloud environment of the Teams user identifier
+     *
      * @return cloud environment in which this identifier is created
      */
     public CommunicationCloudEnvironment getCloudEnvironment() {
         return cloudEnvironment;
     }
 
     /**
-     * Get full id of the identifier. This id is optional.
-     * @return full id of the identifier
+     * Set cloud environment of the Teams user identifier
+     *
+     * @param cloudEnvironment the cloud environment in which this identifier is created
+     * @return this object
      */
-    public String getRawId() {
-        return rawId;
+    public MicrosoftTeamsUserIdentifier setCloudEnvironment(CommunicationCloudEnvironment cloudEnvironment) {
+        this.cloudEnvironment = cloudEnvironment;
+        generateRawId();
+        return this;
     }
 
     /**
      * Set full id of the identifier
+     *
      * @param rawId full id of the identifier
      * @return CommunicationIdentifier object itself
      */
     public MicrosoftTeamsUserIdentifier setRawId(String rawId) {
         this.rawId = rawId;
+        rawIdSet = true;
         return this;
     }
 
@@ -104,10 +102,6 @@ public boolean equals(Object that) {
         }
 
         MicrosoftTeamsUserIdentifier thatId = (MicrosoftTeamsUserIdentifier) that;
-        if (!thatId.getUserId().equals(this.getUserId())
-            || thatId.isAnonymous != this.isAnonymous) {
-            return false;
-        }
 
         if (cloudEnvironment != null && !cloudEnvironment.equals(thatId.cloudEnvironment)) {
             return false;
@@ -122,10 +116,22 @@ public boolean equals(Object that) {
             || thatId.getRawId().equals(this.getRawId());
     }
 
-
     @Override
     public int hashCode() {
-        return userId.hashCode();
+        return getRawId().hashCode();
     }
 
+    private void generateRawId() {
+        if (!rawIdSet) {
+            if (this.isAnonymous) {
+                this.rawId = "8:teamsvisitor:" + this.userId;
+            } else if (cloudEnvironment.equals(CommunicationCloudEnvironment.DOD)) {
+                this.rawId = "8:dod:" + this.userId;
+            } else if (cloudEnvironment.equals(CommunicationCloudEnvironment.GCCH)) {
+                this.rawId = "8:gcch:" + this.userId;
+            } else {
+                this.rawId = "8:orgid:" + this.userId;
+            }
+        }
+    }
 }

sdk/communication/azure-communication-common/src/main/java/com/azure/communication/common/PhoneNumberIdentifier.java

@@ -10,20 +10,20 @@
 public final class PhoneNumberIdentifier extends CommunicationIdentifier {
 
     private final String phoneNumber;
-    private String rawId;
 
     /**
      * Creates a PhoneNumberIdentifier object
      *
      * @param phoneNumber the string identifier representing the PhoneNumber in E.164 format.
-     * E.164 is a phone number formatted as +[CountryCode][AreaCode][LocalNumber] eg. "+18005555555"
+     *                    E.164 is a phone number formatted as +[CountryCode][AreaCode][LocalNumber] eg. "+18005555555"
      * @throws IllegalArgumentException thrown if phoneNumber parameter fail the validation.
      */
     public PhoneNumberIdentifier(String phoneNumber) {
         if (CoreUtils.isNullOrEmpty(phoneNumber)) {
             throw new IllegalArgumentException("The initialization parameter [phoneNumber] cannot be null to empty.");
         }
         this.phoneNumber = phoneNumber;
+        this.rawId = "4:" + phoneNumber.replaceAll("^[+]", "");
     }
 
     /**
@@ -33,16 +33,9 @@ public String getPhoneNumber() {
         return phoneNumber;
     }
 
-    /**
-     * Get full id of the identifier. This id is optional.
-     * @return full id of the identifier
-     */
-    public String getRawId() {
-        return rawId;
-    }
-
     /**
      * Set full id of the identifier
+     *
      * @param rawId full id of the identifier
      * @return PhoneNumberIdentifier object itself
      */
@@ -62,9 +55,6 @@ public boolean equals(Object that) {
         }
 
         PhoneNumberIdentifier phoneId = (PhoneNumberIdentifier) that;
-        if (!phoneNumber.equals(phoneId.phoneNumber)) {
-            return false;
-        }
 
         return getRawId() == null
             || phoneId.getRawId() == null
@@ -73,6 +63,6 @@ public boolean equals(Object that) {
 
     @Override
     public int hashCode() {
-        return phoneNumber.hashCode();
+        return getRawId().hashCode();
     }
 }

sdk/communication/azure-communication-common/src/main/java/com/azure/communication/common/UnknownIdentifier.java

@@ -22,10 +22,12 @@ public UnknownIdentifier(String id) {
             throw new IllegalArgumentException("The initialization parameter [id] cannot be null or empty.");
         }
         this.id = id;
+        this.rawId = id;
     }
 
     /**
      * Get id of this identifier
+     *
      * @return id of this identifier
      */
     public String getId() {
@@ -43,11 +45,11 @@ public boolean equals(Object that) {
         }
 
         UnknownIdentifier thatId = (UnknownIdentifier) that;
-        return this.id.equals(thatId.id);
+        return this.getRawId().equals(thatId.getRawId());
     }
 
     @Override
     public int hashCode() {
-        return id.hashCode();
+        return getRawId().hashCode();
     }
 }