Introduce Named, FullyNamed, FullyNamedModelObject interfaces (#10827)

* Introduce `Nameable`, `FullyNameable`, `FullyNameableModelObject` interfaces

These correspond to methods `getName`, `getFullName`, `getFullDisplayName` that did not have any common interface to call them, causing some inconvenient usages of switch statements or even reflection in CloudBees CI HA.

* Nameable -> Named

* Improve javadoc

Co-authored-by: Jesse Glick <jglick@cloudbees.com>

* Make ResourceActivity extend ModelObject

* Use full name for affinity key if available.

---------

Co-authored-by: Jesse Glick <jglick@cloudbees.com>

Author: Vlatombe

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

@@ -129,6 +129,7 @@ protected AbstractItem(ItemGroup parent, String name) {
         doSetName(name);
     }
 
+    @NonNull
     @Override
     @Exported(visibility = 999)
     public String getName() {
@@ -470,6 +471,7 @@ public void movedTo(DirectlyModifiableTopLevelItemGroup destination, AbstractIte
     @Override
     public abstract Collection<? extends Job> getAllJobs();
 
+    @NonNull
     @Override
     @Exported
     public final String getFullName() {

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

@@ -38,7 +38,10 @@
 import hudson.util.Secret;
 import java.io.IOException;
 import java.util.Collection;
+import jenkins.model.FullyNamed;
+import jenkins.model.FullyNamedModelObject;
 import jenkins.model.Jenkins;
+import jenkins.model.Named;
 import jenkins.search.SearchGroup;
 import jenkins.util.SystemProperties;
 import jenkins.util.io.OnMaster;
@@ -73,7 +76,7 @@
  * @see Items
  * @see ItemVisitor
  */
-public interface Item extends PersistenceRoot, SearchableModelObject, AccessControlled, OnMaster {
+public interface Item extends PersistenceRoot, FullyNamedModelObject, SearchableModelObject, FullyNamed, Named, AccessControlled, OnMaster {
     /**
      * Gets the parent that contains this item.
      */
@@ -97,6 +100,8 @@ public interface Item extends PersistenceRoot, SearchableModelObject, AccessCont
      *
      * @see #getFullName()
      */
+    @NonNull
+    @Override
     String getName();
 
     /**
@@ -110,6 +115,8 @@ public interface Item extends PersistenceRoot, SearchableModelObject, AccessCont
      *
      * @see jenkins.model.Jenkins#getItemByFullName(String,Class)
      */
+    @NonNull
+    @Override
     String getFullName();
 
     /**
@@ -127,13 +134,6 @@ public interface Item extends PersistenceRoot, SearchableModelObject, AccessCont
     @Override
     String getDisplayName();
 
-    /**
-     * Works like {@link #getDisplayName()} but return
-     * the full path that includes all the display names
-     * of the ancestors.
-     */
-    String getFullDisplayName();
-
     /**
      * Gets the relative name to this item from the specified group.
      *

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

@@ -33,6 +33,8 @@
 import java.util.function.Predicate;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
+import jenkins.model.FullyNamed;
+import jenkins.model.FullyNamedModelObject;
 import org.springframework.security.access.AccessDeniedException;
 
 /**
@@ -41,19 +43,7 @@
  * @author Kohsuke Kawaguchi
  * @see ItemGroupMixIn
  */
-public interface ItemGroup<T extends Item> extends PersistenceRoot, ModelObject {
-    /**
-     * Gets the full name of this {@link ItemGroup}.
-     *
-     * @see Item#getFullName()
-     */
-    String getFullName();
-
-    /**
-     * @see Item#getFullDisplayName()
-     */
-    String getFullDisplayName();
-
+public interface ItemGroup<T extends Item> extends FullyNamed, FullyNamedModelObject, PersistenceRoot {
     /**
      * Gets all the items in this collection in a read-only view.
      */

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

@@ -109,6 +109,8 @@
 import java.util.logging.Logger;
 import java.util.stream.Collectors;
 import jenkins.console.WithConsoleUrl;
+import jenkins.model.FullyNamed;
+import jenkins.model.FullyNamedModelObject;
 import jenkins.model.Jenkins;
 import jenkins.model.queue.AsynchronousExecution;
 import jenkins.model.queue.CompositeCauseOfBlockage;
@@ -1882,7 +1884,7 @@ public interface NonBlockingTask extends Task {}
      * design, a {@link Task} must have at least one sub-task.)
      * Most of the time, the primary subtask is the only sub task.
      */
-    public interface Task extends ModelObject, SubTask {
+    public interface Task extends FullyNamedModelObject, SubTask {
         /**
          * Returns true if the execution should be blocked
          * for temporary reasons.
@@ -1928,21 +1930,22 @@ default CauseOfBlockage getCauseOfBlockage() {
          */
         String getName();
 
-        /**
-         * @see hudson.model.Item#getFullDisplayName()
-         */
-        String getFullDisplayName();
-
         /**
          * Returns task-specific key which is used by the {@link LoadBalancer} to choose one particular executor
          * amongst all the free executors on all possibly suitable nodes.
          * NOTE: To be able to re-use the same node during the next run this key should not change from one run to
          * another. You probably want to compute that key based on the job's name.
          *
-         * @return by default: {@link #getFullDisplayName()}
+         * @return by default: {@link FullyNamed#getFullName()} if implements {@link FullyNamed} or {@link #getFullDisplayName()} otherwise.
          * @see hudson.model.LoadBalancer
          */
-        default String getAffinityKey() { return getFullDisplayName(); }
+        default String getAffinityKey() {
+            if (this instanceof FullyNamed fullyNamed) {
+                return fullyNamed.getFullName();
+            } else {
+                return getFullDisplayName();
+            }
+        }
 
         /**
          * Checks the permission to see if the current user can abort this executable.

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

@@ -29,7 +29,7 @@
  *
  * @author Kohsuke Kawaguchi
  */
-public interface ResourceActivity {
+public interface ResourceActivity extends ModelObject {
     /**
      * Gets the list of {@link Resource}s that this task requires.
      * Used to make sure no two conflicting tasks run concurrently.
@@ -47,9 +47,4 @@ public interface ResourceActivity {
     default ResourceList getResourceList() {
         return ResourceList.EMPTY;
     }
-
-    /**
-     * Used for rendering HTML.
-     */
-    String getDisplayName();
 }

core/src/main/java/hudson/model/queue/MappingWorksheet.java

@@ -27,6 +27,7 @@
 import static java.lang.Math.max;
 
 import com.google.common.collect.Iterables;
+import edu.umd.cs.findbugs.annotations.NonNull;
 import hudson.model.Computer;
 import hudson.model.Executor;
 import hudson.model.Label;
@@ -48,6 +49,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.logging.Logger;
+import jenkins.model.Named;
 
 /**
  * Defines a mapping problem for answering "where do we execute this task?"
@@ -114,7 +116,7 @@ public int size() {
         }
     }
 
-    public final class ExecutorChunk extends ReadOnlyList<ExecutorSlot> {
+    public final class ExecutorChunk extends ReadOnlyList<ExecutorSlot> implements Named {
         public final int index;
         public final Computer computer;
         public final Node node;
@@ -150,6 +152,8 @@ public boolean canAccept(WorkChunk c) {
         /**
          * Node name.
          */
+        @NonNull
+        @Override
         public String getName() {
             return node.getNodeName();
         }

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

@@ -0,0 +1,17 @@
+package jenkins.model;
+
+import edu.umd.cs.findbugs.annotations.NonNull;
+
+/**
+ * An interface for objects that have a name and a parent, so exposing a full name.
+ */
+public interface FullyNamed {
+    /**
+     * Returns the full name of this object, which is a qualified name
+     * that includes the names of all its ancestors, separated by '/'.
+     *
+     * @return the full name of this object.
+     */
+    @NonNull
+    String getFullName();
+}

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

@@ -0,0 +1,23 @@
+package jenkins.model;
+
+import hudson.model.ModelObject;
+import jenkins.security.stapler.StaplerAccessibleType;
+
+/**
+ * A model object that has a human-readable full name. This is usually valid when nested as part of an object hierarchy.
+ *
+ * <p>
+ * This interface is used to mark objects that can be qualified in the context of a Jenkins instance.
+ * It is typically used for objects that are part of the Jenkins model and can be referenced by their names.
+ *
+ * @see ModelObject
+ */
+@StaplerAccessibleType
+public interface FullyNamedModelObject extends ModelObject {
+    /**
+     * Works like {@link #getDisplayName()} but return
+     * the full path that includes all the display names
+     * of the ancestors in an unspecified format.
+     */
+    String getFullDisplayName();
+}

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

@@ -29,7 +29,6 @@
 import hudson.markup.MarkupFormatter;
 import hudson.model.BallColor;
 import hudson.model.BuildBadgeAction;
-import hudson.model.ModelObject;
 import hudson.model.ParameterValue;
 import hudson.model.ParametersAction;
 import hudson.model.Queue;
@@ -48,7 +47,7 @@
  * @since 2.477
  */
 @Restricted(Beta.class)
-public interface HistoricalBuild extends ModelObject {
+public interface HistoricalBuild extends FullyNamedModelObject {
 
     /**
      * @return A build number
@@ -74,12 +73,6 @@ public interface HistoricalBuild extends ModelObject {
     @CheckForNull
     String getDescription();
 
-    /**
-     * @return a human-readable full display name of this build.
-     */
-    @NonNull
-    String getFullDisplayName();
-
     /**
      * Get the {@link Queue.Item#getId()} of the original queue item from where this {@link HistoricalBuild} instance
      * originated.

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

@@ -27,7 +27,7 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 import hudson.Util;
 import hudson.model.Computer;
-import hudson.model.Node;
+import hudson.model.ModelObject;
 import hudson.security.ACL;
 import hudson.security.AccessControlled;
 import java.util.List;
@@ -45,13 +45,7 @@
  * @since 2.480
  */
 @Restricted(Beta.class)
-public interface IComputer extends AccessControlled, IconSpec {
-    /**
-     * Returns {@link Node#getNodeName() the name of the node}.
-     */
-    @NonNull
-    String getName();
-
+public interface IComputer extends AccessControlled, IconSpec, ModelObject, Named {
     /**
      * Used to render the list of executors.
      * @return a snapshot of the executor display information
@@ -64,12 +58,6 @@ public interface IComputer extends AccessControlled, IconSpec {
      */
     boolean isOffline();
 
-    /**
-     * @return the node name for UI purposes.
-     */
-    @NonNull
-    String getDisplayName();
-
     /**
      * Returns {@code true} if the computer is accepting tasks. Needed to allow agents programmatic suspension of task
      * scheduling that does not overlap with being offline.