Properly documenting the AccessDeniedException as thrown by ItemGroup.read...

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

@@ -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);

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.

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;