Add a method isConnected to IComputer and provide implementation in Computer (#10607)

Co-authored-by: Mark Waite <mark.earl.waite@gmail.com>
Co-authored-by: Tim Jacomb <21194782+timja@users.noreply.github.com>
Co-authored-by: Vincent Latombe <vincent@latombe.net>

Author: 4 people

core/src/main/java/hudson/model/Computer.java

@@ -625,6 +625,19 @@ public final boolean isOnline() {
         return !isOffline();
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Uses {@link #getChannel()} to check the connection.
+     * A connected agent may still be offline for scheduling if marked temporarily offline.
+     * @return {@code true} if the agent is connected, {@code false} otherwise.
+     * @see #isOffline()
+     */
+    @Override
+    public boolean isConnected() {
+        return getChannel() != null;
+    }
+
     /**
      * This method is called to determine whether manual launching of the agent is allowed at this point in time.
      * @return {@code true} if manual launching of the agent is allowed at this point in time.

core/src/main/java/jenkins/model/IComputer.java

@@ -54,7 +54,11 @@ public interface IComputer extends AccessControlled, IconSpec, ModelObject, Name
     List<? extends IDisplayExecutor> getDisplayExecutors();
 
     /**
-     * @return {@code true} if the node is offline. {@code false} if it is online.
+     * Returns whether the agent is offline for scheduling new tasks.
+     * Even if {@code true}, the agent may still be connected to the controller and executing a task,
+     * but is considered offline for scheduling.
+     * @return {@code true} if the agent is offline; {@code false} if online.
+     * @see #isConnected()
      */
     boolean isOffline();
 
@@ -180,10 +184,21 @@ default String getIconClassName() {
     int countExecutors();
 
     /**
-     * @return true if the computer is online.
+     * Indicates whether the agent can accept a new task when it becomes idle.
+     * {@code false} does not necessarily mean the agent is disconnected.
+     * @return {@code true} if the agent is online.
+     * @see #isConnected()
      */
     boolean isOnline();
 
+    /**
+     * Indicates whether the agent is actually connected to the controller.
+     * @return {@code true} if the agent is connected to the controller.
+     */
+    default boolean isConnected() {
+        return isOnline();
+    }
+
     /**
      * @return the number of {@link IExecutor}s that are idle right now.
      */

test/src/test/java/hudson/model/ComputerTest.java

@@ -31,6 +31,7 @@
 import static org.hamcrest.Matchers.containsInAnyOrder;
 import static org.hamcrest.Matchers.containsString;
 import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.is;
 import static org.hamcrest.Matchers.isA;
 import static org.hamcrest.Matchers.not;
 import static org.hamcrest.Matchers.nullValue;
@@ -320,4 +321,37 @@ void computersCollected() throws Exception {
         MemoryAssert.assertGC(channelRef, false);
     }
 
+    @Test
+    public void isConnectedTest() throws Exception {
+        var agent = j.createSlave();
+        var computer = agent.toComputer();
+
+        // Verify initial state: computer is not connected
+        assertThat(computer.isOnline(), is(false));
+        assertThat(computer.isConnected(), is(false));
+
+        // Connect the computer
+        computer.connect(false);
+        await("computer should be online after connect").until(() -> computer.isOnline(), is(true));
+        assertThat(computer.isConnected(), is(true));
+        assertThat(computer.isOffline(), is(false));
+
+        // Mark computer temporary offline
+        computer.doToggleOffline(null);
+        assertThat("temporary offline agent is still connected", computer.isConnected(), is(true));
+        assertThat("temporary offline agent is not available for scheduling", computer.isOnline(), is(false));
+        assertThat(computer.isOffline(), is(true));
+
+        // Bring it back online
+        computer.doToggleOffline(null);
+        assertThat(computer.isOnline(), is(true));
+        assertThat(computer.isConnected(), is(true)); // channel is still there.
+
+        // Disconnect the computer
+        computer.disconnect(new OfflineCause.UserCause(null, null));
+        // wait for the slave process to be killed
+        await("disconnected agent is not available for scheduling").until(() -> computer.isOnline(), is(false));
+        assertThat(computer.isConnected(), is(false));
+        assertThat(computer.isOffline(), is(true));
+    }
 }