Added annotations to kernel security classes.

Most of methods define @Nonnull inputs and outputs (the legacy behavior is mostly non-documented), but there're several exceptions
Signed-off-by: NOleg Nenashev <o.v.nenashev@gmail.com>

core/src/main/java/hudson/security/ACL.java

@@ -23,6 +23,7 @@
  */
 package hudson.security;
 
+import javax.annotation.Nonnull;
 import jenkins.security.NonSerializableSecurityContext;
 import jenkins.model.Jenkins;
 import org.acegisecurity.AccessDeniedException;
@@ -48,7 +49,7 @@ public abstract class ACL {
      * @throws AccessDeniedException
      *      if the user doesn't have the permission.
      */
-    public final void checkPermission(Permission p) {
+    public final void checkPermission(@Nonnull Permission p) {
         Authentication a = Jenkins.getAuthentication();
         if(!hasPermission(a,p))
             throw new AccessDeniedException2(a,p);
@@ -60,7 +61,7 @@ public abstract class ACL {
      * @return false
      *      if the user doesn't have the permission.
      */
-    public final boolean hasPermission(Permission p) {
+    public final boolean hasPermission(@Nonnull Permission p) {
         return hasPermission(Jenkins.getAuthentication(),p);
     }
 
@@ -71,7 +72,7 @@ public abstract class ACL {
      * Note that {@link #SYSTEM} can be passed in as the authentication parameter,
      * in which case you should probably just assume it has every permission.
      */
-    public abstract boolean hasPermission(Authentication a, Permission permission);
+    public abstract boolean hasPermission(@Nonnull Authentication a, @Nonnull Permission permission);
 
     //
     // Sid constants
@@ -124,7 +125,7 @@ public abstract class ACL {
      * because the same {@link SecurityContext} object is reused for all the concurrent requests from the same session.
      * @since 1.462
      */
-    public static SecurityContext impersonate(Authentication auth) {
+    public static @Nonnull SecurityContext impersonate(@Nonnull Authentication auth) {
         SecurityContext old = SecurityContextHolder.getContext();
         SecurityContextHolder.setContext(new NonSerializableSecurityContext(auth));
         return old;
@@ -136,7 +137,7 @@ public abstract class ACL {
      * @param body an action to run with this alternate authentication in effect
      * @since 1.509
      */
-    public static void impersonate(Authentication auth, Runnable body) {
+    public static void impersonate(@Nonnull Authentication auth, @Nonnull Runnable body) {
         SecurityContext old = impersonate(auth);
         try {
             body.run();

core/src/main/java/hudson/security/AccessControlled.java

@@ -23,6 +23,7 @@
  */
 package hudson.security;
 
+import javax.annotation.Nonnull;
 import org.acegisecurity.AccessDeniedException;
 
 /**
@@ -36,16 +37,16 @@ public interface AccessControlled {
      *
      * @return never null.
      */
-    ACL getACL();
+    @Nonnull ACL getACL();
 
     /**
      * Convenient short-cut for {@code getACL().checkPermission(permission)}
      */
-    void checkPermission(Permission permission) throws AccessDeniedException;
+    void checkPermission(@Nonnull Permission permission) throws AccessDeniedException;
 
     /**
      * Convenient short-cut for {@code getACL().hasPermission(permission)}
      */
-    boolean hasPermission(Permission permission);
+    boolean hasPermission(@Nonnull Permission permission);
 
 }

core/src/main/java/hudson/security/AuthorizationStrategy.java

@@ -33,6 +33,7 @@ import hudson.util.DescriptorList;
 import java.io.Serializable;
 import java.util.Collection;
 import java.util.Collections;
+import javax.annotation.Nonnull;
 
 import jenkins.model.Jenkins;
 import net.sf.json.JSONObject;
@@ -68,18 +69,18 @@ public abstract class AuthorizationStrategy extends AbstractDescribableImpl<Auth
      * <p>
      * IOW, this ACL will have the ultimate say on the access control.
      */
-    public abstract ACL getRootACL();
+    public abstract @Nonnull ACL getRootACL();
 
     /**
      * @deprecated since 1.277
      *      Override {@link #getACL(Job)} instead.
      */
     @Deprecated
-    public ACL getACL(AbstractProject<?,?> project) {
+    public @Nonnull ACL getACL(@Nonnull AbstractProject<?,?> project) {
     	return getACL((Job)project);
     }
 
-    public ACL getACL(Job<?,?> project) {
+    public @Nonnull ACL getACL(@Nonnull Job<?,?> project) {
     	return getRootACL();
     }
 
@@ -93,7 +94,7 @@ public abstract class AuthorizationStrategy extends AbstractDescribableImpl<Auth
      *
      * @since 1.220
      */
-    public ACL getACL(final View item) {
+    public @Nonnull ACL getACL(final @Nonnull View item) {
         return new ACL() {
             @Override
             public boolean hasPermission(Authentication a, Permission permission) {
@@ -118,7 +119,7 @@ public abstract class AuthorizationStrategy extends AbstractDescribableImpl<Auth
      *
      * @since 1.220
      */
-    public ACL getACL(AbstractItem item) {
+    public @Nonnull ACL getACL(@Nonnull AbstractItem item) {
         return getRootACL();
     }
 
@@ -131,7 +132,7 @@ public abstract class AuthorizationStrategy extends AbstractDescribableImpl<Auth
      *
      * @since 1.221
      */
-    public ACL getACL(User user) {
+    public @Nonnull ACL getACL(@Nonnull User user) {
         return getRootACL();
     }
 
@@ -144,7 +145,7 @@ public abstract class AuthorizationStrategy extends AbstractDescribableImpl<Auth
      *
      * @since 1.220
      */
-    public ACL getACL(Computer computer) {
+    public @Nonnull ACL getACL(@Nonnull Computer computer) {
         return getACL(computer.getNode());
     }
 
@@ -157,11 +158,11 @@ public abstract class AuthorizationStrategy extends AbstractDescribableImpl<Auth
      *
      * @since 1.252
      */
-    public ACL getACL(Cloud cloud) {
+    public @Nonnull ACL getACL(@Nonnull Cloud cloud) {
         return getRootACL();
     }
 
-    public ACL getACL(Node node) {
+    public @Nonnull ACL getACL(@Nonnull Node node) {
         return getRootACL();
     }
 
@@ -179,12 +180,12 @@ public abstract class AuthorizationStrategy extends AbstractDescribableImpl<Auth
      * @return
      *      never null.
      */
-    public abstract Collection<String> getGroups();
+    public abstract @Nonnull Collection<String> getGroups();
 
     /**
      * Returns all the registered {@link AuthorizationStrategy} descriptors.
      */
-    public static DescriptorExtensionList<AuthorizationStrategy,Descriptor<AuthorizationStrategy>> all() {
+    public static @Nonnull DescriptorExtensionList<AuthorizationStrategy,Descriptor<AuthorizationStrategy>> all() {
         return Jenkins.getInstance().<AuthorizationStrategy,Descriptor<AuthorizationStrategy>>getDescriptorList(AuthorizationStrategy.class);
     }
 
@@ -214,15 +215,17 @@ public abstract class AuthorizationStrategy extends AbstractDescribableImpl<Auth
         }
 
         @Override
-        public ACL getRootACL() {
+        public @Nonnull ACL getRootACL() {
             return UNSECURED_ACL;
         }
 
-        public Collection<String> getGroups() {
+        @Override
+        public @Nonnull Collection<String> getGroups() {
             return Collections.emptySet();
         }
 
         private static final ACL UNSECURED_ACL = new ACL() {
+            @Override
             public boolean hasPermission(Authentication a, Permission permission) {
                 return true;
             }
@@ -230,12 +233,13 @@ public abstract class AuthorizationStrategy extends AbstractDescribableImpl<Auth
 
         @Extension
         public static final class DescriptorImpl extends Descriptor<AuthorizationStrategy> {
+            @Override
             public String getDisplayName() {
                 return Messages.AuthorizationStrategy_DisplayName();
             }
 
             @Override
-            public AuthorizationStrategy newInstance(StaplerRequest req, JSONObject formData) throws FormException {
+            public @Nonnull AuthorizationStrategy newInstance(StaplerRequest req, JSONObject formData) throws FormException {
                 return UNSECURED;
             }
 

core/src/main/java/hudson/security/Permission.java

@@ -34,6 +34,7 @@ import java.util.List;
 import java.util.Set;
 import java.util.concurrent.CopyOnWriteArrayList;
 import javax.annotation.CheckForNull;
+import javax.annotation.Nonnull;
 
 import org.jvnet.localizer.Localizable;
 
@@ -58,14 +59,14 @@ public final class Permission {
          */
         // break eclipse compilation 
         //Override
-        public int compare(Permission one, Permission two) {
+        public int compare(@Nonnull Permission one, @Nonnull Permission two) {
             return one.getId().compareTo(two.getId());
         }
     };
 
-    public final Class owner;
+    public final @Nonnull Class owner;
 
-    public final PermissionGroup group;
+    public final @Nonnull PermissionGroup group;
 
     /**
      * Human readable ID of the permission.
@@ -76,7 +77,7 @@ public final class Permission {
      * <p>
      * The expected naming convention is something like "BrowseWorkspace".
      */
-    public final String name;
+    public final @Nonnull String name;
 
     /**
      * Human-readable description of this permission.
@@ -86,7 +87,7 @@ public final class Permission {
      * <p>
      * If null, there will be no description text.
      */
-    public final Localizable description;
+    public final @CheckForNull Localizable description;
 
     /**
      * Bundled {@link Permission} that also implies this permission.
@@ -101,7 +102,7 @@ public final class Permission {
      * such broad permission bundle is good enough, and those few
      * that need finer control can do so.
      */
-    public final Permission impliedBy;
+    public final @CheckForNull Permission impliedBy;
 
     /**
      * Whether this permission is available for use.
@@ -118,7 +119,7 @@ public final class Permission {
     /**
      * Scopes that this permission is directly contained by.
      */
-    private final Set<PermissionScope> scopes;
+    private final @Nonnull Set<PermissionScope> scopes;
 
     /**
      * Defines a new permission.
@@ -144,7 +145,9 @@ public final class Permission {
      * @param impliedBy
      *      See {@link #impliedBy}.
      */
-    public Permission(PermissionGroup group, String name, Localizable description, Permission impliedBy, boolean enable, PermissionScope[] scopes) {
+    public Permission(@Nonnull PermissionGroup group, @Nonnull String name, 
+            @CheckForNull Localizable description, @CheckForNull Permission impliedBy, boolean enable, 
+            @Nonnull PermissionScope[] scopes) {
         if(!JSONUtils.isJavaIdentifier(name))
             throw new IllegalArgumentException(name+" is not a Java identifier");
         this.owner = group.owner;
@@ -159,7 +162,8 @@ public final class Permission {
         ALL.add(this);
     }
 
-    public Permission(PermissionGroup group, String name, Localizable description, Permission impliedBy, PermissionScope scope) {
+    public Permission(@Nonnull PermissionGroup group, @Nonnull String name, 
+            @CheckForNull Localizable description, @CheckForNull Permission impliedBy, @Nonnull PermissionScope scope) {
         this(group,name,description,impliedBy,true,new PermissionScope[]{scope});
         assert scope!=null;
     }
@@ -168,7 +172,7 @@ public final class Permission {
      * @deprecated as of 1.421
      *      Use {@link #Permission(PermissionGroup, String, Localizable, Permission, boolean, PermissionScope[])}
      */
-    public Permission(PermissionGroup group, String name, Localizable description, Permission impliedBy, boolean enable) {
+    public Permission(@Nonnull PermissionGroup group, @Nonnull String name, @CheckForNull Localizable description, @CheckForNull Permission impliedBy, boolean enable) {
         this(group,name,description,impliedBy,enable,new PermissionScope[]{PermissionScope.JENKINS});
     }
 
@@ -176,7 +180,7 @@ public final class Permission {
      * @deprecated as of 1.421
      *      Use {@link #Permission(PermissionGroup, String, Localizable, Permission, PermissionScope)}
      */
-    public Permission(PermissionGroup group, String name, Localizable description, Permission impliedBy) {
+    public Permission(@Nonnull PermissionGroup group, @Nonnull String name, @CheckForNull Localizable description, @CheckForNull Permission impliedBy) {
         this(group, name, description, impliedBy, PermissionScope.JENKINS);
     }
 
@@ -184,18 +188,18 @@ public final class Permission {
      * @deprecated since 1.257.
      *      Use {@link #Permission(PermissionGroup, String, Localizable, Permission)}
      */
-    public Permission(PermissionGroup group, String name, Permission impliedBy) {
+    public Permission(@Nonnull PermissionGroup group, @Nonnull String name, @CheckForNull Permission impliedBy) {
         this(group,name,null,impliedBy);
     }
 
-    private Permission(PermissionGroup group, String name) {
+    private Permission(@Nonnull PermissionGroup group, @Nonnull String name) {
         this(group,name,null,null);
     }
 
     /**
      * Checks if this permission is contained in the specified scope, (either directly or indirectly.)
      */
-    public boolean isContainedBy(PermissionScope s) {
+    public boolean isContainedBy(@Nonnull PermissionScope s) {
         for (PermissionScope c : scopes) {
             if (c.isContainedBy(s))
                 return true;
@@ -210,10 +214,10 @@ public final class Permission {
      *
      * <p>
      * This string representation is suitable for persistence.
-     *
+     * @return ID with the following format: <i>permissionClass.permissionName</i> 
      * @see #fromId(String)
      */
-    public String getId() {
+    public @Nonnull String getId() {
         return owner.getName()+'.'+name;
     }
 
@@ -224,7 +228,7 @@ public final class Permission {
      *      null if the conversion failed.
      * @see #getId()
      */
-    public static @CheckForNull Permission fromId(String id) {
+    public static @CheckForNull Permission fromId(@Nonnull String id) {
         int idx = id.lastIndexOf('.');
         if(idx<0)   return null;
 
@@ -257,7 +261,7 @@ public final class Permission {
      * @return
      *      always non-null. Read-only.
      */
-    public static List<Permission> getAll() {
+    public static @Nonnull List<Permission> getAll() {
         return ALL_VIEW;
     }