Permissioning - improve java docs (#2618)

Signed-off-by: Antony Denyer <git@antonydenyer.co.uk>

Co-authored-by: Sally MacFarlane <sally.macfarlane@consensys.net>

plugin-api/build.gradle

@@ -64,7 +64,7 @@ Calculated : ${currentHash}
 tasks.register('checkAPIChanges', FileStateChecker) {
   description = "Checks that the API for the Plugin-API project does not change without deliberate thought"
   files = sourceSets.main.allJava.files
-  knownHash = '2JAuicCNps4APcYpEbWHqNOawoJAakVi19pPI5NwvsE='
+  knownHash = 'OR7Vv5zfD/qRVBs601gbEVLctGjQYNnL80iPja83+ag='
 }
 check.dependsOn('checkAPIChanges')
 

plugin-api/src/main/java/org/hyperledger/besu/plugin/services/PermissioningService.java

@@ -17,8 +17,31 @@ package org.hyperledger.besu.plugin.services;
 import org.hyperledger.besu.plugin.services.permissioning.NodeConnectionPermissioningProvider;
 import org.hyperledger.besu.plugin.services.permissioning.NodeMessagePermissioningProvider;
 
+/**
+ * This service allows plugins to decide who you should connect to and what you should send them.
+ *
+ * <p>Currently there are two hooks available; connection permissioning and message permissioning.
+ *
+ * <ul>
+ *   <li><b>Connection permissioning</b> - checks if inbound and outbound connections to peers are
+ *       permitted. {@link NodeConnectionPermissioningProvider}
+ *   <li><b>Message permissioning</b> - checks if a devp2p message can be sent to a peer. {@link
+ *       NodeMessagePermissioningProvider}
+ * </ul>
+ */
 public interface PermissioningService extends BesuService {
+
+  /**
+   * Registers a callback to allow the interception of a peer connection request
+   *
+   * @param provider The provider to register
+   */
   void registerNodePermissioningProvider(NodeConnectionPermissioningProvider provider);
 
+  /**
+   * Registers a callback to allow the interception of a devp2p message sending request
+   *
+   * @param provider The provider to register
+   */
   void registerNodeMessagePermissioningProvider(NodeMessagePermissioningProvider provider);
 }

plugin-api/src/main/java/org/hyperledger/besu/plugin/services/permissioning/NodeConnectionPermissioningProvider.java

@@ -16,6 +16,21 @@ package org.hyperledger.besu.plugin.services.permissioning;
 
 import org.hyperledger.besu.plugin.data.EnodeURL;
 
+/**
+ * Allows you to register a provider that will decide if a peer connection is permitted. <br>
+ * <br>
+ * A simple implementation can look like:
+ *
+ * <pre>{@code
+ * context
+ *    .getService(PermissioningService.class)
+ *    .get()
+ *    .registerNodePermissioningProvider((sourceEnode, destinationEnode) -> {
+ *        // Your logic here
+ *        return true;
+ *     });
+ * }</pre>
+ */
 @FunctionalInterface
 public interface NodeConnectionPermissioningProvider {
   /**

plugin-api/src/main/java/org/hyperledger/besu/plugin/services/permissioning/NodeMessagePermissioningProvider.java

@@ -17,10 +17,27 @@ package org.hyperledger.besu.plugin.services.permissioning;
 
 import org.hyperledger.besu.plugin.data.EnodeURL;
 
+/**
+ * Allows you to register a provider that will decide if a devp2p message is permitted. <br>
+ * <br>
+ * A simple implementation can look like:
+ *
+ * <pre>{@code
+ * context
+ *    .getService(PermissioningService.class)
+ *    .get()
+ *    .registerNodeMessagePermissioningProvider((destinationEnode, code) -> {
+ *        // Your logic here
+ *        return true;
+ *    });
+ * }</pre>
+ */
 @FunctionalInterface
 public interface NodeMessagePermissioningProvider {
   /**
-   * Can be used to intercept messages before they are sent from besu.
+   * Can be used to intercept messages before they are sent from besu. <br>
+   * <br>
+   * <b>Note: this will be called on every message!</b>
    *
    * @param destinationEnode the enode you are about to send to
    * @param code devp2p code for the message