From 174786b9f75847ad95beab9041db8d1c0a7e518a Mon Sep 17 00:00:00 2001
From: Jesse Glick <jglick@cloudbees.com>
Date: Tue, 26 Aug 2014 12:26:22 -0400
Subject: [PATCH] Properly documenting the AccessDeniedException as thrown by
 ItemGroup.read (and methods that call it). Also making DISCOVER permission be
 implied by READ, which is natural since it is only checked if READ is denied.

---
 core/src/main/java/hudson/model/Item.java      | 2 +-
 core/src/main/java/hudson/model/ItemGroup.java | 5 ++++-
 core/src/main/java/jenkins/model/Jenkins.java  | 5 +++--
 3 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/core/src/main/java/hudson/model/Item.java b/core/src/main/java/hudson/model/Item.java
index d0931b85f7..726796fa8e 100644
--- a/core/src/main/java/hudson/model/Item.java
+++ b/core/src/main/java/hudson/model/Item.java
@@ -224,7 +224,7 @@ public interface Item extends PersistenceRoot, SearchableModelObject, AccessCont
     Permission DELETE = new Permission(PERMISSIONS, "Delete", Messages._Item_DELETE_description(), Permission.DELETE, PermissionScope.ITEM);
     Permission CONFIGURE = new Permission(PERMISSIONS, "Configure", Messages._Item_CONFIGURE_description(), Permission.CONFIGURE, PermissionScope.ITEM);
     Permission READ = new Permission(PERMISSIONS, "Read", Messages._Item_READ_description(), Permission.READ, PermissionScope.ITEM);
-    Permission DISCOVER = new Permission(PERMISSIONS, "Discover", Messages._AbstractProject_DiscoverPermission_Description(), Permission.READ, PermissionScope.ITEM);
+    Permission DISCOVER = new Permission(PERMISSIONS, "Discover", Messages._AbstractProject_DiscoverPermission_Description(), READ, PermissionScope.ITEM);
     Permission EXTENDED_READ = new Permission(PERMISSIONS,"ExtendedRead", Messages._AbstractProject_ExtendedReadPermission_Description(), CONFIGURE, Boolean.getBoolean("hudson.security.ExtendedReadPermission"), new PermissionScope[]{PermissionScope.ITEM});
     // TODO the following really belong in Job, not Item, but too late to move since the owner.name is encoded in the ID:
     Permission BUILD = new Permission(PERMISSIONS, "Build", Messages._AbstractProject_BuildPermission_Description(),  Permission.UPDATE, PermissionScope.ITEM);
diff --git a/core/src/main/java/hudson/model/ItemGroup.java b/core/src/main/java/hudson/model/ItemGroup.java
index bc042c8925..ace90e16b4 100644
--- a/core/src/main/java/hudson/model/ItemGroup.java
+++ b/core/src/main/java/hudson/model/ItemGroup.java
@@ -28,6 +28,7 @@ import java.io.IOException;
 import java.util.Collection;
 import java.io.File;
 import javax.annotation.CheckForNull;
+import org.acegisecurity.AccessDeniedException;
 
 /**
  * Represents a grouping inherent to a kind of {@link Item}s.
@@ -67,8 +68,10 @@ public interface ItemGroup<T extends Item> extends PersistenceRoot, ModelObject
 
     /**
      * Gets the {@link Item} inside this group that has a given name, or null if it does not exist.
+     * @throws AccessDeniedException if the current user has {@link Item#DISCOVER} but not {@link Item#READ} on this item
+     * @return an item whose {@link Item#getName} is {@code name} and whose {@link Item#getParent} is {@code this}, or null if there is no such item, or there is but the current user lacks both {@link Item#DISCOVER} and {@link Item#READ} on it
      */
-    @CheckForNull T getItem(String name);
+    @CheckForNull T getItem(String name) throws AccessDeniedException;
 
     /**
      * Assigns the {@link Item#getRootDir() root directory} for children.
diff --git a/core/src/main/java/jenkins/model/Jenkins.java b/core/src/main/java/jenkins/model/Jenkins.java
index 419c4c528a..6826652fe9 100644
--- a/core/src/main/java/jenkins/model/Jenkins.java
+++ b/core/src/main/java/jenkins/model/Jenkins.java
@@ -2307,7 +2307,7 @@ public class Jenkins extends AbstractCIBase implements DirectlyModifiableTopLeve
      *
      * Note that the look up is case-insensitive.
      */
-    public TopLevelItem getItem(String name) {
+    @Override public TopLevelItem getItem(String name) throws AccessDeniedException {
         if (name==null)    return null;
     	TopLevelItem item = items.get(name);
         if (item==null)
@@ -2411,8 +2411,9 @@ public class Jenkins extends AbstractCIBase implements DirectlyModifiableTopLeve
      * @return
      *      null if either such {@link Item} doesn't exist under the given full name,
      *      or it exists but it's no an instance of the given type.
+     * @throws AccessDeniedException as per {@link ItemGroup#getItem}
      */
-    public @CheckForNull <T extends Item> T getItemByFullName(String fullName, Class<T> type) {
+    public @CheckForNull <T extends Item> T getItemByFullName(String fullName, Class<T> type) throws AccessDeniedException {
         StringTokenizer tokens = new StringTokenizer(fullName,"/");
         ItemGroup parent = this;
 
-- 
GitLab