Merge remote-tracking branch 'upstream/item-categorisation-2' into JE…

…NKINS-31162
jenkinsci · Mar 10, 2016 · 8b47f5c · 8b47f5c
2 parents 4e27ea2 + 277a743
commit 8b47f5c
Show file tree

Hide file tree

Showing 3 changed files with 142 additions and 0 deletions.
diff --git a/core/src/main/java/jenkins/model/ItemCategory.java b/core/src/main/java/jenkins/model/ItemCategory.java
@@ -0,0 +1,54 @@
+package jenkins.model;
+
+import hudson.Extension;
+import hudson.ExtensionPoint;
+import hudson.model.ModelObject;
+
+/**
+ * A category for {@link hudson.model.Item}s.
+ */
+public abstract class ItemCategory implements ModelObject, ExtensionPoint {
+
+    /**
+     * The icon class specification e.g. 'icon-category-folder', 'icon-help' etc.
+     * The size specification should not be provided as that is determined by the
+     * context of where the category is displayed.
+     *
+     * @return the icon class specification
+     */
+    public abstract String getIconClassName();
+
+    /**
+     * The default category, if an item doesn't belong anywhere else, this is where it goes by default.
+     */
+    @Extension
+    public static final class Default extends ItemCategory {
+
+        @Override
+        public String getIconClassName() {
+            return "icon-category-default"; //TODO whatever Gus decides
+        }
+
+        @Override
+        public String getDisplayName() {
+            return Messages.ItemCategory_Default_DisplayName();
+        }
+    }
+
+    /**
+     * A category suitable for folder and container (not docker) like items.
+     */
+    @Extension
+    public static final class Folders extends ItemCategory {
+
+        @Override
+        public String getIconClassName() {
+            return "icon-category-folders"; //TODO whatever Gus decides
+        }
+
+        @Override
+        public String getDisplayName() {
+            return Messages.ItemCategory_Folders_DisplayName();
+        }
+    }
+}
diff --git a/core/src/main/java/jenkins/model/ItemCategoryMapper.java b/core/src/main/java/jenkins/model/ItemCategoryMapper.java
@@ -0,0 +1,85 @@
+package jenkins.model;
+
+import hudson.Extension;
+import hudson.ExtensionList;
+import hudson.ExtensionPoint;
+import hudson.model.Item;
+
+import javax.annotation.CheckForNull;
+import javax.annotation.Nonnull;
+import java.util.Collection;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+/**
+ * A mapper of {@link ItemCategory}s to {@link hudson.model.Item}s.
+ * TODO maybe find a better name
+ */
+public abstract class ItemCategoryMapper implements ExtensionPoint {
+
+    public static final Logger LOGGER = Logger.getLogger(ItemCategoryMapper.class.getName());
+
+    /**
+     * Provides the category for the requested item or null if this mapper doesn't have one.
+     *
+     * @param item the item to categorise
+     *
+     * @return the category or null
+     */
+    @CheckForNull
+    public abstract ItemCategory getCategoryFor(@Nonnull Item item);
+
+    /**
+     * Finds the category specified by the first mapper.
+     * If none can be found {@link jenkins.model.ItemCategory.Default} is returned.
+     *
+     * @param item the item to categorise.
+     *
+     * @return the category
+     */
+    @Nonnull
+    public static ItemCategory getCategory(@Nonnull Item item) {
+        for (ItemCategoryMapper m : all()) {
+            try {
+                ItemCategory category = m.getCategoryFor(item);
+                if (category != null) {
+                    return category;
+                }
+            } catch (Exception ignored) {
+                LOGGER.log(Level.WARNING, ignored.getMessage(), ignored);
+            }
+        }
+        return ExtensionList.lookup(ItemCategory.Default.class).iterator().next();
+    }
+
+    public static Collection<ItemCategoryMapper> all() {
+        return ExtensionList.lookup(ItemCategoryMapper.class);
+    }
+
+    /**
+     * Provides some sensible defaults for at least the 2.0 recommended plugins.
+     * Any plugin that wants to override this list for their own item should extend {@link ItemCategoryMapper}
+     * with an {@link Extension#ordinal()} higher than {@code -10000}.
+     */
+    @Extension(ordinal = -10000)
+    public static final class SensibleDefaultMapper extends ItemCategoryMapper {
+
+        @Override
+        public ItemCategory getCategoryFor(@Nonnull Item item) {
+            //TODO load from some file provided by Gus or just if then else hardcoding
+            return null;
+        }
+    }
+
+    /**
+     * Mapper implementation with the lowest ordinal that simply returns {@link jenkins.model.ItemCategory.Default}.
+     */
+    @Extension(ordinal = Integer.MIN_VALUE)
+    public static final class DefaultMapper extends ItemCategoryMapper {
+
+        @Override
+        public ItemCategory getCategoryFor(@Nonnull Item item) {
+            return ExtensionList.lookup(ItemCategory.Default.class).iterator().next();
+        }
+    }
+}
diff --git a/core/src/main/resources/jenkins/model/Messages.properties b/core/src/main/resources/jenkins/model/Messages.properties
@@ -71,3 +71,6 @@ ParameterizedJobMixIn.build_now=Build Now
 BlockedBecauseOfBuildInProgress.shortDescription=Build #{0} is already in progress{1}
 BlockedBecauseOfBuildInProgress.ETA=\ (ETA:{0})
 BuildDiscarderProperty.displayName=Discard Old Builds
+
+ItemCategory.Default.DisplayName=Default/Unsorted
+ItemCategory.Folders.DisplayName=Folders and Containers