Merge pull request #56 from jglick/RoleSensitive-Javadoc

Trying to guide people away from implementing RoleSensitive manually
jenkinsci · Aug 5, 2015 · 6fb8f96 · 6fb8f96
2 parents eb771ca + 3e3d2d0
commit 6fb8f96
Show file tree

Hide file tree

Showing 2 changed files with 5 additions and 2 deletions.
diff --git a/src/main/java/org/jenkinsci/remoting/RoleChecker.java b/src/main/java/org/jenkinsci/remoting/RoleChecker.java
@@ -19,7 +19,7 @@ public abstract class RoleChecker {
     /**
      * Called from {@link RoleSensitive#checkRoles(RoleChecker)} to ensure that this side of the channel
      * is willing to execute {@link Callable}s that expects one of the given roles on their intended recipients.
-     *
+     * <p><strong>If you think you need to implement {@link RoleSensitive#checkRoles}</strong> please reread that method’s Javadoc.
      * <p>
      * Normally, each side of the channel has a fixed set of roles (say {@code actualRoles}),
      * and the implementation would be {@code actualRoles.containsAll(roles)}.

diff --git a/src/main/java/org/jenkinsci/remoting/RoleSensitive.java b/src/main/java/org/jenkinsci/remoting/RoleSensitive.java
@@ -20,7 +20,10 @@ public interface RoleSensitive {
     /**
      * Verifies the roles expected by this callable by invoking {@link RoleChecker#check(RoleSensitive, Collection)}
      * method (or its variants), to provide an opportunity for {@link RoleChecker} to reject this object.
-     *
+     * <p><strong>Do not implement this method</strong> unless you know what you are doing.
+     * If you have a Jenkins {@link Callable} or {@code FileCallable}, use the standard abstract base classes instead,
+     * such as {@code MasterToSlaveCallable}, {@code MasterToSlaveFileCallable}, {@code NotReallyRoleSensitiveCallable}, etc.
+     * See <a href="https://wiki.jenkins-ci.org/display/JENKINS/Slave+To+Master+Access+Control/#SlaveToMasterAccessControl-I%27maplugindeveloper.WhatshouldIdo%3F">this document</a> for details.
      * @return
      *      If the method returns normally, the check has passed.
      *