Update API to 4.1

api/src/main/java/me/lucko/luckperms/api/Node.java

@@ -32,22 +32,59 @@ import java.util.List;
 import java.util.Map;
 import java.util.Optional;
 import java.util.Set;
+import java.util.stream.Stream;
 
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
 
 /**
- * Represents a permission node.
+ * Represents a LuckPerms "node".
  *
- * <p>All implementations of this interface must be immutable.</p>
+ * <p>The {@link Node} class encapsulates more than just permission assignments.
+ * Nodes are used to store data about inherited groups, as well as assigned
+ * prefixes, suffixes and meta values.</p>
  *
- * <p>Use the {@link NodeFactory} to obtain and construct instances.</p>
+ * <p>Combining these various states into one object (a "node") means that a
+ * holder only has to have one type of data set (a set of nodes) in order to
+ * take on various properties.</p>
  *
+ * <p>It is recommended that users of the API make use of {@link Stream}s
+ * to manipulate data and obtain the required information.</p>
+ *
+ * <p>This interface provides a number of methods to read the attributes of the
+ * node, as well as methods to query and extract additional state and properties
+ * from these settings.</p>
+ *
+ * <p>Nodes have the following attributes:</p>
+ * <p></p>
+ * <ul>
+ *     <li>{@link #getPermission() permission} - the actual permission string</li>
+ *     <li>{@link #getValuePrimitive() value} - the value of the node (false for negated)</li>
+ *     <li>{@link #isOverride() override} - if the node is marked as having special priority over other nodes</li>
+ *     <li>{@link #getServer() server} - the specific server where this node should apply</li>
+ *     <li>{@link #getWorld() world} - the specific world where this node should apply</li>
+ *     <li>{@link #getContexts() context} - the additional contexts required for this node to apply </li>
+ *     <li>{@link #getExpiry() expiry} - the time when this node should expire</li>
+ * </ul>
+ *
+ * <p>Nodes can also fall into the following sub categories.</p>
+ * <p></p>
+ * <ul>
+ *     <li>normal - just a regular permission</li>
+ *     <li>{@link #isGroupNode() group node} - a "group node" marks that the holder should inherit data from another group</li>
+ *     <li>{@link #isPrefix() prefix} - represents an assigned prefix</li>
+ *     <li>{@link #isSuffix() suffix} - represents an assigned suffix</li>
+ *     <li>{@link #isMeta() meta} - represents an assigned meta option</li>
+ * </ul>
+ *
+ * <p>The core node state must be immutable in all implementations.</p>
+ *
+ * @see NodeFactory for obtaining and constructing instances.
  * @since 2.6
  */
 @Immutable
-public interface Node extends Map.Entry<String, Boolean> {
+public interface Node {
 
     /**
      * Gets the permission string
@@ -64,7 +101,6 @@ public interface Node extends Map.Entry<String, Boolean> {
      *
      * @return the permission's value
      */
-    @Override
     @Nonnull
     default Boolean getValue() {
         return getValuePrimitive();
@@ -394,6 +430,15 @@ public interface Node extends Map.Entry<String, Boolean> {
         return equals(other, StandardNodeEquality.IGNORE_VALUE_OR_IF_TEMPORARY);
     }
 
+    /**
+     * Constructs a new builder initially containing the current properties of
+     * this node.
+     *
+     * @return a new builder
+     * @since 4.1
+     */
+    Builder toBuilder();
+
     /**
      * Builds a Node instance
      */