Amqp Message Update - API Change (Azure#17464)

1. New Type AmqpMessageId ( Based on discussion from Clemens, dotnet had)

2. New Type AmqpAddress ( Based on discussion from Clemens, dotnet had)

3. Return type change in AmqpMessageProperties for above two new types.

3. Following changes are to keep consistency with dotnet and common prefix -> AmqpMessage

A. Renamed AmqpDataBody to AmqpMessageBody (to be same name as in dotnet)

B. Renamed AmqpBodyType to AmqpMessageBodyType (Same name in dotnet)

4. Added AmqpMessageBody .getFirstData () Based on team review

5. Returning IterableStream in AmqpMessageBody .getData () Based on team review

6. Removed Copy constructor AmqpAnnotatedMessage (matching with dotnet) and because it is servicebus specific . So moving this logic into servicebus

Author: hemanttanwar

eng/code-quality-reports/src/main/resources/revapi/revapi.json

@@ -269,6 +269,92 @@
         "code": "java.annotation.added",
         "new": "class com.azure.storage.blob.models.PageList",
         "justification": "Annotation required to resolve deserialization bug."
+      },{
+        "code": "java.method.returnTypeChanged",
+        "old": "method com.azure.core.util.IterableStream<byte[]> com.azure.core.amqp.models.AmqpDataBody::getData()",
+        "new": "method java.util.List<byte[]> com.azure.core.amqp.models.AmqpDataBody::getData()",
+        "justification": "Updated "
+      },
+      {
+        "code": "java.class.removed",
+        "old": "class com.azure.core.amqp.models.AmqpDataBody",
+        "justification": "Renamed as AmqpMessageBody."
+      },
+      {
+        "code": "java.class.kindChanged",
+        "old": "interface com.azure.core.amqp.models.AmqpMessageBody",
+        "new": "class com.azure.core.amqp.models.AmqpMessageBody",
+        "justification": "AmqpMessageBody is class representing all the new AMQP data types."
+      },
+      {
+        "code": "java.class.nowFinal",
+        "old": "interface com.azure.core.amqp.models.AmqpMessageBody",
+        "new": "class com.azure.core.amqp.models.AmqpMessageBody",
+        "justification": "Made it final."
+      },
+      {
+        "code": "java.class.removed",
+        "old": "enum com.azure.core.amqp.models.AmqpBodyType",
+        "justification": "Because It is renamed to AmqpMessageBodyType"
+      },
+      {
+        "code": "java.method.returnTypeChanged",
+        "old": "method com.azure.core.amqp.models.AmqpBodyType com.azure.core.amqp.models.AmqpMessageBody::getBodyType()",
+        "new": "method com.azure.core.amqp.models.AmqpMessageBodyType com.azure.core.amqp.models.AmqpMessageBody::getBodyType()",
+        "justification": "Renamed to match AmqpMessage prefix."
+      },
+      {
+        "code": "java.method.returnTypeChanged",
+        "old": "method java.lang.String com.azure.core.amqp.models.AmqpMessageProperties::getCorrelationId()",
+        "new": "method com.azure.core.amqp.models.AmqpMessageId com.azure.core.amqp.models.AmqpMessageProperties::getCorrelationId()",
+        "justification": "New return type AmqpMessageId."
+      },
+      {
+        "code": "java.method.returnTypeChanged",
+        "old": "method java.lang.String com.azure.core.amqp.models.AmqpMessageProperties::getMessageId()",
+        "new": "method com.azure.core.amqp.models.AmqpMessageId com.azure.core.amqp.models.AmqpMessageProperties::getMessageId()",
+        "justification": "New return type."
+      },
+      {
+        "code": "java.method.returnTypeChanged",
+        "old": "method java.lang.String com.azure.core.amqp.models.AmqpMessageProperties::getReplyTo()",
+        "new": "method com.azure.core.amqp.models.AmqpAddress com.azure.core.amqp.models.AmqpMessageProperties::getReplyTo()",
+        "justification": "New return type."
+      },
+      {
+        "code": "java.method.returnTypeChanged",
+        "old": "method java.lang.String com.azure.core.amqp.models.AmqpMessageProperties::getTo()",
+        "new": "method com.azure.core.amqp.models.AmqpAddress com.azure.core.amqp.models.AmqpMessageProperties::getTo()",
+        "justification": "New return type."
+      },
+      {
+        "code": "java.method.parameterTypeChanged",
+        "old": "parameter com.azure.core.amqp.models.AmqpMessageProperties com.azure.core.amqp.models.AmqpMessageProperties::setCorrelationId(===java.lang.String===)",
+        "new": "parameter com.azure.core.amqp.models.AmqpMessageProperties com.azure.core.amqp.models.AmqpMessageProperties::setCorrelationId(===com.azure.core.amqp.models.AmqpMessageId===)",
+        "justification": "Introduced new type AmqpMessageId."
+      },
+      {
+        "code": "java.method.parameterTypeChanged",
+        "old": "parameter com.azure.core.amqp.models.AmqpMessageProperties com.azure.core.amqp.models.AmqpMessageProperties::setMessageId(===java.lang.String===)",
+        "new": "parameter com.azure.core.amqp.models.AmqpMessageProperties com.azure.core.amqp.models.AmqpMessageProperties::setMessageId(===com.azure.core.amqp.models.AmqpMessageId===)",
+        "justification":"Introduced new type AmqpMessageId."
+      },
+      {
+        "code": "java.method.parameterTypeChanged",
+        "old": "parameter com.azure.core.amqp.models.AmqpMessageProperties com.azure.core.amqp.models.AmqpMessageProperties::setReplyTo(===java.lang.String===)",
+        "new": "parameter com.azure.core.amqp.models.AmqpMessageProperties com.azure.core.amqp.models.AmqpMessageProperties::setReplyTo(===com.azure.core.amqp.models.AmqpAddress===)",
+        "justification": "Introduced new type AmqpAddress."
+      },
+      {
+        "code": "java.method.parameterTypeChanged",
+        "old": "parameter com.azure.core.amqp.models.AmqpMessageProperties com.azure.core.amqp.models.AmqpMessageProperties::setTo(===java.lang.String===)",
+        "new": "parameter com.azure.core.amqp.models.AmqpMessageProperties com.azure.core.amqp.models.AmqpMessageProperties::setTo(===com.azure.core.amqp.models.AmqpAddress===)",
+        "justification": "Introduced new type AmqpAddress."
+      },
+      {
+        "code": "java.method.removed",
+        "old": "method void com.azure.core.amqp.models.AmqpAnnotatedMessage::<init>(com.azure.core.amqp.models.AmqpAnnotatedMessage)",
+        "justification": "Removed copy constructor, It is not required for Service bus message."
       }
     ]
   }

eng/code-quality-reports/src/main/resources/spotbugs/spotbugs-exclude.xml

@@ -2297,7 +2297,7 @@
       <Field name="authenticationRecord"/>
       <Bug pattern="SE_TRANSIENT_FIELD_NOT_RESTORED"/>
   </Match>
-  
+
   <!-- These fields are designed to be not written. They are for deserializing. -->
   <Match>
       <Class name="com.azure.identity.implementation.LinuxKeyRingAccessor$GError"/>
@@ -2430,4 +2430,12 @@
     </Or>
     <Bug pattern="NM_CONFUSING" />
   </Match>
+  <!-- Returning a new copy of the object is not necessary for queuing system use cases.
+  Client do not change content of message once message is created. Array copy would degrade the performance.
+  https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/core/azure-core-amqp/src/main/java/com/azure/core/amqp/models/AmqpMessageBody.java#L115 -->
+  <Match>
+    <Class name="com.azure.core.amqp.models.AmqpMessageBody"/>
+    <Field name="data"/>
+    <Bug pattern="EI_EXPOSE_REP"/>
+  </Match>
 </FindBugsFilter>

eng/versioning/version_client.txt

@@ -177,6 +177,7 @@ com.microsoft:microsoft-opentelemetry-exporter-azuremonitor;1.0.0-beta.1;1.0.0-b
 # unreleased_<groupId>:<artifactId>;dependency-version
 # note: The unreleased dependencies will not be manipulated with the automatic PR creation code.
 unreleased_com.azure:azure-core-experimental;1.0.0-beta.9
+unreleased_com.azure:azure-core-amqp;1.7.0-beta.3
 unreleased_com.azure:azure-messaging-servicebus;7.0.0-beta.7
 
 # Released Beta dependencies: Copy the entry from above, prepend "beta_", remove the current

sdk/core/azure-core-amqp/src/main/java/com/azure/core/amqp/models/AmqpAddress.java

@@ -0,0 +1,66 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.core.amqp.models;
+
+import java.util.Objects;
+
+/**
+ * This represents amqp address information. This will be used in populating information like 'To', 'ReplyTo' etc.
+ *
+ * <p><strong>Create and retrieve address</strong></p>
+ * {@codesnippet com.azure.core.amqp.models.AmqpAddress.createAndGet}
+ *
+ * @see <a href="http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-address-string">
+ *     Address type Format.</a>
+ */
+public final class AmqpAddress {
+
+    private final String address;
+
+    /**
+     * Creates the {@link AmqpAddress} with given {@code address}.
+     *
+     * @param address The address to set for this instance.
+     * @throws NullPointerException if {@code address} is null.
+     */
+    public AmqpAddress(String address) {
+        this.address = Objects.requireNonNull(address, "'address' cannot be null.");
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public int hashCode() {
+        return address.hashCode();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public boolean equals(Object other) {
+        if (other == null) {
+            return false;
+        }
+
+        if (this.getClass() != other.getClass()) {
+            return false;
+        }
+
+        if (this == other) {
+            return true;
+        }
+
+        return Objects.equals(address, other.toString());
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public String toString() {
+        return this.address;
+    }
+}

sdk/core/azure-core-amqp/src/main/java/com/azure/core/amqp/models/AmqpAnnotatedMessage.java

@@ -10,8 +10,9 @@
 /**
  * The representation of message as defined by AMQP protocol.
  *
- * @see <a href="http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#section-message-format">
- *     Amqp Message Format.</a>
+ * @see <a href="http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#section-message-format" target="_blank">
+ *     Amqp Message Format</a>
+ * @see AmqpMessageBody
  */
 public final class AmqpAnnotatedMessage {
     private final AmqpMessageBody amqpMessageBody;
@@ -31,7 +32,6 @@ public final class AmqpAnnotatedMessage {
      */
     public AmqpAnnotatedMessage(AmqpMessageBody body) {
         amqpMessageBody = Objects.requireNonNull(body, "'body' cannot be null.");
-
         applicationProperties = new HashMap<>();
         deliveryAnnotations = new HashMap<>();
         messageAnnotations = new HashMap<>();
@@ -40,24 +40,6 @@ public AmqpAnnotatedMessage(AmqpMessageBody body) {
         properties = new AmqpMessageProperties();
     }
 
-    /**
-     * Creates instance of {@link AmqpAnnotatedMessage} with given {@link AmqpAnnotatedMessage} instance.
-     *
-     * @param message used to create another instance of {@link AmqpAnnotatedMessage}.
-     *
-     * @throws NullPointerException if {@code message} or {@link AmqpAnnotatedMessage#getBody() body} is null.
-     */
-    public AmqpAnnotatedMessage(AmqpAnnotatedMessage message) {
-        Objects.requireNonNull(message, "'message' cannot be null.");
-        amqpMessageBody = Objects.requireNonNull(message.getBody(), "'message.body' cannot be null.");
-        applicationProperties = new HashMap<>(message.getApplicationProperties());
-        deliveryAnnotations = new HashMap<>(message.getDeliveryAnnotations());
-        messageAnnotations = new HashMap<>(message.getMessageAnnotations());
-        footer = new HashMap<>(message.getFooter());
-        header = new AmqpMessageHeader(message.getHeader());
-        properties = new AmqpMessageProperties(message.getProperties());
-    }
-
     /**
      * Gets the {@link Map} of application properties.
      *
@@ -71,6 +53,7 @@ public Map<String, Object> getApplicationProperties() {
      * Gets the {@link AmqpMessageBody} of an amqp message.
      *
      * @return the {@link AmqpMessageBody} object.
+     * @see AmqpMessageBody
      */
     public AmqpMessageBody getBody() {
         return amqpMessageBody;