Add ReferenceManager to azure-core (Azure#24320)

alzimmermsft · web-flow · commit 4625e0ed05c1 · 2021-10-07T13:32:56.000-07:00
Add ReferenceManager to azure-core
diff --git a/eng/code-quality-reports/src/main/resources/spotbugs/spotbugs-exclude.xml b/eng/code-quality-reports/src/main/resources/spotbugs/spotbugs-exclude.xml
@@ -2426,7 +2426,7 @@
 
    <!-- For BinaryData, copying array contents degrades performance. The data returned as byte array from BinaryData is expected to be copied by the call if mutability is desired. -->
   <Match>
-    <Class name="com.azure.core.util.implementation.ByteArrayContent"/>
+    <Class name="com.azure.core.implementation.util.ByteArrayContent"/>
     <Field name="content"/>
     <Bug pattern="EI_EXPOSE_REP"/>
   </Match>
diff --git a/eng/pipelines/templates/jobs/ci.tests.yml b/eng/pipelines/templates/jobs/ci.tests.yml
@@ -104,7 +104,7 @@ jobs:
           jdkVersionOption: $(JavaTestVersion)
           jdkArchitectureOption: 'x64'
           publishJUnitResults: false
-          goals: $(TestGoals)
+          goals: $(TestGoals) $(AdditionalTestGoals)
         # we want to run this when TestFromSource isn't true
         condition: and(succeeded(), ne(variables['TestFromSource'],'true'))
 
@@ -158,7 +158,7 @@ jobs:
           # as well as libraries which depend on them and not the other stages in the Maven
           # lifecycle that test or verify targets would execute. The libraries were already
           # compiled and installed in the previous task, this tasks only runs tests.
-          goals: $(TestGoals)
+          goals: $(TestGoals) $(AdditionalTestGoals)
         condition: and(succeeded(), and(eq(variables['TestFromSource'],'true'), eq(variables['ShouldRunSourceTests'],'true')))
 
       - template: ../steps/upload-repository-on-failure.yml
@@ -177,6 +177,6 @@ jobs:
         condition: and(eq(variables['Agent.OS'], 'Windows_NT'), eq(variables['JavaTestVersion'], '1.11'), eq('${{ parameters.SDKType }}', 'client'))
         inputs:
           codeCoverageTool: JaCoCo
-          summaryFileLocation: sdk/${{ parameters.ServiceDirectory }}/target/site/jacoco-aggregate/jacoco.xml
-          reportDirectory: sdk/${{ parameters.ServiceDirectory }}/target/site/jacoco-aggregate/
+          summaryFileLocation: sdk/${{ parameters.ServiceDirectory }}/target/site/test-coverage/jacoco.xml
+          reportDirectory: sdk/${{ parameters.ServiceDirectory }}/target/site/test-coverage/
           failIfCoverageEmpty: false
diff --git a/eng/pipelines/templates/stages/platform-matrix.json b/eng/pipelines/templates/stages/platform-matrix.json
@@ -11,6 +11,7 @@
     "JavaTestVersion": [ "1.8", "1.11" ],
     "AZURE_TEST_HTTP_CLIENTS": [ "okhttp", "netty" ],
     "TestGoals": "surefire:test",
+    "AdditionalTestGoals": "",
     "TestOptions": ""
   },
   "exclude": [
diff --git a/eng/pipelines/templates/variables/globals.yml b/eng/pipelines/templates/variables/globals.yml
@@ -17,6 +17,7 @@ variables:
   DefaultTestMavenOptions: '$(MemoryOptions) $(LoggingOptions)'
   AdditionalOptions: ''
   TestFromSource: false
+  AdditionalTestGoals: ''
 
   skipComponentGovernanceDetection: true
   IsDebug: $[coalesce(variables['System.Debug'], 'false')]
diff --git a/sdk/core/azure-core-amqp/src/test/java/com/azure/core/amqp/implementation/ReactorHandlerProviderTest.java b/sdk/core/azure-core-amqp/src/test/java/com/azure/core/amqp/implementation/ReactorHandlerProviderTest.java
@@ -60,7 +60,7 @@
  * Tests {@link ReactorHandlerProvider}.
  */
 @Execution(ExecutionMode.SAME_THREAD)
-@Isolated("Mutates global ProxySelector")
+@Isolated("Mutates the global ProxySelector")
 public class ReactorHandlerProviderTest {
     private static final String CONNECTION_ID = "test-connection-id";
     private static final String FULLY_QUALIFIED_DOMAIN_NAME = "my-hostname.windows.com";
diff --git a/sdk/core/azure-core-amqp/src/test/java/com/azure/core/amqp/implementation/handler/WebSocketsProxyConnectionHandlerTest.java b/sdk/core/azure-core-amqp/src/test/java/com/azure/core/amqp/implementation/handler/WebSocketsProxyConnectionHandlerTest.java
@@ -42,7 +42,7 @@
 import static org.mockito.Mockito.when;
 
 @Execution(ExecutionMode.SAME_THREAD)
-@Isolated("Mutates global ProxySelector")
+@Isolated("Mutates the global ProxySelector")
 public class WebSocketsProxyConnectionHandlerTest {
     private static final String CONNECTION_ID = "some-connection-id";
     private static final String HOSTNAME = "event-hubs.windows.core.net";
diff --git a/sdk/core/azure-core/pom.xml b/sdk/core/azure-core/pom.xml
@@ -292,6 +292,14 @@
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-failsafe-plugin</artifactId>
         <version>2.22.0</version> <!-- {x-version-update;org.apache.maven.plugins:maven-failsafe-plugin;external_dependency} -->
+        <configuration>
+          <!-- This configures failsafe to use the compiled JAR in the build directory. -->
+          <!-- This was added as running the failsafe goals directly used the class files in the build directory and they don't support MR JARs, as they don't have a MANIFEST. -->
+          <classesDirectory>${project.build.directory}</classesDirectory>
+          <additionalClasspathElements>
+            <additionalClasspathElement>${project.build.directory}${file.separator}${project.artifactId}-${project.version}.jar</additionalClasspathElement>
+          </additionalClasspathElements>
+        </configuration>
       </plugin>
     </plugins>
   </build>
diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/BinaryDataContent.java b/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/BinaryDataContent.java
@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-package com.azure.core.util.implementation;
+package com.azure.core.implementation.util;
 
 import com.azure.core.util.BinaryData;
 import com.azure.core.util.serializer.JsonSerializer;
diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/ByteArrayContent.java b/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/ByteArrayContent.java
@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-package com.azure.core.util.implementation;
+package com.azure.core.implementation.util;
 
 import com.azure.core.util.serializer.ObjectSerializer;
 import com.azure.core.util.serializer.TypeReference;
diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/FileContent.java b/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/FileContent.java
@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-package com.azure.core.util.implementation;
+package com.azure.core.implementation.util;
 
 import com.azure.core.util.logging.ClientLogger;
 import com.azure.core.util.serializer.ObjectSerializer;
diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/FluxByteBufferContent.java b/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/FluxByteBufferContent.java
@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-package com.azure.core.util.implementation;
+package com.azure.core.implementation.util;
 
 import com.azure.core.util.FluxUtil;
 import com.azure.core.util.serializer.ObjectSerializer;
diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/InputStreamContent.java b/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/InputStreamContent.java
@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-package com.azure.core.util.implementation;
+package com.azure.core.implementation.util;
 
 import com.azure.core.util.FluxUtil;
 import com.azure.core.util.logging.ClientLogger;
diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/ReferenceManagerImpl.java b/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/ReferenceManagerImpl.java
@@ -0,0 +1,171 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.core.implementation.util;
+
+import com.azure.core.util.ReferenceManager;
+import com.azure.core.util.logging.ClientLogger;
+import com.azure.core.util.logging.LogLevel;
+
+import java.lang.ref.PhantomReference;
+import java.lang.ref.ReferenceQueue;
+import java.util.Objects;
+
+// This is the base implementation of ReferenceManager, there is another Java 9 specific implementation in
+// /src/main/java9 for multi-release JARs.
+/**
+ * Implementation of {@link ReferenceManager}.
+ */
+public final class ReferenceManagerImpl implements ReferenceManager {
+    private static final ClientLogger LOGGER = new ClientLogger(ReferenceManagerImpl.class);
+
+    // If multiple instances of ReferenceManaged needs to be supported this maintains Thread name uniqueness.
+    // Used to create a unique thread which is used to clean up the resources managed by an instance ReferenceManager.
+    // private static final AtomicInteger RESOURCE_MANAGER_THREAD_NUMBER = new AtomicInteger();
+
+    // Base name for ResourceManager threads.
+    private static final String BASE_THREAD_NAME = "azure-sdk-referencemanager";
+
+    private final CleanableReference<?> cleanableReferenceList;
+    private final ReferenceQueue<Object> queue;
+
+    /**
+     * Creates a new instance of {@link ReferenceManagerImpl}.
+     */
+    public ReferenceManagerImpl() {
+        this.queue = new ReferenceQueue<>();
+        this.cleanableReferenceList = new CleanableReference<>();
+
+        Thread thread = new Thread(this::clearReferenceQueue, BASE_THREAD_NAME);
+
+        // Register this instance of ReferenceManager as the head of the cleaning queue. Doing so will allow the
+        // ReferenceManager to clean itself up when no longer in use, for now it simply shuts down the backing thread.
+        new CleanableReference<>(this, () -> {
+            try {
+                thread.join();
+            } catch (InterruptedException e) {
+                LOGGER.log(LogLevel.WARNING, () -> "Failed to shutdown ReferenceManager thread.", e);
+            }
+        }, this);
+
+        // If multiple instances of ReferenceManager needs to be supported each Thread should have a unique name with a
+        // consistent base name.
+        // Thread thread = new Thread(Thread.currentThread().getThreadGroup(), this,
+        //     BASE_THREAD_NAME + "-" + RESOURCE_MANAGER_THREAD_NUMBER.getAndIncrement());
+
+        // Make the ReferenceManager Thread a daemon, this will prevent it from halting a JVM shutdown.
+        thread.setDaemon(true);
+        thread.start();
+    }
+
+    @Override
+    public void register(Object object, Runnable cleanupAction) {
+        new CleanableReference<>(Objects.requireNonNull(object, "'object' cannot be null."),
+            Objects.requireNonNull(cleanupAction, "'cleanupAction' cannot be null."), this);
+    }
+
+    /*
+     * Attempts to clear the reference queue managed by the ReferenceManager.
+     *
+     * This will run in a loop until either the application is shutdown or the ReferenceManager itself is no longer
+     * being referenced
+     */
+    void clearReferenceQueue() {
+        while (cleanableReferenceList.hasRemaining()) {
+            CleanableReference<?> reference = null;
+            try {
+                // Block the ReferenceManager thread until either an element is emitted from the queue or 30 seconds
+                // elapses.
+                reference = (CleanableReference<?>) queue.remove(30000);
+            } catch (InterruptedException ex) {
+                // Thread has been interrupted while waiting for the queue to emit an element.
+                LOGGER.log(LogLevel.VERBOSE,
+                    () -> "ReferenceManager Thread interrupted while waiting for a reference to clean.", ex);
+            }
+
+            try {
+                if (reference != null) {
+                    reference.clean();
+                }
+            } catch (Throwable ex) {
+                // Cleaning action threw an exception.
+                LOGGER.log(LogLevel.INFORMATIONAL, () -> "Cleaning a reference threw an exception.", ex);
+            }
+        }
+    }
+
+    static int getJavaImplementationMajorVersion() {
+        return 8;
+    }
+
+    /*
+     * This class manages maintaining a reference to an object that will trigger a cleanup action once it is phantom
+     * reachable.
+     */
+    private static final class CleanableReference<T> extends PhantomReference<T> {
+        // The cleanup action to run once the reference is phantom reachable.
+        private final Runnable cleanupAction;
+
+        // The list of cleanable references.
+        private final CleanableReference<?> cleanupList;
+
+        CleanableReference<?> previous = this;
+        CleanableReference<?> next = this;
+
+        CleanableReference() {
+            super(null, null);
+            this.cleanupAction = null;
+            this.cleanupList = this;
+        }
+
+        CleanableReference(T referent, Runnable cleanupAction, ReferenceManagerImpl manager) {
+            super(referent, manager.queue);
+            this.cleanupAction = cleanupAction;
+            this.cleanupList = manager.cleanableReferenceList;
+            insert();
+        }
+
+        public void clean() {
+            if (remove()) {
+                super.clear();
+                cleanupAction.run();
+            }
+        }
+
+        @Override
+        public void clear() {
+            if (remove()) {
+                super.clear();
+            }
+        }
+
+        boolean hasRemaining() {
+            synchronized (cleanupList) {
+                return cleanupList != cleanupList.next;
+            }
+        }
+
+        private void insert() {
+            synchronized (cleanupList) {
+                previous = cleanupList;
+                next = cleanupList.next;
+                next.previous = this;
+                cleanupList.next = this;
+            }
+        }
+
+        private boolean remove() {
+            synchronized (cleanupList) {
+                if (next != this) {
+                    next.previous = previous;
+                    previous.next = next;
+                    previous = this;
+                    next = this;
+                    return true;
+                }
+
+                return false;
+            }
+        }
+    }
+}
diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/SerializableContent.java b/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/SerializableContent.java
@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-package com.azure.core.util.implementation;
+package com.azure.core.implementation.util;
 
 import com.azure.core.util.serializer.ObjectSerializer;
 import com.azure.core.util.serializer.TypeReference;
diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/StringContent.java b/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/StringContent.java
@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-package com.azure.core.util.implementation;
+package com.azure.core.implementation.util;
 
 import com.azure.core.util.serializer.ObjectSerializer;
 import com.azure.core.util.serializer.TypeReference;
@@ -18,7 +18,7 @@
  * A {@link BinaryDataContent} implementation which is backed by a {@code String}.
  */
 public final class StringContent extends BinaryDataContent {
-    private String content;
+    private final String content;
     private final AtomicReference<byte[]> bytes = new AtomicReference<>();
 
     /**
diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/package-info.java b/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/package-info.java
@@ -0,0 +1,7 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+/**
+ * Package containing implementation-specific utility APIs that should not be used by end-users.
+ */
+package com.azure.core.implementation.util;
diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/util/BinaryData.java b/sdk/core/azure-core/src/main/java/com/azure/core/util/BinaryData.java
@@ -3,12 +3,12 @@
 
 package com.azure.core.util;
 
-import com.azure.core.util.implementation.BinaryDataContent;
-import com.azure.core.util.implementation.ByteArrayContent;
-import com.azure.core.util.implementation.FileContent;
-import com.azure.core.util.implementation.InputStreamContent;
-import com.azure.core.util.implementation.SerializableContent;
-import com.azure.core.util.implementation.StringContent;
+import com.azure.core.implementation.util.BinaryDataContent;
+import com.azure.core.implementation.util.ByteArrayContent;
+import com.azure.core.implementation.util.FileContent;
+import com.azure.core.implementation.util.InputStreamContent;
+import com.azure.core.implementation.util.SerializableContent;
+import com.azure.core.implementation.util.StringContent;
 import com.azure.core.util.logging.ClientLogger;
 import com.azure.core.util.serializer.JsonSerializer;
 import com.azure.core.util.serializer.JsonSerializerProvider;
@@ -28,7 +28,7 @@
 import java.util.Objects;
 
 import static com.azure.core.util.FluxUtil.monoError;
-import static com.azure.core.util.implementation.BinaryDataContent.STREAM_READ_SIZE;
+import static com.azure.core.implementation.util.BinaryDataContent.STREAM_READ_SIZE;
 
 /**
  *
diff --git a/sdk/core/azure-core/src/main/java/com/azure/core/util/ReferenceManager.java b/sdk/core/azure-core/src/main/java/com/azure/core/util/ReferenceManager.java
@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.core.util;
+
+import com.azure.core.implementation.util.ReferenceManagerImpl;
+
+/**
+ * This interface represents managing references to {@link Object Objects} and providing the ability to run a
+ * cleaning operation once the object is no longer able to be reference.
+ * <p>
+ * Expected usage of this is through {@link ReferenceManager#INSTANCE}.
+ */
+public interface ReferenceManager {
+    /**
+     * The global instance of {@link ReferenceManager} that should be used to maintain object references.
+     */
+    ReferenceManager INSTANCE = new ReferenceManagerImpl();
+
+    /**
+     * Registers the {@code object} and the cleaning action to run once the object becomes phantom reachable.
+     * <p>
+     * The {@code cleanupAction} cannot have a reference to the {@code object}, otherwise the object will never be able
+     * to become phantom reachable.
+     * <p>
+     * Exceptions thrown by {@code cleanupAction} are ignored.
+     *
+     * @param object The object to monitor.
+     * @param cleanupAction The cleanup action to perform when the {@code object} becomes phantom reachable.
+     * @throws NullPointerException If either {@code object} or {@code cleanupAction} are null.
+     */
+    void register(Object object, Runnable cleanupAction);
+}
diff --git a/sdk/core/azure-core/src/main/java9/com/azure/core/implementation/util/ReferenceManagerImpl.java b/sdk/core/azure-core/src/main/java9/com/azure/core/implementation/util/ReferenceManagerImpl.java
diff --git a/sdk/core/azure-core/src/main/java9/com/azure/core/implementation/util/package-info.java b/sdk/core/azure-core/src/main/java9/com/azure/core/implementation/util/package-info.java
diff --git a/sdk/core/azure-core/src/test/java/com/azure/core/implementation/util/ReferenceManagerImplIT.java b/sdk/core/azure-core/src/test/java/com/azure/core/implementation/util/ReferenceManagerImplIT.java
diff --git a/sdk/core/azure-core/src/test/java/com/azure/core/util/BinaryDataTest.java b/sdk/core/azure-core/src/test/java/com/azure/core/util/BinaryDataTest.java
diff --git a/sdk/core/azure-core/src/test/java/com/azure/core/util/ReferenceManagerIT.java b/sdk/core/azure-core/src/test/java/com/azure/core/util/ReferenceManagerIT.java
diff --git a/sdk/core/ci.yml b/sdk/core/ci.yml
diff --git a/sdk/core/tests.yml b/sdk/core/tests.yml
