[Core] Add ETag Implementation (Azure#24148)

Author: mssfang

sdk/core/azure-core/src/main/java/com/azure/core/util/ETag.java

@@ -0,0 +1,83 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.core.util;
+
+import com.azure.core.util.logging.ClientLogger;
+
+import java.util.Objects;
+
+/**
+ * This class represents an HTTP ETag. A ETag value could be strong or weak ETag.
+ * More information, check https://en.wikipedia.org/wiki/HTTP_ETag
+ */
+public final class ETag {
+    private static final ClientLogger LOGGER = new ClientLogger(ETag.class);
+
+    private static final String QUOTE_STRING = "\"";
+    private static final String WEAK_ETAG_PREFIX_QUOTE = "W/\"";
+    private static final String ASTERISK = "*";
+
+    /**
+     * The asterisk is a special value representing any resource.
+     */
+    public static final ETag ALL = new ETag(ASTERISK);
+
+    private final String eTag;
+
+    /**
+     * Creates a new instance of {@link ETag}.
+     *
+     * @param eTag The HTTP entity tag string value.
+     */
+    public ETag(String eTag) {
+        checkValidETag(eTag);
+        this.eTag = eTag;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (o == this) {
+            return true;
+        } else if (o == null) {
+            return false;
+        } else if (!(o instanceof ETag)) {
+            return false;
+        } else if (eTag == null) {
+            return ((ETag) o).eTag == null;
+        } else {
+            return eTag.equals(((ETag) o).eTag);
+        }
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hashCode(eTag);
+    }
+
+    @Override
+    public String toString() {
+        return eTag;
+    }
+
+    /**
+     * Checks if the {@code eTag} a valid ETag value. Valid ETags show below,
+     *  - The special character, '*'.
+     *  - A strong ETag, which the value is wrapped in quotes, ex, "12345".
+     *  - A weak ETag, which value is wrapped in quotes and prefixed by "W/", ex, W/"12345".
+     *
+     * @param eTag ETag string value.
+     */
+    private void checkValidETag(String eTag) {
+        if (eTag == null || ASTERISK.equals(eTag)) {
+            return;
+        }
+
+        if (!((eTag.startsWith(QUOTE_STRING) || eTag.startsWith(WEAK_ETAG_PREFIX_QUOTE))
+                  && eTag.endsWith(QUOTE_STRING))) {
+            throw LOGGER.logExceptionAsError(new IllegalArgumentException(String.format(
+                "The value=%s should be equal to * , be wrapped in quotes, or be wrapped in quotes prefixed by W/",
+                eTag)));
+        }
+    }
+}

sdk/core/azure-core/src/test/java/com/azure/core/util/ETagTests.java

@@ -0,0 +1,70 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.core.util;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Tests {@link ETag}.
+ */
+public class ETagTests {
+    private static final String ETAG_CONTENT = "12345";
+    private static final String QUOTE_STRING = "\"";
+    private static final String WEAK_ETAG_PREFIX_QUOTE = "W/\"";
+
+    @Test
+    public void validETag() {
+        // Valid Strong ETag
+        String strongETagExpect = QUOTE_STRING + ETAG_CONTENT + QUOTE_STRING;
+        ETag strongETag = new ETag(strongETagExpect);
+        assertEquals(strongETagExpect, strongETag.toString());
+        // Valid Weak ETag
+        String weakETagExpect = WEAK_ETAG_PREFIX_QUOTE + ETAG_CONTENT + QUOTE_STRING;
+        ETag weakETag = new ETag(weakETagExpect);
+        assertEquals(weakETagExpect, weakETag.toString());
+        // All * ETag
+        String allETags = "*";
+        ETag asterisk = new ETag(allETags);
+        assertEquals(allETags, asterisk.toString());
+        assertEquals(allETags, ETag.ALL.toString());
+    }
+
+    @Test
+    public void invalidETag() {
+        // Invalid Strong ETag
+        String strongETagExpect = QUOTE_STRING + ETAG_CONTENT;
+        assertThrows(IllegalArgumentException.class, () -> new ETag(strongETagExpect));
+        // Valid Weak ETag
+        String weakETagExpect = WEAK_ETAG_PREFIX_QUOTE + ETAG_CONTENT;
+        assertThrows(IllegalArgumentException.class, () -> new ETag(weakETagExpect));
+    }
+
+    @Test
+    public void equalsTest() {
+        ETag validStrongETag = new ETag(QUOTE_STRING + ETAG_CONTENT + QUOTE_STRING);
+        assertFalse(validStrongETag.equals(null));
+        ETag nullETag = new ETag(null);
+        assertTrue(nullETag.equals(new ETag(null)));
+        assertFalse(nullETag.equals(validStrongETag));
+        assertFalse(validStrongETag.equals(nullETag));
+        assertTrue(validStrongETag.equals(validStrongETag));
+
+        ETag validStrongETagCopy = new ETag(QUOTE_STRING + ETAG_CONTENT + QUOTE_STRING);
+        assertEquals(validStrongETag, validStrongETagCopy);
+    }
+
+    @Test
+    public void hashCodeTest() {
+        ETag nullETag = new ETag(null);
+        ETag validStrongETag = new ETag(QUOTE_STRING + ETAG_CONTENT + QUOTE_STRING);
+        assertEquals(0, nullETag.hashCode());
+        assertNotEquals(0, validStrongETag.hashCode());
+    }
+}