Jedis requires SLF4J (#1579)

This was removed from Minecraft 1.14, and isn't something I feel was ever really necessary to support.

.github/FUNDING.yml

@@ -0,0 +1 @@
+patreon: luckperms

.gitignore

@@ -1,40 +1,12 @@
-# Created by https://www.gitignore.io/
-
 ### Intellij ###
-# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and Webstorm
-# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
-
-# User-specific stuff:
 .idea/
 *.iws
 /out/
 *.iml
 .idea_modules/
-
-# JIRA plugin
 atlassian-ide-plugin.xml
 
-# Crashlytics plugin (for Android Studio and IntelliJ)
-com_crashlytics_export_strings.xml
-crashlytics.properties
-crashlytics-build.properties
-fabric.properties
-
-
-### Maven ###
-target/
-pom.xml.tag
-pom.xml.releaseBackup
-pom.xml.versionsBackup
-pom.xml.next
-release.properties
-dependency-reduced-pom.xml
-buildNumber.properties
-.mvn/timing.properties
-
-
 ### Eclipse ###
-
 .metadata
 bin/
 tmp/
@@ -46,73 +18,27 @@ local.properties
 .settings/
 .loadpath
 .recommenders
-
-# Eclipse Core
-.project
-
-# External tool builders
 .externalToolBuilders/
-
-# Locally stored "Eclipse launch configurations"
 *.launch
-
-# PyDev specific (Python IDE for Eclipse)
-*.pydevproject
-
-# CDT-specific (C/C++ Development Tooling)
-.cproject
-
-# JDT-specific (Eclipse Java Development Tools)
-.classpath
-
-# Java annotation processor (APT)
 .factorypath
-
-# PDT-specific (PHP Development Tools)
-.buildpath
-
-# sbteclipse plugin
-.target
-
-# Tern plugin
-.tern-project
-
-# TeXlipse plugin
-.texlipse
-
-# STS (Spring Tool Suite)
-.springBeans
-
-# Code Recommenders
 .recommenders/
-
+.apt_generated/
+.project
+.classpath
 
 ### Linux ###
 *~
-
-# temporary files which can be created if a process still has a handle open of a deleted file
 .fuse_hidden*
-
-# KDE directory preferences
 .directory
-
-# Linux trash folder which might appear on any partition or disk
 .Trash-*
-
-# .nfs files are created when an open file is removed but is still being accessed
 .nfs*
 
-
 ### macOS ###
-*.DS_Store
+.DS_Store
 .AppleDouble
 .LSOverride
-
-# Icon must end with two \r
 Icon
-# Thumbnails
 ._*
-# Files that might appear in the root of a volume
 .DocumentRevisions-V100
 .fseventsd
 .Spotlight-V100
@@ -120,45 +46,34 @@ Icon
 .Trashes
 .VolumeIcon.icns
 .com.apple.timemachine.donotpresent
-# Directories potentially created on remote AFP share
 .AppleDB
 .AppleDesktop
 Network Trash Folder
 Temporary Items
 .apdisk
 
+### NetBeans ###
+nbproject/private/
+build/
+nbbuild/
+dist/
+nbdist/
+.nb-gradle/
 
 ### Windows ###
-# Windows image file caches
+# Windows thumbnail cache files
 Thumbs.db
 ehthumbs.db
-
-# Folder config file
-Desktop.ini
-
-# Recycle Bin used on file shares
+ehthumbs_vista.db
+*.stackdump
+[Dd]esktop.ini
 $RECYCLE.BIN/
-
-# Windows Installer files
-*.cab
-*.msi
-*.msm
-*.msp
-
-# Windows shortcuts
 *.lnk
 
-
-### Java ###
-*.class
-
-# Mobile Tools for Java (J2ME)
-.mtj.tmp/
-
-# Package Files #
-*.jar
-*.war
-*.ear
-
-# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
-hs_err_pid*
+### Gradle ###
+.gradle
+/build/
+/out/
+gradle-app.setting
+!gradle-wrapper.jar
+.gradletasknamecache

CONTRIBUTING.md

@@ -19,8 +19,8 @@ LuckPerms loosely follows the [Google Java Style Guide](https://google.github.io
 If you're considering submitting a substantial pull request, please open an issue so we can discuss the change before starting work on the contribution. Most pull requests are happily accepted, but larger changes may have an inpact on the maintainability of the project, and require more consideration. 
 
 #### Project Layout
-The project is split up into 5 seperate modules.
+The project is split up into a few seperate modules.
 
 * **API** - The public, semantically versioned API used by other plugins wishing to integrate with and retrieve data from LuckPerms. This module (for the most part) does not contain any implementation itself, and is provided by the plugin.
 * **Common** - The common module contains most of the code which implements the respective LuckPerms plugins. This abstract module reduces duplicated code throughout the project.
-* **Bukkit, BungeeCord & Sponge** - Each use the common module to implement plugins on the respective server platforms.
+* **Bukkit, BungeeCord, Sponge, Nukkit & Velocity** - Each use the common module to implement plugins on the respective server platforms.

HEADER.txt

@@ -0,0 +1,22 @@
+This file is part of LuckPerms, licensed under the MIT License.
+
+ Copyright (c) lucko (Luck) <luck@lucko.me>
+ Copyright (c) contributors
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in all
+ copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.

LICENSE.txt

@@ -1,4 +1,4 @@
-The MIT License.
+MIT License
 
 Copyright (c) lucko (Luck) <luck@lucko.me>
 Copyright (c) contributors
@@ -19,4 +19,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

README.md

@@ -1,35 +1,37 @@
-![alt text](https://i.imgur.com/7TwJZ5e.png "Banner")
-# LuckPerms [![Build Status](https://ci.lucko.me/job/LuckPerms/badge/icon)](https://ci.lucko.me/job/LuckPerms/) [![Javadocs](https://javadoc.io/badge/me.lucko.luckperms/luckperms-api.svg)](https://javadoc.io/doc/me.lucko.luckperms/luckperms-api) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/me.lucko.luckperms/luckperms-api/badge.svg)](https://maven-badges.herokuapp.com/maven-central/me.lucko.luckperms/luckperms-api)
+![alt text](https://i.imgur.com/ToguFkQ.png "Banner")
+# LuckPerms
+[![Build Status](https://ci.lucko.me/job/LuckPerms/badge/icon)](https://ci.lucko.me/job/LuckPerms/)
+[![Javadocs](https://javadoc.io/badge/me.lucko.luckperms/luckperms-api.svg)](https://javadoc.io/doc/me.lucko.luckperms/luckperms-api)
+[![Maven Central](https://img.shields.io/maven-metadata/v/https/repo1.maven.org/maven2/me/lucko/luckperms/luckperms-api/maven-metadata.xml.svg?label=maven%20central&colorB=brightgreen)](https://search.maven.org/artifact/me.lucko.luckperms/luckperms-api)
+[![Discord](https://img.shields.io/discord/241667244927483904.svg?logo=discord&label=)](https://discord.gg/luckperms)
 
 LuckPerms is an advanced permissions implementation aiming to be a fast, reliable and flexible alternative to existing permission plugins. The project's main goals are centered around high performance and a wide feature set, filling the gaps of functionality and building upon existing features found in other plugins.
 
 LuckPerms also includes an extensive API for developers, and support for a variety of Minecraft server software & data storage options.
 
-The main features of the project are detailed on this wiki page: [Why LuckPerms?](https://github.com/lucko/LuckPerms/wiki/Why-LuckPerms)
-
-* [Spigot Plugin Release Page](https://www.spigotmc.org/resources/luckperms-an-advanced-permissions-system.28140/ "Spigot Plugin Page")
-* [Sponge Plugin Release Page](https://forums.spongepowered.org/t/luckperms-an-advanced-permissions-system/14274 "Sponge Plugin Page")
+Still not convinced? More information can be found on the wiki, under: [Why LuckPerms?](https://github.com/lucko/LuckPerms/wiki/Why-LuckPerms)
 
 ## Useful Links
-* **Downloads** - <https://ci.lucko.me/job/LuckPerms>
-* **Wiki** - <https://github.com/lucko/LuckPerms/wiki>
+
+The latest **downloads** can be found on the [project's homepage](https://luckperms.github.io/).
+
+More information about the project & how to use the plugin can be found in the [wiki](https://github.com/lucko/LuckPerms/wiki).
 
 ## Building
-LuckPerms uses Maven to handle dependencies.
+LuckPerms uses Gradle to handle dependencies & building.
 
 #### Requirements
-* Java 8 JDK
-* Maven 3.3.x (the older versions will not work.)
+* Java 8 JDK or newer
 * Git
 
-#### Then run
+#### Compiling from source
 ```sh
 git clone https://github.com/lucko/LuckPerms.git
 cd LuckPerms/
-mvn clean package
+./gradlew build
 ```
 
-You can find the output jars in the `target` directories.
+You can find the output jars in the `build/libs` directories.
 
 ## Contributing
 #### Pull Requests
@@ -38,14 +40,11 @@ If you make any changes or improvements to the plugin which you think would be b
 LuckPerms loosely follows the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). Generally, try to copy the style of code found in the class you're editing. 
 
 #### Project Layout
-The project is split up into 5 seperate modules.
+The project is split up into a few separate modules.
 
 * **API** - The public, semantically versioned API used by other plugins wishing to integrate with and retrieve data from LuckPerms. This module (for the most part) does not contain any implementation itself, and is provided by the plugin.
 * **Common** - The common module contains most of the code which implements the respective LuckPerms plugins. This abstract module reduces duplicated code throughout the project.
-* **Bukkit, BungeeCord & Sponge** - Each use the common module to implement plugins on the respective server platforms.
+* **Bukkit, BungeeCord, Sponge, Nukkit & Velocity** - Each use the common module to implement plugins on the respective server platforms.
 
 ## License
 LuckPerms is licensed under the permissive MIT license. Please see [`LICENSE.txt`](https://github.com/lucko/LuckPerms/blob/master/LICENSE.txt) for more info.
-
-## Thanks
-Thanks to ej-technologies for granting LuckPerms an open source licence to their [Java Profiling Software](http://www.ej-technologies.com/products/jprofiler/overview.html "Java Profiler").

api/build.gradle

@@ -0,0 +1,98 @@
+project.version = '4.4'
+
+dependencies {
+    compileOnly 'com.google.guava:guava:19.0'
+    compileOnly 'org.checkerframework:checker-qual:2.5.5'
+}
+
+// Only used occasionally for deployment - not needed for normal builds.
+/*
+if (project.hasProperty('sonatypeUsername') && project.hasProperty('sonatypePassword')) {
+    apply plugin: 'signing'
+
+    javadoc {
+        options.encoding = 'UTF-8'
+        options.charSet = 'UTF-8'
+        options.links(
+                'https://google.github.io/guava/releases/21.0/api/docs/',
+                'https://docs.oracle.com/javase/8/docs/api/'
+        )
+        options.addStringOption('Xdoclint:none', '-quiet')
+    }
+
+    task javadocJar(type: Jar, dependsOn: javadoc) {
+        classifier 'javadoc'
+        from javadoc.destinationDir
+    }
+
+    task sourcesJar(type: Jar) {
+        classifier 'sources'
+        from sourceSets.main.allSource
+    }
+
+    artifacts {
+        archives javadocJar
+        archives sourcesJar
+    }
+
+    signing {
+        useGpgCmd()
+        sign configurations.archives
+    }
+
+    uploadArchives {
+        repositories {
+            mavenDeployer {
+                beforeDeployment { MavenDeployment deployment -> signing.signPom(deployment) }
+
+                repository(url: 'https://oss.sonatype.org/service/local/staging/deploy/maven2/') {
+                    authentication(userName: sonatypeUsername, password: sonatypePassword)
+                }
+
+                snapshotRepository(url: 'https://oss.sonatype.org/content/repositories/snapshots/') {
+                    authentication(userName: sonatypeUsername, password: sonatypePassword)
+                }
+
+                pom {
+                    project {
+                        name 'LuckPerms API'
+                        description 'An advanced permissions plugin for Bukkit/Spigot, BungeeCord, Sponge, Nukkit and Velocity.'
+                        url 'https://luckperms.github.io'
+
+                        licenses {
+                            license {
+                                name 'MIT'
+                                url 'https://opensource.org/licenses/MIT'
+                            }
+                        }
+
+                        developers {
+                            developer {
+                                name 'Luck'
+                                email 'git@lucko.me'
+                                url 'https://github.com/lucko'
+                            }
+                        }
+
+                        scm {
+                            connection 'scm:git:https://github.com/lucko/LuckPerms.git'
+                            developerConnection 'scm:git:git@github.com:lucko/LuckPerms.git'
+                            url 'https://github.com/lucko/LuckPerms'
+                        }
+
+                        ciManagement {
+                            system 'Jenkins'
+                            url 'https://ci.lucko.me/job/LuckPerms'
+                        }
+
+                        issueManagement {
+                            system 'GitHub'
+                            url 'https://github.com/lucko/LuckPerms/issues'
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+*/

api/pom.xml

@@ -1,96 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xmlns="http://maven.apache.org/POM/4.0.0"
-         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-    <parent>
-        <artifactId>luckperms</artifactId>
-        <groupId>me.lucko.luckperms</groupId>
-        <version>4.1-SNAPSHOT</version>
-    </parent>
-    <modelVersion>4.0.0</modelVersion>
-
-    <artifactId>luckperms-api</artifactId>
-
-    <build>
-        <finalName>LuckPerms-API-${release.version}</finalName>
-        <resources>
-            <resource>
-                <directory>../</directory>
-                <filtering>false</filtering>
-                <includes>
-                    <include>LICENSE.txt</include>
-                </includes>
-            </resource>
-        </resources>
-        <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-compiler-plugin</artifactId>
-                <version>${compiler.version}</version>
-                <configuration>
-                    <source>1.8</source>
-                    <target>1.8</target>
-                </configuration>
-            </plugin>
-        </plugins>
-    </build>
-
-    <profiles>
-        <profile>
-            <id>deployment</id>
-            <build>
-                <plugins>
-                    <plugin>
-                        <groupId>org.apache.maven.plugins</groupId>
-                        <artifactId>maven-source-plugin</artifactId>
-                        <version>3.0.1</version>
-                        <executions>
-                            <execution>
-                                <id>attach-sources</id>
-                                <goals>
-                                    <goal>jar</goal>
-                                </goals>
-                            </execution>
-                        </executions>
-                    </plugin>
-                    <plugin>
-                        <groupId>org.apache.maven.plugins</groupId>
-                        <artifactId>maven-javadoc-plugin</artifactId>
-                        <version>3.0.0</version>
-                        <executions>
-                            <execution>
-                                <id>attach-javadocs</id>
-                                <goals>
-                                    <goal>jar</goal>
-                                </goals>
-                            </execution>
-                        </executions>
-                        <configuration>
-                            <links>
-                                <link>https://google.github.io/guava/releases/21.0/api/docs/</link>
-                            </links>
-                        </configuration>
-                    </plugin>
-                </plugins>
-            </build>
-        </profile>
-    </profiles>
-
-    <dependencies>
-        <!-- guava -->
-        <dependency>
-            <groupId>com.google.guava</groupId>
-            <artifactId>guava</artifactId>
-            <version>19.0</version>
-            <scope>provided</scope>
-        </dependency>
-        <!-- jsr305 -->
-        <dependency>
-            <groupId>com.google.code.findbugs</groupId>
-            <artifactId>jsr305</artifactId>
-            <version>3.0.2</version>
-            <scope>provided</scope>
-        </dependency>
-    </dependencies>
-
-</project>

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

@@ -27,9 +27,9 @@ package me.lucko.luckperms;
 
 import me.lucko.luckperms.api.LuckPermsApi;
 
-import java.util.Optional;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
-import javax.annotation.Nonnull;
+import java.util.Optional;
 
 /**
  * Provides static access to the {@link LuckPermsApi}.
@@ -49,8 +49,7 @@ public final class LuckPerms {
      * @return an api instance
      * @throws IllegalStateException if the api is not loaded
      */
-    @Nonnull
-    public static LuckPermsApi getApi() {
+    public static @NonNull LuckPermsApi getApi() {
         if (instance == null) {
             throw new IllegalStateException("API is not loaded.");
         }
@@ -66,8 +65,7 @@ public final class LuckPerms {
      *
      * @return an optional api instance
      */
-    @Nonnull
-    public static Optional<LuckPermsApi> getApiSafe() {
+    public static @NonNull Optional<LuckPermsApi> getApiSafe() {
         return Optional.ofNullable(instance);
     }
 

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

@@ -25,9 +25,9 @@
 
 package me.lucko.luckperms.api;
 
-import java.util.concurrent.CompletableFuture;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
-import javax.annotation.Nonnull;
+import java.util.concurrent.CompletableFuture;
 
 /**
  * Represents the object responsible for handling action logging.
@@ -41,19 +41,15 @@ public interface ActionLogger {
      *
      * @return a new builder
      */
-    @Nonnull
-    LogEntry.Builder newEntryBuilder();
+    LogEntry.@NonNull Builder newEntryBuilder();
 
     /**
      * Gets a {@link Log} instance from the plugin storage.
      *
-     * <p>Returns the same result as {@link Storage#getLog()}.</p>
-     *
      * @return a log instance
      * @see Storage#getLog()
      */
-    @Nonnull
-    CompletableFuture<Log> getLog();
+    @NonNull CompletableFuture<Log> getLog();
 
     /**
      * Submits a log entry to the plugin to be handled.
@@ -71,8 +67,7 @@ public interface ActionLogger {
      * @param entry the entry to submit
      * @return a future which will complete when the action is done
      */
-    @Nonnull
-    CompletableFuture<Void> submit(@Nonnull LogEntry entry);
+    @NonNull CompletableFuture<Void> submit(@NonNull LogEntry entry);
 
     /**
      * Submits a log entry to the plugins storage handler.
@@ -82,8 +77,7 @@ public interface ActionLogger {
      * @param entry the entry to submit
      * @return a future which will complete when the action is done
      */
-    @Nonnull
-    CompletableFuture<Void> submitToStorage(@Nonnull LogEntry entry);
+    @NonNull CompletableFuture<Void> submitToStorage(@NonNull LogEntry entry);
 
     /**
      * Submits a log entry to the plugins log broadcasting handler.
@@ -94,7 +88,6 @@ public interface ActionLogger {
      * @param entry the entry to submit
      * @return a future which will complete when the action is done
      */
-    @Nonnull
-    CompletableFuture<Void> broadcastAction(@Nonnull LogEntry entry);
+    @NonNull CompletableFuture<Void> broadcastAction(@NonNull LogEntry entry);
 
 }

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

@@ -25,12 +25,12 @@
 
 package me.lucko.luckperms.api;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+
 import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
 
-import javax.annotation.Nonnull;
-
 /**
  * Represents a type of chat meta
  *
@@ -43,13 +43,12 @@ public enum ChatMetaType {
      */
     PREFIX("prefix") {
         @Override
-        public boolean matches(@Nonnull Node node) {
+        public boolean matches(@NonNull Node node) {
             return Objects.requireNonNull(node, "node").isPrefix();
         }
 
-        @Nonnull
         @Override
-        public Map.Entry<Integer, String> getEntry(@Nonnull Node node) {
+        public Map.@NonNull Entry<Integer, String> getEntry(@NonNull Node node) {
             return Objects.requireNonNull(node, "node").getPrefix();
         }
     },
@@ -59,13 +58,12 @@ public enum ChatMetaType {
      */
     SUFFIX("suffix") {
         @Override
-        public boolean matches(@Nonnull Node node) {
+        public boolean matches(@NonNull Node node) {
             return Objects.requireNonNull(node, "node").isSuffix();
         }
 
-        @Nonnull
         @Override
-        public Map.Entry<Integer, String> getEntry(@Nonnull Node node) {
+        public Map.@NonNull Entry<Integer, String> getEntry(@NonNull Node node) {
             return Objects.requireNonNull(node, "node").getSuffix();
         }
     };
@@ -82,7 +80,7 @@ public enum ChatMetaType {
      * @param node the node to test
      * @return true if the node has the same type
      */
-    public abstract boolean matches(@Nonnull Node node);
+    public abstract boolean matches(@NonNull Node node);
 
     /**
      * Returns if the passed node should be ignored when searching for meta of this type
@@ -90,7 +88,7 @@ public enum ChatMetaType {
      * @param node the node to test
      * @return true if the node does not share the same type
      */
-    public boolean shouldIgnore(@Nonnull Node node) {
+    public boolean shouldIgnore(@NonNull Node node) {
         return !matches(node);
     }
 
@@ -101,8 +99,7 @@ public enum ChatMetaType {
      * @return the entry
      * @throws IllegalStateException if the node does not share the same type
      */
-    @Nonnull
-    public abstract Map.Entry<Integer, String> getEntry(@Nonnull Node node);
+    public abstract Map.@NonNull Entry<Integer, String> getEntry(@NonNull Node node);
 
     @Override
     public String toString() {
@@ -116,8 +113,7 @@ public enum ChatMetaType {
      * @return the parsed chat meta type
      * @since 3.4
      */
-    @Nonnull
-    public static Optional<ChatMetaType> ofNode(@Nonnull Node node) {
+    public static @NonNull Optional<ChatMetaType> ofNode(@NonNull Node node) {
         if (node.isPrefix()) {
             return Optional.of(PREFIX);
         } else if (node.isSuffix()) {

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

@@ -28,19 +28,19 @@ package me.lucko.luckperms.api;
 import me.lucko.luckperms.api.context.ContextSet;
 import me.lucko.luckperms.api.context.ImmutableContextSet;
 
-import java.util.Objects;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
-import javax.annotation.Nonnull;
-import javax.annotation.concurrent.Immutable;
+import java.util.Objects;
+import java.util.Set;
 
 /**
- * Encapsulates the options and settings for a permission or meta lookup.
+ * Encapsulates the {@link ContextSet contexts} and {@link LookupSetting settings} for
+ * a permission or meta lookup.
  *
  * <p>This class is immutable.</p>
  *
  * @since 2.11
  */
-@Immutable
 public class Contexts {
 
     /**
@@ -53,168 +53,283 @@ public class Contexts {
      */
     public static final String WORLD_KEY = "world";
 
+    /**
+     * The default {@link LookupSetting}s as a flag.
+     */
+    private static final byte DEFAULT_SETTINGS_FLAG = LookupSetting.createFlag(
+            LookupSetting.INCLUDE_NODES_SET_WITHOUT_SERVER,
+            LookupSetting.INCLUDE_NODES_SET_WITHOUT_WORLD,
+            LookupSetting.RESOLVE_INHERITANCE,
+            LookupSetting.APPLY_PARENTS_SET_WITHOUT_SERVER,
+            LookupSetting.APPLY_PARENTS_SET_WITHOUT_WORLD
+    );
+
     /**
      * A 'global' or default contexts instance.
      *
-     * Simply passes an empty context set, with all accumulation settings set to true.
+     * <p>Formed of an empty {@link ContextSet} and all inclusion and
+     * inheritance {@link LookupSetting}s applied.</p>
      */
-    private static final Contexts GLOBAL = new Contexts(ContextSet.empty(), true, true, true, true, true, false);
+    private static final Contexts GLOBAL = new Contexts(ImmutableContextSet.empty(), DEFAULT_SETTINGS_FLAG);
 
     /**
      * Gets the {@link FullySatisfiedContexts} instance.
      *
      * @return a context that will satisfy all contextual requirements.
      */
-    @Nonnull
-    public static Contexts allowAll() {
+    public static @NonNull Contexts allowAll() {
         return FullySatisfiedContexts.getInstance();
     }
 
     /**
-     * A contexts instance with no defined context.
+     * Returns a 'global' or default contexts instance.
+     *
+     * <p>Formed of an empty {@link ContextSet} and all inclusion and
+     * inheritance {@link LookupSetting}s applied.</p>
      *
      * @return the global contexts
      * @since 3.3
      */
-    @Nonnull
-    public static Contexts global() {
+    public static @NonNull Contexts global() {
         return GLOBAL;
     }
 
-    @Nonnull
-    public static Contexts of(@Nonnull ContextSet context, boolean includeGlobal, boolean includeGlobalWorld, boolean applyGroups, boolean applyGlobalGroups, boolean applyGlobalWorldGroups, boolean op) {
-        return new Contexts(context, includeGlobal, includeGlobalWorld, applyGroups, applyGlobalGroups, applyGlobalWorldGroups, op);
+    /**
+     * Creates a new {@link Contexts} instance.
+     *
+     * @param contextSet the context set
+     * @param includeNodesSetWithoutServer the value of {@link LookupSetting#INCLUDE_NODES_SET_WITHOUT_SERVER}
+     * @param includeNodesSetWithoutWorld the value of {@link LookupSetting#INCLUDE_NODES_SET_WITHOUT_WORLD}
+     * @param resolveInheritance the value of {@link LookupSetting#RESOLVE_INHERITANCE}
+     * @param applyParentsWithoutServer the value of {@link LookupSetting#APPLY_PARENTS_SET_WITHOUT_SERVER}
+     * @param applyParentsWithoutWorld the value of {@link LookupSetting#APPLY_PARENTS_SET_WITHOUT_WORLD}
+     * @param isOp the value of {@link LookupSetting#IS_OP}
+     * @return a new instance
+     */
+    public static @NonNull Contexts of(@NonNull ContextSet contextSet, boolean includeNodesSetWithoutServer, boolean includeNodesSetWithoutWorld, boolean resolveInheritance, boolean applyParentsWithoutServer, boolean applyParentsWithoutWorld, boolean isOp) {
+        Objects.requireNonNull(contextSet, "contextSet");
+        byte settingsFlag = LookupSetting.createFlag(
+                includeNodesSetWithoutServer,
+                includeNodesSetWithoutWorld,
+                resolveInheritance,
+                applyParentsWithoutServer,
+                applyParentsWithoutWorld,
+                isOp
+        );
+        if (contextSet.isEmpty() && DEFAULT_SETTINGS_FLAG == settingsFlag) {
+            return GLOBAL;
+        }
+        return new Contexts(contextSet.makeImmutable(), settingsFlag);
+    }
+
+    /**
+     * Creates a new {@link Contexts} instance.
+     *
+     * @param contextSet the context set
+     * @param settings the settings
+     * @return a new instance
+     */
+    public static Contexts of(@NonNull ContextSet contextSet, @NonNull Set<LookupSetting> settings) {
+        Objects.requireNonNull(contextSet, "contextSet");
+        Objects.requireNonNull(settings, "settings");
+
+        byte settingsFlag = LookupSetting.createFlag(settings);
+        if (contextSet.isEmpty() && DEFAULT_SETTINGS_FLAG == settingsFlag) {
+            return GLOBAL;
+        }
+
+        return new Contexts(contextSet.makeImmutable(), settingsFlag);
     }
 
     /**
      * The contexts that apply for this lookup
      */
-    private final ImmutableContextSet context;
+    private final ImmutableContextSet contextSet;
 
     /**
-     * If the target subject is OP. This is used to parse defaults on Bukkit,
-     * and is ignored on all other platforms.
-     *
-     * @since 2.12
+     * The settings for this lookup
      */
-    private final boolean op;
-
-    /**
-     * If global or non server specific nodes should be applied
-     */
-    private final boolean includeGlobal;
-
-    /**
-     * If global or non world specific nodes should be applied
-     */
-    private final boolean includeGlobalWorld;
-
-    /**
-     * If parent groups should be applied
-     */
-    private final boolean applyGroups;
-
-    /**
-     * If global or non server specific group memberships should be applied
-     */
-    private final boolean applyGlobalGroups;
-
-    /**
-     * If global or non world specific group memberships should be applied
-     */
-    private final boolean applyGlobalWorldGroups;
+    private final byte settingsFlag;
 
     // cache hashcode - this class is immutable, and is used as an index in the permission cache.
     private final int hashCode;
 
-    public Contexts(@Nonnull ContextSet context, boolean includeGlobal, boolean includeGlobalWorld, boolean applyGroups, boolean applyGlobalGroups, boolean applyGlobalWorldGroups, boolean op) {
-        this.context = Objects.requireNonNull(context, "context").makeImmutable();
-        this.includeGlobal = includeGlobal;
-        this.includeGlobalWorld = includeGlobalWorld;
-        this.applyGroups = applyGroups;
-        this.applyGlobalGroups = applyGlobalGroups;
-        this.applyGlobalWorldGroups = applyGlobalWorldGroups;
-        this.op = op;
+    /**
+     * Creates a new {@link Contexts} instance.
+     *
+     * @param contextSet the context set
+     * @param includeNodesSetWithoutServer the value of {@link LookupSetting#INCLUDE_NODES_SET_WITHOUT_SERVER}
+     * @param includeNodesSetWithoutWorld the value of {@link LookupSetting#INCLUDE_NODES_SET_WITHOUT_WORLD}
+     * @param resolveInheritance the value of {@link LookupSetting#RESOLVE_INHERITANCE}
+     * @param applyParentsWithoutServer the value of {@link LookupSetting#APPLY_PARENTS_SET_WITHOUT_SERVER}
+     * @param applyParentsWithoutWorld the value of {@link LookupSetting#APPLY_PARENTS_SET_WITHOUT_WORLD}
+     * @param isOp the value of {@link LookupSetting#IS_OP}
+     * @deprecated in favour of {@link #of(ContextSet, boolean, boolean, boolean, boolean, boolean, boolean)}
+     */
+    @Deprecated
+    public Contexts(@NonNull ContextSet contextSet, boolean includeNodesSetWithoutServer, boolean includeNodesSetWithoutWorld, boolean resolveInheritance, boolean applyParentsWithoutServer, boolean applyParentsWithoutWorld, boolean isOp) {
+        this.contextSet = Objects.requireNonNull(contextSet, "contextSet").makeImmutable();
+        this.settingsFlag = LookupSetting.createFlag(
+                includeNodesSetWithoutServer,
+                includeNodesSetWithoutWorld,
+                resolveInheritance,
+                applyParentsWithoutServer,
+                applyParentsWithoutWorld,
+                isOp
+        );
+        this.hashCode = calculateHashCode();
+    }
+
+    protected Contexts(@NonNull ImmutableContextSet contextSet, byte settingsFlag) {
+        this.contextSet = contextSet;
+        this.settingsFlag = settingsFlag;
         this.hashCode = calculateHashCode();
     }
 
     /**
-     * Gets the contexts that apply for this lookup
+     * Gets the {@link ContextSet set of context pairs} for this {@link Contexts} instance.
      *
-     * @return an immutable set of context key value pairs
+     * @return an immutable context from this instance
      * @since 2.13
      */
-    @Nonnull
-    public ContextSet getContexts() {
-        return this.context;
+    public @NonNull ContextSet getContexts() {
+        return this.contextSet;
     }
 
     /**
-     * Gets if the target subject is OP. This is used to parse defaults on Bukkit,
-     * and is ignored on all other platforms.
+     * Gets the set of {@link LookupSetting}s for this {@link Contexts} instance.
      *
-     * @return true if op defaults should be included
+     * @return the settings
+     * @since 4.2
      */
+    public @NonNull Set<LookupSetting> getSettings() {
+        return LookupSetting.createSetFromFlag(this.settingsFlag);
+    }
+
+    /**
+     * Creates a copy of this {@link Contexts} instance, but with the
+     * {@link ContextSet set of context pairs} replaced by the given set.
+     *
+     * @param contextSet the context set
+     * @return a new contexts instance representing the new settings
+     * @since 4.4
+     */
+    public @NonNull Contexts setContexts(@NonNull ContextSet contextSet) {
+        ImmutableContextSet cs = Objects.requireNonNull(contextSet, "contextSet").makeImmutable();
+        if (this.contextSet.equals(cs)) {
+            return this;
+        }
+        return new Contexts(cs, this.settingsFlag);
+    }
+
+    /**
+     * Creates a copy of this {@link Contexts} instance, but with the
+     * {@link LookupSetting}s replaced by the given settings.
+     *
+     * @param settings the lookup settings
+     * @return a new contexts instance representing the new settings
+     * @since 4.4
+     */
+    public @NonNull Contexts setSettings(@NonNull Set<LookupSetting> settings) {
+        Objects.requireNonNull(settings, "settings");
+
+        byte settingsFlag = LookupSetting.createFlag(settings);
+        if (this.settingsFlag == settingsFlag) {
+            return this;
+        }
+        if (DEFAULT_SETTINGS_FLAG == settingsFlag && this.contextSet.isEmpty()) {
+            return GLOBAL;
+        }
+
+        return new Contexts(this.contextSet, settingsFlag);
+    }
+
+    /**
+     * Gets if the given {@link LookupSetting} is set.
+     *
+     * @param setting the setting
+     * @return the value
+     * @since 4.2
+     */
+    public boolean hasSetting(@NonNull LookupSetting setting) {
+        return LookupSetting.isSet(this.settingsFlag, setting);
+    }
+
+    /**
+     * Gets the value of {@link LookupSetting#IS_OP}.
+     *
+     * @return the value
+     * @see LookupSetting#IS_OP
+     * @deprecated in favour of {@link #hasSetting(LookupSetting)}
+     */
+    @Deprecated
     public boolean isOp() {
-        return this.op;
+        return hasSetting(LookupSetting.IS_OP);
     }
 
     /**
-     * Gets if global or non server specific nodes should be applied
+     * Gets the value of {@link LookupSetting#INCLUDE_NODES_SET_WITHOUT_SERVER}.
      *
-     * @return true if global or non server specific nodes should be applied
+     * @return the value
+     * @see LookupSetting#INCLUDE_NODES_SET_WITHOUT_SERVER
+     * @deprecated in favour of {@link #hasSetting(LookupSetting)}
      */
+    @Deprecated
     public boolean isIncludeGlobal() {
-        return this.includeGlobal;
+        return hasSetting(LookupSetting.INCLUDE_NODES_SET_WITHOUT_SERVER);
     }
 
     /**
-     * Gets if global or non world specific nodes should be applied
+     * Gets the value of {@link LookupSetting#INCLUDE_NODES_SET_WITHOUT_WORLD}.
      *
-     * @return true if global or non world specific nodes should be applied
+     * @return the value
+     * @see LookupSetting#INCLUDE_NODES_SET_WITHOUT_WORLD
+     * @deprecated in favour of {@link #hasSetting(LookupSetting)}
      */
+    @Deprecated
     public boolean isIncludeGlobalWorld() {
-        return this.includeGlobalWorld;
+        return hasSetting(LookupSetting.INCLUDE_NODES_SET_WITHOUT_WORLD);
     }
 
     /**
-     * Gets if parent groups should be applied
+     * Gets the value of {@link LookupSetting#RESOLVE_INHERITANCE}.
      *
-     * @return true if parent groups should be applied
+     * @return the value
+     * @see LookupSetting#RESOLVE_INHERITANCE
+     * @deprecated in favour of {@link #hasSetting(LookupSetting)}
      */
+    @Deprecated
     public boolean isApplyGroups() {
-        return this.applyGroups;
+        return hasSetting(LookupSetting.RESOLVE_INHERITANCE);
     }
 
     /**
-     * Gets if global or non server specific group memberships should be applied
+     * Gets the value of {@link LookupSetting#APPLY_PARENTS_SET_WITHOUT_SERVER}.
      *
-     * @return true if global or non server specific group memberships should be applied
+     * @return the value
+     * @see LookupSetting#APPLY_PARENTS_SET_WITHOUT_SERVER
+     * @deprecated in favour of {@link #hasSetting(LookupSetting)}
      */
+    @Deprecated
     public boolean isApplyGlobalGroups() {
-        return this.applyGlobalGroups;
+        return hasSetting(LookupSetting.APPLY_PARENTS_SET_WITHOUT_SERVER);
     }
 
     /**
-     * Gets if global or non world specific group memberships should be applied
+     * Gets the value of {@link LookupSetting#APPLY_PARENTS_SET_WITHOUT_WORLD}.
      *
-     * @return true if global or non world specific group memberships should be applied
+     * @return the value
+     * @see LookupSetting#APPLY_PARENTS_SET_WITHOUT_WORLD
+     * @deprecated in favour of {@link #hasSetting(LookupSetting)}
      */
+    @Deprecated
     public boolean isApplyGlobalWorldGroups() {
-        return this.applyGlobalWorldGroups;
+        return hasSetting(LookupSetting.APPLY_PARENTS_SET_WITHOUT_WORLD);
     }
 
-    @Nonnull
     @Override
-    public String toString() {
-        return "Contexts(" +
-                "context=" + this.context + ", " +
-                "op=" + this.op + ", " +
-                "includeGlobal=" + this.includeGlobal + ", " +
-                "includeGlobalWorld=" + this.includeGlobalWorld + ", " +
-                "applyGroups=" + this.applyGroups + ", " +
-                "applyGlobalGroups=" + this.applyGlobalGroups + ", " +
-                "applyGlobalWorldGroups=" + this.applyGlobalWorldGroups + ")";
+    public @NonNull String toString() {
+        return "Contexts(contextSet=" + this.contextSet + ", settings=" + LookupSetting.createSetFromFlag(this.settingsFlag) + ")";
     }
 
     @Override
@@ -223,26 +338,14 @@ public class Contexts {
         if (o == allowAll()) return false;
         if (!(o instanceof Contexts)) return false;
         final Contexts that = (Contexts) o;
-
-        return this.context.equals(that.context) &&
-                this.op == that.op &&
-                this.includeGlobal == that.includeGlobal &&
-                this.includeGlobalWorld == that.includeGlobalWorld &&
-                this.applyGroups == that.applyGroups &&
-                this.applyGlobalGroups == that.applyGlobalGroups &&
-                this.applyGlobalWorldGroups == that.applyGlobalWorldGroups;
+        return this.contextSet.equals(that.contextSet) && this.settingsFlag == that.settingsFlag;
     }
 
     private int calculateHashCode() {
         final int PRIME = 59;
         int result = 1;
-        result = result * PRIME + this.context.hashCode();
-        result = result * PRIME + (this.op ? 79 : 97);
-        result = result * PRIME + (this.includeGlobal ? 79 : 97);
-        result = result * PRIME + (this.includeGlobalWorld ? 79 : 97);
-        result = result * PRIME + (this.applyGroups ? 79 : 97);
-        result = result * PRIME + (this.applyGlobalGroups ? 79 : 97);
-        result = result * PRIME + (this.applyGlobalWorldGroups ? 79 : 97);
+        result = result * PRIME + this.contextSet.hashCode();
+        result = result * PRIME + this.settingsFlag;
         return result;
     }
 
@@ -250,4 +353,5 @@ public class Contexts {
     public int hashCode() {
         return this.hashCode;
     }
+
 }

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

@@ -26,9 +26,11 @@
 package me.lucko.luckperms.api;
 
 /**
- * Represents the result of a mutation call.
+ * Represents the result of a data mutation call on a LuckPerms object.
+ *
+ * <p>Usually as the result to a call on a {@link PermissionHolder} or {@link Track}.</p>
  */
-public enum DataMutateResult {
+public enum DataMutateResult implements MutateResult {
 
     /**
      * Indicates the mutation was a success
@@ -50,39 +52,14 @@ public enum DataMutateResult {
      */
     FAIL(false);
 
-    private final boolean value;
+    private final boolean success;
 
-    DataMutateResult(boolean value) {
-        this.value = value;
+    DataMutateResult(boolean success) {
+        this.success = success;
     }
 
-    /**
-     * Gets a boolean representation of the result.
-     *
-     * @return a boolean representation
-     */
-    public boolean asBoolean() {
-        return this.value;
-    }
-
-    /**
-     * Gets if the result indicates a success
-     *
-     * @return if the result indicates a success
-     * @since 3.4
-     */
+    @Override
     public boolean wasSuccess() {
-        return this.value;
+        return this.success;
     }
-
-    /**
-     * Gets if the result indicates a failure
-     *
-     * @return if the result indicates a failure
-     * @since 3.4
-     */
-    public boolean wasFailure() {
-        return !this.value;
-    }
-
 }

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

@@ -0,0 +1,127 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package me.lucko.luckperms.api;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Optional;
+
+/**
+ * Encapsulates the result of {@link User}s demotion along a {@link Track}.
+ *
+ * @since 4.2
+ */
+public interface DemotionResult extends MutateResult {
+
+    /**
+     * Gets the status of the result.
+     *
+     * @return the status
+     */
+    @NonNull Status getStatus();
+
+    @Override
+    default boolean wasSuccess() {
+        return getStatus().wasSuccess();
+    }
+
+    /**
+     * Gets the name of the group the user was demoted from, if applicable.
+     *
+     * <p>Will only be present for results with a {@link #getStatus() status} of
+     * {@link Status#SUCCESS} or {@link Status#REMOVED_FROM_FIRST_GROUP}.</p>
+     *
+     * <p>The value will also be set for results with the {@link Status#MALFORMED_TRACK} status,
+     * with this value marking the group which no longer exists.</p>
+     *
+     * @return the group the user was demoted from.
+     */
+    @NonNull Optional<String> getGroupFrom();
+
+    /**
+     * Gets the name of the group the user was demoted from, if applicable.
+     *
+     * <p>Will only be present for results with a {@link #getStatus() status} of
+     * {@link Status#SUCCESS}.</p>
+     *
+     * @return the group the user was demoted to.
+     */
+    @NonNull Optional<String> getGroupTo();
+
+    /**
+     * The result status
+     */
+    enum Status implements MutateResult {
+
+        /**
+         * Indicates that the user was demoted normally.
+         */
+        SUCCESS(true),
+
+        /**
+         * Indicates that the user was removed from the first group in the track.
+         *
+         * <p>This usually occurs when the user is currently on the first group, and was demoted
+         * "over the start" of the track.</p>
+         */
+        REMOVED_FROM_FIRST_GROUP(true),
+
+        /**
+         * Indicates that the previous group in the track no longer exists.
+         */
+        MALFORMED_TRACK(false),
+
+        /**
+         * Indicates that the user isn't a member of any of the groups on this track.
+         */
+        NOT_ON_TRACK(false),
+
+        /**
+         * Indicates that the implementation was unable to determine the users current position on
+         * this track.
+         *
+         * <p>This usually occurs when the user is on more than one group on the track.</p>
+         */
+        AMBIGUOUS_CALL(false),
+
+        /**
+         * An undefined failure occurred.
+         */
+        UNDEFINED_FAILURE(false);
+
+        private final boolean success;
+
+        Status(boolean success) {
+            this.success = success;
+        }
+
+        @Override
+        public boolean wasSuccess() {
+            return this.success;
+        }
+    }
+
+}

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

@@ -25,10 +25,10 @@
 
 package me.lucko.luckperms.api;
 
-import java.util.UUID;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
 
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
+import java.util.UUID;
 
 /**
  * Represents an entity on the server.
@@ -49,24 +49,21 @@ public interface Entity {
      *
      * @return the uuid of the object, if available
      */
-    @Nullable
-    UUID getUniqueId();
+    @Nullable UUID getUniqueId();
 
     /**
      * Gets the name of the object
      *
      * @return the object name
      */
-    @Nonnull
-    String getName();
+    @NonNull String getName();
 
     /**
      * Gets the entities type.
      *
      * @return the type
      */
-    @Nonnull
-    Type getType();
+    @NonNull Type getType();
 
     /**
      * The different types of {@link Entity}

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

@@ -27,9 +27,9 @@ package me.lucko.luckperms.api;
 
 import me.lucko.luckperms.api.caching.CachedData;
 import me.lucko.luckperms.api.caching.MetaContexts;
-import me.lucko.luckperms.api.context.ContextSet;
+import me.lucko.luckperms.api.context.ImmutableContextSet;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * A special instance of {@link Contexts}, which when passed to:
@@ -52,18 +52,16 @@ public final class FullySatisfiedContexts extends Contexts {
     // singleton
     private static final FullySatisfiedContexts INSTANCE = new FullySatisfiedContexts();
 
-    @Nonnull
-    public static Contexts getInstance() {
+    public static @NonNull Contexts getInstance() {
         return INSTANCE;
     }
 
     private FullySatisfiedContexts() {
-        super(ContextSet.empty(), true, true, true, true, true, false);
+        super(ImmutableContextSet.empty(), LookupSetting.createFlag(Contexts.global().getSettings()));
     }
 
-    @Nonnull
     @Override
-    public String toString() {
+    public @NonNull String toString() {
         return "FullySatisfiedContexts()";
     }
 

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

@@ -26,11 +26,13 @@
 package me.lucko.luckperms.api;
 
 import me.lucko.luckperms.api.caching.GroupData;
+import me.lucko.luckperms.api.context.ContextSet;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
 
 import java.util.OptionalInt;
 
-import javax.annotation.Nonnull;
-
 /**
  * An inheritable holder of permission data.
  */
@@ -41,8 +43,32 @@ public interface Group extends PermissionHolder {
      *
      * @return the name of the group
      */
-    @Nonnull
-    String getName();
+    @NonNull String getName();
+
+    /**
+     * Gets the groups "display name", if it has one that differs from it's actual name.
+     *
+     * <p>The lookup is made using the current servers active context.</p>
+     *
+     * <p>Will return <code>null</code> if the groups display name is equal to it's
+     * {@link #getName() actual name}.</p>
+     *
+     * @return the display name
+     * @since 4.3
+     */
+    @Nullable String getDisplayName();
+
+    /**
+     * Gets the groups "display name", if it has one that differs from it's actual name.
+     *
+     * <p>Will return <code>null</code> if the groups display name is equal to it's
+     * {@link #getName() actual name}.</p>
+     *
+     * @param contextSet the contexts to lookup in
+     * @return the display name
+     * @since 4.3
+     */
+    @Nullable String getDisplayName(@NonNull ContextSet contextSet);
 
     /**
      * Gets the weight of this group, if present.
@@ -50,8 +76,7 @@ public interface Group extends PermissionHolder {
      * @return the group weight
      * @since 2.17
      */
-    @Nonnull
-    OptionalInt getWeight();
+    @NonNull OptionalInt getWeight();
 
     /**
      * Gets the groups's {@link GroupData} cache.
@@ -59,8 +84,7 @@ public interface Group extends PermissionHolder {
      * @return the groups cached data.
      * @since 4.0
      */
-    @Nonnull
     @Override
-    GroupData getCachedData();
+    @NonNull GroupData getCachedData();
 
 }

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

@@ -27,19 +27,17 @@ package me.lucko.luckperms.api;
 
 import me.lucko.luckperms.api.context.ContextSet;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+
 import java.util.Optional;
 import java.util.OptionalLong;
 
-import javax.annotation.Nonnull;
-import javax.annotation.concurrent.Immutable;
-
 /**
  * A relationship between a {@link PermissionHolder} and a permission.
  *
  * @param <T> the identifier type of the holder
  * @since 2.17
  */
-@Immutable
 public interface HeldPermission<T> {
 
     /**
@@ -47,16 +45,14 @@ public interface HeldPermission<T> {
      *
      * @return the holder
      */
-    @Nonnull
-    T getHolder();
+    @NonNull T getHolder();
 
     /**
      * Gets the permission being held
      *
      * @return the permission
      */
-    @Nonnull
-    String getPermission();
+    @NonNull String getPermission();
 
     /**
      * Gets the value of the permission
@@ -70,37 +66,34 @@ public interface HeldPermission<T> {
      *
      * @return the server
      */
-    @Nonnull
-    Optional<String> getServer();
+    @NonNull Optional<String> getServer();
 
     /**
      * Gets the world where the permission is held
      *
      * @return the world
      */
-    @Nonnull
-    Optional<String> getWorld();
+    @NonNull Optional<String> getWorld();
 
     /**
      * Gets the time in unix time when the permission will expire
      *
      * @return the expiry time
      */
-    OptionalLong getExpiry();
+    @NonNull OptionalLong getExpiry();
 
     /**
      * Gets the extra context for the permission.
      *
      * @return the extra context
      */
-    ContextSet getContexts();
+    @NonNull ContextSet getContexts();
 
     /**
      * Converts this permission into a Node
      *
      * @return a Node copy of this permission
      */
-    @Nonnull
-    Node asNode();
+    @NonNull Node asNode();
 
 }

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

@@ -25,9 +25,9 @@
 
 package me.lucko.luckperms.api;
 
-import java.util.Map;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
-import javax.annotation.Nonnull;
+import java.util.Map;
 
 /**
  * Wrapper around parts of the LuckPerms configuration file
@@ -39,8 +39,7 @@ public interface LPConfiguration {
      *
      * @return the name of this server
      */
-    @Nonnull
-    String getServer();
+    @NonNull String getServer();
 
     /**
      * Gets if the users on this server will have their global permissions applied
@@ -78,8 +77,7 @@ public interface LPConfiguration {
      *
      * @return the storage method string from the configuration
      */
-    @Nonnull
-    String getStorageMethod();
+    @NonNull String getStorageMethod();
 
     /**
      * Gets true if split storage is enabled
@@ -96,11 +94,9 @@ public interface LPConfiguration {
      * method. For example: key = user, value = json
      * @since 2.7
      */
-    @Nonnull
-    Map<String, String> getSplitStorageOptions();
+    @NonNull Map<String, String> getSplitStorageOptions();
 
-    @Nonnull
-    Unsafe unsafe();
+    @NonNull Unsafe unsafe();
 
     interface Unsafe {
 
@@ -115,8 +111,7 @@ public interface LPConfiguration {
          * @return the corresponding object, if one is present
          * @throws IllegalArgumentException if the key isn't known
          */
-        @Nonnull
-        Object getObject(String key);
+        @NonNull Object getObject(String key);
     }
 
 }

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

@@ -25,32 +25,36 @@
 
 package me.lucko.luckperms.api;
 
-import javax.annotation.Nonnull;
-import javax.annotation.concurrent.Immutable;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
- * A node with a traceable origin
+ * An extension of {@link Node}, providing information about
+ * where the node originated from.
  *
  * @since 2.11
  */
-@Immutable
 public interface LocalizedNode extends Node {
 
     /**
-     * Gets the delegate node
+     * Gets the delegate node.
+     *
+     * <p>Result is never another {@link LocalizedNode} instance.</p>
      *
      * @return the node this instance is representing
      */
-    @Nonnull
-    Node getNode();
+    @NonNull Node getNode();
 
     /**
-     * Gets the location where the {@link Node} is inherited from
+     * Gets the location where the {@link Node} is inherited from.
      *
-     * @return where the node was inherited from. Will not return null.
-     * @see PermissionHolder#getObjectName()
+     * <p>The resultant string is the {@link PermissionHolder#getObjectName() object name} of the
+     * permission holder the node was inherited from.</p>
+     *
+     * <p>If the node was not inherited, the {@link PermissionHolder#getObjectName() object name}
+     * of the permission holder itself (the one that defined the node) will be returned.</p>
+     *
+     * @return where the node was inherited from.
      */
-    @Nonnull
-    String getLocation();
+    @NonNull String getLocation();
 
 }

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

@@ -25,13 +25,11 @@
 
 package me.lucko.luckperms.api;
 
-import java.util.SortedMap;
+import org.checkerframework.checker.nullness.qual.NonNull;
+
 import java.util.SortedSet;
 import java.util.UUID;
 
-import javax.annotation.Nonnull;
-import javax.annotation.concurrent.Immutable;
-
 /**
  * Represents the internal LuckPerms log.
  *
@@ -42,73 +40,22 @@ import javax.annotation.concurrent.Immutable;
  *
  * <p>All methods are thread safe, and return immutable and thread safe collections.</p>
  */
-@Immutable
 public interface Log {
 
     /**
-     * Get the content of the log
+     * Gets the {@link LogEntry}s that make up this log.
      *
-     * @return a {@link SortedSet} of all of the {@link LogEntry} objects in this {@link Log}
+     * @return the content
      */
-    @Nonnull
-    SortedSet<LogEntry> getContent();
+    @NonNull SortedSet<LogEntry> getContent();
 
     /**
-     * Get the content of the log
-     *
-     * @return all content in this log
-     */
-    @Nonnull
-    SortedSet<LogEntry> getRecent();
-
-    /**
-     * Gets the recent content separated by page
-     *
-     * @param pageNo the page number
-     * @return the page content
-     * @throws IllegalArgumentException if the pageNo is less than 1
-     * @throws IllegalStateException if the log doesn't contain enough entries to populate the page. See {@link #getRecentMaxPages()}
-     */
-    @Nonnull
-    SortedMap<Integer, LogEntry> getRecent(int pageNo);
-
-    /**
-     * Gets the max page number for the recent pages.
-     *
-     * @return the max page number allowed in the {@link #getRecent(int)} method
-     */
-    int getRecentMaxPages();
-
-
-    /**
-     * Gets the recent content for a given actor
+     * Gets the entries in the log performed by the given actor.
      *
      * @param actor the uuid of the actor to filter by
-     * @return all content in this log where is actor = uuid
+     * @return the content for the given actor
      */
-    @Nonnull
-    SortedSet<LogEntry> getRecent(@Nonnull UUID actor);
-
-    /**
-     * Gets the recent content for a given actor, separated by page
-     *
-     * @param pageNo the page number
-     * @param actor  the uuid of the actor to filter by
-     * @return the page content
-     * @throws IllegalArgumentException if the pageNo is less than 1
-     * @throws IllegalStateException if the log doesn't contain enough entries to populate the page. See {@link #getRecentMaxPages(UUID)}
-     */
-    @Nonnull
-    SortedMap<Integer, LogEntry> getRecent(int pageNo, @Nonnull UUID actor);
-
-    /**
-     * Gets the max page number for the recent pages.
-     *
-     * @param actor the actor to filter by
-     * @return the max page number allowed in the {@link #getRecent(int, UUID)} method
-     */
-    int getRecentMaxPages(@Nonnull UUID actor);
-
+    @NonNull SortedSet<LogEntry> getContent(@NonNull UUID actor);
 
     /**
      * Gets the log content for a given user
@@ -116,29 +63,7 @@ public interface Log {
      * @param uuid the uuid to filter by
      * @return all content in this log where the user = uuid
      */
-    @Nonnull
-    SortedSet<LogEntry> getUserHistory(@Nonnull UUID uuid);
-
-    /**
-     * Gets the log content for a given user, separated by page
-     *
-     * @param pageNo the page number
-     * @param uuid   the uuid of the acted user to filter by
-     * @return the page content
-     * @throws IllegalArgumentException if the pageNo is less than 1
-     * @throws IllegalStateException if the log doesn't contain enough entries to populate the page. See {@link #getUserHistoryMaxPages(UUID)}
-     */
-    @Nonnull
-    SortedMap<Integer, LogEntry> getUserHistory(int pageNo, @Nonnull UUID uuid);
-
-    /**
-     * Gets the max page number for the user history pages.
-     *
-     * @param uuid the uuid to filter by
-     * @return the max page number allowed in the {@link #getUserHistory(int, UUID)} method
-     */
-    int getUserHistoryMaxPages(@Nonnull UUID uuid);
-
+    @NonNull SortedSet<LogEntry> getUserHistory(@NonNull UUID uuid);
 
     /**
      * Gets the log content for a given group
@@ -146,29 +71,7 @@ public interface Log {
      * @param name the name to filter by
      * @return all content in this log where the group = name
      */
-    @Nonnull
-    SortedSet<LogEntry> getGroupHistory(@Nonnull String name);
-
-    /**
-     * Gets the log content for a given group, separated by page
-     *
-     * @param pageNo the page number
-     * @param name   the name of the acted group to filter by
-     * @return the page content
-     * @throws IllegalArgumentException if the pageNo is less than 1
-     * @throws IllegalStateException if the log doesn't contain enough entries to populate the page. See {@link #getGroupHistoryMaxPages(String)}
-     */
-    @Nonnull
-    SortedMap<Integer, LogEntry> getGroupHistory(int pageNo, @Nonnull String name);
-
-    /**
-     * Gets the max page number for the group history pages.
-     *
-     * @param name the name to filter by
-     * @return the max page number allowed in the {@link #getGroupHistory(int, String)} method
-     */
-    int getGroupHistoryMaxPages(@Nonnull String name);
-
+    @NonNull SortedSet<LogEntry> getGroupHistory(@NonNull String name);
 
     /**
      * Gets the log content for a given track
@@ -176,57 +79,6 @@ public interface Log {
      * @param name the name to filter by
      * @return all content in this log where the track = name
      */
-    @Nonnull
-    SortedSet<LogEntry> getTrackHistory(@Nonnull String name);
-
-    /**
-     * Gets the log content for a given track, separated by page
-     *
-     * @param pageNo the page number
-     * @param name   the name of the acted track to filter by
-     * @return the page content
-     * @throws IllegalArgumentException if the pageNo is less than 1
-     * @throws IllegalStateException if the log doesn't contain enough entries to populate the page. See {@link #getTrackHistoryMaxPages(String)}
-     */
-    @Nonnull
-    SortedMap<Integer, LogEntry> getTrackHistory(int pageNo, @Nonnull String name);
-
-    /**
-     * Gets the max page number for the track history pages.
-     *
-     * @param name the name to filter by
-     * @return the max page number allowed in the {@link #getTrackHistory(int, String)} method
-     */
-    int getTrackHistoryMaxPages(@Nonnull String name);
-
-
-    /**
-     * Gets the log content for a given search query
-     *
-     * @param query the query to filter by
-     * @return all content in this log where the content matches query
-     */
-    @Nonnull
-    SortedSet<LogEntry> getSearch(@Nonnull String query);
-
-    /**
-     * Gets the log content for a given search query, separated by page
-     *
-     * @param pageNo the page number
-     * @param query  the query to filter by
-     * @return the page content
-     * @throws IllegalArgumentException if the pageNo is less than 1
-     * @throws IllegalStateException if the log doesn't contain enough entries to populate the page. See {@link #getSearchMaxPages(String)}}
-     */
-    @Nonnull
-    SortedMap<Integer, LogEntry> getSearch(int pageNo, @Nonnull String query);
-
-    /**
-     * Gets the max page number for the search query pages.
-     *
-     * @param query the query to filter by
-     * @return the max page number allowed in the {@link #getSearch(int, String)} method
-     */
-    int getSearchMaxPages(@Nonnull String query);
+    @NonNull SortedSet<LogEntry> getTrackHistory(@NonNull String name);
 
 }

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

@@ -25,19 +25,17 @@
 
 package me.lucko.luckperms.api;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
 import java.util.Optional;
 import java.util.UUID;
 
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
-import javax.annotation.concurrent.Immutable;
-
 /**
  * Represents a logged action.
  *
  * @see ActionLogger#newEntryBuilder() for creating an instance
  */
-@Immutable
 public interface LogEntry extends Comparable<LogEntry> {
 
     /**
@@ -54,24 +52,21 @@ public interface LogEntry extends Comparable<LogEntry> {
      *
      * @return the actor id
      */
-    @Nonnull
-    UUID getActor();
+    @NonNull UUID getActor();
 
     /**
      * Gets the name describing the actor.
      *
      * @return the name of the actor
      */
-    @Nonnull
-    String getActorName();
+    @NonNull String getActorName();
 
     /**
      * Gets the type of action.
      *
      * @return the action type
      */
-    @Nonnull
-    Type getType();
+    @NonNull Type getType();
 
     /**
      * Gets the uuid of the object which was acted upon.
@@ -80,16 +75,14 @@ public interface LogEntry extends Comparable<LogEntry> {
      *
      * @return the uuid of acted object
      */
-    @Nonnull
-    Optional<UUID> getActed();
+    @NonNull Optional<UUID> getActed();
 
     /**
      * Gets the name describing the object which was acted upon
      *
      * @return the name of the acted object
      */
-    @Nonnull
-    String getActedName();
+    @NonNull String getActedName();
 
     /**
      * Returns a string describing the action which took place.
@@ -99,8 +92,7 @@ public interface LogEntry extends Comparable<LogEntry> {
      *
      * @return the action
      */
-    @Nonnull
-    String getAction();
+    @NonNull String getAction();
 
     /**
      * Represents the type of a {@link LogEntry}.
@@ -108,22 +100,38 @@ public interface LogEntry extends Comparable<LogEntry> {
      * @since 3.3
      */
     enum Type {
-        USER('U'),
-        GROUP('G'),
-        TRACK('T');
+        USER('U'), GROUP('G'), TRACK('T');
 
-        private final char code;
-
-        Type(char code) {
-            this.code = code;
+        /**
+         * Parses a {@link Type} from a string.
+         *
+         * @param type the string
+         * @return a type
+         * @throws IllegalArgumentException if a type could not be parsed
+         * @since 4.4
+         */
+        public static @NonNull Type parse(String type) {
+            try {
+                return valueOf(type);
+            } catch (IllegalArgumentException e) {
+                // ignore
+            }
+            try {
+                return valueOf(type.charAt(0));
+            } catch (IllegalArgumentException e) {
+                // ignore
+            }
+            throw new IllegalArgumentException("Unknown type: " + type);
         }
 
-        public char getCode() {
-            return this.code;
-        }
-
-        @Nonnull
-        public static Type valueOf(char code) {
+        /**
+         * Returns a {@link Type} by its code.
+         *
+         * @param code the code - see {@link Type#getCode()}.
+         * @return a type
+         * @throws IllegalArgumentException if a type could not be resolved
+         */
+        public static @NonNull Type valueOf(char code) {
             switch (code) {
                 case 'U':
                 case 'u':
@@ -138,6 +146,16 @@ public interface LogEntry extends Comparable<LogEntry> {
                     throw new IllegalArgumentException("Unknown code: " + code);
             }
         }
+
+        private final char code;
+
+        Type(char code) {
+            this.code = code;
+        }
+
+        public char getCode() {
+            return this.code;
+        }
     }
 
     /**
@@ -152,8 +170,7 @@ public interface LogEntry extends Comparable<LogEntry> {
          * @return the builder
          * @see LogEntry#getTimestamp()
          */
-        @Nonnull
-        Builder setTimestamp(long timestamp);
+        @NonNull Builder setTimestamp(long timestamp);
 
         /**
          * Sets the actor of the entry.
@@ -162,8 +179,7 @@ public interface LogEntry extends Comparable<LogEntry> {
          * @return the builder
          * @see LogEntry#getActor()
          */
-        @Nonnull
-        Builder setActor(@Nonnull UUID actor);
+        @NonNull Builder setActor(@NonNull UUID actor);
 
         /**
          * Sets the actor name of the entry.
@@ -172,8 +188,7 @@ public interface LogEntry extends Comparable<LogEntry> {
          * @return the builder
          * @see LogEntry#getActorName()
          */
-        @Nonnull
-        Builder setActorName(@Nonnull String actorName);
+        @NonNull Builder setActorName(@NonNull String actorName);
 
         /**
          * Sets the type of the entry.
@@ -182,8 +197,7 @@ public interface LogEntry extends Comparable<LogEntry> {
          * @return the builder
          * @see LogEntry#getType()
          */
-        @Nonnull
-        Builder setType(@Nonnull Type type);
+        @NonNull Builder setType(@NonNull Type type);
 
         /**
          * Sets the acted object for the entry.
@@ -192,8 +206,7 @@ public interface LogEntry extends Comparable<LogEntry> {
          * @return the builder
          * @see LogEntry#getActed()
          */
-        @Nonnull
-        Builder setActed(@Nullable UUID acted);
+        @NonNull Builder setActed(@Nullable UUID acted);
 
         /**
          * Sets the acted name for the entry.
@@ -202,8 +215,7 @@ public interface LogEntry extends Comparable<LogEntry> {
          * @return the builder
          * @see LogEntry#getActedName()
          */
-        @Nonnull
-        Builder setActedName(@Nonnull String actedName);
+        @NonNull Builder setActedName(@NonNull String actedName);
 
         /**
          * Sets the action of the entry.
@@ -212,16 +224,14 @@ public interface LogEntry extends Comparable<LogEntry> {
          * @return the builder
          * @see LogEntry#getAction()
          */
-        @Nonnull
-        Builder setAction(@Nonnull String action);
+        @NonNull Builder setAction(@NonNull String action);
 
         /**
          * Creates a {@link LogEntry} instance from the builder.
          *
          * @return a new log entry instance
          */
-        @Nonnull
-        LogEntry build();
+        @NonNull LogEntry build();
 
     }
 

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

@@ -0,0 +1,124 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package me.lucko.luckperms.api;
+
+import java.util.EnumSet;
+import java.util.Set;
+
+/**
+ * The various lookup setting flags for {@link Contexts}.
+ *
+ * @since 4.2
+ */
+public enum LookupSetting {
+
+    /**
+     * If the target subject is OP
+     */
+    IS_OP,
+
+    /**
+     * If global or non-server-specific nodes should be applied
+     */
+    INCLUDE_NODES_SET_WITHOUT_SERVER,
+
+    /**
+     * If global or non-world-specific nodes should be applied
+     */
+    INCLUDE_NODES_SET_WITHOUT_WORLD,
+
+    /**
+     * If parent groups should be resolved
+     */
+    RESOLVE_INHERITANCE,
+
+    /**
+     * If global or non-server-specific group memberships should be applied
+     */
+    APPLY_PARENTS_SET_WITHOUT_SERVER,
+
+    /**
+     * If global or non-world-specific group memberships should be applied
+     */
+    APPLY_PARENTS_SET_WITHOUT_WORLD;
+
+
+
+    /* bitwise utility methods */
+
+    static boolean isSet(byte b, LookupSetting setting) {
+        return ((b >> setting.ordinal()) & 1) == 1;
+    }
+
+    static byte createFlag(LookupSetting... settings) {
+        byte b = 0;
+        for (LookupSetting setting : settings) {
+            b |= (1 << setting.ordinal());
+        }
+        return b;
+    }
+
+    static byte createFlag(Set<LookupSetting> settings) {
+        byte b = 0;
+        for (LookupSetting setting : settings) {
+            b |= (1 << setting.ordinal());
+        }
+        return b;
+    }
+
+    static Set<LookupSetting> createSetFromFlag(byte b) {
+        EnumSet<LookupSetting> settings = EnumSet.noneOf(LookupSetting.class);
+        for (LookupSetting setting : LookupSetting.values()) {
+            if (((b >> setting.ordinal()) & 1) == 1) {
+                settings.add(setting);
+            }
+        }
+        return settings;
+    }
+
+    static byte createFlag(boolean includeNodesSetWithoutServer, boolean includeNodesSetWithoutWorld, boolean resolveInheritance, boolean applyParentsWithoutServer, boolean applyParentsWithoutWorld, boolean isOp) {
+        byte b = 0;
+        if (includeNodesSetWithoutServer) {
+            b |= (1 << LookupSetting.INCLUDE_NODES_SET_WITHOUT_SERVER.ordinal());
+        }
+        if (includeNodesSetWithoutWorld) {
+            b |= (1 << LookupSetting.INCLUDE_NODES_SET_WITHOUT_WORLD.ordinal());
+        }
+        if (resolveInheritance) {
+            b |= (1 << LookupSetting.RESOLVE_INHERITANCE.ordinal());
+        }
+        if (applyParentsWithoutServer) {
+            b |= (1 << LookupSetting.APPLY_PARENTS_SET_WITHOUT_SERVER.ordinal());
+        }
+        if (applyParentsWithoutWorld) {
+            b |= (1 << LookupSetting.APPLY_PARENTS_SET_WITHOUT_WORLD.ordinal());
+        }
+        if (isOp) {
+            b |= (1 << LookupSetting.IS_OP.ordinal());
+        }
+        return b;
+    }
+}

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

@@ -26,10 +26,12 @@
 package me.lucko.luckperms.api;
 
 import me.lucko.luckperms.LuckPerms;
+import me.lucko.luckperms.api.caching.CachedData;
 import me.lucko.luckperms.api.context.ContextCalculator;
 import me.lucko.luckperms.api.context.ContextManager;
 import me.lucko.luckperms.api.context.ContextSet;
 import me.lucko.luckperms.api.event.EventBus;
+import me.lucko.luckperms.api.manager.CachedDataManager;
 import me.lucko.luckperms.api.manager.GroupManager;
 import me.lucko.luckperms.api.manager.TrackManager;
 import me.lucko.luckperms.api.manager.UserManager;
@@ -37,14 +39,15 @@ import me.lucko.luckperms.api.messenger.MessengerProvider;
 import me.lucko.luckperms.api.metastacking.MetaStackFactory;
 import me.lucko.luckperms.api.platform.PlatformInfo;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+import java.util.Collection;
 import java.util.Optional;
 import java.util.Set;
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
 
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
-
 /**
  * The LuckPerms API.
  *
@@ -62,8 +65,7 @@ public interface LuckPermsApi {
      * @return the platform info
      * @since 4.0
      */
-    @Nonnull
-    PlatformInfo getPlatformInfo();
+    @NonNull PlatformInfo getPlatformInfo();
 
     /**
      * Gets the {@link UserManager}, responsible for managing
@@ -78,8 +80,7 @@ public interface LuckPermsApi {
      * @return the user manager
      * @since 4.0
      */
-    @Nonnull
-    UserManager getUserManager();
+    @NonNull UserManager getUserManager();
 
     /**
      * Gets the {@link GroupManager}, responsible for managing
@@ -94,8 +95,7 @@ public interface LuckPermsApi {
      * @return the group manager
      * @since 4.0
      */
-    @Nonnull
-    GroupManager getGroupManager();
+    @NonNull GroupManager getGroupManager();
 
     /**
      * Gets the {@link TrackManager}, responsible for managing
@@ -110,8 +110,16 @@ public interface LuckPermsApi {
      * @return the track manager
      * @since 4.0
      */
-    @Nonnull
-    TrackManager getTrackManager();
+    @NonNull TrackManager getTrackManager();
+
+    /**
+     * Gets the {@link CachedDataManager}, responsible for managing
+     * {@link CachedData} instances.
+     *
+     * @return the cached data manager
+     * @since 4.5
+     */
+    @NonNull CachedDataManager getCachedDataManager();
 
     /**
      * Schedules the execution of an update task, and returns an encapsulation
@@ -125,8 +133,7 @@ public interface LuckPermsApi {
      * @return a future
      * @since 4.0
      */
-    @Nonnull
-    CompletableFuture<Void> runUpdateTask();
+    @NonNull CompletableFuture<Void> runUpdateTask();
 
     /**
      * Gets the {@link EventBus}, used for subscribing to internal LuckPerms
@@ -135,16 +142,14 @@ public interface LuckPermsApi {
      * @return the event bus
      * @since 3.0
      */
-    @Nonnull
-    EventBus getEventBus();
+    @NonNull EventBus getEventBus();
 
     /**
      * Gets a representation of the plugins configuration
      *
      * @return the configuration
      */
-    @Nonnull
-    LPConfiguration getConfiguration();
+    @NonNull LPConfiguration getConfiguration();
 
     /**
      * Gets an object representing the plugins primary {@link Storage} backend.
@@ -155,8 +160,7 @@ public interface LuckPermsApi {
      * @return a storage instance
      * @since 2.14
      */
-    @Nonnull
-    Storage getStorage();
+    @NonNull Storage getStorage();
 
     /**
      * Gets the {@link MessagingService}, if present.
@@ -170,8 +174,7 @@ public interface LuckPermsApi {
      *
      * @return the messaging service instance, if present.
      */
-    @Nonnull
-    Optional<MessagingService> getMessagingService();
+    @NonNull Optional<MessagingService> getMessagingService();
 
     /**
      * Registers a {@link MessengerProvider} for use by the platform.
@@ -182,7 +185,7 @@ public interface LuckPermsApi {
      * @param messengerProvider the messenger provider.
      * @since 4.1
      */
-    void registerMessengerProvider(@Nonnull MessengerProvider messengerProvider);
+    void registerMessengerProvider(@NonNull MessengerProvider messengerProvider);
 
     /**
      * Gets the {@link ActionLogger}.
@@ -193,7 +196,7 @@ public interface LuckPermsApi {
      * @return the action logger
      * @since 4.1
      */
-    ActionLogger getActionLogger();
+    @NonNull ActionLogger getActionLogger();
 
     /**
      * Gets a {@link UuidCache}.
@@ -203,11 +206,10 @@ public interface LuckPermsApi {
      *
      * @return the uuid cache
      * @deprecated this feature is now handled internally - and the API returns a
-     *             No-op implementation of this class.
+     * No-op implementation of this class.
      */
-    @Nonnull
     @Deprecated
-    UuidCache getUuidCache();
+    @NonNull UuidCache getUuidCache();
 
     /**
      * Gets the {@link ContextManager}.
@@ -218,7 +220,15 @@ public interface LuckPermsApi {
      * @return the context manager
      * @since 4.0
      */
-    ContextManager getContextManager();
+    @NonNull ContextManager getContextManager();
+
+    /**
+     * Gets a {@link Collection} of all known permission strings.
+     *
+     * @return a collection of the known permissions
+     * @since 4.4
+     */
+    @NonNull Collection<String> getKnownPermissions();
 
     /**
      * Gets the {@link NodeFactory}.
@@ -227,8 +237,7 @@ public interface LuckPermsApi {
      *
      * @return the node factory
      */
-    @Nonnull
-    NodeFactory getNodeFactory();
+    @NonNull NodeFactory getNodeFactory();
 
     /**
      * Gets the {@link MetaStackFactory}.
@@ -240,8 +249,7 @@ public interface LuckPermsApi {
      * @return the meta stack factory
      * @since 3.2
      */
-    @Nonnull
-    MetaStackFactory getMetaStackFactory();
+    @NonNull MetaStackFactory getMetaStackFactory();
 
 
 
@@ -263,8 +271,7 @@ public interface LuckPermsApi {
      * @return a {@link User} object, if one matching the uuid is loaded, or null if not
      * @throws NullPointerException if the uuid is null
      */
-    @Nullable
-    default User getUser(@Nonnull UUID uuid) {
+    default @Nullable User getUser(@NonNull UUID uuid) {
         return getUserManager().getUser(uuid);
     }
 
@@ -275,8 +282,7 @@ public interface LuckPermsApi {
      * @return an optional {@link User} object
      * @throws NullPointerException if the uuid is null
      */
-    @Nonnull
-    default Optional<User> getUserSafe(@Nonnull UUID uuid) {
+    default @NonNull Optional<User> getUserSafe(@NonNull UUID uuid) {
         return getUserManager().getUserOpt(uuid);
     }
 
@@ -287,8 +293,7 @@ public interface LuckPermsApi {
      * @return a {@link User} object, if one matching the uuid is loaded, or null if not
      * @throws NullPointerException if the name is null
      */
-    @Nullable
-    default User getUser(@Nonnull String name) {
+    default @Nullable User getUser(@NonNull String name) {
         return getUserManager().getUser(name);
     }
 
@@ -299,8 +304,7 @@ public interface LuckPermsApi {
      * @return an optional {@link User} object
      * @throws NullPointerException if the name is null
      */
-    @Nonnull
-    default Optional<User> getUserSafe(@Nonnull String name) {
+    default @NonNull Optional<User> getUserSafe(@NonNull String name) {
         return getUserManager().getUserOpt(name);
     }
 
@@ -309,8 +313,7 @@ public interface LuckPermsApi {
      *
      * @return a {@link Set} of {@link User} objects
      */
-    @Nonnull
-    default Set<User> getUsers() {
+    default @NonNull Set<User> getUsers() {
         return getUserManager().getLoadedUsers();
     }
 
@@ -321,7 +324,7 @@ public interface LuckPermsApi {
      * @return true if the user is loaded
      * @throws NullPointerException if the uuid is null
      */
-    default boolean isUserLoaded(@Nonnull UUID uuid) {
+    default boolean isUserLoaded(@NonNull UUID uuid) {
         return getUserManager().isLoaded(uuid);
     }
 
@@ -331,7 +334,7 @@ public interface LuckPermsApi {
      * @param user the user to unload
      * @throws NullPointerException if the user is null
      */
-    default void cleanupUser(@Nonnull User user) {
+    default void cleanupUser(@NonNull User user) {
         getUserManager().cleanupUser(user);
     }
 
@@ -342,8 +345,7 @@ public interface LuckPermsApi {
      * @return a {@link Group} object, if one matching the name exists, or null if not
      * @throws NullPointerException if the name is null
      */
-    @Nullable
-    default Group getGroup(@Nonnull String name) {
+    default @Nullable Group getGroup(@NonNull String name) {
         return getGroupManager().getGroup(name);
     }
 
@@ -356,8 +358,7 @@ public interface LuckPermsApi {
      * @return an optional {@link Group} object
      * @throws NullPointerException if the name is null
      */
-    @Nonnull
-    default Optional<Group> getGroupSafe(@Nonnull String name) {
+    default @NonNull Optional<Group> getGroupSafe(@NonNull String name) {
         return getGroupManager().getGroupOpt(name);
     }
 
@@ -366,8 +367,7 @@ public interface LuckPermsApi {
      *
      * @return a {@link Set} of {@link Group} objects
      */
-    @Nonnull
-    default Set<Group> getGroups() {
+    default @NonNull Set<Group> getGroups() {
         return getGroupManager().getLoadedGroups();
     }
 
@@ -378,7 +378,7 @@ public interface LuckPermsApi {
      * @return true if the group is loaded
      * @throws NullPointerException if the name is null
      */
-    default boolean isGroupLoaded(@Nonnull String name) {
+    default boolean isGroupLoaded(@NonNull String name) {
         return getGroupManager().isLoaded(name);
     }
 
@@ -390,8 +390,7 @@ public interface LuckPermsApi {
      * if not
      * @throws NullPointerException if the name is null
      */
-    @Nullable
-    default Track getTrack(@Nonnull String name) {
+    default @Nullable Track getTrack(@NonNull String name) {
         return getTrackManager().getTrack(name);
     }
 
@@ -404,8 +403,7 @@ public interface LuckPermsApi {
      * @return an optional {@link Track} object
      * @throws NullPointerException if the name is null
      */
-    @Nonnull
-    default Optional<Track> getTrackSafe(@Nonnull String name) {
+    default @NonNull Optional<Track> getTrackSafe(@NonNull String name) {
         return getTrackManager().getTrackOpt(name);
     }
 
@@ -414,8 +412,7 @@ public interface LuckPermsApi {
      *
      * @return a {@link Set} of {@link Track} objects
      */
-    @Nonnull
-    default Set<Track> getTracks() {
+    default @NonNull Set<Track> getTracks() {
         return getTrackManager().getLoadedTracks();
     }
 
@@ -426,7 +423,7 @@ public interface LuckPermsApi {
      * @return true if the track is loaded
      * @throws NullPointerException if the name is null
      */
-    default boolean isTrackLoaded(@Nonnull String name) {
+    default boolean isTrackLoaded(@NonNull String name) {
         return getTrackManager().isLoaded(name);
     }
 
@@ -436,8 +433,7 @@ public interface LuckPermsApi {
      * @return a new builder
      * @since 4.0
      */
-    @Nonnull
-    default LogEntry.Builder newLogEntryBuilder() {
+    default LogEntry.@NonNull Builder newLogEntryBuilder() {
         return getActionLogger().newEntryBuilder();
     }
 
@@ -450,8 +446,7 @@ public interface LuckPermsApi {
      * @throws NullPointerException     if the permission is null
      * @since 2.6
      */
-    @Nonnull
-    default Node.Builder buildNode(@Nonnull String permission) throws IllegalArgumentException {
+    default Node.@NonNull Builder buildNode(@NonNull String permission) throws IllegalArgumentException {
         return getNodeFactory().newBuilder(permission);
     }
 
@@ -461,7 +456,7 @@ public interface LuckPermsApi {
      * @param calculator the context calculator to register. The type MUST be the player class of the platform.
      * @throws ClassCastException if the type is not the player class of the platform.
      */
-    default void registerContextCalculator(@Nonnull ContextCalculator<?> calculator) {
+    default void registerContextCalculator(@NonNull ContextCalculator<?> calculator) {
         getContextManager().registerCalculator(calculator);
     }
 
@@ -473,8 +468,7 @@ public interface LuckPermsApi {
      * @param user the user to get contexts for
      * @return an optional containing contexts. Will return empty if the user is not online.
      */
-    @Nonnull
-    default Optional<Contexts> getContextForUser(@Nonnull User user) {
+    default @NonNull Optional<Contexts> getContextForUser(@NonNull User user) {
         return getContextManager().lookupApplicableContexts(user);
     }
 
@@ -485,8 +479,7 @@ public interface LuckPermsApi {
      * @return a set of contexts.
      * @since 2.17
      */
-    @Nonnull
-    default ContextSet getContextForPlayer(@Nonnull Object player) {
+    default @NonNull ContextSet getContextForPlayer(@NonNull Object player) {
         return getContextManager().getApplicableContext(player);
     }
 
@@ -497,8 +490,7 @@ public interface LuckPermsApi {
      * @return a set of contexts.
      * @since 3.3
      */
-    @Nonnull
-    default Contexts getContextsForPlayer(@Nonnull Object player) {
+    default @NonNull Contexts getContextsForPlayer(@NonNull Object player) {
         return getContextManager().getApplicableContexts(player);
     }
 

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

@@ -25,7 +25,7 @@
 
 package me.lucko.luckperms.api;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * A means to push changes to other servers using the platforms networking
@@ -71,6 +71,6 @@ public interface MessagingService {
      * @param user the user to push the update for
      * @since 4.1
      */
-    void pushUserUpdate(@Nonnull User user);
+    void pushUserUpdate(@NonNull User user);
 
 }

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

@@ -0,0 +1,74 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package me.lucko.luckperms.api;
+
+/**
+ * Represents the result to a "mutation" on an object.
+ *
+ * @since 4.2
+ */
+public interface MutateResult {
+
+    /**
+     * Instance of {@link MutateResult} which always reports success.
+     */
+    MutateResult GENERIC_SUCCESS = () -> true;
+
+    /**
+     * Instance of {@link MutateResult} which always reports failure.
+     */
+    MutateResult GENERIC_FAILURE = () -> false;
+
+    /**
+     * Gets if the operation which produced this result completed successfully.
+     *
+     * @return if the result indicates a success
+     */
+    boolean wasSuccess();
+
+    /**
+     * Gets if the operation which produced this result failed.
+     *
+     * @return if the result indicates a failure
+     */
+    default boolean wasFailure() {
+        return !wasSuccess();
+    }
+
+    /**
+     * Gets a boolean representation of the result.
+     *
+     * <p>A value of <code>true</code> marks that the operation {@link #wasSuccess() was a success}
+     * and a value of <code>false</code> marks that the operation
+     * {@link #wasFailure() was a failure}.</p>
+     *
+     * @return a boolean representation
+     */
+    default boolean asBoolean() {
+        return wasSuccess();
+    }
+
+}

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

@@ -25,19 +25,30 @@
 
 package me.lucko.luckperms.api;
 
+import com.google.common.base.Preconditions;
+
 import me.lucko.luckperms.api.context.ContextSet;
+import me.lucko.luckperms.api.nodetype.NodeType;
+import me.lucko.luckperms.api.nodetype.NodeTypeKey;
+import me.lucko.luckperms.api.nodetype.types.DisplayNameType;
+import me.lucko.luckperms.api.nodetype.types.InheritanceType;
+import me.lucko.luckperms.api.nodetype.types.MetaType;
+import me.lucko.luckperms.api.nodetype.types.PrefixType;
+import me.lucko.luckperms.api.nodetype.types.SuffixType;
+import me.lucko.luckperms.api.nodetype.types.WeightType;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
 
 import java.util.Date;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 import java.util.Optional;
 import java.util.Set;
+import java.util.concurrent.TimeUnit;
 import java.util.stream.Stream;
 
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
-import javax.annotation.concurrent.Immutable;
-
 /**
  * Represents a LuckPerms "node".
  *
@@ -59,23 +70,32 @@ import javax.annotation.concurrent.Immutable;
  * <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>
+ * <li>{@link #getPermission() permission} - the actual permission string</li>
+ * <li>{@link #getValue() 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>The 'permission' property of a {@link Node} is also used in some cases to represent state
+ * beyond a granted permission. This state is encapsulated by extra {@link NodeType} data which
+ * can be obtained from this instance using {@link #getTypeData(NodeTypeKey)}.</p>
+ *
+ * <p>Type data is mapped by {@link NodeTypeKey}s, which are usually stored as static members of the
+ * corresponding {@link NodeType} class under the <code>KEY</code> field.</p>
+ *
+ * <p>The current types are:</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>
+ * <li>normal - just a regular permission</li>
+ * <li>{@link InheritanceType} - an "inheritance node" marks that the holder should inherit data from another group</li>
+ * <li>{@link PrefixType} - represents an assigned prefix</li>
+ * <li>{@link SuffixType} - represents an assigned suffix</li>
+ * <li>{@link MetaType} - represents an assigned meta option</li>
+ * <li>{@link WeightType} - marks the weight of the object holding this node</li>
+ * <li>{@link DisplayNameType} - marks the display name of the object holding this node</li>
  * </ul>
  *
  * <p>The core node state must be immutable in all implementations.</p>
@@ -83,98 +103,87 @@ import javax.annotation.concurrent.Immutable;
  * @see NodeFactory for obtaining and constructing instances.
  * @since 2.6
  */
-@Immutable
 public interface Node {
 
     /**
-     * Gets the permission string
+     * Gets the permission string this node encapsulates.
+     *
+     * <p>The exact value of this string may vary for nodes which aren't regular
+     * permission settings.</p>
      *
      * @return the actual permission node
      */
-    @Nonnull
-    String getPermission();
+    @NonNull String getPermission();
 
     /**
-     * Gets the value.
+     * Gets the value of the node.
      *
-     * <p>A negated node would return a value of <code>false</code>.</p>
+     * <p>A negated setting would result in a value of <code>false</code>.</p>
      *
-     * @return the permission's value
+     * @return the nodes value
      */
-    @Nonnull
-    default Boolean getValue() {
-        return getValuePrimitive();
-    }
+    boolean getValue();
 
     /**
-     * Gets the value.
-     *
-     * <p>A negated node would return a value of <code>false</code>.</p>
-     *
-     * @return the permission's value
-     */
-    boolean getValuePrimitive();
-
-    /**
-     * Gets the value of this node as a {@link Tristate}
+     * Gets the value of this node as a {@link Tristate}.
      *
      * @return the value of this node as a Tristate
      */
-    @Nonnull
-    default Tristate getTristate() {
-        return Tristate.fromBoolean(getValuePrimitive());
+    default @NonNull Tristate getTristate() {
+        return Tristate.fromBoolean(getValue());
     }
 
     /**
-     * Gets if the node is negated
+     * Gets if the node is negated.
+     *
+     * <p>This is the inverse of the {@link #getValue() value}.</p>
      *
      * @return true if the node is negated
      */
     default boolean isNegated() {
-        return !getValuePrimitive();
+        return !getValue();
     }
 
     /**
      * Gets if this node is set to override explicitly.
      *
-     * <p>This value does not persist across saves, and is therefore only useful for transient nodes</p>
+     * <p>This value does not persist across saves, and is therefore only
+     * useful for transient nodes.</p>
      *
      * @return true if this node is set to override explicitly
      */
     boolean isOverride();
 
     /**
-     * Gets the server this node applies on, if the node is server specific
+     * Gets the server this node applies on, if the node is server specific.
      *
      * @return an {@link Optional} containing the server, if one is defined
      */
-    @Nonnull
-    Optional<String> getServer();
+    @NonNull Optional<String> getServer();
 
     /**
-     * Gets the world this node applies on, if the node is world specific
+     * Gets the world this node applies on, if the node is world specific.
      *
      * @return an {@link Optional} containing the world, if one is defined
      */
-    @Nonnull
-    Optional<String> getWorld();
+    @NonNull Optional<String> getWorld();
 
     /**
-     * Gets if this node is server specific
+     * Gets if this node is server specific.
      *
      * @return true if this node is server specific
      */
     boolean isServerSpecific();
 
     /**
-     * Gets if this node is server specific
+     * Gets if this node is server specific.
      *
      * @return true if this node is server specific
      */
     boolean isWorldSpecific();
 
     /**
-     * Gets if this node applies globally, and therefore has no specific context
+     * Gets if this node applies globally, and therefore has no specific context.
      *
      * @return true if this node applies globally, and has no specific context
      * @since 3.1
@@ -182,7 +191,7 @@ public interface Node {
     boolean appliesGlobally();
 
     /**
-     * Gets if this node has any specific context in order for it to apply
+     * Gets if this node has any specific context in order for it to apply.
      *
      * @return true if this node has specific context
      * @since 3.1
@@ -192,29 +201,31 @@ public interface Node {
     /**
      * Gets if this node should apply in the given context
      *
-     * @param context the context key value pairs
+     * @param contextSet the context set
      * @return true if the node should apply
      * @since 2.13
      */
-    boolean shouldApplyWithContext(@Nonnull ContextSet context);
+    boolean shouldApplyWithContext(@NonNull ContextSet contextSet);
 
     /**
-     * Resolves any shorthand parts of this node and returns the full list
+     * Resolves any shorthand parts of this node and returns the full list of
+     * resolved nodes.
+     *
+     * <p>The list will not contain the exact permission itself.</p>
      *
      * @return a list of full nodes
      */
-    @Nonnull
-    List<String> resolveShorthand();
+    @NonNull List<String> resolveShorthand();
 
     /**
-     * Gets if this node will expire in the future
+     * Gets if this node is assigned temporarily.
      *
      * @return true if this node will expire in the future
      */
     boolean isTemporary();
 
     /**
-     * Gets if this node will not expire
+     * Gets if this node is permanent (will not expire).
      *
      * @return true if this node will not expire
      */
@@ -223,7 +234,7 @@ public interface Node {
     }
 
     /**
-     * Gets a unix timestamp in seconds when this node will expire
+     * Gets the unix timestamp (in seconds) when this node will expire.
      *
      * @return the time in Unix time when this node will expire
      * @throws IllegalStateException if the node is not temporary
@@ -231,16 +242,17 @@ public interface Node {
     long getExpiryUnixTime() throws IllegalStateException;
 
     /**
-     * Gets the date when this node will expire
+     * Gets the date when this node will expire.
      *
      * @return the {@link Date} when this node will expire
      * @throws IllegalStateException if the node is not temporary
      */
-    @Nonnull
-    Date getExpiry() throws IllegalStateException;
+    @NonNull Date getExpiry() throws IllegalStateException;
 
     /**
-     * Gets the number of seconds until this permission will expire
+     * Gets the number of seconds until this permission will expire.
+     *
+     * <p>Will return a negative value if the node has already expired.</p>
      *
      * @return the number of seconds until this permission will expire
      * @throws IllegalStateException if the node is not temporary
@@ -250,55 +262,46 @@ public interface Node {
     /**
      * Gets if the node has expired.
      *
-     * <p>This also returns false if the node is not temporary.</p>
+     * <p>This returns false if the node is not temporary.</p>
      *
      * @return true if this node has expired
      */
     boolean hasExpired();
 
     /**
-     * Gets the extra contexts required for this node to apply
+     * Gets the extra contexts required for this node to apply.
      *
      * @return the extra contexts required for this node to apply
      * @since 2.13
      */
-    @Nonnull
-    ContextSet getContexts();
+    @NonNull ContextSet getContexts();
 
     /**
-     * The same as {@link #getContexts()}, but also includes values for "server" and "world" keys if present.
+     * The same as {@link #getContexts()}, but also includes context pairs for
+     * "server" and "world" keys if present.
      *
      * @return the full contexts required for this node to apply
+     * @see Contexts#SERVER_KEY
+     * @see Contexts#WORLD_KEY
      * @since 3.1
      */
-    @Nonnull
-    ContextSet getFullContexts();
+    @NonNull ContextSet getFullContexts();
 
     /**
-     * Gets if this is a group node
+     * Gets if this node is a wildcard permission.
      *
-     * @return true if this is a group node
-     */
-    boolean isGroupNode();
-
-    /**
-     * Gets the name of the group, if this is a group node.
-     *
-     * @return the name of the group
-     * @throws IllegalStateException if this is not a group node. See {@link #isGroupNode()}
-     */
-    @Nonnull
-    String getGroupName() throws IllegalStateException;
-
-    /**
-     * Gets if this node is a wildcard node
-     *
-     * @return true if this node is a wildcard node
+     * @return true if this node is a wildcard permission
      */
     boolean isWildcard();
 
     /**
-     * Gets the level of this wildcard, higher is more specific
+     * Gets the level of this wildcard.
+     *
+     * <p>The node <code>luckperms.*</code> has a wildcard level of 1.</p>
+     * <p>The node <code>luckperms.user.permission.*</code> has a wildcard level of 3.</p>
+     *
+     * <p>Nodes with a higher wildcard level are more specific and have priority over
+     * less specific nodes (nodes with a lower wildcard level).</p>
      *
      * @return the wildcard level
      * @throws IllegalStateException if this is not a wildcard
@@ -306,55 +309,119 @@ public interface Node {
     int getWildcardLevel() throws IllegalStateException;
 
     /**
-     * Gets if this node is a meta node
+     * Gets if this node has any extra {@link NodeType} data attached to it.
      *
-     * @return true if this node is a meta node
+     * @return if this node has any type data
+     * @since 4.2
      */
-    boolean isMeta();
+    boolean hasTypeData();
 
     /**
-     * Gets the meta value from this node
+     * Gets the type data corresponding to the given <code>key</code>, if present.
      *
-     * @return the meta value
-     * @throws IllegalStateException if this node is not a meta node
+     * @param key the key
+     * @param <T> the {@link NodeType} type
+     * @return the data, if present
+     * @since 4.2
      */
-    @Nonnull
-    Map.Entry<String, String> getMeta() throws IllegalStateException;
+    <T extends NodeType> Optional<T> getTypeData(NodeTypeKey<T> key);
 
     /**
-     * Gets if this node is a prefix node
+     * Gets the type data corresponding to the given <code>key</code>, throwing an exception
+     * if no data is present.
+     *
+     * @param key the key
+     * @param <T> the {@link NodeType} type
+     * @return the data
+     * @throws IllegalStateException if data isn't present
+     * @since 4.2
+     */
+    default <T extends NodeType> T typeData(NodeTypeKey<T> key) throws IllegalStateException {
+        return getTypeData(key).orElseThrow(() -> new IllegalStateException("Node '" + getPermission() + "' does not have the '" + key.getTypeName() + "' type."));
+    }
+
+    /**
+     * Gets if this node has {@link InheritanceType} type data.
+     *
+     * @return true if this is a inheritance (group) node.
+     */
+    default boolean isGroupNode() {
+        return getTypeData(InheritanceType.KEY).isPresent();
+    }
+
+    /**
+     * Gets the name of the inherited group if this node has {@link InheritanceType} type data,
+     * throwing an exception if the data is not present.
+     *
+     * @return the name of the group
+     * @throws IllegalStateException if this node doesn't have {@link InheritanceType} data
+     */
+    default @NonNull String getGroupName() throws IllegalStateException {
+        return typeData(InheritanceType.KEY).getGroupName();
+    }
+
+    /**
+     * Gets if this node has {@link MetaType} type data.
+     *
+     * @return true if this is a meta node.
+     */
+    default boolean isMeta() {
+        return getTypeData(MetaType.KEY).isPresent();
+    }
+
+    /**
+     * Gets the meta entry if this node has {@link MetaType} type data,
+     * throwing an exception if the data is not present.
+     *
+     * @return the meta entry
+     * @throws IllegalStateException if this node doesn't have {@link MetaType} data
+     */
+    default Map.@NonNull Entry<String, String> getMeta() throws IllegalStateException {
+        return typeData(MetaType.KEY);
+    }
+
+    /**
+     * Gets if this node has {@link PrefixType} type data.
      *
      * @return true if this node is a prefix node
      */
-    boolean isPrefix();
+    default boolean isPrefix() {
+        return getTypeData(PrefixType.KEY).isPresent();
+    }
 
     /**
-     * Gets the prefix value from this node
+     * Gets the prefix entry if this node has {@link PrefixType} type data,
+     * throwing an exception if the data is not present.
      *
-     * @return the prefix value
-     * @throws IllegalStateException if this node is a not a prefix node
+     * @return the meta entry
+     * @throws IllegalStateException if this node doesn't have {@link PrefixType} data
      */
-    @Nonnull
-    Map.Entry<Integer, String> getPrefix() throws IllegalStateException;
+    default Map.@NonNull Entry<Integer, String> getPrefix() throws IllegalStateException {
+        return typeData(PrefixType.KEY).getAsEntry();
+    }
 
     /**
-     * Gets if this node is a suffix node
+     * Gets if this node has {@link SuffixType} type data.
      *
      * @return true if this node is a suffix node
      */
-    boolean isSuffix();
+    default boolean isSuffix() {
+        return getTypeData(SuffixType.KEY).isPresent();
+    }
 
     /**
-     * Gets the suffix value from this node
+     * Gets the suffix entry if this node has {@link SuffixType} type data,
+     * throwing an exception if the data is not present.
      *
-     * @return the suffix value
-     * @throws IllegalStateException if this node is a not a suffix node
+     * @return the meta entry
+     * @throws IllegalStateException if this node doesn't have {@link SuffixType} data
      */
-    @Nonnull
-    Map.Entry<Integer, String> getSuffix() throws IllegalStateException;
+    default Map.@NonNull Entry<Integer, String> getSuffix() throws IllegalStateException {
+        return typeData(SuffixType.KEY).getAsEntry();
+    }
 
     /**
-     * Returns if this Node is equal to another node
+     * Gets if this Node is equal to another node.
      *
      * @param obj the other node
      * @return true if this node is equal to the other provided
@@ -364,28 +431,15 @@ public interface Node {
     boolean equals(Object obj);
 
     /**
-     * Returns if this Node is equal to another node as defined by the given
-     * {@link StandardNodeEquality} predicate.
-     *
-     * @param other the other node
-     * @param equalityPredicate the predicate
-     * @return true if this node is considered equal
-     * @since 4.1
-     */
-    boolean standardEquals(Node other, StandardNodeEquality equalityPredicate);
-
-    /**
-     * Returns if this Node is equal to another node as defined by the given
+     * Gets if this Node is equal to another node as defined by the given
      * {@link NodeEqualityPredicate}.
      *
-     * @param other the other node
+     * @param other             the other node
      * @param equalityPredicate the predicate
      * @return true if this node is considered equal
      * @since 4.1
      */
-    default boolean equals(Node other, NodeEqualityPredicate equalityPredicate) {
-        return equalityPredicate.areEqual(this, other);
-    }
+    boolean equals(Node other, NodeEqualityPredicate equalityPredicate);
 
     /**
      * Similar to {@link Node#equals(Object)}, except doesn't take note of the
@@ -393,11 +447,11 @@ public interface Node {
      *
      * @param other the other node
      * @return true if the two nodes are almost equal
-     * @deprecated in favour of {@link #equals(Node, NodeEqualityPredicate)}
      * @see StandardNodeEquality#IGNORE_VALUE
+     * @deprecated in favour of {@link #equals(Node, NodeEqualityPredicate)}
      */
     @Deprecated
-    default boolean equalsIgnoringValue(@Nonnull Node other) {
+    default boolean equalsIgnoringValue(@NonNull Node other) {
         return equals(other, StandardNodeEquality.IGNORE_VALUE);
     }
 
@@ -407,11 +461,11 @@ public interface Node {
      *
      * @param other the other node
      * @return true if the two nodes are almost equal
-     * @deprecated in favour of {@link #equals(Node, NodeEqualityPredicate)}
      * @see StandardNodeEquality#IGNORE_EXPIRY_TIME_AND_VALUE
+     * @deprecated in favour of {@link #equals(Node, NodeEqualityPredicate)}
      */
     @Deprecated
-    default boolean almostEquals(@Nonnull Node other) {
+    default boolean almostEquals(@NonNull Node other) {
         return equals(other, StandardNodeEquality.IGNORE_EXPIRY_TIME_AND_VALUE);
     }
 
@@ -421,12 +475,12 @@ public interface Node {
      *
      * @param other the other node
      * @return true if the two nodes are almost equal
+     * @see StandardNodeEquality#IGNORE_VALUE_OR_IF_TEMPORARY
      * @since 2.8
      * @deprecated in favour of {@link #equals(Node, NodeEqualityPredicate)}
-     * @see StandardNodeEquality#IGNORE_VALUE_OR_IF_TEMPORARY
      */
     @Deprecated
-    default boolean equalsIgnoringValueOrTemp(@Nonnull Node other) {
+    default boolean equalsIgnoringValueOrTemp(@NonNull Node other) {
         return equals(other, StandardNodeEquality.IGNORE_VALUE_OR_IF_TEMPORARY);
     }
 
@@ -444,6 +498,19 @@ public interface Node {
      */
     interface Builder {
 
+        /**
+         * Copies the attributes from the given node and applies them to this
+         * builder.
+         *
+         * <p>Note that this copies all attributes <strong>except</strong> the
+         * permission itself.</p>
+         *
+         * @param node the node to copy from
+         * @return the builder
+         * @since 4.2
+         */
+        Builder copyFrom(@NonNull Node node);
+
         /**
          * Sets the value of negated for the node.
          *
@@ -451,18 +518,16 @@ public interface Node {
          * @return the builder
          * @see Node#isNegated()
          */
-        @Nonnull
-        Builder setNegated(boolean negated);
+        @NonNull Builder setNegated(boolean negated);
 
         /**
          * Sets the value of the node.
          *
          * @param value the value
          * @return the builder
-         * @see Node#getValuePrimitive()
+         * @see Node#getValue()
          */
-        @Nonnull
-        Builder setValue(boolean value);
+        @NonNull Builder setValue(boolean value);
 
         /**
          * Sets the override property for the node.
@@ -474,18 +539,45 @@ public interface Node {
          * @return the builder
          * @see Node#isOverride()
          */
-        @Nonnull
-        Builder setOverride(boolean override);
+        @NonNull Builder setOverride(boolean override);
 
         /**
-         * Sets the nodes expiry as a unix timestamp in seconds.
+         * Sets the time when the node should expire.
          *
-         * @param expireAt the expiry time
+         * <p>The parameter passed to this method must be the unix timestamp
+         * (in seconds) when the node should expire.</p>
+         *
+         * @param expiryUnixTimestamp the expiry timestamp (unix seconds)
          * @return the builder
          * @see Node#getExpiryUnixTime()
          */
-        @Nonnull
-        Builder setExpiry(long expireAt);
+        @NonNull Builder setExpiry(long expiryUnixTimestamp);
+
+        /**
+         * Sets the time when the node should expire.
+         *
+         * <p>The expiry timestamp is calculated relative to the current
+         * system time.</p>
+         *
+         * @param duration how long the node should be added for
+         * @param unit     the unit <code>duration</code> is measured in
+         * @return the builder
+         * @since 4.2
+         */
+        default @NonNull Builder setExpiry(long duration, TimeUnit unit) {
+            Preconditions.checkArgument(duration > 0, "duration must be positive");
+            long seconds = Objects.requireNonNull(unit, "unit").toSeconds(duration);
+            long timeNow = System.currentTimeMillis() / 1000L;
+            return setExpiry(timeNow + seconds);
+        }
+
+        /**
+         * Marks that the node being built should never expire.
+         *
+         * @return the builder
+         * @since 4.2
+         */
+        @NonNull Builder clearExpiry();
 
         /**
          * Sets the world value for the node.
@@ -494,8 +586,7 @@ public interface Node {
          * @return the builder
          * @see Node#getWorld()
          */
-        @Nonnull
-        Builder setWorld(@Nullable String world);
+        @NonNull Builder setWorld(@Nullable String world);
 
         /**
          * Sets the server value for the node.
@@ -504,20 +595,18 @@ public interface Node {
          * @return the builder
          * @see Node#getServer()
          */
-        @Nonnull
-        Builder setServer(@Nullable String server);
+        @NonNull Builder setServer(@Nullable String server);
 
         /**
          * Appends an extra context onto the node.
          *
-         * @param key the context key
+         * @param key   the context key
          * @param value the context value
          * @return the builder
          * @see ContextSet
          * @see Node#getContexts()
          */
-        @Nonnull
-        Builder withExtraContext(@Nonnull String key, @Nonnull String value);
+        @NonNull Builder withExtraContext(@NonNull String key, @NonNull String value);
 
         /**
          * Appends extra contexts onto the node.
@@ -527,8 +616,7 @@ public interface Node {
          * @see ContextSet
          * @see Node#getContexts()
          */
-        @Nonnull
-        Builder withExtraContext(@Nonnull Map<String, String> map);
+        @NonNull Builder withExtraContext(@NonNull Map<String, String> map);
 
         /**
          * Appends extra contexts onto the node.
@@ -538,8 +626,7 @@ public interface Node {
          * @see ContextSet
          * @see Node#getContexts()
          */
-        @Nonnull
-        Builder withExtraContext(@Nonnull Set<Map.Entry<String, String>> context);
+        @NonNull Builder withExtraContext(@NonNull Set<Map.Entry<String, String>> context);
 
         /**
          * Appends an extra context onto the node.
@@ -549,27 +636,35 @@ public interface Node {
          * @see ContextSet
          * @see Node#getContexts()
          */
-        @Nonnull
-        Builder withExtraContext(@Nonnull Map.Entry<String, String> entry);
+        @NonNull Builder withExtraContext(Map.@NonNull Entry<String, String> entry);
 
         /**
          * Appends extra contexts onto the node.
          *
-         * @param set a contextset
+         * @param contextSet a context set
          * @return the builder
          * @see ContextSet
          * @see Node#getContexts()
          */
-        @Nonnull
-        Builder withExtraContext(@Nonnull ContextSet set);
+        @NonNull Builder withExtraContext(@NonNull ContextSet contextSet);
+
+        /**
+         * Sets the extra contexts for the node.
+         *
+         * @param contextSet a context set
+         * @return the builder
+         * @see ContextSet
+         * @see Node#getContexts()
+         * @since 4.2
+         */
+        @NonNull Builder setExtraContext(@NonNull ContextSet contextSet);
 
         /**
          * Creates a {@link Node} instance from the builder.
          *
          * @return a new node instance
          */
-        @Nonnull
-        Node build();
+        @NonNull Node build();
     }
 
 }

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

@@ -25,7 +25,7 @@
 
 package me.lucko.luckperms.api;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * A rule for determining if two nodes are equal.
@@ -33,8 +33,7 @@ import javax.annotation.Nonnull;
  * <p>Generally, individual instances of this interface should fulfil the same
  * requirements as the {@link Object#equals(Object)} contract.</p>
  *
- * <p>Some standard implementations are provided by
- * {@link StandardNodeEquality}.</p>
+ * <p>Some standard implementations are provided by {@link StandardNodeEquality}.</p>
  *
  * @since 4.1
  */
@@ -42,12 +41,15 @@ import javax.annotation.Nonnull;
 public interface NodeEqualityPredicate {
 
     /**
-     * Returns if the two nodes are equal
+     * Returns if the two nodes are equal.
+     *
+     * <p>This method should avoid making calls to {@link Node#equals(Node, NodeEqualityPredicate)}
+     * with {@code this} as the second argument, directly or otherwise.</p>
      *
      * @param o1 the first node
      * @param o2 the second node
      * @return true if equal
      */
-    boolean areEqual(@Nonnull Node o1, @Nonnull Node o2);
+    boolean areEqual(@NonNull Node o1, @NonNull Node o2);
 
 }

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

@@ -25,7 +25,7 @@
 
 package me.lucko.luckperms.api;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Assists with constructing {@link Node} instances.
@@ -41,8 +41,7 @@ public interface NodeFactory {
      * @return a node builder instance
      * @throws NullPointerException if the permission is null
      */
-    @Nonnull
-    Node.Builder newBuilder(@Nonnull String permission);
+    Node.@NonNull Builder newBuilder(@NonNull String permission);
 
     /**
      * Creates a node builder instance from an existing node
@@ -51,8 +50,7 @@ public interface NodeFactory {
      * @return a node builder instance
      * @throws NullPointerException if the other node is null
      */
-    @Nonnull
-    Node.Builder newBuilderFromExisting(@Nonnull Node other);
+    Node.@NonNull Builder newBuilderFromExisting(@NonNull Node other);
 
 
     /**
@@ -64,19 +62,17 @@ public interface NodeFactory {
      * @throws IllegalStateException if the group instance was not obtained from LuckPerms.
      * @since 3.1
      */
-    @Nonnull
-    Node.Builder makeGroupNode(@Nonnull Group group);
+    Node.@NonNull Builder makeGroupNode(@NonNull Group group);
 
     /**
      * Creates a node builder from a group
      *
      * @param groupName the name of the group
      * @return a node builder instance
-     * @throws NullPointerException  if the groupName is null
+     * @throws NullPointerException if the groupName is null
      * @since 4.0
      */
-    @Nonnull
-    Node.Builder makeGroupNode(@Nonnull String groupName);
+    Node.@NonNull Builder makeGroupNode(@NonNull String groupName);
 
     /**
      * Creates a node builder from a key value pair
@@ -86,21 +82,19 @@ public interface NodeFactory {
      * @return a node builder instance
      * @throws NullPointerException if the key or value is null
      */
-    @Nonnull
-    Node.Builder makeMetaNode(@Nonnull String key, @Nonnull String value);
+    Node.@NonNull Builder makeMetaNode(@NonNull String key, @NonNull String value);
 
     /**
      * Creates a node builder for the given chat meta type
      *
-     * @param type the type
+     * @param type     the type
      * @param priority the priority
-     * @param value the value for the prefix/suffix
+     * @param value    the value for the prefix/suffix
      * @return a node builder instance
      * @throws NullPointerException if the type or value is null
      * @since 3.2
      */
-    @Nonnull
-    Node.Builder makeChatMetaNode(@Nonnull ChatMetaType type, int priority, @Nonnull String value);
+    Node.@NonNull Builder makeChatMetaNode(@NonNull ChatMetaType type, int priority, @NonNull String value);
 
     /**
      * Creates a node builder from a prefix string and priority
@@ -110,8 +104,7 @@ public interface NodeFactory {
      * @return a node builder instance
      * @throws NullPointerException if the prefix is null
      */
-    @Nonnull
-    Node.Builder makePrefixNode(int priority, @Nonnull String prefix);
+    Node.@NonNull Builder makePrefixNode(int priority, @NonNull String prefix);
 
     /**
      * Creates a node builder from a prefix string and priority
@@ -121,7 +114,6 @@ public interface NodeFactory {
      * @return a node builder instance
      * @throws NullPointerException if the suffix is null
      */
-    @Nonnull
-    Node.Builder makeSuffixNode(int priority, @Nonnull String suffix);
+    Node.@NonNull Builder makeSuffixNode(int priority, @NonNull String suffix);
 
 }

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

@@ -31,46 +31,61 @@ import com.google.common.collect.Multimap;
 import me.lucko.luckperms.api.caching.CachedData;
 import me.lucko.luckperms.api.context.ContextSet;
 import me.lucko.luckperms.api.context.ImmutableContextSet;
+import me.lucko.luckperms.api.manager.GroupManager;
+import me.lucko.luckperms.api.manager.UserManager;
+import me.lucko.luckperms.api.nodetype.types.MetaType;
+import me.lucko.luckperms.api.nodetype.types.PrefixType;
+import me.lucko.luckperms.api.nodetype.types.SuffixType;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import java.util.SortedSet;
+import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Predicate;
 
-import javax.annotation.Nonnull;
-
 /**
- * An object which holds permissions.
- *
- * <p>Any changes made to permission holding objects will be lost unless the
- * instance is saved back to the {@link Storage}.</p>
+ * Generic superinterface for an object which holds permissions.
  */
 public interface PermissionHolder {
 
     /**
-     * Gets the objects name.
+     * Gets the objects generic name.
      *
-     * <p>{@link User#getUuid()}, {@link User#getName()} or {@link Group#getName()} should normally be used instead of
-     * this method.</p>
+     * <p>The result of this method is guaranteed to be a unique identifier for distinct instances
+     * of the same type of object.</p>
+     *
+     * <p>For {@link User}s, this method returns a {@link UUID#toString() string} representation of
+     * the users {@link User#getUuid() unique id}.</p>
+     *
+     * <p>For {@link Group}s, this method returns the {@link Group#getName() group name}.</p>
+     *
+     * <p>The {@link User#getUuid()}, {@link User#getName()} and {@link Group#getName()} methods
+     * define a "tighter" specification for obtaining object identifiers.</p>
      *
      * @return the identifier for this object. Either a uuid string or name.
      */
-    @Nonnull
-    String getObjectName();
+    @NonNull String getObjectName();
 
     /**
      * Gets a friendly name for this holder, to be displayed in command output, etc.
      *
-     * <p>This will <strong>always</strong> return a value, eventually falling back to {@link #getObjectName()} if no
-     * other "friendlier" identifiers are present.</p>
+     * <p>This will <strong>always</strong> return a value, eventually falling back to
+     * {@link #getObjectName()} if no other "friendlier" identifiers are present.</p>
+     *
+     * <p>For {@link User}s, this method will attempt to return the {@link User#getName() username},
+     * before falling back to {@link #getObjectName()}.</p>
+     *
+     * <p>For {@link Group}s, this method will attempt to return the groups display name, before
+     * falling back to {@link #getObjectName()}.</p>
      *
      * @return a friendly identifier for this holder
      * @since 3.2
      */
-    @Nonnull
-    String getFriendlyName();
+    @NonNull String getFriendlyName();
 
     /**
      * Gets the holders {@link CachedData} cache.
@@ -78,17 +93,18 @@ public interface PermissionHolder {
      * @return the holders cached data.
      * @since 3.2
      */
-    @Nonnull
-    CachedData getCachedData();
+    @NonNull CachedData getCachedData();
 
     /**
      * Refreshes and applies any changes to the cached holder data.
      *
+     * <p>Calling this method is unnecessary in most cases. Cache updates are handled
+     * behind the scenes by the implementation.</p>
+     *
      * @return the task future
      * @since 4.0
      */
-    @Nonnull
-    CompletableFuture<Void> refreshCachedData();
+    @NonNull CompletableFuture<Void> refreshCachedData();
 
     /**
      * Gets the backing multimap containing every permission this holder has.
@@ -99,8 +115,7 @@ public interface PermissionHolder {
      * @return the holders own permissions
      * @since 3.3
      */
-    @Nonnull
-    ImmutableSetMultimap<ImmutableContextSet, Node> getNodes();
+    @NonNull ImmutableSetMultimap<ImmutableContextSet, Node> getNodes();
 
     /**
      * Gets the backing multimap containing every transient permission this holder has.
@@ -112,8 +127,7 @@ public interface PermissionHolder {
      * @return the holders own permissions
      * @since 3.3
      */
-    @Nonnull
-    ImmutableSetMultimap<ImmutableContextSet, Node> getTransientNodes();
+    @NonNull ImmutableSetMultimap<ImmutableContextSet, Node> getTransientNodes();
 
     /**
      * Gets a flattened/squashed view of the holders permissions.
@@ -125,60 +139,90 @@ public interface PermissionHolder {
      *
      * <p>Use {@link #getPermissions()} for a view without duplicates.</p>
      *
+     * <p>This method <b>does not</b> resolve inheritance rules.</p>
+     *
      * @return a list of the holders own nodes.
      * @since 3.3
      */
-    @Nonnull
-    List<Node> getOwnNodes();
+    @NonNull List<Node> getOwnNodes();
 
     /**
      * Gets a sorted set of all held permissions.
      *
+     * <p>Effectively a sorted version of {@link #getOwnNodes()}, without duplicates. Use the
+     * aforementioned method if you don't require either of these attributes.</p>
+     *
+     * <p>This method <b>does not</b> resolve inheritance rules.</p>
+     *
+     * <p>Although this method is named getPermissions, it will actually return all types of node.</p>
+     *
      * @return an immutable set of permissions in priority order
      * @since 2.6
      */
-    @Nonnull
-    SortedSet<? extends Node> getPermissions();
+    @NonNull SortedSet<? extends Node> getPermissions();
 
     /**
-     * Similar to {@link #getPermissions()}, except without transient permissions.
+     * Similar to {@link #getPermissions()}, except only including permissions from the enduring
+     * node map. (See {@link #getNodes()})
      *
-     * <p>Unlike transient permissions, enduring permissions will be saved to storage, and exist after the session.</p>
+     * <p>Unlike transient permissions, enduring permissions will be saved to storage, and exist
+     * after the session.</p>
+     *
+     * <p>This method <b>does not</b> resolve inheritance rules.</p>
+     *
+     * <p>Although this method is named getEnduringPermissions, it will actually return all types
+     * of node.</p>
      *
      * @return a set of nodes
      * @since 2.6
      */
-    @Nonnull
-    Set<? extends Node> getEnduringPermissions();
+    @NonNull Set<? extends Node> getEnduringPermissions();
 
     /**
-     * Similar to {@link #getPermissions()}, except without enduring permissions.
+     * Similar to {@link #getPermissions()}, except only including permissions from the enduring
+     * node map. (See {@link #getTransientNodes()})
      *
      * <p>Transient permissions only exist for the duration of the session.</p>
      *
+     * <p>This method <b>does not</b> resolve inheritance rules.</p>
+     *
+     * <p>Although this method is named getTransientPermissions, it will actually return all types
+     * of node.</p>
+     *
      * @return a set of nodes
      * @since 2.6
      */
-    @Nonnull
-    Set<? extends Node> getTransientPermissions();
+    @NonNull Set<? extends Node> getTransientPermissions();
 
     /**
-     * Processes the nodes and returns the non-temporary ones.
+     * A filtered view of this holders nodes, only including permanent entries.
+     *
+     * <p>Data is sourced from {@link #getOwnNodes()}, filtered, and then collected to a set.</p>
+     *
+     * <p>This method <b>does not</b> resolve inheritance rules.</p>
+     *
+     * <p>Although this method is named getPermanentPermissionNodes, it will actually return all types
+     * of node.</p>
      *
      * @return a set of permanent nodes
      * @since 2.6
      */
-    @Nonnull
-    Set<Node> getPermanentPermissionNodes();
+    @NonNull Set<Node> getPermanentPermissionNodes();
 
     /**
-     * Processes the nodes and returns the temporary ones.
+     * A filtered view of this holders nodes, only including temporary entries.
+     *
+     * <p>Data is sourced from {@link #getOwnNodes()}, filtered, and then collected to a set.</p>
+     *
+     * <p>This method <b>does not</b> resolve inheritance rules.</p>
+     *
+     * <p>Although this method is named getTemporaryPermissionNodes, it will actually return all types
+     * of node.</p>
      *
      * @return a set of temporary nodes
      * @since 2.6
      */
-    @Nonnull
-    Set<Node> getTemporaryPermissionNodes();
+    @NonNull Set<Node> getTemporaryPermissionNodes();
 
     /**
      * Recursively resolves this holders permissions.
@@ -188,12 +232,15 @@ public interface PermissionHolder {
      *
      * <p>This means the list will contain duplicates.</p>
      *
+     * <p>Inheritance is performed according to the platforms rules, and the order will vary
+     * depending on the accumulation order. By default, the holders own nodes are first in the list,
+     * with the entries from the end of the inheritance tree appearing last.</p>
+     *
      * @param contexts the contexts for the lookup
      * @return a list of nodes
      * @since 3.3
      */
-    @Nonnull
-    List<LocalizedNode> resolveInheritances(Contexts contexts);
+    @NonNull List<LocalizedNode> resolveInheritances(@NonNull Contexts contexts);
 
     /**
      * Recursively resolves this holders permissions.
@@ -206,142 +253,157 @@ public interface PermissionHolder {
      * <p>Unlike {@link #resolveInheritances(Contexts)}, this method does not
      * filter by context, at all.</p>
      *
+     * <p>Inheritance is performed according to the platforms rules, and the order will vary
+     * depending on the accumulation order. By default, the holders own nodes are first in the list,
+     * with the entries from the end of the inheritance tree appearing last.</p>
+     *
      * @return a list of nodes
      * @since 3.3
      */
-    @Nonnull
-    List<LocalizedNode> resolveInheritances();
+    @NonNull List<LocalizedNode> resolveInheritances();
 
     /**
      * Gets a mutable sorted set of the nodes that this object has and inherits, filtered by context
      *
-     * <p>Unlike {@link #getAllNodesFiltered(Contexts)}, this method will not filter individual nodes. The context is only
-     * used to determine which groups should apply.</p>
+     * <p>Unlike {@link #getAllNodesFiltered(Contexts)}, this method will not filter individual
+     * nodes by context. The context is only used to determine which groups should apply.</p>
      *
-     * <p>Nodes are sorted into priority order.</p>
+     * <p>Nodes are sorted into priority order. The order of inheritance is only important during
+     * the process of flattening inherited entries.</p>
      *
      * @param contexts the context for the lookup
-     * @return a mutable sorted set of permissions
+     * @return an immutable sorted set of permissions
      * @throws NullPointerException if the context is null
      * @since 2.11
      */
-    @Nonnull
-    SortedSet<LocalizedNode> getAllNodes(@Nonnull Contexts contexts);
+    @NonNull SortedSet<LocalizedNode> getAllNodes(@NonNull Contexts contexts);
 
     /**
      * Gets a mutable sorted set of the nodes that this object has and inherits.
      *
      * <p>Unlike {@link #getAllNodes(Contexts)}, this method does not filter by context, at all.</p>
      *
-     * <p>Nodes are sorted into priority order.</p>
+     * <p>Nodes are sorted into priority order. The order of inheritance is only important during
+     * the process of flattening inherited entries.</p>
      *
-     * @return a mutable sorted set of permissions
+     * @return an immutable sorted set of permissions
      * @throws NullPointerException if the context is null
      * @since 3.3
      */
-    @Nonnull
-    SortedSet<LocalizedNode> getAllNodes();
+    @NonNull SortedSet<LocalizedNode> getAllNodes();
 
     /**
      * Gets a mutable set of the nodes that this object has and inherits, filtered by context.
      *
-     * <p>Unlike {@link #getAllNodes(Contexts)}, this method WILL filter individual nodes, and only return ones that fully
-     * meet the context provided.</p>
+     * <p>Unlike {@link #getAllNodes(Contexts)}, this method WILL filter individual nodes,
+     * and only return ones that fully meet the context provided.</p>
      *
      * @param contexts the context for the lookup
      * @return a mutable set of permissions
      * @throws NullPointerException if the context is null
      * @since 2.11
      */
-    @Nonnull
-    Set<LocalizedNode> getAllNodesFiltered(@Nonnull Contexts contexts);
+    @NonNull Set<LocalizedNode> getAllNodesFiltered(@NonNull Contexts contexts);
 
     /**
-     * Converts the output of {@link #getAllNodesFiltered(Contexts)}, and expands shorthand permissions.
+     * Converts the output of {@link #getAllNodesFiltered(Contexts)} into string and boolean form,
+     * and expands shorthand permissions.
      *
-     * @param contexts the context for the lookup
-     * @param lowerCase if the keys should be made lowercase whilst being exported
+     * @param contexts           the context for the lookup
+     * @param convertToLowercase if the keys should be made lowercase whilst being exported
      * @return a mutable map of permissions
      */
-    @Nonnull
-    Map<String, Boolean> exportNodes(@Nonnull Contexts contexts, boolean lowerCase);
+    @NonNull Map<String, Boolean> exportNodes(@NonNull Contexts contexts, boolean convertToLowercase);
 
     /**
-     * Removes temporary permissions that have expired
+     * Removes any temporary permissions that have expired.
+     *
+     * <p>This method is called periodically by the platform, so it is only necessary to run
+     * if you want to guarentee that the current data is totally up-to-date.</p>
      */
     void auditTemporaryPermissions();
 
     /**
-     * Checks to see if the object has a certain permission
+     * Checks to see if the object has a certain permission.
      *
-     * @param node the node to check for
+     * <p>Although this method is named hasPermission, it can be used for all node types.</p>
+     *
+     * @param node              the node to check for
      * @param equalityPredicate how to determine if a node matches
      * @return a Tristate for the holders permission status for the node
      * @throws NullPointerException if the node is null
      * @since 4.1
      */
-    @Nonnull
-    Tristate hasPermission(@Nonnull Node node, @Nonnull NodeEqualityPredicate equalityPredicate);
+    @NonNull Tristate hasPermission(@NonNull Node node, @NonNull NodeEqualityPredicate equalityPredicate);
 
     /**
-     * Checks to see if the object has a certain permission
+     * Checks to see if the object has a certain permission.
      *
-     * @param node the node to check for
+     * <p>Although this method is named hasTransientPermission, it can be used for all node types.</p>
+     *
+     * @param node              the node to check for
      * @param equalityPredicate how to determine if a node matches
      * @return a Tristate for the holders permission status for the node
      * @throws NullPointerException if the node is null
      * @since 4.1
      */
-    @Nonnull
-    Tristate hasTransientPermission(@Nonnull Node node, @Nonnull NodeEqualityPredicate equalityPredicate);
+    @NonNull Tristate hasTransientPermission(@NonNull Node node, @NonNull NodeEqualityPredicate equalityPredicate);
 
     /**
-     * Checks to see if the object inherits a certain permission
+     * Checks to see if the object inherits a certain permission.
      *
-     * @param node the node to check for
+     * <p>Although this method is named inheritsPermission, it can be used for all node types.</p>
+     *
+     * @param node              the node to check for
      * @param equalityPredicate how to determine if a node matches
      * @return a Tristate for the holders inheritance status for the node
      * @throws NullPointerException if the node is null
      * @since 4.1
      */
-    @Nonnull
-    Tristate inheritsPermission(@Nonnull Node node, @Nonnull NodeEqualityPredicate equalityPredicate);
+    @NonNull Tristate inheritsPermission(@NonNull Node node, @NonNull NodeEqualityPredicate equalityPredicate);
 
     /**
-     * Checks to see if the object has a certain permission
+     * Checks to see if the object has a certain permission.
+     *
+     * <p>Although this method is named hasPermission, it can be used for all node types.</p>
      *
      * @param node the node to check for
      * @return a Tristate for the holders permission status for the node
      * @throws NullPointerException if the node is null
      * @since 2.6
      */
-    @Nonnull
-    Tristate hasPermission(@Nonnull Node node);
+    @NonNull Tristate hasPermission(@NonNull Node node);
 
     /**
-     * Checks to see if the object has a certain permission
+     * Checks to see if the object has a certain permission.
+     *
+     * <p>Although this method is named hasTransientPermission, it can be used for all node types.</p>
      *
      * @param node the node to check for
      * @return a Tristate for the holders permission status for the node
      * @throws NullPointerException if the node is null
      * @since 2.6
      */
-    @Nonnull
-    Tristate hasTransientPermission(@Nonnull Node node);
+    @NonNull Tristate hasTransientPermission(@NonNull Node node);
 
     /**
-     * Checks to see if the object inherits a certain permission
+     * Checks to see if the object inherits a certain permission.
+     *
+     * <p>Although this method is named inheritsPermission, it can be used for all node types.</p>
      *
      * @param node the node to check for
      * @return a Tristate for the holders inheritance status for the node
      * @throws NullPointerException if the node is null
      * @since 2.6
      */
-    @Nonnull
-    Tristate inheritsPermission(@Nonnull Node node);
+    @NonNull Tristate inheritsPermission(@NonNull Node node);
 
     /**
-     * Check to see if this holder inherits another group directly
+     * Check to see if this holder inherits another group in the global context.
+     *
+     * <p>"Global context" simply means an empty context set.</p>
+     *
+     * <p>This method only checks for direct inheritance - one hop up the inheritance tree.</p>
      *
      * @param group The group to check membership of
      * @return true if the group inherits the other group
@@ -349,141 +411,315 @@ public interface PermissionHolder {
      * @throws IllegalStateException if the group instance was not obtained from LuckPerms.
      * @since 4.0
      */
-    boolean inheritsGroup(@Nonnull Group group);
+    boolean inheritsGroup(@NonNull Group group);
 
     /**
-     * Check to see if this holder inherits another group directly
+     * Check to see if this holder inherits another group.
      *
-     * @param group The group to check membership of
+     * <p>This method only checks for direct inheritance - one hop up the inheritance tree.</p>
+     *
+     * @param group      The group to check membership of
      * @param contextSet the context set to filter by
      * @return true if the group inherits the other group
      * @throws NullPointerException  if the group is null
      * @throws IllegalStateException if the group instance was not obtained from LuckPerms.
      * @since 4.0
      */
-    boolean inheritsGroup(@Nonnull Group group, @Nonnull ContextSet contextSet);
+    boolean inheritsGroup(@NonNull Group group, @NonNull ContextSet contextSet);
 
     /**
-     * Sets a permission for the object
+     * Sets a permission node for the permission holder.
+     *
+     * <p>Although this method is named setPermission, it can be used for all node types.</p>
+     *
+     * <p>The effect of this mutate operation will not persist in storage unless changes are
+     * explicitly saved. If changes are not saved, the effect will only be observed until the next
+     * time the holders permission data is (re)loaded. Changes to {@link User}s should be saved
+     * using {@link UserManager#saveUser(User)}, and changes to {@link Group}s should be saved
+     * using {@link GroupManager#saveGroup(Group)}.</p>
+     *
+     * <p>Before making changes to a user or group, it may be a good idea to load a fresh copy of
+     * the backing data from the storage if you haven't done so already, to avoid overwriting changes
+     * made already. This can be done via {@link UserManager#loadUser(UUID)} or
+     * {@link GroupManager#loadGroup(String)} respectively.</p>
      *
      * @param node The node to be set
      * @return the result of the operation
      * @throws NullPointerException if the node is null
      * @since 4.0
      */
-    @Nonnull
-    DataMutateResult setPermission(@Nonnull Node node);
+    @NonNull DataMutateResult setPermission(@NonNull Node node);
 
     /**
-     * Sets a transient permission for the object
+     * Sets a permission node for the permission holder.
+     *
+     * <p>Although this method is named setPermission, it can be used for all node types.</p>
+     *
+     * <p>The effect of this mutate operation will not persist in storage unless changes are
+     * explicitly saved. If changes are not saved, the effect will only be observed until the next
+     * time the holders permission data is (re)loaded. Changes to {@link User}s should be saved
+     * using {@link UserManager#saveUser(User)}, and changes to {@link Group}s should be saved
+     * using {@link GroupManager#saveGroup(Group)}.</p>
+     *
+     * <p>Before making changes to a user or group, it may be a good idea to load a fresh copy of
+     * the backing data from the storage if you haven't done so already, to avoid overwriting changes
+     * made already. This can be done via {@link UserManager#loadUser(UUID)} or
+     * {@link GroupManager#loadGroup(String)} respectively.</p>
+     *
+     * @param node                    The node to be set
+     * @param temporaryMergeBehaviour The behaviour used to merge temporary permission entries
+     * @return the result of the operation
+     * @throws NullPointerException if the node is null
+     * @since 4.3
+     */
+    @NonNull TemporaryDataMutateResult setPermission(@NonNull Node node, @NonNull TemporaryMergeBehaviour temporaryMergeBehaviour);
+
+    /**
+     * Sets a transient permission for the permission holder.
      *
      * <p>A transient node is a permission that does not persist.
-     * Whenever a user logs out of the server, or the server restarts, this permission will disappear.
-     * It is never saved to the datastore, and therefore will not apply on other servers.</p>
+     * Whenever a user logs out of the server, or the server restarts, this permission will
+     * disappear. It is never saved to the datastore, and therefore will not apply on other
+     * servers.</p>
      *
-     * <p>This is useful if you want to temporarily set a permission for a user while they're online, but don't
-     * want it to persist, and have to worry about removing it when they log out.</p>
+     * <p>This is useful if you want to temporarily set a permission for a user while they're
+     * online, but don't want it to persist, and have to worry about removing it when they log
+     * out.</p>
      *
-     * <p>For unsetting a transient permission, see {@link #unsetTransientPermission(Node)}</p>
+     * <p>For unsetting a transient permission, see {@link #unsetTransientPermission(Node)}.</p>
+     *
+     * <p>Although this method is named setTransientPermission, it can be used for all node types.</p>
      *
      * @param node The node to be set
      * @return the result of the operation
      * @throws NullPointerException if the node is null
      * @since 4.0
      */
-    @Nonnull
-    DataMutateResult setTransientPermission(@Nonnull Node node);
+    @NonNull DataMutateResult setTransientPermission(@NonNull Node node);
 
     /**
-     * Unsets a permission for the object
+     * Sets a transient permission for the permission holder.
+     *
+     * <p>A transient node is a permission that does not persist.
+     * Whenever a user logs out of the server, or the server restarts, this permission will
+     * disappear. It is never saved to the datastore, and therefore will not apply on other
+     * servers.</p>
+     *
+     * <p>This is useful if you want to temporarily set a permission for a user while they're
+     * online, but don't want it to persist, and have to worry about removing it when they log
+     * out.</p>
+     *
+     * <p>For unsetting a transient permission, see {@link #unsetTransientPermission(Node)}.</p>
+     *
+     * <p>Although this method is named setTransientPermission, it can be used for all node types.</p>
+     *
+     * @param node                    The node to be se
+     * @param temporaryMergeBehaviour The behaviour used to merge temporary permission entries
+     * @return the result of the operation
+     * @throws NullPointerException if the node is null
+     * @since 4.3
+     */
+    @NonNull TemporaryDataMutateResult setTransientPermission(@NonNull Node node, @NonNull TemporaryMergeBehaviour temporaryMergeBehaviour);
+
+    /**
+     * Unsets a permission for the permission holder.
+     *
+     * <p>Although this method is named unsetPermission, it can be used for all node types.</p>
+     *
+     * <p>The effect of this mutate operation will not persist in storage unless changes are
+     * explicitly saved. If changes are not saved, the effect will only be observed until the next
+     * time the holders permission data is (re)loaded. Changes to {@link User}s should be saved
+     * using {@link UserManager#saveUser(User)}, and changes to {@link Group}s should be saved
+     * using {@link GroupManager#saveGroup(Group)}.</p>
+     *
+     * <p>Before making changes to a user or group, it may be a good idea to load a fresh copy of
+     * the backing data from the storage if you haven't done so already, to avoid overwriting changes
+     * made already. This can be done via {@link UserManager#loadUser(UUID)} or
+     * {@link GroupManager#loadGroup(String)} respectively.</p>
      *
      * @param node The node to be unset
      * @return the result of the operation
      * @throws NullPointerException if the node is null
      * @since 4.0
      */
-    @Nonnull
-    DataMutateResult unsetPermission(@Nonnull Node node);
+    @NonNull DataMutateResult unsetPermission(@NonNull Node node);
 
     /**
-     * Unsets a transient permission for the object
+     * Unsets a transient permission for the permission holder.
+     *
+     * <p>Although this method is named unsetTransientPermission, it can be used for all node types.</p>
      *
      * @param node The node to be unset
      * @return the result of the operation
      * @throws NullPointerException if the node is null
      * @since 4.0
      */
-    @Nonnull
-    DataMutateResult unsetTransientPermission(@Nonnull Node node);
+    @NonNull DataMutateResult unsetTransientPermission(@NonNull Node node);
 
     /**
-     * Clears any nodes from the holder which pass the predicate
+     * Clears any nodes from the holder which pass the predicate.
+     *
+     * <p>This method only targets enduring data.</p>
+     *
+     * <p>The effect of this mutate operation will not persist in storage unless changes are
+     * explicitly saved. If changes are not saved, the effect will only be observed until the next
+     * time the holders permission data is (re)loaded. Changes to {@link User}s should be saved
+     * using {@link UserManager#saveUser(User)}, and changes to {@link Group}s should be saved
+     * using {@link GroupManager#saveGroup(Group)}.</p>
+     *
+     * <p>Before making changes to a user or group, it may be a good idea to load a fresh copy of
+     * the backing data from the storage if you haven't done so already, to avoid overwriting changes
+     * made already. This can be done via {@link UserManager#loadUser(UUID)} or
+     * {@link GroupManager#loadGroup(String)} respectively.</p>
      *
      * @param test the predicate to test for nodes which should be removed
      * @since 3.2
      */
-    void clearMatching(@Nonnull Predicate<Node> test);
+    void clearMatching(@NonNull Predicate<Node> test);
 
     /**
-     * Clears any transient nodes from the holder which pass the predicate
+     * Clears any transient nodes from the holder which pass the predicate.
+     *
+     * <p>The effect of this mutate operation will not persist in storage unless changes are
+     * explicitly saved. If changes are not saved, the effect will only be observed until the next
+     * time the holders permission data is (re)loaded. Changes to {@link User}s should be saved
+     * using {@link UserManager#saveUser(User)}, and changes to {@link Group}s should be saved
+     * using {@link GroupManager#saveGroup(Group)}.</p>
+     *
+     * <p>Before making changes to a user or group, it may be a good idea to load a fresh copy of
+     * the backing data from the storage if you haven't done so already, to avoid overwriting changes
+     * made already. This can be done via {@link UserManager#loadUser(UUID)} or
+     * {@link GroupManager#loadGroup(String)} respectively.</p>
      *
      * @param test the predicate to test for nodes which should be removed
      * @since 3.2
      */
-    void clearMatchingTransient(@Nonnull Predicate<Node> test);
+    void clearMatchingTransient(@NonNull Predicate<Node> test);
 
     /**
-     * Clears all nodes held by the object
+     * Clears all nodes held by the permission holder.
+     *
+     * <p>The effect of this mutate operation will not persist in storage unless changes are
+     * explicitly saved. If changes are not saved, the effect will only be observed until the next
+     * time the holders permission data is (re)loaded. Changes to {@link User}s should be saved
+     * using {@link UserManager#saveUser(User)}, and changes to {@link Group}s should be saved
+     * using {@link GroupManager#saveGroup(Group)}.</p>
+     *
+     * <p>Before making changes to a user or group, it may be a good idea to load a fresh copy of
+     * the backing data from the storage if you haven't done so already, to avoid overwriting changes
+     * made already. This can be done via {@link UserManager#loadUser(UUID)} or
+     * {@link GroupManager#loadGroup(String)} respectively.</p>
      *
      * @since 2.17
      */
     void clearNodes();
 
     /**
-     * Clears all nodes held by the object in a specific context
+     * Clears all nodes held by the permission holder in a specific context.
+     *
+     * <p>The effect of this mutate operation will not persist in storage unless changes are
+     * explicitly saved. If changes are not saved, the effect will only be observed until the next
+     * time the holders permission data is (re)loaded. Changes to {@link User}s should be saved
+     * using {@link UserManager#saveUser(User)}, and changes to {@link Group}s should be saved
+     * using {@link GroupManager#saveGroup(Group)}.</p>
+     *
+     * <p>Before making changes to a user or group, it may be a good idea to load a fresh copy of
+     * the backing data from the storage if you haven't done so already, to avoid overwriting changes
+     * made already. This can be done via {@link UserManager#loadUser(UUID)} or
+     * {@link GroupManager#loadGroup(String)} respectively.</p>
      *
      * @param contextSet the contexts to filter by
      * @since 3.2
      */
-    void clearNodes(@Nonnull ContextSet contextSet);
+    void clearNodes(@NonNull ContextSet contextSet);
 
     /**
-     * Clears all parent groups
+     * Clears all parent groups.
+     *
+     * <p>The effect of this mutate operation will not persist in storage unless changes are
+     * explicitly saved. If changes are not saved, the effect will only be observed until the next
+     * time the holders permission data is (re)loaded. Changes to {@link User}s should be saved
+     * using {@link UserManager#saveUser(User)}, and changes to {@link Group}s should be saved
+     * using {@link GroupManager#saveGroup(Group)}.</p>
+     *
+     * <p>Before making changes to a user or group, it may be a good idea to load a fresh copy of
+     * the backing data from the storage if you haven't done so already, to avoid overwriting changes
+     * made already. This can be done via {@link UserManager#loadUser(UUID)} or
+     * {@link GroupManager#loadGroup(String)} respectively.</p>
      *
      * @since 2.17
      */
     void clearParents();
 
     /**
-     * Clears all parent groups in a specific context
+     * Clears all parent groups in a specific context.
+     *
+     * <p>The effect of this mutate operation will not persist in storage unless changes are
+     * explicitly saved. If changes are not saved, the effect will only be observed until the next
+     * time the holders permission data is (re)loaded. Changes to {@link User}s should be saved
+     * using {@link UserManager#saveUser(User)}, and changes to {@link Group}s should be saved
+     * using {@link GroupManager#saveGroup(Group)}.</p>
+     *
+     * <p>Before making changes to a user or group, it may be a good idea to load a fresh copy of
+     * the backing data from the storage if you haven't done so already, to avoid overwriting changes
+     * made already. This can be done via {@link UserManager#loadUser(UUID)} or
+     * {@link GroupManager#loadGroup(String)} respectively.</p>
      *
      * @param contextSet the contexts to filter by
      * @since 3.2
      */
-    void clearParents(@Nonnull ContextSet contextSet);
+    void clearParents(@NonNull ContextSet contextSet);
 
     /**
-     * Clears all meta held by the object
+     * Clears all meta held by the permission holder.
+     *
+     * <p>Meta nodes in this case, are any nodes which have a {@link MetaType}, {@link PrefixType}
+     * or {@link SuffixType} type.</p>
+     *
+     * <p>The effect of this mutate operation will not persist in storage unless changes are
+     * explicitly saved. If changes are not saved, the effect will only be observed until the next
+     * time the holders permission data is (re)loaded. Changes to {@link User}s should be saved
+     * using {@link UserManager#saveUser(User)}, and changes to {@link Group}s should be saved
+     * using {@link GroupManager#saveGroup(Group)}.</p>
+     *
+     * <p>Before making changes to a user or group, it may be a good idea to load a fresh copy of
+     * the backing data from the storage if you haven't done so already, to avoid overwriting changes
+     * made already. This can be done via {@link UserManager#loadUser(UUID)} or
+     * {@link GroupManager#loadGroup(String)} respectively.</p>
      *
      * @since 2.17
      */
     void clearMeta();
 
     /**
-     * Clears all meta held by the object in a specific context
+     * Clears all meta held by the permission holder in a specific context.
+     *
+     * <p>Meta nodes in this case, are any nodes which have a {@link MetaType}, {@link PrefixType}
+     * or {@link SuffixType} type.</p>
+     *
+     * <p>The effect of this mutate operation will not persist in storage unless changes are
+     * explicitly saved. If changes are not saved, the effect will only be observed until the next
+     * time the holders permission data is (re)loaded. Changes to {@link User}s should be saved
+     * using {@link UserManager#saveUser(User)}, and changes to {@link Group}s should be saved
+     * using {@link GroupManager#saveGroup(Group)}.</p>
+     *
+     * <p>Before making changes to a user or group, it may be a good idea to load a fresh copy of
+     * the backing data from the storage if you haven't done so already, to avoid overwriting changes
+     * made already. This can be done via {@link UserManager#loadUser(UUID)} or
+     * {@link GroupManager#loadGroup(String)} respectively.</p>
      *
      * @param contextSet the contexts to filter by
      * @since 3.2
      */
-    void clearMeta(@Nonnull ContextSet contextSet);
+    void clearMeta(@NonNull ContextSet contextSet);
 
     /**
-     * Clears all transient permissions the holder has.
+     * Clears all transient nodes the permission holder has.
      */
     void clearTransientNodes();
 
     /**
-     * Sets a permission for the object
+     * Sets a permission for the permission holder.
      *
      * @param node The node to be set
      * @return the result of the operation
@@ -491,14 +727,13 @@ public interface PermissionHolder {
      * @since 3.1
      * @deprecated now forwards to {@link #setPermission(Node)}.
      */
-    @Nonnull
     @Deprecated
-    default DataMutateResult setPermissionUnchecked(@Nonnull Node node) {
+    default @NonNull DataMutateResult setPermissionUnchecked(@NonNull Node node) {
         return setPermission(node);
     }
 
     /**
-     * Sets a transient permission for the object
+     * Sets a transient permission for the permission holder.
      *
      * @param node The node to be set
      * @return the result of the operation
@@ -506,39 +741,36 @@ public interface PermissionHolder {
      * @since 3.1
      * @deprecated now forwards to {@link #setTransientPermission(Node)}
      */
-    @Nonnull
     @Deprecated
-    default DataMutateResult setTransientPermissionUnchecked(@Nonnull Node node) {
+    default @NonNull DataMutateResult setTransientPermissionUnchecked(@NonNull Node node) {
         return setTransientPermission(node);
     }
 
     /**
-     * Unsets a permission for the object
+     * Unsets a permission for the permission holder.
      *
      * @param node The node to be unset
-     * @throws NullPointerException if the node is null
      * @return the result of the operation
+     * @throws NullPointerException if the node is null
      * @since 3.1
      * @deprecated now forwards to {@link #unsetPermission(Node)}
      */
-    @Nonnull
     @Deprecated
-    default DataMutateResult unsetPermissionUnchecked(@Nonnull Node node) {
+    default @NonNull DataMutateResult unsetPermissionUnchecked(@NonNull Node node) {
         return unsetPermission(node);
     }
 
     /**
-     * Unsets a transient permission for the object
+     * Unsets a transient permission for the permission holder.
      *
      * @param node The node to be unset
-     * @throws NullPointerException if the node is null
      * @return the result of the operation
+     * @throws NullPointerException if the node is null
      * @since 3.1
      * @deprecated now forwards to {@link #unsetTransientPermission(Node)}
      */
-    @Nonnull
     @Deprecated
-    default DataMutateResult unsetTransientPermissionUnchecked(@Nonnull Node node) {
+    default @NonNull DataMutateResult unsetTransientPermissionUnchecked(@NonNull Node node) {
         return unsetTransientPermission(node);
     }
 

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

@@ -0,0 +1,124 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package me.lucko.luckperms.api;
+
+import me.lucko.luckperms.api.manager.UserManager;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+import java.util.Objects;
+import java.util.Set;
+import java.util.UUID;
+
+/**
+ * Encapsulates the result of an operation to save uuid data about a player.
+ *
+ * <p>The corresponding method can be found at
+ * {@link UserManager#savePlayerData(UUID, String)}.</p>
+ *
+ * @since 4.2
+ */
+public interface PlayerSaveResult {
+
+    /**
+     * Gets the status returned by the operation
+     *
+     * @return the status
+     */
+    @NonNull Set<Status> getStatus();
+
+    /**
+     * Gets if the result includes a certain status code.
+     *
+     * @param status the status to check for
+     * @return if the result includes the status
+     */
+    default boolean includes(@NonNull Status status) {
+        Objects.requireNonNull(status, "status");
+        return getStatus().contains(status);
+    }
+
+    /**
+     * Gets the old username involved in the result.
+     *
+     * <p>Returns null when the result doesn't {@link #includes(Status) include} the
+     * {@link Status#USERNAME_UPDATED} status.</p>
+     *
+     * @return the old username
+     * @see Status#USERNAME_UPDATED
+     */
+    @Nullable String getOldUsername();
+
+    /**
+     * Gets the other uuids involved in the result.
+     *
+     * <p>Returns null when the result doesn't {@link #includes(Status) include} the
+     * {@link Status#OTHER_UUIDS_PRESENT_FOR_USERNAME} status.</p>
+     *
+     * @return the other uuids
+     * @see Status#OTHER_UUIDS_PRESENT_FOR_USERNAME
+     */
+    @Nullable Set<UUID> getOtherUuids();
+
+    /**
+     * The various states the result can take
+     */
+    enum Status {
+
+        /**
+         * There was no existing data saved for either the uuid or username
+         */
+        CLEAN_INSERT,
+
+        /**
+         * There was existing data for the player, no change was needed.
+         */
+        NO_CHANGE,
+
+        /**
+         * There was already a record for the UUID saved, but it was for a different username.
+         *
+         * <p>This is normal, players are able to change their usernames.</p>
+         */
+        USERNAME_UPDATED,
+
+        /**
+         * There was already a record for the username saved, but it was under a different uuid.
+         *
+         * <p>This is a bit of a cause for concern. It's possible that "player1" has changed
+         * their username to "player2", and "player3" has changed their username to "player1".
+         * If the original "player1" doesn't join after changing their name, this conflict could
+         * occur.</p>
+         *
+         * <p>However, what's more likely is that the server is not setup to authenticate
+         * correctly. Usually this is a problem with BungeeCord "ip-forwarding", but could be
+         * that the user of the plugin is running a network off a shared database with one
+         * server in online mode and another in offline mode.</p>
+         */
+        OTHER_UUIDS_PRESENT_FOR_USERNAME,
+    }
+}

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

@@ -0,0 +1,127 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package me.lucko.luckperms.api;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Optional;
+
+/**
+ * Encapsulates the result of {@link User}s promotion along a {@link Track}.
+ *
+ * @since 4.2
+ */
+public interface PromotionResult extends MutateResult {
+
+    /**
+     * Gets the status of the result.
+     *
+     * @return the status
+     */
+    @NonNull Status getStatus();
+
+    @Override
+    default boolean wasSuccess() {
+        return getStatus().wasSuccess();
+    }
+
+    /**
+     * Gets the name of the group the user was promoted from, if applicable.
+     *
+     * <p>Will only be present for results with a {@link #getStatus() status} of
+     * {@link Status#SUCCESS}.</p>
+     *
+     * @return the group the user was promoted from.
+     */
+    @NonNull Optional<String> getGroupFrom();
+
+    /**
+     * Gets the name of the group the user was promoted from, if applicable.
+     *
+     * <p>Will only be present for results with a {@link #getStatus() status} of
+     * {@link Status#SUCCESS} or {@link Status#ADDED_TO_FIRST_GROUP}.</p>
+     *
+     * <p>The value will also be set for results with the {@link Status#MALFORMED_TRACK} status,
+     * with this value marking the group which no longer exists.</p>
+     *
+     * @return the group the user was promoted to.
+     */
+    @NonNull Optional<String> getGroupTo();
+
+    /**
+     * The result status
+     */
+    enum Status implements MutateResult {
+
+        /**
+         * Indicates that the user was promoted normally.
+         */
+        SUCCESS(true),
+
+        /**
+         * Indicates that the user was added to the first group in the track.
+         *
+         * <p>This usually occurs when the user isn't already on any of the groups in the track.</p>
+         */
+        ADDED_TO_FIRST_GROUP(true),
+
+        /**
+         * Indicates that the next group in the track no longer exists.
+         */
+        MALFORMED_TRACK(false),
+
+        /**
+         * Indicates that the user is already a member of the group at the end of the track,
+         * and as such cannot be promoted any further.
+         */
+        END_OF_TRACK(false),
+
+        /**
+         * Indicates that the implementation was unable to determine the users current position on
+         * this track.
+         *
+         * <p>This usually occurs when the user is on more than one group on the track.</p>
+         */
+        AMBIGUOUS_CALL(false),
+
+        /**
+         * An undefined failure occurred.
+         */
+        UNDEFINED_FAILURE(false);
+
+        private final boolean success;
+
+        Status(boolean success) {
+            this.success = success;
+        }
+
+        @Override
+        public boolean wasSuccess() {
+            return this.success;
+        }
+    }
+
+}

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

@@ -25,7 +25,7 @@
 
 package me.lucko.luckperms.api;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Standard {@link NodeEqualityPredicate}s.
@@ -44,7 +44,7 @@ public enum StandardNodeEquality implements NodeEqualityPredicate {
 
     /**
      * All attributes must match, except for
-     * {@link Node#getValuePrimitive() value}, which is ignored.
+     * {@link Node#getValue() value}, which is ignored.
      */
     IGNORE_VALUE,
 
@@ -59,20 +59,20 @@ public enum StandardNodeEquality implements NodeEqualityPredicate {
 
     /**
      * All attributes must match, except for
-     * {@link Node#getValuePrimitive() value} and the
+     * {@link Node#getValue() value} and the
      * {@link Node#getExpiry() expiry time}, which are ignored.
      */
     IGNORE_EXPIRY_TIME_AND_VALUE,
 
     /**
      * All attributes must match, except for
-     * {@link Node#getValuePrimitive() value} and the if the node is
+     * {@link Node#getValue() value} and the if the node is
      * {@link Node#isTemporary() temporary}, which are ignored.
      */
     IGNORE_VALUE_OR_IF_TEMPORARY;
 
     @Override
-    public boolean areEqual(@Nonnull Node o1, @Nonnull Node o2) {
-        return o1.standardEquals(o2, this);
+    public boolean areEqual(@NonNull Node o1, @NonNull Node o2) {
+        return o1.equals(o2, this);
     }
 }

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

@@ -29,29 +29,18 @@ import me.lucko.luckperms.api.manager.GroupManager;
 import me.lucko.luckperms.api.manager.TrackManager;
 import me.lucko.luckperms.api.manager.UserManager;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
 import java.util.List;
 import java.util.Set;
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.Executor;
-import java.util.function.Consumer;
-
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
 
 /**
  * A means of loading and saving permission data to/from the backend.
  *
- * <p>All blocking methods return {@link CompletableFuture}s, which will be
- * populated with the result once the data has been loaded/saved asynchronously.
- * Care should be taken when using such methods to ensure that the main server
- * thread is not blocked.</p>
- *
- * <p>Methods such as {@link CompletableFuture#get()} and equivalent should
- * <strong>not</strong> be called on the main server thread. If you need to use
- * the result of these operations on the main server thread, register a
- * callback using {@link CompletableFuture#thenAcceptAsync(Consumer, Executor)}.</p>
- *
  * @since 2.14
  */
 public interface Storage {
@@ -61,82 +50,7 @@ public interface Storage {
      *
      * @return the name of the implementation
      */
-    @Nonnull
-    String getName();
-
-    /**
-     * Loads and returns the entire log from storage
-     *
-     * @return a log instance, could be null if loading failed
-     */
-    @Nonnull
-    CompletableFuture<Log> getLog();
-
-    /**
-     * Gets a set all "unique" user UUIDs.
-     *
-     * <p>"Unique" meaning the user isn't just a member of the "default" group.</p>
-     *
-     * @return a set of uuids, or null if the operation failed.
-     */
-    @Nonnull
-    CompletableFuture<Set<UUID>> getUniqueUsers();
-
-    /**
-     * Searches for a list of users with a given permission.
-     *
-     * @param permission the permission to search for
-     * @return a list of held permissions, or null if the operation failed
-     * @throws NullPointerException if the permission is null
-     * @since 2.17
-     */
-    @Nonnull
-    CompletableFuture<List<HeldPermission<UUID>>> getUsersWithPermission(@Nonnull String permission);
-
-    /**
-     * Searches for a list of groups with a given permission.
-     *
-     * @param permission the permission to search for
-     * @return a list of held permissions, or null if the operation failed
-     * @throws NullPointerException if the permission is null
-     * @since 2.17
-     */
-    @Nonnull
-    CompletableFuture<List<HeldPermission<String>>> getGroupsWithPermission(@Nonnull String permission);
-
-    /**
-     * Saves UUID caching data to the global cache
-     *
-     * @param username the users username
-     * @param uuid     the users mojang unique id
-     * @return true if the operation completed successfully.
-     * @throws NullPointerException     if either parameters are null
-     * @throws IllegalArgumentException if the username is invalid
-     */
-    @Nonnull
-    CompletableFuture<Boolean> saveUUIDData(@Nonnull String username, @Nonnull UUID uuid);
-
-    /**
-     * Gets a UUID from a username
-     *
-     * @param username the corresponding username
-     * @return a uuid object, could be null
-     * @throws NullPointerException     if either parameters are null
-     * @throws IllegalArgumentException if the username is invalid
-     */
-    @Nonnull
-    CompletableFuture<UUID> getUUID(@Nonnull String username);
-
-    /**
-     * Gets a username from a UUID
-     *
-     * @param uuid the corresponding uuid
-     * @return a name string, could be null
-     * @throws NullPointerException if either parameters are null
-     * @since 2.17
-     */
-    @Nonnull
-    CompletableFuture<String> getName(@Nonnull UUID uuid);
+    @NonNull String getName();
 
     /**
      * Gets whether the storage instance is allowing logins on the platform.
@@ -147,34 +61,6 @@ public interface Storage {
     @Deprecated
     boolean isAcceptingLogins();
 
-    /**
-     * Returns an executor which will run all passed runnables on the
-     * main server thread.
-     *
-     * <p>This method is deprecated as plugins should create and use their own
-     * executor instances.</p>
-     *
-     * @return an executor instance
-     * @deprecated as plugins should create their own executors
-     */
-    @Nonnull
-    @Deprecated
-    Executor getSyncExecutor();
-
-    /**
-     * Returns an executor which will run all passed runnables asynchronously
-     * using the platforms scheduler and thread pools.
-     *
-     * <p>This method is deprecated as plugins should create and use their own
-     * executor instances.</p>
-     *
-     * @return an executor instance
-     * @deprecated as plugins should create their own executors
-     */
-    @Nonnull
-    @Deprecated
-    Executor getAsyncExecutor();
-
     /**
      * Saves an action to storage
      *
@@ -183,9 +69,17 @@ public interface Storage {
      * @throws NullPointerException if entry is null
      * @deprecated in favour of {@link ActionLogger#submit(LogEntry)}.
      */
-    @Nonnull
     @Deprecated
-    CompletableFuture<Boolean> logAction(@Nonnull LogEntry entry);
+    @NonNull CompletableFuture<Boolean> logAction(@NonNull LogEntry entry);
+
+    /**
+     * Loads and returns the entire log from storage
+     *
+     * @return a log instance, could be null if loading failed
+     * @deprecated in favour of {@link ActionLogger#getLog()}
+     */
+    @Deprecated
+    @NonNull CompletableFuture<Log> getLog();
 
     /**
      * Loads a user's data from the main storage into the plugins local storage.
@@ -196,9 +90,8 @@ public interface Storage {
      * @throws NullPointerException if uuid is null
      * @deprecated in favour of {@link UserManager#loadUser(UUID, String)}
      */
-    @Nonnull
     @Deprecated
-    CompletableFuture<Boolean> loadUser(@Nonnull UUID uuid, @Nullable String username);
+    @NonNull CompletableFuture<Boolean> loadUser(@NonNull UUID uuid, @Nullable String username);
 
     /**
      * Loads a user's data from the main storage into the plugins local storage.
@@ -208,9 +101,8 @@ public interface Storage {
      * @throws NullPointerException if uuid is null
      * @deprecated in favour of {@link UserManager#loadUser(UUID)}
      */
-    @Nonnull
     @Deprecated
-    default CompletableFuture<Boolean> loadUser(@Nonnull UUID uuid) {
+    default @NonNull CompletableFuture<Boolean> loadUser(@NonNull UUID uuid) {
         return loadUser(uuid, null);
     }
 
@@ -225,9 +117,31 @@ public interface Storage {
      * @throws IllegalStateException if the user instance was not obtained from LuckPerms.
      * @deprecated in favour of {@link UserManager#saveUser(User)}
      */
-    @Nonnull
     @Deprecated
-    CompletableFuture<Boolean> saveUser(@Nonnull User user);
+    @NonNull CompletableFuture<Boolean> saveUser(@NonNull User user);
+
+    /**
+     * Gets a set all "unique" user UUIDs.
+     *
+     * <p>"Unique" meaning the user isn't just a member of the "default" group.</p>
+     *
+     * @return a set of uuids, or null if the operation failed.
+     * @deprecated in favour of {@link UserManager#getUniqueUsers()}
+     */
+    @Deprecated
+    @NonNull CompletableFuture<Set<UUID>> getUniqueUsers();
+
+    /**
+     * Searches for a list of users with a given permission.
+     *
+     * @param permission the permission to search for
+     * @return a list of held permissions, or null if the operation failed
+     * @throws NullPointerException if the permission is null
+     * @since 2.17
+     * @deprecated in favour of {@link UserManager#getWithPermission(String)}
+     */
+    @Deprecated
+    @NonNull CompletableFuture<List<HeldPermission<UUID>>> getUsersWithPermission(@NonNull String permission);
 
     /**
      * Creates and loads a group into the plugins local storage
@@ -238,9 +152,8 @@ public interface Storage {
      * @throws IllegalArgumentException if the name is invalid
      * @deprecated in favour of {@link GroupManager#createAndLoadGroup(String)}
      */
-    @Nonnull
     @Deprecated
-    CompletableFuture<Boolean> createAndLoadGroup(@Nonnull String name);
+    @NonNull CompletableFuture<Boolean> createAndLoadGroup(@NonNull String name);
 
     /**
      * Loads a group into the plugins local storage.
@@ -251,9 +164,8 @@ public interface Storage {
      * @throws IllegalArgumentException if the name is invalid
      * @deprecated in favour of {@link GroupManager#loadGroup(String)}
      */
-    @Nonnull
     @Deprecated
-    CompletableFuture<Boolean> loadGroup(@Nonnull String name);
+    @NonNull CompletableFuture<Boolean> loadGroup(@NonNull String name);
 
     /**
      * Loads all groups from the storage into memory
@@ -261,9 +173,8 @@ public interface Storage {
      * @return true if the operation completed successfully.
      * @deprecated in favour of {@link GroupManager#loadAllGroups()}
      */
-    @Nonnull
     @Deprecated
-    CompletableFuture<Boolean> loadAllGroups();
+    @NonNull CompletableFuture<Boolean> loadAllGroups();
 
     /**
      * Saves a group back to storage.
@@ -276,9 +187,8 @@ public interface Storage {
      * @throws IllegalStateException if the group instance was not obtained from LuckPerms.
      * @deprecated in favour of {@link GroupManager#saveGroup(Group)}
      */
-    @Nonnull
     @Deprecated
-    CompletableFuture<Boolean> saveGroup(@Nonnull Group group);
+    @NonNull CompletableFuture<Boolean> saveGroup(@NonNull Group group);
 
     /**
      * Permanently deletes a group from storage.
@@ -289,9 +199,20 @@ public interface Storage {
      * @throws IllegalStateException if the group instance was not obtained from LuckPerms.
      * @deprecated in favour of {@link GroupManager#deleteGroup(Group)}
      */
-    @Nonnull
     @Deprecated
-    CompletableFuture<Boolean> deleteGroup(@Nonnull Group group);
+    @NonNull CompletableFuture<Boolean> deleteGroup(@NonNull Group group);
+
+    /**
+     * Searches for a list of groups with a given permission.
+     *
+     * @param permission the permission to search for
+     * @return a list of held permissions, or null if the operation failed
+     * @throws NullPointerException if the permission is null
+     * @since 2.17
+     * @deprecated in favour of {@link GroupManager#getWithPermission(String)}
+     */
+    @Deprecated
+    @NonNull CompletableFuture<List<HeldPermission<String>>> getGroupsWithPermission(@NonNull String permission);
 
     /**
      * Creates and loads a track into the plugins local storage
@@ -302,9 +223,8 @@ public interface Storage {
      * @throws IllegalArgumentException if the name is invalid
      * @deprecated in favour of {@link TrackManager#createAndLoadTrack(String)}
      */
-    @Nonnull
     @Deprecated
-    CompletableFuture<Boolean> createAndLoadTrack(@Nonnull String name);
+    @NonNull CompletableFuture<Boolean> createAndLoadTrack(@NonNull String name);
 
     /**
      * Loads a track into the plugins local storage.
@@ -315,9 +235,8 @@ public interface Storage {
      * @throws IllegalArgumentException if the name is invalid
      * @deprecated in favour of {@link TrackManager#loadTrack(String)}
      */
-    @Nonnull
     @Deprecated
-    CompletableFuture<Boolean> loadTrack(@Nonnull String name);
+    @NonNull CompletableFuture<Boolean> loadTrack(@NonNull String name);
 
     /**
      * Loads all tracks from the storage into memory
@@ -325,9 +244,8 @@ public interface Storage {
      * @return true if the operation completed successfully.
      * @deprecated in favour of {@link TrackManager#loadAllTracks()}
      */
-    @Nonnull
     @Deprecated
-    CompletableFuture<Boolean> loadAllTracks();
+    @NonNull CompletableFuture<Boolean> loadAllTracks();
 
     /**
      * Saves a track back to storage. You should call this after you make any changes to a track.
@@ -338,9 +256,8 @@ public interface Storage {
      * @throws IllegalStateException if the track instance was not obtained from LuckPerms.
      * @deprecated in favour of {@link TrackManager#saveTrack(Track)}
      */
-    @Nonnull
     @Deprecated
-    CompletableFuture<Boolean> saveTrack(@Nonnull Track track);
+    @NonNull CompletableFuture<Boolean> saveTrack(@NonNull Track track);
 
     /**
      * Permanently deletes a track from storage
@@ -351,8 +268,65 @@ public interface Storage {
      * @throws IllegalStateException if the track instance was not obtained from LuckPerms.
      * @deprecated in favour of {@link TrackManager#deleteTrack(Track)}
      */
-    @Nonnull
     @Deprecated
-    CompletableFuture<Boolean> deleteTrack(@Nonnull Track track);
+    @NonNull CompletableFuture<Boolean> deleteTrack(@NonNull Track track);
+
+    /**
+     * Saves UUID caching data to the global cache
+     *
+     * @param username the users username
+     * @param uuid     the users mojang unique id
+     * @return true if the operation completed successfully.
+     * @throws NullPointerException     if either parameters are null
+     * @throws IllegalArgumentException if the username is invalid
+     * @deprecated in favour of {@link UserManager#savePlayerData(UUID, String)}
+     */
+    @NonNull CompletableFuture<Boolean> saveUUIDData(@NonNull String username, @NonNull UUID uuid);
+
+    /**
+     * Gets a UUID from a username
+     *
+     * @param username the corresponding username
+     * @return a uuid object, could be null
+     * @throws NullPointerException     if either parameters are null
+     * @throws IllegalArgumentException if the username is invalid
+     * @deprecated in favour of {@link UserManager#lookupUuid(String)}
+     */
+    @NonNull CompletableFuture<UUID> getUUID(@NonNull String username);
+
+    /**
+     * Gets a username from a UUID
+     *
+     * @param uuid the corresponding uuid
+     * @return a name string, could be null
+     * @throws NullPointerException if either parameters are null
+     * @since 2.17
+     * @deprecated in favour of {@link UserManager#lookupUsername(UUID)}
+     */
+    @NonNull @Deprecated CompletableFuture<String> getName(@NonNull UUID uuid);
+
+    /**
+     * Returns an executor which will run all passed runnables on the
+     * main server thread.
+     *
+     * <p>This method is deprecated as plugins should create and use their own
+     * executor instances.</p>
+     *
+     * @return an executor instance
+     * @deprecated as plugins should create their own executors
+     */
+    @NonNull @Deprecated Executor getSyncExecutor();
+
+    /**
+     * Returns an executor which will run all passed runnables asynchronously
+     * using the platforms scheduler and thread pools.
+     *
+     * <p>This method is deprecated as plugins should create and use their own
+     * executor instances.</p>
+     *
+     * @return an executor instance
+     * @deprecated as plugins should create their own executors
+     */
+    @NonNull @Deprecated Executor getAsyncExecutor();
 
 }

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

@@ -23,35 +23,33 @@
  *  SOFTWARE.
  */
 
-package me.lucko.luckperms.common.bulkupdate.comparisons;
+package me.lucko.luckperms.api;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
- * A method of comparing two strings
+ * Extension of {@link DataMutateResult} for temporary set operations.
+ *
+ * @since 4.3
  */
-public interface Comparison {
+public interface TemporaryDataMutateResult {
 
     /**
-     * Gets the symbol which represents this comparison
+     * Gets the underlying result.
      *
-     * @return the comparison symbol
+     * @return the result
      */
-    String getSymbol();
+    @NonNull DataMutateResult getResult();
 
     /**
-     * Compares two strings according to this comparisons
-     * behaviour, and returns if they match.
+     * Gets the node that resulted from any {@link TemporaryMergeBehaviour}
+     * processing.
      *
-     * @param str the string
-     * @param expr the expression
-     * @return if the string matches the expression
-     */
-    boolean matches(String str, String expr);
-
-    /**
-     * Returns the comparison operator in SQL form
+     * <p>If no processing took place, the same instance will be returned by
+     * this method.</p>
      *
-     * @return a sql form of this comparison
+     * @return the resultant node
      */
-    String getAsSql();
+    @NonNull Node getMergedNode();
 
 }

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

@@ -0,0 +1,58 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package me.lucko.luckperms.api;
+
+/**
+ * Controls how the implementation should behave when new temporary nodes are set
+ * that would otherwise conflict with existing entries.
+ *
+ * <p>The default behaviour of {@link PermissionHolder#setPermission(Node)} is
+ * to return a result of {@link DataMutateResult#ALREADY_HAS} when an equivalent
+ * node is found. This can be replicated using {@link #FAIL_WITH_ALREADY_HAS}.</p>
+ *
+ * <p>However, the {@link PermissionHolder#setPermission(Node, TemporaryMergeBehaviour)}
+ * method allows this behaviour to be customized for temporary permissions.</p>
+ *
+ * @since 4.3
+ */
+public enum TemporaryMergeBehaviour {
+
+    /**
+     * Expiry durations will be added to the existing expiry time of a permission.
+     */
+    ADD_NEW_DURATION_TO_EXISTING,
+
+    /**
+     * Expiry durations will be replaced if the new duration is longer than the current one.
+     */
+    REPLACE_EXISTING_IF_DURATION_LONGER,
+
+    /**
+     * The operation will fail if an existing temporary node is present.
+     */
+    FAIL_WITH_ALREADY_HAS
+
+}

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

@@ -25,10 +25,12 @@
 
 package me.lucko.luckperms.api;
 
-import java.util.List;
+import me.lucko.luckperms.api.context.ContextSet;
 
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+import java.util.List;
 
 /**
  * An ordered chain of {@link Group}s.
@@ -40,8 +42,7 @@ public interface Track {
      *
      * @return the name of this track
      */
-    @Nonnull
-    String getName();
+    @NonNull String getName();
 
     /**
      * Gets a list of the groups on this track
@@ -52,8 +53,7 @@ public interface Track {
      *
      * @return an ordered {@link List} of the groups on this track
      */
-    @Nonnull
-    List<String> getGroups();
+    @NonNull List<String> getGroups();
 
     /**
      * Gets the number of groups on this track
@@ -72,8 +72,7 @@ public interface Track {
      * @throws NullPointerException  if the group is null
      * @throws IllegalStateException if the group instance was not obtained from LuckPerms.
      */
-    @Nullable
-    String getNext(@Nonnull Group current);
+    @Nullable String getNext(@NonNull Group current);
 
     /**
      * Gets the previous group on the track, before the one provided
@@ -85,18 +84,37 @@ public interface Track {
      * @throws NullPointerException  if the group is null
      * @throws IllegalStateException if the group instance was not obtained from LuckPerms.
      */
-    @Nullable
-    String getPrevious(@Nonnull Group current);
+    @Nullable String getPrevious(@NonNull Group current);
+
+    /**
+     * Promotes the given user along this track.
+     *
+     * @param user       the user to promote
+     * @param contextSet the contexts to promote the user in
+     * @return the result of the action
+     * @since 4.2
+     */
+    @NonNull PromotionResult promote(@NonNull User user, @NonNull ContextSet contextSet);
+
+    /**
+     * Demotes the given user along this track.
+     *
+     * @param user       the user to demote
+     * @param contextSet the contexts to demote the user in
+     * @return the result of the action
+     * @since 4.2
+     */
+    @NonNull DemotionResult demote(@NonNull User user, @NonNull ContextSet contextSet);
 
     /**
      * Appends a group to the end of this track
      *
      * @param group the group to append
      * @return the result of the operation
-     * @throws NullPointerException      if the group is null
-     * @throws IllegalStateException     if the group instance was not obtained from LuckPerms.
+     * @throws NullPointerException  if the group is null
+     * @throws IllegalStateException if the group instance was not obtained from LuckPerms.
      */
-    DataMutateResult appendGroup(@Nonnull Group group);
+    @NonNull DataMutateResult appendGroup(@NonNull Group group);
 
     /**
      * Inserts a group at a certain position on this track
@@ -108,7 +126,7 @@ public interface Track {
      * @throws NullPointerException      if the group is null
      * @throws IllegalStateException     if the group instance was not obtained from LuckPerms.
      */
-    DataMutateResult insertGroup(@Nonnull Group group, int position) throws IndexOutOfBoundsException;
+    @NonNull DataMutateResult insertGroup(@NonNull Group group, int position) throws IndexOutOfBoundsException;
 
     /**
      * Removes a group from this track
@@ -118,7 +136,7 @@ public interface Track {
      * @throws NullPointerException  if the group is null
      * @throws IllegalStateException if the group instance was not obtained from LuckPerms.
      */
-    DataMutateResult removeGroup(@Nonnull Group group);
+    @NonNull DataMutateResult removeGroup(@NonNull Group group);
 
     /**
      * Removes a group from this track
@@ -127,7 +145,7 @@ public interface Track {
      * @return the result of the operation
      * @throws NullPointerException if the group is null
      */
-    DataMutateResult removeGroup(@Nonnull String group);
+    @NonNull DataMutateResult removeGroup(@NonNull String group);
 
     /**
      * Checks if a group features on this track
@@ -137,7 +155,7 @@ public interface Track {
      * @throws NullPointerException  if the group is null
      * @throws IllegalStateException if the group instance was not obtained from LuckPerms.
      */
-    boolean containsGroup(@Nonnull Group group);
+    boolean containsGroup(@NonNull Group group);
 
     /**
      * Checks if a group features on this track
@@ -146,7 +164,7 @@ public interface Track {
      * @return true if the group is on this track
      * @throws NullPointerException if the group is null
      */
-    boolean containsGroup(@Nonnull String group);
+    boolean containsGroup(@NonNull String group);
 
     /**
      * Clear all of the groups from this track

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

@@ -25,7 +25,7 @@
 
 package me.lucko.luckperms.api;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Represents three different states of a setting.
@@ -61,8 +61,7 @@ public enum Tristate {
      * @param val the boolean value
      * @return {@link #TRUE} or {@link #FALSE}, if the value is <code>true</code> or <code>false</code>, respectively.
      */
-    @Nonnull
-    public static Tristate fromBoolean(boolean val) {
+    public static @NonNull Tristate fromBoolean(boolean val) {
         return val ? TRUE : FALSE;
     }
 
@@ -77,8 +76,7 @@ public enum Tristate {
      *         is <code>null</code>, <code>true</code> or <code>false</code>, respectively.
      * @since 4.1
      */
-    @Nonnull
-    public static Tristate fromNullableBoolean(Boolean val) {
+    public static @NonNull Tristate fromNullableBoolean(Boolean val) {
         return val == null ? UNDEFINED : val ? TRUE : FALSE;
     }
 

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

@@ -27,10 +27,10 @@ package me.lucko.luckperms.api;
 
 import me.lucko.luckperms.api.caching.UserData;
 
-import java.util.UUID;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
 
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
+import java.util.UUID;
 
 /**
  * A player which holds permission data.
@@ -42,39 +42,40 @@ public interface User extends PermissionHolder {
      *
      * @return the users Mojang assigned unique id
      */
-    @Nonnull
-    UUID getUuid();
+    @NonNull UUID getUuid();
 
     /**
      * Gets the users username
      *
-     * <p>Returns null if no username is associated with this user.</p>
+     * <p>Returns null if no username is known for the user.</p>
      *
      * @return the users username
      */
-    @Nullable
-    String getName();
+    @Nullable String getName();
 
     /**
      * Gets the users current primary group.
      *
-     * <p>The result of this method depends on which method is configured for primary group calculation. It may not
-     * be the same as any value set through {@link #setPrimaryGroup(String)}.</p>
+     * <p>The result of this method depends on which method is configured for primary group
+     * calculation. It may not be the same as any value set through
+     * {@link #setPrimaryGroup(String)}.</p>
      *
      * @return the users primary group
      */
-    @Nonnull
-    String getPrimaryGroup();
+    @NonNull String getPrimaryGroup();
 
     /**
-     * Sets a users primary group. This will only take effect if platform is using stored primary groups.
+     * Sets a users primary group.
+     *
+     * <p>This modifies the "stored value" for the users primary group, which may or may not
+     * actually take effect, depending on how the platform is calculating primary groups.</p>
      *
      * @param group the new primary group
      * @return if the change was applied successfully
-     * @throws IllegalStateException     if the user is not a member of that group
-     * @throws NullPointerException      if the group is null
+     * @throws IllegalStateException if the user is not a member of that group
+     * @throws NullPointerException  if the group is null
      */
-    DataMutateResult setPrimaryGroup(@Nonnull String group);
+    @NonNull DataMutateResult setPrimaryGroup(@NonNull String group);
 
     /**
      * Gets the user's {@link UserData} cache.
@@ -82,17 +83,15 @@ public interface User extends PermissionHolder {
      * @return the users cached data.
      * @since 3.2
      */
-    @Nonnull
     @Override
-    UserData getCachedData();
+    @NonNull UserData getCachedData();
 
     /**
      * Refresh and re-assign the users permissions.
      *
-     * <p>This request is not buffered, and the refresh call will be ran directly. This should be called on an
-     * asynchronous thread.</p>
-     *
-     * @deprecated in favour of {@link #refreshCachedData()}.
+     * @deprecated Calling this method is no longer necessary. Permissions data is now refreshed on
+     * demand, as changes are made. Consider use of {@link #refreshCachedData()}
+     * instead. This method is now implemented as a no-op.
      */
     @Deprecated
     void refreshPermissions();
@@ -100,11 +99,8 @@ public interface User extends PermissionHolder {
     /**
      * Pre-calculates some values in the user's data cache.
      *
-     * <p>Is it <b>not</b> necessary to call this method before
-     * using {@link #getCachedData()}.</p>
-     *
      * @since 2.17
-     * @deprecated because use of this method is no longer necessary.
+     * @deprecated Use of this method is no longer necessary. It is implemented as a no-op.
      */
     @Deprecated
     void setupDataCache();

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

@@ -25,16 +25,16 @@
 
 package me.lucko.luckperms.api;
 
-import java.util.UUID;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
-import javax.annotation.Nonnull;
+import java.util.UUID;
 
 /**
  * A UUID cache for online users, between external Mojang UUIDs, and internal
  * LuckPerms UUIDs.
  *
  * @deprecated this feature is now handled internally - and the API returns a
- *             No-op implementation of this class.
+ * No-op implementation of this class.
  */
 @Deprecated
 public interface UuidCache {
@@ -50,9 +50,8 @@ public interface UuidCache {
      *                   <code>ProxiedPlayer#getUniqueId</code>
      * @return the corresponding internal UUID
      */
-    @Nonnull
     @Deprecated
-    UUID getUUID(@Nonnull UUID mojangUuid);
+    @NonNull UUID getUUID(@NonNull UUID mojangUuid);
 
     /**
      * Gets a users "external", server assigned unique id, from the internal
@@ -62,8 +61,7 @@ public interface UuidCache {
      *                     <code>User#getUuid</code>
      * @return the corresponding external UUID
      */
-    @Nonnull
     @Deprecated
-    UUID getExternalUUID(@Nonnull UUID internalUuid);
+    @NonNull UUID getExternalUUID(@NonNull UUID internalUuid);
 
 }

api/src/main/java/me/lucko/luckperms/api/caching/CachedData.java

@@ -28,20 +28,23 @@ package me.lucko.luckperms.api.caching;
 import me.lucko.luckperms.api.Contexts;
 import me.lucko.luckperms.api.PermissionHolder;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Objects;
 import java.util.Set;
 import java.util.concurrent.CompletableFuture;
 
-import javax.annotation.Nonnull;
-
 /**
  * Holds cached permission and meta lookup data for a {@link PermissionHolder}.
  *
- * <p>All calls will account for inheritance, as well as any default data provided by
- * the platform. This calls are heavily cached and are therefore fast.</p>
+ * <p>All calls will account for inheritance, as well as any default data
+ * provided by the platform. This calls are heavily cached and are therefore
+ * fast.</p>
  *
- * <p>For meta, both methods accepting {@link Contexts} and {@link MetaContexts} are provided. The only difference is that
- * the latter allows you to define how the meta stack should be structured internally. Where {@link Contexts} are passed, the
- * values from the configuration are used.</p>
+ * <p>For meta, both methods accepting {@link Contexts} and {@link MetaContexts}
+ * are provided. The only difference is that the latter allows you to define
+ * how the meta stack should be structured internally. Where {@link Contexts}
+ * are passed, the values from the configuration are used.</p>
  *
  * @since 4.0
  */
@@ -54,8 +57,7 @@ public interface CachedData {
      * @return a permission data instance
      * @throws NullPointerException if contexts is null
      */
-    @Nonnull
-    PermissionData getPermissionData(@Nonnull Contexts contexts);
+    @NonNull PermissionData getPermissionData(@NonNull Contexts contexts);
 
     /**
      * Gets MetaData from the cache, given a specified context.
@@ -65,8 +67,7 @@ public interface CachedData {
      * @throws NullPointerException if contexts is null
      * @since 3.2
      */
-    @Nonnull
-    MetaData getMetaData(@Nonnull MetaContexts contexts);
+    @NonNull MetaData getMetaData(@NonNull MetaContexts contexts);
 
     /**
      * Gets MetaData from the cache, given a specified context.
@@ -75,8 +76,7 @@ public interface CachedData {
      * @return a meta data instance
      * @throws NullPointerException if contexts is null
      */
-    @Nonnull
-    MetaData getMetaData(@Nonnull Contexts contexts);
+    @NonNull MetaData getMetaData(@NonNull Contexts contexts);
 
     /**
      * Calculates permission data, bypassing the cache.
@@ -93,8 +93,7 @@ public interface CachedData {
      * @return a permission data instance
      * @throws NullPointerException if contexts is null
      */
-    @Nonnull
-    PermissionData calculatePermissions(@Nonnull Contexts contexts);
+    @NonNull PermissionData calculatePermissions(@NonNull Contexts contexts);
 
     /**
      * Calculates meta data, bypassing the cache.
@@ -112,8 +111,7 @@ public interface CachedData {
      * @throws NullPointerException if contexts is null
      * @since 3.2
      */
-    @Nonnull
-    MetaData calculateMeta(@Nonnull MetaContexts contexts);
+    @NonNull MetaData calculateMeta(@NonNull MetaContexts contexts);
 
     /**
      * Calculates meta data, bypassing the cache.
@@ -130,8 +128,7 @@ public interface CachedData {
      * @return a meta data instance
      * @throws NullPointerException if contexts is null
      */
-    @Nonnull
-    MetaData calculateMeta(@Nonnull Contexts contexts);
+    @NonNull MetaData calculateMeta(@NonNull Contexts contexts);
 
     /**
      * (Re)calculates permission data for a given context.
@@ -149,7 +146,7 @@ public interface CachedData {
      * @param contexts the contexts to recalculate in.
      * @throws NullPointerException if contexts is null
      */
-    void recalculatePermissions(@Nonnull Contexts contexts);
+    void recalculatePermissions(@NonNull Contexts contexts);
 
     /**
      * (Re)calculates meta data for a given context.
@@ -168,7 +165,7 @@ public interface CachedData {
      * @throws NullPointerException if contexts is null
      * @since 3.2
      */
-    void recalculateMeta(@Nonnull MetaContexts contexts);
+    void recalculateMeta(@NonNull MetaContexts contexts);
 
     /**
      * (Re)calculates meta data for a given context.
@@ -186,7 +183,7 @@ public interface CachedData {
      * @param contexts the contexts to recalculate in.
      * @throws NullPointerException if contexts is null
      */
-    void recalculateMeta(@Nonnull Contexts contexts);
+    void recalculateMeta(@NonNull Contexts contexts);
 
     /**
      * (Re)loads permission data for a given context.
@@ -209,12 +206,11 @@ public interface CachedData {
      * until the recalculation has been performed.</p>
      *
      * @param contexts the contexts to reload in.
-     * @throws NullPointerException if contexts is null
      * @return a future
+     * @throws NullPointerException if contexts is null
      * @since 4.0
      */
-    @Nonnull
-    CompletableFuture<? extends PermissionData> reloadPermissions(@Nonnull Contexts contexts);
+    @NonNull CompletableFuture<? extends PermissionData> reloadPermissions(@NonNull Contexts contexts);
 
     /**
      * (Re)loads meta data for a given context.
@@ -237,12 +233,11 @@ public interface CachedData {
      * until the recalculation has been performed.</p>
      *
      * @param contexts the contexts to reload in.
-     * @throws NullPointerException if contexts is null
      * @return a future
+     * @throws NullPointerException if contexts is null
      * @since 4.0
      */
-    @Nonnull
-    CompletableFuture<? extends MetaData> reloadMeta(@Nonnull MetaContexts contexts);
+    @NonNull CompletableFuture<? extends MetaData> reloadMeta(@NonNull MetaContexts contexts);
 
     /**
      * (Re)loads meta data for a given context.
@@ -265,12 +260,11 @@ public interface CachedData {
      * until the recalculation has been performed.</p>
      *
      * @param contexts the contexts to reload in.
-     * @throws NullPointerException if contexts is null
      * @return a future
+     * @throws NullPointerException if contexts is null
      * @since 4.0
      */
-    @Nonnull
-    CompletableFuture<? extends MetaData> reloadMeta(@Nonnull Contexts contexts);
+    @NonNull CompletableFuture<? extends MetaData> reloadMeta(@NonNull Contexts contexts);
 
     /**
      * Recalculates permission data for all known contexts.
@@ -315,8 +309,7 @@ public interface CachedData {
      * @return a future
      * @since 4.0
      */
-    @Nonnull
-    CompletableFuture<Void> reloadPermissions();
+    @NonNull CompletableFuture<Void> reloadPermissions();
 
     /**
      * Reloads meta data for all known contexts.
@@ -339,8 +332,7 @@ public interface CachedData {
      * @return a future
      * @since 4.0
      */
-    @Nonnull
-    CompletableFuture<Void> reloadMeta();
+    @NonNull CompletableFuture<Void> reloadMeta();
 
     /**
      * Pre-calculates and caches {@link PermissionData} and {@link MetaData}
@@ -354,7 +346,7 @@ public interface CachedData {
      * @param contexts a set of contexts
      * @throws NullPointerException if contexts is null
      */
-    default void preCalculate(@Nonnull Set<Contexts> contexts) {
+    default void preCalculate(@NonNull Set<Contexts> contexts) {
         contexts.forEach(this::preCalculate);
     }
 
@@ -370,7 +362,14 @@ public interface CachedData {
      * @param contexts the contexts to pre-calculate for
      * @throws NullPointerException if contexts is null
      */
-    void preCalculate(@Nonnull Contexts contexts);
+    default void preCalculate(@NonNull Contexts contexts) {
+        Objects.requireNonNull(contexts, "contexts");
+
+        // pre-calculate just by requesting the data from this cache.
+        // if the data isn't already loaded, it will be calculated.
+        getPermissionData(contexts);
+        getMetaData(contexts);
+    }
 
     /**
      * Invalidates any cached {@link PermissionData} instances mapped to the given
@@ -379,7 +378,7 @@ public interface CachedData {
      * @param contexts the contexts to invalidate for
      * @since 4.0
      */
-    void invalidatePermissions(@Nonnull Contexts contexts);
+    void invalidatePermissions(@NonNull Contexts contexts);
 
     /**
      * Invalidates any cached {@link MetaData} instances mapped to the given
@@ -388,7 +387,7 @@ public interface CachedData {
      * @param contexts the contexts to invalidate for
      * @since 4.0
      */
-    void invalidateMeta(@Nonnull MetaContexts contexts);
+    void invalidateMeta(@NonNull MetaContexts contexts);
 
     /**
      * Invalidates any cached {@link MetaData} instances mapped to the given
@@ -397,7 +396,29 @@ public interface CachedData {
      * @param contexts the contexts to invalidate for
      * @since 4.0
      */
-    void invalidateMeta(@Nonnull Contexts contexts);
+    void invalidateMeta(@NonNull Contexts contexts);
+
+    /**
+     * Invalidates all cached {@link PermissionData} instances.
+     *
+     * @since 4.2
+     */
+    void invalidatePermissions();
+
+    /**
+     * Invalidates all cached {@link MetaData} instances.
+     *
+     * @since 4.2
+     */
+    void invalidateMeta();
+
+    /**
+     * Invalidates all cached {@link PermissionData} and {@link MetaData}
+     * instances.
+     *
+     * @since 4.5
+     */
+    void invalidate();
 
     /**
      * Invalidates all of the underlying Permission calculators.

api/src/main/java/me/lucko/luckperms/api/caching/CachedDataContainer.java

@@ -27,7 +27,7 @@ package me.lucko.luckperms.api.caching;
 
 import me.lucko.luckperms.api.Contexts;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Holds cached lookup data in a specific set of contexts.
@@ -41,7 +41,6 @@ public interface CachedDataContainer {
      *
      * @return the contexts this container is caching
      */
-    @Nonnull
-    Contexts getContexts();
+    @NonNull Contexts getContexts();
 
 }

api/src/main/java/me/lucko/luckperms/api/caching/MetaContexts.java

@@ -28,10 +28,9 @@ package me.lucko.luckperms.api.caching;
 import me.lucko.luckperms.api.Contexts;
 import me.lucko.luckperms.api.metastacking.MetaStackDefinition;
 
-import java.util.Objects;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
-import javax.annotation.Nonnull;
-import javax.annotation.concurrent.Immutable;
+import java.util.Objects;
 
 /**
  * Encapsulates the options and settings for a meta lookup.
@@ -41,18 +40,17 @@ import javax.annotation.concurrent.Immutable;
  *
  * @since 3.2
  */
-@Immutable
 public final class MetaContexts {
 
     /**
      * Creates a new meta contexts instance
      *
-     * @param contexts the standard contexts for the query
+     * @param contexts              the standard contexts for the query
      * @param prefixStackDefinition the prefix stack definition to be used
      * @param suffixStackDefinition the suffix stack definition to be used
      * @return the new instance
      */
-    public static MetaContexts of(@Nonnull Contexts contexts, @Nonnull MetaStackDefinition prefixStackDefinition, @Nonnull MetaStackDefinition suffixStackDefinition) {
+    public static MetaContexts of(@NonNull Contexts contexts, @NonNull MetaStackDefinition prefixStackDefinition, @NonNull MetaStackDefinition suffixStackDefinition) {
         return new MetaContexts(contexts, prefixStackDefinition, suffixStackDefinition);
     }
 
@@ -66,35 +64,31 @@ public final class MetaContexts {
     /**
      * Creates a new meta contexts instance
      *
-     * @param contexts the standard contexts for the query
+     * @param contexts              the standard contexts for the query
      * @param prefixStackDefinition the prefix stack definition to be used
      * @param suffixStackDefinition the suffix stack definition to be used
      */
-    public MetaContexts(@Nonnull Contexts contexts, @Nonnull MetaStackDefinition prefixStackDefinition, @Nonnull MetaStackDefinition suffixStackDefinition) {
+    public MetaContexts(@NonNull Contexts contexts, @NonNull MetaStackDefinition prefixStackDefinition, @NonNull MetaStackDefinition suffixStackDefinition) {
         this.contexts = Objects.requireNonNull(contexts, "contexts");
         this.prefixStackDefinition = Objects.requireNonNull(prefixStackDefinition, "prefixStackDefinition");
         this.suffixStackDefinition = Objects.requireNonNull(suffixStackDefinition, "suffixStackDefinition");
         this.hashCode = calculateHashCode();
     }
 
-    @Nonnull
-    public Contexts getContexts() {
+    public @NonNull Contexts getContexts() {
         return this.contexts;
     }
 
-    @Nonnull
-    public MetaStackDefinition getPrefixStackDefinition() {
+    public @NonNull MetaStackDefinition getPrefixStackDefinition() {
         return this.prefixStackDefinition;
     }
 
-    @Nonnull
-    public MetaStackDefinition getSuffixStackDefinition() {
+    public @NonNull MetaStackDefinition getSuffixStackDefinition() {
         return this.suffixStackDefinition;
     }
 
     @Override
-    @Nonnull
-    public String toString() {
+    public @NonNull String toString() {
         return "MetaContexts(" +
                 "contexts=" + this.getContexts() + ", " +
                 "prefixStackDefinition=" + this.getPrefixStackDefinition() + ", " +

api/src/main/java/me/lucko/luckperms/api/caching/MetaData.java

@@ -29,12 +29,12 @@ import com.google.common.collect.ListMultimap;
 
 import me.lucko.luckperms.api.metastacking.MetaStackDefinition;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
 import java.util.Map;
 import java.util.SortedMap;
 
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
-
 /**
  * Holds cached meta lookup data for a specific set of contexts.
  *
@@ -47,8 +47,7 @@ public interface MetaData extends CachedDataContainer {
      *
      * @return the contexts this container is caching
      */
-    @Nonnull
-    MetaContexts getMetaContexts();
+    @NonNull MetaContexts getMetaContexts();
 
     /**
      * Gets an immutable copy of the meta this user has.
@@ -62,8 +61,7 @@ public interface MetaData extends CachedDataContainer {
      * @return an immutable multimap of meta
      * @since 3.3
      */
-    @Nonnull
-    ListMultimap<String, String> getMetaMultimap();
+    @NonNull ListMultimap<String, String> getMetaMultimap();
 
     /**
      * Gets an immutable copy of the meta this user has.
@@ -73,8 +71,7 @@ public interface MetaData extends CachedDataContainer {
      *
      * @return an immutable map of meta
      */
-    @Nonnull
-    Map<String, String> getMeta();
+    @NonNull Map<String, String> getMeta();
 
     /**
      * Gets an immutable sorted map of all of the prefixes the user has, whereby the first value is the highest priority
@@ -82,8 +79,7 @@ public interface MetaData extends CachedDataContainer {
      *
      * @return a sorted map of prefixes
      */
-    @Nonnull
-    SortedMap<Integer, String> getPrefixes();
+    @NonNull SortedMap<Integer, String> getPrefixes();
 
     /**
      * Gets an immutable sorted map of all of the suffixes the user has, whereby the first value is the highest priority
@@ -91,24 +87,21 @@ public interface MetaData extends CachedDataContainer {
      *
      * @return a sorted map of suffixes
      */
-    @Nonnull
-    SortedMap<Integer, String> getSuffixes();
+    @NonNull SortedMap<Integer, String> getSuffixes();
 
     /**
      * Gets the user's highest priority prefix, or null if the user has no prefixes
      *
      * @return a prefix string, or null
      */
-    @Nullable
-    String getPrefix();
+    @Nullable String getPrefix();
 
     /**
      * Gets the user's highest priority suffix, or null if the user has no suffixes
      *
      * @return a suffix string, or null
      */
-    @Nullable
-    String getSuffix();
+    @Nullable String getSuffix();
 
     /**
      * Gets the definition used for the prefix stack
@@ -116,8 +109,7 @@ public interface MetaData extends CachedDataContainer {
      * @return the definition used for the prefix stack
      * @since 3.2
      */
-    @Nonnull
-    MetaStackDefinition getPrefixStackDefinition();
+    @NonNull MetaStackDefinition getPrefixStackDefinition();
 
     /**
      * Gets the definition used for the suffix stack
@@ -125,7 +117,6 @@ public interface MetaData extends CachedDataContainer {
      * @return the definition used for the suffix stack
      * @since 3.2
      */
-    @Nonnull
-    MetaStackDefinition getSuffixStackDefinition();
+    @NonNull MetaStackDefinition getSuffixStackDefinition();
 
 }

api/src/main/java/me/lucko/luckperms/api/caching/PermissionData.java

@@ -27,9 +27,9 @@ package me.lucko.luckperms.api.caching;
 
 import me.lucko.luckperms.api.Tristate;
 
-import java.util.Map;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
-import javax.annotation.Nonnull;
+import java.util.Map;
 
 /**
  * Holds cached permission lookup data for a specific set of contexts.
@@ -45,8 +45,7 @@ public interface PermissionData extends CachedDataContainer {
      * @return a tristate result
      * @throws NullPointerException if permission is null
      */
-    @Nonnull
-    Tristate getPermissionValue(@Nonnull String permission);
+    @NonNull Tristate getPermissionValue(@NonNull String permission);
 
     /**
      * Invalidates the underlying permission calculator cache.
@@ -60,7 +59,6 @@ public interface PermissionData extends CachedDataContainer {
      *
      * @return an immutable set of permissions
      */
-    @Nonnull
-    Map<String, Boolean> getImmutableBacking();
+    @NonNull Map<String, Boolean> getImmutableBacking();
 
 }

api/src/main/java/me/lucko/luckperms/api/context/AbstractContextSet.java

@@ -25,70 +25,37 @@
 
 package me.lucko.luckperms.api.context;
 
-import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
-import com.google.common.collect.Multimap;
+import com.google.common.collect.SetMultimap;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.Collection;
-import java.util.Map;
 import java.util.Objects;
 import java.util.Set;
 
-import javax.annotation.Nonnull;
-
 abstract class AbstractContextSet implements ContextSet {
 
-    protected abstract Multimap<String, String> backing();
+    protected abstract SetMultimap<String, String> backing();
 
-    @Nonnull
-    @Override
-    @Deprecated
-    public Map<String, String> toMap() {
-        ImmutableMap.Builder<String, String> m = ImmutableMap.builder();
-        for (Map.Entry<String, String> e : backing().entries()) {
-            m.put(e.getKey(), e.getValue());
-        }
-        return m.build();
-    }
+    protected abstract void copyTo(SetMultimap<String, String> other);
 
     @Override
-    public boolean containsKey(@Nonnull String key) {
+    public boolean containsKey(@NonNull String key) {
         return backing().containsKey(sanitizeKey(key));
     }
 
-    @Nonnull
     @Override
-    public Set<String> getValues(@Nonnull String key) {
+    public @NonNull Set<String> getValues(@NonNull String key) {
         Collection<String> values = backing().asMap().get(sanitizeKey(key));
         return values != null ? ImmutableSet.copyOf(values) : ImmutableSet.of();
     }
 
     @Override
-    public boolean has(@Nonnull String key, @Nonnull String value) {
+    public boolean has(@NonNull String key, @NonNull String value) {
         return backing().containsEntry(sanitizeKey(key), sanitizeValue(value));
     }
 
-    @Override
-    public boolean hasIgnoreCase(@Nonnull String key, @Nonnull String value) {
-        String v = sanitizeValue(value);
-
-        Collection<String> values = backing().asMap().get(sanitizeKey(key));
-        if (values == null || values.isEmpty()) {
-            return false;
-        }
-
-        if (values.contains(v)) {
-            return true;
-        }
-
-        for (String val : values) {
-            if (val.equalsIgnoreCase(v)) {
-                return true;
-            }
-        }
-        return false;
-    }
-
     @Override
     public boolean isEmpty() {
         return backing().isEmpty();
@@ -99,23 +66,6 @@ abstract class AbstractContextSet implements ContextSet {
         return backing().size();
     }
 
-    @Override
-    public boolean equals(Object o) {
-        if (o == this) return true;
-        if (!(o instanceof ContextSet)) return false;
-        final ContextSet that = (ContextSet) o;
-
-        final Multimap<String, String> otherContexts;
-
-        if (that instanceof AbstractContextSet) {
-            otherContexts = ((AbstractContextSet) that).backing();
-        } else {
-            otherContexts = that.toMultimap();
-        }
-
-        return backing().equals(otherContexts);
-    }
-
     @Override
     public int hashCode() {
         return backing().hashCode();
@@ -126,8 +76,7 @@ abstract class AbstractContextSet implements ContextSet {
         if (stringIsEmpty(key)) {
             throw new IllegalArgumentException("key is (effectively) empty");
         }
-
-        return key.toLowerCase().intern();
+        return key.toLowerCase();
     }
 
     static String sanitizeValue(String value) {
@@ -135,8 +84,7 @@ abstract class AbstractContextSet implements ContextSet {
         if (stringIsEmpty(value)) {
             throw new IllegalArgumentException("value is (effectively) empty");
         }
-
-        return value.intern();
+        return value.toLowerCase();
     }
 
     private static boolean stringIsEmpty(String s) {

api/src/main/java/me/lucko/luckperms/api/context/ContextCalculator.java

@@ -25,10 +25,10 @@
 
 package me.lucko.luckperms.api.context;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
- * Calculates whether contexts are applicable to {@link T}
+ * Calculates whether contexts are applicable to a {@link T subject}.
  *
  * @param <T> the subject type. Is ALWAYS the player class of the platform.
  * @since 2.13
@@ -44,7 +44,6 @@ public interface ContextCalculator<T> {
      * @return the map
      * @since 2.13
      */
-    @Nonnull
-    MutableContextSet giveApplicableContext(@Nonnull T subject, @Nonnull MutableContextSet accumulator);
+    @NonNull MutableContextSet giveApplicableContext(@NonNull T subject, @NonNull MutableContextSet accumulator);
 
 }

api/src/main/java/me/lucko/luckperms/api/context/ContextManager.java

@@ -28,9 +28,9 @@ package me.lucko.luckperms.api.context;
 import me.lucko.luckperms.api.Contexts;
 import me.lucko.luckperms.api.User;
 
-import java.util.Optional;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
-import javax.annotation.Nonnull;
+import java.util.Optional;
 
 /**
  * Manages {@link ContextCalculator}s, and calculates applicable contexts for a
@@ -44,9 +44,11 @@ import javax.annotation.Nonnull;
  *
  * <p></p>
  * <ul>
- *     <li>{@code org.bukkit.entity.Player}</li>
- *     <li>{@code net.md_5.bungee.api.connection.ProxiedPlayer}</li>
- *     <li>{@code org.spongepowered.api.service.permission.Subject}</li>
+ * <li>{@code org.bukkit.entity.Player}</li>
+ * <li>{@code net.md_5.bungee.api.connection.ProxiedPlayer}</li>
+ * <li>{@code org.spongepowered.api.service.permission.Subject}</li>
+ * <li>{@code cn.nukkit.Player}</li>
+ * <li>{@code com.velocitypowered.api.proxy.Player}</li>
  * </ul>
  *
  * @since 4.0
@@ -59,8 +61,7 @@ public interface ContextManager {
      * @param subject the subject
      * @return the applicable context for the subject
      */
-    @Nonnull
-    ImmutableContextSet getApplicableContext(@Nonnull Object subject);
+    @NonNull ImmutableContextSet getApplicableContext(@NonNull Object subject);
 
     /**
      * Queries the ContextManager for current context values for the subject.
@@ -68,8 +69,7 @@ public interface ContextManager {
      * @param subject the subject
      * @return the applicable context for the subject
      */
-    @Nonnull
-    Contexts getApplicableContexts(@Nonnull Object subject);
+    @NonNull Contexts getApplicableContexts(@NonNull Object subject);
 
     /**
      * Queries the ContextManager for current context values for the given User.
@@ -83,8 +83,7 @@ public interface ContextManager {
      * @param user the user
      * @return the applicable context for the subject
      */
-    @Nonnull
-    Optional<ImmutableContextSet> lookupApplicableContext(@Nonnull User user);
+    @NonNull Optional<ImmutableContextSet> lookupApplicableContext(@NonNull User user);
 
     /**
      * Queries the ContextManager for current context values for the given User.
@@ -98,8 +97,7 @@ public interface ContextManager {
      * @param user the user
      * @return the applicable context for the subject
      */
-    @Nonnull
-    Optional<Contexts> lookupApplicableContexts(@Nonnull User user);
+    @NonNull Optional<Contexts> lookupApplicableContexts(@NonNull User user);
 
     /**
      * Gets the contexts from the static calculators in this manager.
@@ -109,8 +107,7 @@ public interface ContextManager {
      *
      * @return the current active static contexts
      */
-    @Nonnull
-    ImmutableContextSet getStaticContext();
+    @NonNull ImmutableContextSet getStaticContext();
 
     /**
      * Gets the contexts from the static calculators in this manager.
@@ -120,8 +117,7 @@ public interface ContextManager {
      *
      * @return the current active static contexts
      */
-    @Nonnull
-    Contexts getStaticContexts();
+    @NonNull Contexts getStaticContexts();
 
     /**
      * Forms a {@link Contexts} instance from an {@link ImmutableContextSet}.
@@ -129,12 +125,11 @@ public interface ContextManager {
      * <p>This method relies on the plugins configuration to form the
      * {@link Contexts} instance.</p>
      *
-     * @param subject the reference subject
+     * @param subject    the reference subject
      * @param contextSet the context set
      * @return a contexts instance
      */
-    @Nonnull
-    Contexts formContexts(@Nonnull Object subject, @Nonnull ImmutableContextSet contextSet);
+    @NonNull Contexts formContexts(@NonNull Object subject, @NonNull ImmutableContextSet contextSet);
 
     /**
      * Forms a {@link Contexts} instance from an {@link ImmutableContextSet}.
@@ -145,30 +140,28 @@ public interface ContextManager {
      * @param contextSet the context set
      * @return a contexts instance
      */
-    @Nonnull
-    Contexts formContexts(@Nonnull ImmutableContextSet contextSet);
+    @NonNull Contexts formContexts(@NonNull ImmutableContextSet contextSet);
 
     /**
      * Registers a context calculator with the manager.
      *
      * @param calculator the calculator
      */
-    void registerCalculator(@Nonnull ContextCalculator<?> calculator);
+    void registerCalculator(@NonNull ContextCalculator<?> calculator);
 
     /**
-     * Registers a static context calculator with the manager.
-     *
-     * <p>Static calculators provide the same context for all subjects.</p>
+     * Unregisters a context calculator with the manager.
      *
      * @param calculator the calculator
+     * @since 4.4
      */
-    void registerStaticCalculator(@Nonnull StaticContextCalculator calculator);
+    void unregisterCalculator(@NonNull ContextCalculator<?> calculator);
 
     /**
      * Invalidates the lookup cache for a given subject
      *
      * @param subject the subject
      */
-    void invalidateCache(@Nonnull Object subject);
+    void invalidateCache(@NonNull Object subject);
 
 }

api/src/main/java/me/lucko/luckperms/api/context/ContextSet.java

@@ -27,13 +27,14 @@ package me.lucko.luckperms.api.context;
 
 import com.google.common.collect.Multimap;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Iterator;
 import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
 import java.util.Set;
 
-import javax.annotation.Nonnull;
-
 /**
  * A set of contexts.
  *
@@ -47,9 +48,8 @@ import javax.annotation.Nonnull;
  * <p>Contexts can be combined with each other to form so called
  * "context sets" - simply a collection of context pairs.</p>
  *
- * <p>Context keys are case-insensitive, and will be converted to
- * {@link String#toLowerCase() lowercase} by all implementations.
- * Values however are case-sensitive.</p>
+ * <p>Context keys and values are case-insensitive, and will be converted to
+ * {@link String#toLowerCase() lowercase} by all implementations.</p>
  *
  * <p>Context keys and values may not be null or empty. A key/value will be
  * deemed empty if it's length is zero, or if it consists of only space
@@ -61,7 +61,7 @@ import javax.annotation.Nonnull;
  *
  * @since 2.13
  */
-public interface ContextSet {
+public interface ContextSet extends Iterable<Map.Entry<String, String>> {
 
     /**
      * Creates an {@link ImmutableContextSet} from a context pair.
@@ -71,24 +71,22 @@ public interface ContextSet {
      * @return a new ImmutableContextSet containing one context pair
      * @throws NullPointerException if key or value is null
      */
-    @Nonnull
-    static ImmutableContextSet singleton(@Nonnull String key, @Nonnull String value) {
+    static @NonNull ImmutableContextSet singleton(@NonNull String key, @NonNull String value) {
         return ImmutableContextSet.singleton(key, value);
     }
 
     /**
      * Creates an {@link ImmutableContextSet} from two context pairs.
      *
-     * @param key1 the first key
+     * @param key1   the first key
      * @param value1 the first value
-     * @param key2 the second key
+     * @param key2   the second key
      * @param value2 the second value
      * @return a new ImmutableContextSet containing the two pairs
      * @throws NullPointerException if any of the keys or values are null
      * @since 3.1
      */
-    @Nonnull
-    static ImmutableContextSet of(@Nonnull String key1, @Nonnull String value1, @Nonnull String key2, @Nonnull String value2) {
+    static @NonNull ImmutableContextSet of(@NonNull String key1, @NonNull String value1, @NonNull String key2, @NonNull String value2) {
         return ImmutableContextSet.of(key1, value1, key2, value2);
     }
 
@@ -99,8 +97,7 @@ public interface ContextSet {
      * @return a new ImmutableContextSet representing the pairs in the iterable
      * @throws NullPointerException if the iterable is null
      */
-    @Nonnull
-    static ImmutableContextSet fromEntries(@Nonnull Iterable<? extends Map.Entry<String, String>> iterable) {
+    static @NonNull ImmutableContextSet fromEntries(@NonNull Iterable<? extends Map.Entry<String, String>> iterable) {
         return ImmutableContextSet.fromEntries(iterable);
     }
 
@@ -111,8 +108,7 @@ public interface ContextSet {
      * @return a new ImmutableContextSet representing the pairs from the map
      * @throws NullPointerException if the map is null
      */
-    @Nonnull
-    static ImmutableContextSet fromMap(@Nonnull Map<String, String> map) {
+    static @NonNull ImmutableContextSet fromMap(@NonNull Map<String, String> map) {
         return ImmutableContextSet.fromMap(map);
     }
 
@@ -124,8 +120,7 @@ public interface ContextSet {
      * @throws NullPointerException if the multimap is null
      * @since 2.16
      */
-    @Nonnull
-    static ImmutableContextSet fromMultimap(@Nonnull Multimap<String, String> multimap) {
+    static @NonNull ImmutableContextSet fromMultimap(@NonNull Multimap<String, String> multimap) {
         return ImmutableContextSet.fromMultimap(multimap);
     }
 
@@ -138,8 +133,7 @@ public interface ContextSet {
      * @return a new ImmutableContextSet with the same content and the one provided
      * @throws NullPointerException if contextSet is null
      */
-    @Nonnull
-    static ImmutableContextSet fromSet(@Nonnull ContextSet contextSet) {
+    static @NonNull ImmutableContextSet fromSet(@NonNull ContextSet contextSet) {
         return ImmutableContextSet.fromSet(contextSet);
     }
 
@@ -148,8 +142,7 @@ public interface ContextSet {
      *
      * @return an empty ImmutableContextSet
      */
-    @Nonnull
-    static ImmutableContextSet empty() {
+    static @NonNull ImmutableContextSet empty() {
         return ImmutableContextSet.empty();
     }
 
@@ -170,8 +163,7 @@ public interface ContextSet {
      *
      * @return an immutable representation of this set
      */
-    @Nonnull
-    ImmutableContextSet makeImmutable();
+    @NonNull ImmutableContextSet makeImmutable();
 
     /**
      * Creates a mutable copy of this {@link ContextSet}.
@@ -182,8 +174,7 @@ public interface ContextSet {
      * @return a mutable ContextSet
      * @since 2.16
      */
-    @Nonnull
-    MutableContextSet mutableCopy();
+    @NonNull MutableContextSet mutableCopy();
 
     /**
      * Returns a {@link Set} of {@link Map.Entry}s representing the current
@@ -194,8 +185,7 @@ public interface ContextSet {
      *
      * @return an immutable set
      */
-    @Nonnull
-    Set<Map.Entry<String, String>> toSet();
+    @NonNull Set<Map.Entry<String, String>> toSet();
 
     /**
      * Returns a {@link Map} <b>loosely</b> representing the current state of
@@ -214,9 +204,8 @@ public interface ContextSet {
      * @return an immutable map
      * @deprecated because the resultant map may not contain all data in the ContextSet
      */
-    @Nonnull
     @Deprecated
-    Map<String, String> toMap();
+    @NonNull Map<String, String> toMap();
 
     /**
      * Returns a {@link Multimap} representing the current state of this
@@ -228,8 +217,20 @@ public interface ContextSet {
      * @return a multimap
      * @since 2.16
      */
-    @Nonnull
-    Multimap<String, String> toMultimap();
+    @NonNull Multimap<String, String> toMultimap();
+
+    /**
+     * Returns an {@link Iterator} over each of the context pairs in this set.
+     *
+     * <p>The returned iterator represents the state of the set at the time of creation. It is not
+     * updated as the set changes.</p>
+     *
+     * <p>The iterator does not support {@link Iterator#remove()} calls.</p>
+     *
+     * @return an iterator
+     */
+    @Override
+    @NonNull Iterator<Map.Entry<String, String>> iterator();
 
     /**
      * Returns if the {@link ContextSet} contains at least one value for the
@@ -239,7 +240,7 @@ public interface ContextSet {
      * @return true if the set contains a value for the key
      * @throws NullPointerException if the key is null
      */
-    boolean containsKey(@Nonnull String key);
+    boolean containsKey(@NonNull String key);
 
     /**
      * Returns a {@link Set} of the values mapped to the given key.
@@ -251,8 +252,7 @@ public interface ContextSet {
      * @return a set of values
      * @throws NullPointerException if the key is null
      */
-    @Nonnull
-    Set<String> getValues(@Nonnull String key);
+    @NonNull Set<String> getValues(@NonNull String key);
 
     /**
      * Returns any value from this {@link ContextSet} matching the key, if present.
@@ -264,65 +264,32 @@ public interface ContextSet {
      * @return an optional containing any match
      * @since 3.1
      */
-    @Nonnull
-    default Optional<String> getAnyValue(@Nonnull String key) {
+    default @NonNull Optional<String> getAnyValue(@NonNull String key) {
         return getValues(key).stream().findAny();
     }
 
     /**
      * Returns if the {@link ContextSet} contains a given context pairing.
      *
-     * <p>This lookup is case-sensitive on the value.</p>
-     *
-     * @param key   the key to look for
-     * @param value the value to look for (case sensitive)
-     * @return true if the set contains the context pair
-     * @throws NullPointerException if the key or value is null
-     */
-    boolean has(@Nonnull String key, @Nonnull String value);
-
-    /**
-     * Returns if the {@link ContextSet} contains a given context pairing,
-     * ignoring the case of values.
-     *
-     * <p>This lookup is case-insensitive on the value.</p>
-     *
      * @param key   the key to look for
      * @param value the value to look for
      * @return true if the set contains the context pair
      * @throws NullPointerException if the key or value is null
      */
-    boolean hasIgnoreCase(@Nonnull String key, @Nonnull String value);
+    boolean has(@NonNull String key, @NonNull String value);
 
     /**
      * Returns if the {@link ContextSet} contains a given context pairing.
      *
-     * <p>This lookup is case-sensitive on the value.</p>
-     *
      * @param entry the entry to look for
      * @return true if the set contains the context pair
      * @throws NullPointerException if the key or value is null
      */
-    default boolean has(@Nonnull Map.Entry<String, String> entry) {
+    default boolean has(Map.@NonNull Entry<String, String> entry) {
         Objects.requireNonNull(entry, "entry");
         return has(entry.getKey(), entry.getValue());
     }
 
-    /**
-     * Returns if the {@link ContextSet} contains a given context pairing,
-     * ignoring the case of values.
-     *
-     * <p>This lookup is case-insensitive on the value.</p>
-     *
-     * @param entry the entry to look for
-     * @return true if the set contains the context pair
-     * @throws NullPointerException if the key or value is null
-     */
-    default boolean hasIgnoreCase(@Nonnull Map.Entry<String, String> entry) {
-        Objects.requireNonNull(entry, "entry");
-        return hasIgnoreCase(entry.getKey(), entry.getValue());
-    }
-
     /**
      * Returns if this {@link ContextSet} is fully "satisfied" by another set.
      *
@@ -331,31 +298,11 @@ public interface ContextSet {
      *
      * <p>Mathematically, this method returns true if this set is a <b>subset</b> of the other.</p>
      *
-     * <p>This check is case-sensitive. For a case-insensitive check,
-     * use {@link #isSatisfiedBy(ContextSet, boolean)}.</p>
-     *
      * @param other the other set to check
      * @return true if all entries in this set are also in the other set
      * @since 3.1
      */
-    default boolean isSatisfiedBy(@Nonnull ContextSet other) {
-        return isSatisfiedBy(other, true);
-    }
-
-    /**
-     * Returns if this {@link ContextSet} is fully "satisfied" by another set.
-     *
-     * <p>For a context set to "satisfy" another, it must itself contain all of
-     * the context pairings in the other set.</p>
-     *
-     * <p>Mathematically, this method returns true if this set is a <b>subset</b> of the other.</p>
-     *
-     * @param other the other set to check
-     * @param caseSensitive if the check should be case sensitive
-     * @return true if all entries in this set are also in the other set
-     * @since 3.4
-     */
-    default boolean isSatisfiedBy(@Nonnull ContextSet other, boolean caseSensitive) {
+    default boolean isSatisfiedBy(@NonNull ContextSet other) {
         if (this == other) {
             return true;
         }
@@ -373,14 +320,8 @@ public interface ContextSet {
         } else {
             // neither are empty, we need to compare the individual entries
             for (Map.Entry<String, String> context : toSet()) {
-                if (caseSensitive) {
-                    if (!other.has(context)) {
-                        return false;
-                    }
-                } else {
-                    if (!other.hasIgnoreCase(context)) {
-                        return false;
-                    }
+                if (!other.has(context)) {
+                    return false;
                 }
             }
             return true;

api/src/main/java/me/lucko/luckperms/api/context/ImmutableContextSet.java

@@ -25,22 +25,24 @@
 
 package me.lucko.luckperms.api.context;
 
+import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSetMultimap;
 import com.google.common.collect.Multimap;
+import com.google.common.collect.SetMultimap;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Iterator;
 import java.util.Map;
 import java.util.Objects;
 import java.util.Set;
-
-import javax.annotation.Nonnull;
-import javax.annotation.concurrent.Immutable;
+import java.util.Spliterator;
 
 /**
  * An immutable implementation of {@link ContextSet}.
  *
  * @since 2.16
  */
-@Immutable
 public final class ImmutableContextSet extends AbstractContextSet implements ContextSet {
     private static final ImmutableContextSet EMPTY = new ImmutableContextSet(ImmutableSetMultimap.of());
 
@@ -50,8 +52,7 @@ public final class ImmutableContextSet extends AbstractContextSet implements Con
      * @return a new ImmutableContextSet builder
      * @since 4.1
      */
-    @Nonnull
-    public static Builder builder() {
+    public static @NonNull Builder builder() {
         return new Builder();
     }
 
@@ -63,8 +64,7 @@ public final class ImmutableContextSet extends AbstractContextSet implements Con
      * @return a new ImmutableContextSet containing one context pair
      * @throws NullPointerException if key or value is null
      */
-    @Nonnull
-    public static ImmutableContextSet singleton(@Nonnull String key, @Nonnull String value) {
+    public static @NonNull ImmutableContextSet singleton(@NonNull String key, @NonNull String value) {
         return new ImmutableContextSet(ImmutableSetMultimap.of(sanitizeKey(key), sanitizeValue(value)));
     }
 
@@ -79,8 +79,7 @@ public final class ImmutableContextSet extends AbstractContextSet implements Con
      * @throws NullPointerException if any of the keys or values are null
      * @since 3.1
      */
-    @Nonnull
-    public static ImmutableContextSet of(@Nonnull String key1, @Nonnull String value1, @Nonnull String key2, @Nonnull String value2) {
+    public static @NonNull ImmutableContextSet of(@NonNull String key1, @NonNull String value1, @NonNull String key2, @NonNull String value2) {
         return new ImmutableContextSet(ImmutableSetMultimap.of(
                 sanitizeKey(key1),
                 sanitizeValue(value1),
@@ -96,8 +95,7 @@ public final class ImmutableContextSet extends AbstractContextSet implements Con
      * @return a new ImmutableContextSet representing the pairs in the iterable
      * @throws NullPointerException if the iterable is null
      */
-    @Nonnull
-    public static ImmutableContextSet fromEntries(@Nonnull Iterable<? extends Map.Entry<String, String>> iterable) {
+    public static @NonNull ImmutableContextSet fromEntries(@NonNull Iterable<? extends Map.Entry<String, String>> iterable) {
         Objects.requireNonNull(iterable, "iterable");
         ImmutableContextSet.Builder builder = builder();
         for (Map.Entry<String, String> entry : iterable) {
@@ -113,8 +111,7 @@ public final class ImmutableContextSet extends AbstractContextSet implements Con
      * @return a new ImmutableContextSet representing the pairs from the map
      * @throws NullPointerException if the map is null
      */
-    @Nonnull
-    public static ImmutableContextSet fromMap(@Nonnull Map<String, String> map) {
+    public static @NonNull ImmutableContextSet fromMap(@NonNull Map<String, String> map) {
         return fromEntries(Objects.requireNonNull(map, "map").entrySet());
     }
 
@@ -126,8 +123,7 @@ public final class ImmutableContextSet extends AbstractContextSet implements Con
      * @throws NullPointerException if the multimap is null
      * @since 2.16
      */
-    @Nonnull
-    public static ImmutableContextSet fromMultimap(@Nonnull Multimap<String, String> multimap) {
+    public static @NonNull ImmutableContextSet fromMultimap(@NonNull Multimap<String, String> multimap) {
         return fromEntries(Objects.requireNonNull(multimap, "multimap").entries());
     }
 
@@ -140,8 +136,7 @@ public final class ImmutableContextSet extends AbstractContextSet implements Con
      * @return a new ImmutableContextSet with the same content and the one provided
      * @throws NullPointerException if contextSet is null
      */
-    @Nonnull
-    public static ImmutableContextSet fromSet(@Nonnull ContextSet contextSet) {
+    public static @NonNull ImmutableContextSet fromSet(@NonNull ContextSet contextSet) {
         return Objects.requireNonNull(contextSet, "contextSet").makeImmutable();
     }
 
@@ -150,8 +145,7 @@ public final class ImmutableContextSet extends AbstractContextSet implements Con
      *
      * @return an empty ImmutableContextSet
      */
-    @Nonnull
-    public static ImmutableContextSet empty() {
+    public static @NonNull ImmutableContextSet empty() {
         return EMPTY;
     }
 
@@ -164,40 +158,83 @@ public final class ImmutableContextSet extends AbstractContextSet implements Con
     }
 
     @Override
-    protected Multimap<String, String> backing() {
+    protected SetMultimap<String, String> backing() {
         return this.map;
     }
 
+    @Override
+    protected void copyTo(SetMultimap<String, String> other) {
+        other.putAll(this.map);
+    }
+
     @Override
     public boolean isImmutable() {
         return true;
     }
 
-    @Nonnull
-    @Override
-    @Deprecated // This set is already immutable!
-    public ImmutableContextSet makeImmutable() {
+    @Deprecated
+    @Override // This set is already immutable!
+    public @NonNull ImmutableContextSet makeImmutable() {
         return this;
     }
 
-    @Nonnull
     @Override
-    public MutableContextSet mutableCopy() {
+    public @NonNull MutableContextSet mutableCopy() {
         return MutableContextSet.fromSet(this);
     }
 
-    @Nonnull
     @Override
-    public Set<Map.Entry<String, String>> toSet() {
+    public @NonNull Set<Map.Entry<String, String>> toSet() {
         return this.map.entries();
     }
 
-    @Nonnull
+    @Deprecated
     @Override
-    public Multimap<String, String> toMultimap() {
+    public @NonNull Map<String, String> toMap() {
+        ImmutableMap.Builder<String, String> m = ImmutableMap.builder();
+        for (Map.Entry<String, String> e : this.map.entries()) {
+            m.put(e.getKey(), e.getValue());
+        }
+        return m.build();
+    }
+
+    @Override
+    public @NonNull Multimap<String, String> toMultimap() {
         return this.map;
     }
 
+    @Override
+    public @NonNull Iterator<Map.Entry<String, String>> iterator() {
+        return this.map.entries().iterator();
+    }
+
+    @Override
+    public Spliterator<Map.Entry<String, String>> spliterator() {
+        return this.map.entries().spliterator();
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (o == this) return true;
+        if (!(o instanceof ContextSet)) return false;
+        final ContextSet that = (ContextSet) o;
+
+        // fast(er) path for ImmutableContextSet comparisons
+        if (that instanceof ImmutableContextSet) {
+            ImmutableContextSet immutableThat = (ImmutableContextSet) that;
+            if (this.hashCode != immutableThat.hashCode) return false;
+        }
+
+        final Multimap<String, String> thatBacking;
+        if (that instanceof AbstractContextSet) {
+            thatBacking = ((AbstractContextSet) that).backing();
+        } else {
+            thatBacking = that.toMultimap();
+        }
+
+        return backing().equals(thatBacking);
+    }
+
     @Override
     public int hashCode() {
         return this.hashCode;
@@ -240,8 +277,7 @@ public final class ImmutableContextSet extends AbstractContextSet implements Con
          * @throws NullPointerException if the key or value is null
          * @see MutableContextSet#add(String, String)
          */
-        @Nonnull
-        public Builder add(@Nonnull String key, @Nonnull String value) {
+        public @NonNull Builder add(@NonNull String key, @NonNull String value) {
             put(sanitizeKey(key), sanitizeValue(value));
             return this;
         }
@@ -254,8 +290,7 @@ public final class ImmutableContextSet extends AbstractContextSet implements Con
          * @throws NullPointerException if the entry is null
          * @see MutableContextSet#add(Map.Entry)
          */
-        @Nonnull
-        public Builder add(@Nonnull Map.Entry<String, String> entry) {
+        public @NonNull Builder add(Map.@NonNull Entry<String, String> entry) {
             Objects.requireNonNull(entry, "entry");
             add(entry.getKey(), entry.getValue());
             return this;
@@ -269,8 +304,7 @@ public final class ImmutableContextSet extends AbstractContextSet implements Con
          * @throws NullPointerException if iterable is null
          * @see MutableContextSet#addAll(Iterable)
          */
-        @Nonnull
-        public Builder addAll(@Nonnull Iterable<? extends Map.Entry<String, String>> iterable) {
+        public @NonNull Builder addAll(@NonNull Iterable<? extends Map.Entry<String, String>> iterable) {
             for (Map.Entry<String, String> e : Objects.requireNonNull(iterable, "iterable")) {
                 add(e);
             }
@@ -285,8 +319,7 @@ public final class ImmutableContextSet extends AbstractContextSet implements Con
          * @throws NullPointerException if the map is null
          * @see MutableContextSet#addAll(Map)
          */
-        @Nonnull
-        public Builder addAll(@Nonnull Map<String, String> map) {
+        public @NonNull Builder addAll(@NonNull Map<String, String> map) {
             addAll(Objects.requireNonNull(map, "map").entrySet());
             return this;
         }
@@ -300,8 +333,7 @@ public final class ImmutableContextSet extends AbstractContextSet implements Con
          * @since 3.4
          * @see MutableContextSet#addAll(Multimap)
          */
-        @Nonnull
-        public Builder addAll(@Nonnull Multimap<String, String> multimap) {
+        public @NonNull Builder addAll(@NonNull Multimap<String, String> multimap) {
             addAll(Objects.requireNonNull(multimap, "multimap").entries());
             return this;
         }
@@ -314,8 +346,7 @@ public final class ImmutableContextSet extends AbstractContextSet implements Con
          * @throws NullPointerException if the contextSet is null
          * @see MutableContextSet#addAll(ContextSet)
          */
-        @Nonnull
-        public Builder addAll(@Nonnull ContextSet contextSet) {
+        public @NonNull Builder addAll(@NonNull ContextSet contextSet) {
             Objects.requireNonNull(contextSet, "contextSet");
             if (contextSet instanceof AbstractContextSet) {
                 AbstractContextSet other = ((AbstractContextSet) contextSet);
@@ -334,8 +365,7 @@ public final class ImmutableContextSet extends AbstractContextSet implements Con
          *
          * @return an {@link ImmutableContextSet} from the builder
          */
-        @Nonnull
-        public ImmutableContextSet build() {
+        public @NonNull ImmutableContextSet build() {
             if (this.builder == null) {
                 return empty();
             } else {

api/src/main/java/me/lucko/luckperms/api/context/MutableContextSet.java

@@ -26,18 +26,20 @@
 package me.lucko.luckperms.api.context;
 
 import com.google.common.collect.HashMultimap;
+import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
 import com.google.common.collect.ImmutableSetMultimap;
 import com.google.common.collect.Multimap;
 import com.google.common.collect.Multimaps;
 import com.google.common.collect.SetMultimap;
 
-import java.util.Collection;
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.Iterator;
 import java.util.Map;
 import java.util.Objects;
 import java.util.Set;
-
-import javax.annotation.Nonnull;
+import java.util.Spliterator;
 
 /**
  * A mutable implementation of {@link ContextSet}.
@@ -54,8 +56,7 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
      * @return a new MutableContextSet containing one context pair
      * @throws NullPointerException if key or value is null
      */
-    @Nonnull
-    public static MutableContextSet singleton(@Nonnull String key, @Nonnull String value) {
+    public static @NonNull MutableContextSet singleton(@NonNull String key, @NonNull String value) {
         Objects.requireNonNull(key, "key");
         Objects.requireNonNull(value, "value");
         MutableContextSet set = MutableContextSet.create();
@@ -74,8 +75,7 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
      * @throws NullPointerException if any of the keys or values are null
      * @since 3.1
      */
-    @Nonnull
-    public static MutableContextSet of(@Nonnull String key1, @Nonnull String value1, @Nonnull String key2, @Nonnull String value2) {
+    public static @NonNull MutableContextSet of(@NonNull String key1, @NonNull String value1, @NonNull String key2, @NonNull String value2) {
         Objects.requireNonNull(key1, "key1");
         Objects.requireNonNull(value1, "value1");
         Objects.requireNonNull(key2, "key2");
@@ -93,8 +93,7 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
      * @return a new MutableContextSet representing the pairs in the iterable
      * @throws NullPointerException if the iterable is null
      */
-    @Nonnull
-    public static MutableContextSet fromEntries(@Nonnull Iterable<? extends Map.Entry<String, String>> iterable) {
+    public static @NonNull MutableContextSet fromEntries(@NonNull Iterable<? extends Map.Entry<String, String>> iterable) {
         Objects.requireNonNull(iterable, "iterable");
         MutableContextSet set = create();
         set.addAll(iterable);
@@ -108,8 +107,7 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
      * @return a new MutableContextSet representing the pairs from the map
      * @throws NullPointerException if the map is null
      */
-    @Nonnull
-    public static MutableContextSet fromMap(@Nonnull Map<String, String> map) {
+    public static @NonNull MutableContextSet fromMap(@NonNull Map<String, String> map) {
         Objects.requireNonNull(map, "map");
         MutableContextSet set = create();
         set.addAll(map);
@@ -124,8 +122,7 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
      * @throws NullPointerException if the multimap is null
      * @since 2.16
      */
-    @Nonnull
-    public static MutableContextSet fromMultimap(@Nonnull Multimap<String, String> multimap) {
+    public static @NonNull MutableContextSet fromMultimap(@NonNull Multimap<String, String> multimap) {
         Objects.requireNonNull(multimap, "multimap");
         MutableContextSet set = create();
         set.addAll(multimap);
@@ -141,12 +138,19 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
      * @return a new MutableContextSet with the same content and the one provided
      * @throws NullPointerException if contextSet is null
      */
-    @Nonnull
-    public static MutableContextSet fromSet(@Nonnull ContextSet contextSet) {
+    public static @NonNull MutableContextSet fromSet(@NonNull ContextSet contextSet) {
         Objects.requireNonNull(contextSet, "contextSet");
-        MutableContextSet set = create();
-        set.addAll(contextSet);
-        return set;
+
+        if (contextSet instanceof ImmutableContextSet) {
+            SetMultimap<String, String> map = ((ImmutableContextSet) contextSet).backing();
+            return new MutableContextSet(map);
+        } else if (contextSet instanceof MutableContextSet) {
+            return contextSet.mutableCopy();
+        } else {
+            MutableContextSet set = create();
+            set.addAll(contextSet);
+            return set;
+        }
     }
 
     /**
@@ -154,8 +158,7 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
      *
      * @return a new MutableContextSet
      */
-    @Nonnull
-    public static MutableContextSet create() {
+    public static @NonNull MutableContextSet create() {
         return new MutableContextSet();
     }
 
@@ -165,46 +168,80 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
         this.map = Multimaps.synchronizedSetMultimap(HashMultimap.create());
     }
 
-    private MutableContextSet(MutableContextSet other) {
-        this.map = Multimaps.synchronizedSetMultimap(HashMultimap.create(other.map));
+    private MutableContextSet(SetMultimap<String, String> other) {
+        this.map = Multimaps.synchronizedSetMultimap(HashMultimap.create(other));
     }
 
     @Override
-    protected Multimap<String, String> backing() {
+    protected SetMultimap<String, String> backing() {
         return this.map;
     }
 
+    @Override
+    protected void copyTo(SetMultimap<String, String> other) {
+        synchronized (this.map) {
+            other.putAll(this.map);
+        }
+    }
+
     @Override
     public boolean isImmutable() {
         return false;
     }
 
-    @Nonnull
     @Override
-    public ImmutableContextSet makeImmutable() {
+    public @NonNull ImmutableContextSet makeImmutable() {
         // if the map is empty, don't create a new instance
         if (this.map.isEmpty()) {
             return ImmutableContextSet.empty();
         }
-        return new ImmutableContextSet(ImmutableSetMultimap.copyOf(this.map));
+        synchronized (this.map) {
+            return new ImmutableContextSet(ImmutableSetMultimap.copyOf(this.map));
+        }
     }
 
-    @Nonnull
     @Override
-    public MutableContextSet mutableCopy() {
-        return new MutableContextSet(this);
+    public @NonNull MutableContextSet mutableCopy() {
+        synchronized (this.map) {
+            return new MutableContextSet(this.map);
+        }
     }
 
-    @Nonnull
     @Override
-    public Set<Map.Entry<String, String>> toSet() {
-        return ImmutableSet.copyOf(this.map.entries());
+    public @NonNull Set<Map.Entry<String, String>> toSet() {
+        synchronized (this.map) {
+            // map.entries() returns immutable Map.Entry instances, so we can just call copyOf
+            return ImmutableSet.copyOf(this.map.entries());
+        }
     }
 
-    @Nonnull
+    @Deprecated
     @Override
-    public Multimap<String, String> toMultimap() {
-        return ImmutableSetMultimap.copyOf(this.map);
+    public @NonNull Map<String, String> toMap() {
+        ImmutableMap.Builder<String, String> m = ImmutableMap.builder();
+        synchronized (this.map) {
+            for (Map.Entry<String, String> e : this.map.entries()) {
+                m.put(e.getKey(), e.getValue());
+            }
+        }
+        return m.build();
+    }
+
+    @Override
+    public @NonNull Multimap<String, String> toMultimap() {
+        synchronized (this.map) {
+            return ImmutableSetMultimap.copyOf(this.map);
+        }
+    }
+
+    @Override
+    public @NonNull Iterator<Map.Entry<String, String>> iterator() {
+        return toSet().iterator();
+    }
+
+    @Override
+    public Spliterator<Map.Entry<String, String>> spliterator() {
+        return toSet().spliterator();
     }
 
     /**
@@ -214,7 +251,7 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
      * @param value the value to add
      * @throws NullPointerException if the key or value is null
      */
-    public void add(@Nonnull String key, @Nonnull String value) {
+    public void add(@NonNull String key, @NonNull String value) {
         this.map.put(sanitizeKey(key), sanitizeValue(value));
     }
 
@@ -224,7 +261,7 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
      * @param entry the entry to add
      * @throws NullPointerException if the entry is null
      */
-    public void add(@Nonnull Map.Entry<String, String> entry) {
+    public void add(Map.@NonNull Entry<String, String> entry) {
         Objects.requireNonNull(entry, "entry");
         add(entry.getKey(), entry.getValue());
     }
@@ -235,7 +272,7 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
      * @param iterable an iterable of key value context pairs
      * @throws NullPointerException if iterable is null
      */
-    public void addAll(@Nonnull Iterable<? extends Map.Entry<String, String>> iterable) {
+    public void addAll(@NonNull Iterable<? extends Map.Entry<String, String>> iterable) {
         for (Map.Entry<String, String> e : Objects.requireNonNull(iterable, "iterable")) {
             add(e);
         }
@@ -247,7 +284,7 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
      * @param map the map to add from
      * @throws NullPointerException if the map is null
      */
-    public void addAll(@Nonnull Map<String, String> map) {
+    public void addAll(@NonNull Map<String, String> map) {
         addAll(Objects.requireNonNull(map, "map").entrySet());
     }
 
@@ -258,7 +295,7 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
      * @throws NullPointerException if the map is null
      * @since 3.4
      */
-    public void addAll(@Nonnull Multimap<String, String> multimap) {
+    public void addAll(@NonNull Multimap<String, String> multimap) {
         addAll(Objects.requireNonNull(multimap, "multimap").entries());
     }
 
@@ -268,11 +305,13 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
      * @param contextSet the set to add from
      * @throws NullPointerException if the contextSet is null
      */
-    public void addAll(@Nonnull ContextSet contextSet) {
+    public void addAll(@NonNull ContextSet contextSet) {
         Objects.requireNonNull(contextSet, "contextSet");
         if (contextSet instanceof AbstractContextSet) {
             AbstractContextSet other = ((AbstractContextSet) contextSet);
-            this.map.putAll(other.backing());
+            synchronized (this.map) {
+                other.copyTo(this.map);
+            }
         } else {
             addAll(contextSet.toMultimap());
         }
@@ -282,26 +321,11 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
      * Removes a context from this set.
      *
      * @param key   the key to remove
-     * @param value the value to remove (case sensitive)
-     * @throws NullPointerException if the key or value is null
-     */
-    public void remove(@Nonnull String key, @Nonnull String value) {
-        this.map.remove(sanitizeKey(key), sanitizeValue(value));
-    }
-
-    /**
-     * Removes a context from this set. (case-insensitive)
-     *
-     * @param key   the key to remove
      * @param value the value to remove
      * @throws NullPointerException if the key or value is null
      */
-    public void removeIgnoreCase(@Nonnull String key, @Nonnull String value) {
-        String v = sanitizeValue(value);
-        Collection<String> strings = this.map.asMap().get(sanitizeKey(key));
-        if (strings != null) {
-            strings.removeIf(e -> e.equalsIgnoreCase(v));
-        }
+    public void remove(@NonNull String key, @NonNull String value) {
+        this.map.remove(sanitizeKey(key), sanitizeValue(value));
     }
 
     /**
@@ -310,7 +334,7 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
      * @param key the key to remove
      * @throws NullPointerException if the key is null
      */
-    public void removeAll(@Nonnull String key) {
+    public void removeAll(@NonNull String key) {
         this.map.removeAll(sanitizeKey(key));
     }
 
@@ -321,6 +345,22 @@ public final class MutableContextSet extends AbstractContextSet implements Conte
         this.map.clear();
     }
 
+    @Override
+    public boolean equals(Object o) {
+        if (o == this) return true;
+        if (!(o instanceof ContextSet)) return false;
+        final ContextSet that = (ContextSet) o;
+
+        final Multimap<String, String> thatBacking;
+        if (that instanceof AbstractContextSet) {
+            thatBacking = ((AbstractContextSet) that).backing();
+        } else {
+            thatBacking = that.toMultimap();
+        }
+
+        return backing().equals(thatBacking);
+    }
+
     @Override
     public String toString() {
         return "MutableContextSet(contexts=" + this.map + ")";

api/src/main/java/me/lucko/luckperms/api/context/StaticContextCalculator.java

@@ -25,8 +25,8 @@
 
 package me.lucko.luckperms.api.context;
 
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
  * Extension of {@link ContextCalculator} which provides the same context
@@ -43,20 +43,18 @@ public interface StaticContextCalculator extends ContextCalculator<Object> {
      * @param accumulator a map of contexts to add to
      * @return the map
      */
-    @Nonnull
-    MutableContextSet giveApplicableContext(@Nonnull MutableContextSet accumulator);
+    @NonNull MutableContextSet giveApplicableContext(@NonNull MutableContextSet accumulator);
 
     /**
      * Gives the subject all of the applicable contexts they meet
      *
-     * @param subject the subject to add contexts to
+     * @param subject     the subject to add contexts to
      * @param accumulator a map of contexts to add to
      * @return the map
      */
-    @Nonnull
-    @Override
     @Deprecated
-    default MutableContextSet giveApplicableContext(@Nullable Object subject, @Nonnull MutableContextSet accumulator) {
+    @Override
+    default @NonNull MutableContextSet giveApplicableContext(@Nullable Object subject, @NonNull MutableContextSet accumulator) {
         return giveApplicableContext(accumulator);
     }
 

api/src/main/java/me/lucko/luckperms/api/event/Cancellable.java

@@ -25,9 +25,9 @@
 
 package me.lucko.luckperms.api.event;
 
-import java.util.concurrent.atomic.AtomicBoolean;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
-import javax.annotation.Nonnull;
+import java.util.concurrent.atomic.AtomicBoolean;
 
 /**
  * Represents an event that can be cancelled
@@ -39,8 +39,7 @@ public interface Cancellable {
      *
      * @return the cancellation
      */
-    @Nonnull
-    AtomicBoolean getCancellationState();
+    @NonNull @Param(-1) AtomicBoolean getCancellationState();
 
     /**
      * Returns true if the event is currently cancelled.

api/src/main/java/me/lucko/luckperms/api/event/EventBus.java

@@ -25,30 +25,53 @@
 
 package me.lucko.luckperms.api.event;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+
 import java.util.Set;
 import java.util.function.Consumer;
 
-import javax.annotation.Nonnull;
-
 /**
- * The internal LuckPerms event bus.
+ * The LuckPerms event bus.
  *
- * <p>LuckPerms events are posted to any listeners registered with the bus.</p>
+ * <p>Used to subscribe (or "listen") to LuckPerms events.</p>
  *
  * @since 3.0
  */
 public interface EventBus {
 
     /**
-     * Subscribes to an event.
+     * Registers a new subscription to the given event.
+     *
+     * <p>The returned {@link EventHandler} instance encapsulates the subscription state. It has
+     * methods which can be used to terminate the subscription, or view stats about the nature of
+     * the subscription.</p>
      *
      * @param eventClass the event class
      * @param handler    the event handler
      * @param <T>        the event class
      * @return an event handler instance representing this subscription
      */
-    @Nonnull
-    <T extends LuckPermsEvent> EventHandler<T> subscribe(@Nonnull Class<T> eventClass, @Nonnull Consumer<T> handler);
+    @NonNull <T extends LuckPermsEvent> EventHandler<T> subscribe(@NonNull Class<T> eventClass, @NonNull Consumer<? super T> handler);
+
+    /**
+     * Registers a new subscription to the given event.
+     *
+     * <p>The returned {@link EventHandler} instance encapsulates the subscription state. It has
+     * methods which can be used to terminate the subscription, or view stats about the nature of
+     * the subscription.</p>
+     *
+     * <p>Unlike {@link #subscribe(Class, Consumer)}, this method accepts an additional parameter
+     * for {@code plugin}. This object must be a "plugin" instance on the platform, and is used to
+     * automatically {@link EventHandler#unregister() unregister} the subscription when the
+     * corresponding plugin is disabled.</p>
+     *
+     * @param <T>        the event class
+     * @param plugin     a plugin instance to bind the subscription to.
+     * @param eventClass the event class
+     * @param handler    the event handler
+     * @return an event handler instance representing this subscription
+     */
+    @NonNull <T extends LuckPermsEvent> EventHandler<T> subscribe(Object plugin, @NonNull Class<T> eventClass, @NonNull Consumer<? super T> handler);
 
     /**
      * Gets a set of all registered handlers for a given event.
@@ -57,7 +80,6 @@ public interface EventBus {
      * @param <T>        the event class
      * @return an immutable set of event handlers
      */
-    @Nonnull
-    <T extends LuckPermsEvent> Set<EventHandler<T>> getHandlers(@Nonnull Class<T> eventClass);
+    @NonNull <T extends LuckPermsEvent> Set<EventHandler<T>> getHandlers(@NonNull Class<T> eventClass);
 
 }

api/src/main/java/me/lucko/luckperms/api/event/EventHandler.java

@@ -25,12 +25,12 @@
 
 package me.lucko.luckperms.api.event;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+
 import java.util.function.Consumer;
 
-import javax.annotation.Nonnull;
-
 /**
- * Represents a handler for a LuckPerms event
+ * Represents a subscription to a {@link LuckPermsEvent}.
  *
  * @param <T> the event class
  */
@@ -41,8 +41,7 @@ public interface EventHandler<T extends LuckPermsEvent> extends AutoCloseable {
      *
      * @return the event class
      */
-    @Nonnull
-    Class<T> getEventClass();
+    @NonNull Class<T> getEventClass();
 
     /**
      * Returns true if this handler is active
@@ -63,8 +62,7 @@ public interface EventHandler<T extends LuckPermsEvent> extends AutoCloseable {
      *
      * @return the event consumer
      */
-    @Nonnull
-    Consumer<T> getConsumer();
+    @NonNull Consumer<? super T> getConsumer();
 
     /**
      * Gets the number of times this handler has been called

api/src/main/java/me/lucko/luckperms/api/event/LuckPermsEvent.java

@@ -27,7 +27,7 @@ package me.lucko.luckperms.api.event;
 
 import me.lucko.luckperms.api.LuckPermsApi;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * A superinterface for all LuckPerms events.
@@ -41,7 +41,14 @@ public interface LuckPermsEvent {
      *
      * @return the api instance
      */
-    @Nonnull
-    LuckPermsApi getApi();
+    @NonNull LuckPermsApi getApi();
+
+    /**
+     * Gets the type of the event.
+     *
+     * @return the type of the event
+     * @since 4.4
+     */
+    @NonNull Class<? extends LuckPermsEvent> getEventType();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/Param.java

@@ -23,28 +23,27 @@
  *  SOFTWARE.
  */
 
-package me.lucko.luckperms.common.locale;
+package me.lucko.luckperms.api.event;
 
-import me.lucko.luckperms.common.commands.Arg;
-
-import java.util.List;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 /**
- * Represents a localized instance of a {@link CommandSpec}.
+ * Represents the position of a parameter within an event.
+ *
+ * <p>This is an implementation detail and should not be relied upon.</p>
  */
-public interface LocalizedSpec {
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Param {
 
     /**
-     * Gets the locale manager used to translate the {@link CommandSpec}.
+     * Gets the index of the parameter.
      *
-     * @return the locale manager
+     * @return the index
      */
-    LocaleManager getLocaleManager();
-
-    String description();
-
-    String usage();
-
-    List<Arg> args();
+    int value();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/Sourced.java

@@ -27,7 +27,7 @@ package me.lucko.luckperms.api.event;
 
 import me.lucko.luckperms.api.event.source.Source;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Represents an event with a {@link Source}.
@@ -44,7 +44,6 @@ public interface Sourced {
      *
      * @return the source
      */
-    @Nonnull
-    Source getSource();
+    @NonNull @Param(-1) Source getSource();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/group/GroupCacheLoadEvent.java

@@ -28,8 +28,9 @@ package me.lucko.luckperms.api.event.group;
 import me.lucko.luckperms.api.Group;
 import me.lucko.luckperms.api.caching.GroupData;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Called when a groups {@link GroupData} is loaded.
@@ -43,15 +44,13 @@ public interface GroupCacheLoadEvent extends LuckPermsEvent {
      *
      * @return the group
      */
-    @Nonnull
-    Group getGroup();
+    @NonNull @Param(0) Group getGroup();
 
     /**
      * Gets the data that was loaded
      *
      * @return the loaded data
      */
-    @Nonnull
-    GroupData getLoadedData();
+    @NonNull @Param(1) GroupData getLoadedData();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/group/GroupCreateEvent.java

@@ -27,9 +27,10 @@ package me.lucko.luckperms.api.event.group;
 
 import me.lucko.luckperms.api.Group;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
 import me.lucko.luckperms.api.event.cause.CreationCause;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Called when a group is created
@@ -41,15 +42,13 @@ public interface GroupCreateEvent extends LuckPermsEvent {
      *
      * @return the new group
      */
-    @Nonnull
-    Group getGroup();
+    @NonNull @Param(0) Group getGroup();
 
     /**
      * Gets the cause of the creation
      *
      * @return the cause of the creation
      */
-    @Nonnull
-    CreationCause getCause();
+    @NonNull @Param(1) CreationCause getCause();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/group/GroupDataRecalculateEvent.java

@@ -28,8 +28,9 @@ package me.lucko.luckperms.api.event.group;
 import me.lucko.luckperms.api.Group;
 import me.lucko.luckperms.api.caching.GroupData;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Called when a groups cached data is refreshed
@@ -43,15 +44,13 @@ public interface GroupDataRecalculateEvent extends LuckPermsEvent {
      *
      * @return the group
      */
-    @Nonnull
-    Group getGroup();
+    @NonNull @Param(0) Group getGroup();
 
     /**
      * Gets the data that was recalculated
      *
      * @return the data
      */
-    @Nonnull
-    GroupData getData();
+    @NonNull @Param(1) GroupData getData();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/group/GroupDeleteEvent.java

@@ -27,11 +27,12 @@ package me.lucko.luckperms.api.event.group;
 
 import me.lucko.luckperms.api.Node;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
 import me.lucko.luckperms.api.event.cause.DeletionCause;
 
-import java.util.Set;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
-import javax.annotation.Nonnull;
+import java.util.Set;
 
 /**
  * Called when a group is deleted
@@ -43,23 +44,20 @@ public interface GroupDeleteEvent extends LuckPermsEvent {
      *
      * @return the name of the deleted group
      */
-    @Nonnull
-    String getGroupName();
+    @NonNull @Param(0) String getGroupName();
 
     /**
      * Gets an immutable copy of the groups existing data
      *
      * @return a copy of the groups existing data
      */
-    @Nonnull
-    Set<Node> getExistingData();
+    @NonNull @Param(1) Set<Node> getExistingData();
 
     /**
      * Gets the cause of the deletion
      *
      * @return the cause of the deletion
      */
-    @Nonnull
-    DeletionCause getCause();
+    @NonNull @Param(2) DeletionCause getCause();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/group/GroupLoadEvent.java

@@ -27,8 +27,9 @@ package me.lucko.luckperms.api.event.group;
 
 import me.lucko.luckperms.api.Group;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Called when a group is loaded into memory from the storage.
@@ -42,7 +43,6 @@ public interface GroupLoadEvent extends LuckPermsEvent {
      *
      * @return the group that was loaded
      */
-    @Nonnull
-    Group getGroup();
+    @NonNull @Param(0) Group getGroup();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/log/LogBroadcastEvent.java

@@ -28,8 +28,9 @@ package me.lucko.luckperms.api.event.log;
 import me.lucko.luckperms.api.LogEntry;
 import me.lucko.luckperms.api.event.Cancellable;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Called when a log entry is about to be sent to notifiable players on the platform
@@ -41,8 +42,7 @@ public interface LogBroadcastEvent extends LuckPermsEvent, Cancellable {
      *
      * @return the log entry to be broadcasted
      */
-    @Nonnull
-    LogEntry getEntry();
+    @NonNull @Param(0) LogEntry getEntry();
 
     /**
      * Gets where the log entry originated from.
@@ -50,8 +50,7 @@ public interface LogBroadcastEvent extends LuckPermsEvent, Cancellable {
      * @return the origin of the log
      * @since 3.3
      */
-    @Nonnull
-    Origin getOrigin();
+    @NonNull @Param(1) Origin getOrigin();
 
     /**
      * Represents where a log entry is from

api/src/main/java/me/lucko/luckperms/api/event/log/LogNetworkPublishEvent.java

@@ -28,11 +28,12 @@ package me.lucko.luckperms.api.event.log;
 import me.lucko.luckperms.api.LogEntry;
 import me.lucko.luckperms.api.event.Cancellable;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.UUID;
 
-import javax.annotation.Nonnull;
-
 /**
  * Called when a log is about to be published to the network via the MessagingService
  *
@@ -45,15 +46,13 @@ public interface LogNetworkPublishEvent extends LuckPermsEvent, Cancellable {
      *
      * @return the id of the log entry being published
      */
-    @Nonnull
-    UUID getLogId();
+    @NonNull @Param(0) UUID getLogId();
 
     /**
      * Gets the log entry to be published
      *
      * @return the log entry to be published
      */
-    @Nonnull
-    LogEntry getEntry();
+    @NonNull @Param(1) LogEntry getEntry();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/log/LogNotifyEvent.java

@@ -29,8 +29,9 @@ import me.lucko.luckperms.api.Entity;
 import me.lucko.luckperms.api.LogEntry;
 import me.lucko.luckperms.api.event.Cancellable;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Called when a log entry is about to be sent to specific notifiable object on
@@ -49,24 +50,21 @@ public interface LogNotifyEvent extends LuckPermsEvent, Cancellable {
      *
      * @return the log entry to be sent
      */
-    @Nonnull
-    LogEntry getEntry();
+    @NonNull @Param(0) LogEntry getEntry();
 
     /**
      * Gets where the log entry originated from.
      *
      * @return the origin of the log
      */
-    @Nonnull
-    Origin getOrigin();
+    @NonNull @Param(1) Origin getOrigin();
 
     /**
      * Gets the object to be notified.
      *
      * @return the object to notify
      */
-    @Nonnull
-    Entity getNotifiable();
+    @NonNull @Param(2) Entity getNotifiable();
 
     /**
      * Represents where a log entry is from

api/src/main/java/me/lucko/luckperms/api/event/log/LogPublishEvent.java

@@ -28,8 +28,9 @@ package me.lucko.luckperms.api.event.log;
 import me.lucko.luckperms.api.LogEntry;
 import me.lucko.luckperms.api.event.Cancellable;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Called when a log is about to be published to the storage file/table
@@ -41,7 +42,6 @@ public interface LogPublishEvent extends LuckPermsEvent, Cancellable {
      *
      * @return the log entry to be published
      */
-    @Nonnull
-    LogEntry getEntry();
+    @NonNull @Param(0) LogEntry getEntry();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/log/LogReceiveEvent.java

@@ -27,11 +27,12 @@ package me.lucko.luckperms.api.event.log;
 
 import me.lucko.luckperms.api.LogEntry;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.UUID;
 
-import javax.annotation.Nonnull;
-
 /**
  * Called when a log entry is received via the MessagingService
  *
@@ -44,15 +45,13 @@ public interface LogReceiveEvent extends LuckPermsEvent {
      *
      * @return the id of the log entry being received
      */
-    @Nonnull
-    UUID getLogId();
+    @NonNull @Param(0) UUID getLogId();
 
     /**
      * Gets the log entry being received
      *
      * @return the log entry being received
      */
-    @Nonnull
-    LogEntry getEntry();
+    @NonNull @Param(1) LogEntry getEntry();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/node/NodeAddEvent.java

@@ -26,8 +26,9 @@
 package me.lucko.luckperms.api.event.node;
 
 import me.lucko.luckperms.api.Node;
+import me.lucko.luckperms.api.event.Param;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Called when a node is added to a holder
@@ -39,7 +40,6 @@ public interface NodeAddEvent extends NodeMutateEvent {
      *
      * @return the node that was added
      */
-    @Nonnull
-    Node getNode();
+    @NonNull @Param(3) Node getNode();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/node/NodeMutateEvent.java

@@ -25,14 +25,17 @@
 
 package me.lucko.luckperms.api.event.node;
 
+import me.lucko.luckperms.api.Group;
 import me.lucko.luckperms.api.Node;
 import me.lucko.luckperms.api.PermissionHolder;
+import me.lucko.luckperms.api.User;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.Set;
 
-import javax.annotation.Nonnull;
-
 /**
  * Called when a node is added to/removed from a user/group
  */
@@ -43,24 +46,21 @@ public interface NodeMutateEvent extends LuckPermsEvent {
      *
      * @return the event target
      */
-    @Nonnull
-    PermissionHolder getTarget();
+    @NonNull @Param(0) PermissionHolder getTarget();
 
     /**
      * Gets an immutable copy of the holders data before the change
      *
      * @return the data before the change
      */
-    @Nonnull
-    Set<Node> getDataBefore();
+    @NonNull @Param(1) Set<Node> getDataBefore();
 
     /**
      * Gets an immutable copy of the holders data after the change
      *
      * @return the data after the change
      */
-    @Nonnull
-    Set<Node> getDataAfter();
+    @NonNull @Param(2) Set<Node> getDataAfter();
 
     /**
      * Gets whether the target of this event is a {@link me.lucko.luckperms.api.User}
@@ -69,7 +69,9 @@ public interface NodeMutateEvent extends LuckPermsEvent {
      *
      * @return if the event is targeting a user
      */
-    boolean isUser();
+    default boolean isUser() {
+        return getTarget() instanceof User;
+    }
 
     /**
      * Gets whether the target of this event is a {@link me.lucko.luckperms.api.Group}
@@ -78,6 +80,8 @@ public interface NodeMutateEvent extends LuckPermsEvent {
      *
      * @return if the event is targeting a group
      */
-    boolean isGroup();
+    default boolean isGroup() {
+        return getTarget() instanceof Group;
+    }
 
 }

api/src/main/java/me/lucko/luckperms/api/event/node/NodeRemoveEvent.java

@@ -26,8 +26,9 @@
 package me.lucko.luckperms.api.event.node;
 
 import me.lucko.luckperms.api.Node;
+import me.lucko.luckperms.api.event.Param;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Called when a node is removed from a holder
@@ -39,7 +40,6 @@ public interface NodeRemoveEvent extends NodeMutateEvent {
      *
      * @return the node that was removed
      */
-    @Nonnull
-    Node getNode();
+    @NonNull @Param(3) Node getNode();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/player/PlayerDataSaveEvent.java

@@ -0,0 +1,67 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package me.lucko.luckperms.api.event.player;
+
+import me.lucko.luckperms.api.PlayerSaveResult;
+import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
+import me.lucko.luckperms.api.manager.UserManager;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+import java.util.UUID;
+
+/**
+ * Called when player data is saved to the storage.
+ *
+ * <p>Data can be saved using {@link UserManager#savePlayerData(UUID, String)}.</p>
+ *
+ * @since 4.3
+ */
+public interface PlayerDataSaveEvent extends LuckPermsEvent {
+
+    /**
+     * Gets the unique ID that was saved.
+     *
+     * @return the uuid
+     */
+    @NonNull @Param(0) UUID getUuid();
+
+    /**
+     * Gets the username that was saved.
+     *
+     * @return the username
+     */
+    @NonNull @Param(1) String getUsername();
+
+    /**
+     * Gets the result of the operation.
+     *
+     * @return the result
+     */
+    @NonNull @Param(2) PlayerSaveResult getResult();
+
+}

api/src/main/java/me/lucko/luckperms/api/event/player/PlayerLoginProcessEvent.java

@@ -23,50 +23,68 @@
  *  SOFTWARE.
  */
 
-package me.lucko.luckperms.api.event.user;
+package me.lucko.luckperms.api.event.player;
 
 import me.lucko.luckperms.api.User;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
 
 import java.util.UUID;
 
-import javax.annotation.Nonnull;
-
 /**
- * Called when LuckPerms has finished processing a certain Player's connection.
+ * Called when LuckPerms has finished processing a Player's initial connection.
  *
- * <p>This event will always execute during the platforms async login/auth event.
- * All handlers will be called instantly.</p>
+ * <p>This event will always execute during the platforms async connection
+ * event. The LuckPerms platform listener processing the connection will block
+ * while this event is posted.</p>
  *
- * <p>This, among other things, allows you to wait until permission data is loaded
- * for a User during the BungeeCord 'LoginEvent', as event priorities are ignored
- * by the current implementation.</p>
+ * <p>This, among other things, allows you to wait until permission data is
+ * loaded for a User during the BungeeCord 'LoginEvent', as event priorities are
+ * ignored by the current implementation.</p>
  *
- * @since 3.4
+ * <p>The implementation will make an attempt to ensure this event is called
+ * for all connections, even if the operation to load User data was not
+ * successful. Note that LuckPerms will usually cancel the platform connection
+ * event if data could not be loaded.</p>
+ *
+ * @since 4.4
  */
-public interface UserLoginProcessEvent extends LuckPermsEvent {
+public interface PlayerLoginProcessEvent extends LuckPermsEvent {
 
     /**
      * Gets the UUID of the connection which was processed
      *
      * @return the uuid of the connection which was processed
      */
-    @Nonnull
-    UUID getUuid();
+    @NonNull @Param(0) UUID getUuid();
 
     /**
      * Gets the username of the connection which was processed
      *
      * @return the username of the connection which was processed
      */
-    @Nonnull
-    String getUsername();
+    @NonNull @Param(1) String getUsername();
+
+    /**
+     * Gets if the login was processed successfully.
+     *
+     * @return true if the login was successful
+     */
+    default boolean wasSuccessful() {
+        return getUser() != null;
+    }
 
     /**
      * Gets the resultant User instance which was loaded.
      *
+     * <p>Returns {@code null} if the login was not processed
+     * {@link #wasSuccessful() successfully.}</p>
+     *
      * @return the user instance
      */
-    User getUser();
+    @Nullable @Param(2) User getUser();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/source/EntitySource.java

@@ -27,7 +27,7 @@ package me.lucko.luckperms.api.event.source;
 
 import me.lucko.luckperms.api.Entity;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Represents an {@link Entity} which was the {@link Source} of something.
@@ -41,7 +41,6 @@ public interface EntitySource extends Source {
      *
      * @return the entity
      */
-    @Nonnull
-    Entity getEntity();
+    @NonNull Entity getEntity();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/source/Source.java

@@ -27,7 +27,7 @@ package me.lucko.luckperms.api.event.source;
 
 import me.lucko.luckperms.api.Entity;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Represents the source of an event.
@@ -43,8 +43,7 @@ public interface Source {
      *
      * @return the type
      */
-    @Nonnull
-    Type getType();
+    @NonNull Type getType();
 
     /**
      * Represents a type of source

api/src/main/java/me/lucko/luckperms/api/event/sync/PreNetworkSyncEvent.java

@@ -27,11 +27,12 @@ package me.lucko.luckperms.api.event.sync;
 
 import me.lucko.luckperms.api.event.Cancellable;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.UUID;
 
-import javax.annotation.Nonnull;
-
 /**
  * Called before a received network sync task runs
  */
@@ -42,7 +43,6 @@ public interface PreNetworkSyncEvent extends LuckPermsEvent, Cancellable {
      *
      * @return the id of the sync request
      */
-    @Nonnull
-    UUID getSyncId();
+    @NonNull @Param(0) UUID getSyncId();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/track/TrackCreateEvent.java

@@ -27,9 +27,10 @@ package me.lucko.luckperms.api.event.track;
 
 import me.lucko.luckperms.api.Track;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
 import me.lucko.luckperms.api.event.cause.CreationCause;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Called when a track is created
@@ -41,15 +42,13 @@ public interface TrackCreateEvent extends LuckPermsEvent {
      *
      * @return the new track
      */
-    @Nonnull
-    Track getTrack();
+    @NonNull @Param(0) Track getTrack();
 
     /**
      * Gets the cause of the creation
      *
      * @return the cause of the creation
      */
-    @Nonnull
-    CreationCause getCause();
+    @NonNull @Param(1) CreationCause getCause();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/track/TrackDeleteEvent.java

@@ -26,11 +26,12 @@
 package me.lucko.luckperms.api.event.track;
 
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
 import me.lucko.luckperms.api.event.cause.DeletionCause;
 
-import java.util.List;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
-import javax.annotation.Nonnull;
+import java.util.List;
 
 /**
  * Called when a track is deleted
@@ -42,23 +43,20 @@ public interface TrackDeleteEvent extends LuckPermsEvent {
      *
      * @return the name of the deleted track
      */
-    @Nonnull
-    String getTrackName();
+    @NonNull @Param(0) String getTrackName();
 
     /**
      * Gets an immutable copy of the tracks existing data
      *
      * @return a copy of the tracks existing data
      */
-    @Nonnull
-    List<String> getExistingData();
+    @NonNull @Param(1) List<String> getExistingData();
 
     /**
      * Gets the cause of the deletion
      *
      * @return the cause of the deletion
      */
-    @Nonnull
-    DeletionCause getCause();
+    @NonNull @Param(2) DeletionCause getCause();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/track/TrackLoadEvent.java

@@ -27,8 +27,9 @@ package me.lucko.luckperms.api.event.track;
 
 import me.lucko.luckperms.api.Track;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Called when a track is loaded into memory from the storage.
@@ -42,7 +43,6 @@ public interface TrackLoadEvent extends LuckPermsEvent {
      *
      * @return the track that was loaded
      */
-    @Nonnull
-    Track getTrack();
+    @NonNull @Param(0) Track getTrack();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/track/mutate/TrackAddGroupEvent.java

@@ -25,7 +25,9 @@
 
 package me.lucko.luckperms.api.event.track.mutate;
 
-import javax.annotation.Nonnull;
+import me.lucko.luckperms.api.event.Param;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Called when a group is added to a track
@@ -37,7 +39,6 @@ public interface TrackAddGroupEvent extends TrackMutateEvent {
      *
      * @return the group that was added
      */
-    @Nonnull
-    String getGroup();
+    @NonNull @Param(3) String getGroup();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/track/mutate/TrackMutateEvent.java

@@ -27,11 +27,12 @@ package me.lucko.luckperms.api.event.track.mutate;
 
 import me.lucko.luckperms.api.Track;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.List;
 
-import javax.annotation.Nonnull;
-
 /**
  * Called when a track is changed
  */
@@ -42,23 +43,20 @@ public interface TrackMutateEvent extends LuckPermsEvent {
      *
      * @return the track that was mutated
      */
-    @Nonnull
-    Track getTrack();
+    @NonNull @Param(0) Track getTrack();
 
     /**
      * Gets an immutable copy of the tracks data before the change
      *
      * @return the data before the change
      */
-    @Nonnull
-    List<String> getDataBefore();
+    @NonNull @Param(1) List<String> getDataBefore();
 
     /**
      * Gets an immutable copy of the tracks data after the change
      *
      * @return the data after the change
      */
-    @Nonnull
-    List<String> getDataAfter();
+    @NonNull @Param(2) List<String> getDataAfter();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/track/mutate/TrackRemoveGroupEvent.java

@@ -25,7 +25,9 @@
 
 package me.lucko.luckperms.api.event.track.mutate;
 
-import javax.annotation.Nonnull;
+import me.lucko.luckperms.api.event.Param;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Called when a group is removed from a track
@@ -37,7 +39,6 @@ public interface TrackRemoveGroupEvent extends TrackMutateEvent {
      *
      * @return the group that was removed
      */
-    @Nonnull
-    String getGroup();
+    @NonNull @Param(3) String getGroup();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/user/UserCacheLoadEvent.java

@@ -28,11 +28,12 @@ package me.lucko.luckperms.api.event.user;
 import me.lucko.luckperms.api.User;
 import me.lucko.luckperms.api.caching.UserData;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
- * Called when a users {@link me.lucko.luckperms.api.caching.UserData} is loaded.
+ * Called when a users {@link UserData} is loaded.
  */
 public interface UserCacheLoadEvent extends LuckPermsEvent {
 
@@ -41,15 +42,13 @@ public interface UserCacheLoadEvent extends LuckPermsEvent {
      *
      * @return the user
      */
-    @Nonnull
-    User getUser();
+    @NonNull @Param(0) User getUser();
 
     /**
      * Gets the data that was loaded
      *
      * @return the loaded data
      */
-    @Nonnull
-    UserData getLoadedData();
+    @NonNull @Param(1) UserData getLoadedData();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/user/UserDataRecalculateEvent.java

@@ -28,8 +28,9 @@ package me.lucko.luckperms.api.event.user;
 import me.lucko.luckperms.api.User;
 import me.lucko.luckperms.api.caching.UserData;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Called when a users cached data is refreshed
@@ -41,15 +42,13 @@ public interface UserDataRecalculateEvent extends LuckPermsEvent {
      *
      * @return the user
      */
-    @Nonnull
-    User getUser();
+    @NonNull @Param(0) User getUser();
 
     /**
      * Gets the data that was recalculated
      *
      * @return the data
      */
-    @Nonnull
-    UserData getData();
+    @NonNull @Param(1) UserData getData();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/user/UserFirstLoginEvent.java

@@ -26,11 +26,12 @@
 package me.lucko.luckperms.api.event.user;
 
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.UUID;
 
-import javax.annotation.Nonnull;
-
 /**
  * Called when the user logs into the network for the first time.
  *
@@ -49,15 +50,13 @@ public interface UserFirstLoginEvent extends LuckPermsEvent {
      *
      * @return the uuid of the user
      */
-    @Nonnull
-    UUID getUuid();
+    @NonNull @Param(0) UUID getUuid();
 
     /**
      * Gets the username of the user
      *
      * @return the username of the user
      */
-    @Nonnull
-    String getUsername();
+    @NonNull @Param(1) String getUsername();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/user/UserLoadEvent.java

@@ -27,8 +27,9 @@ package me.lucko.luckperms.api.event.user;
 
 import me.lucko.luckperms.api.User;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Called when a user is loaded into memory from the storage.
@@ -40,7 +41,6 @@ public interface UserLoadEvent extends LuckPermsEvent {
      *
      * @return the user that was loaded
      */
-    @Nonnull
-    User getUser();
+    @NonNull @Param(0) User getUser();
 
 }

api/src/main/java/me/lucko/luckperms/api/event/user/track/UserDemoteEvent.java

@@ -25,6 +25,8 @@
 
 package me.lucko.luckperms.api.event.user.track;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+
 /**
  * Called when a user is demoted down a track.
  *
@@ -32,4 +34,8 @@ package me.lucko.luckperms.api.event.user.track;
  */
 public interface UserDemoteEvent extends UserTrackEvent {
 
+    @Override
+    default @NonNull TrackAction getAction() {
+        return TrackAction.DEMOTION;
+    }
 }

api/src/main/java/me/lucko/luckperms/api/event/user/track/UserPromoteEvent.java

@@ -25,6 +25,8 @@
 
 package me.lucko.luckperms.api.event.user.track;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+
 /**
  * Called when a user is promoted up a track.
  *
@@ -32,4 +34,8 @@ package me.lucko.luckperms.api.event.user.track;
  */
 public interface UserPromoteEvent extends UserTrackEvent {
 
+    @Override
+    default @NonNull TrackAction getAction() {
+        return TrackAction.PROMOTION;
+    }
 }

api/src/main/java/me/lucko/luckperms/api/event/user/track/UserTrackEvent.java

@@ -28,11 +28,12 @@ package me.lucko.luckperms.api.event.user.track;
 import me.lucko.luckperms.api.Track;
 import me.lucko.luckperms.api.User;
 import me.lucko.luckperms.api.event.LuckPermsEvent;
+import me.lucko.luckperms.api.event.Param;
 import me.lucko.luckperms.api.event.Sourced;
 
-import java.util.Optional;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
-import javax.annotation.Nonnull;
+import java.util.Optional;
 
 /**
  * Called when a user interacts with a track through a promotion or demotion
@@ -44,24 +45,21 @@ public interface UserTrackEvent extends LuckPermsEvent, Sourced {
      *
      * @return the track involved in the event
      */
-    @Nonnull
-    Track getTrack();
+    @NonNull @Param(0) Track getTrack();
 
     /**
      * Gets the user who was promoted or demoted
      *
      * @return the user involved in the event
      */
-    @Nonnull
-    User getUser();
+    @NonNull @Param(1) User getUser();
 
     /**
      * Gets the action performed
      *
      * @return the action performed
      */
-    @Nonnull
-    TrackAction getAction();
+    @NonNull TrackAction getAction();
 
     /**
      * Gets the group the user was promoted/demoted from.
@@ -70,15 +68,13 @@ public interface UserTrackEvent extends LuckPermsEvent, Sourced {
      *
      * @return the group the user was promoted/demoted from
      */
-    @Nonnull
-    Optional<String> getGroupFrom();
+    @NonNull @Param(2) Optional<String> getGroupFrom();
 
     /**
      * Gets the group the user was promoted/demoted to
      *
      * @return the group the user was promoted/demoted to
      */
-    @Nonnull
-    Optional<String> getGroupTo();
+    @NonNull @Param(3) Optional<String> getGroupTo();
 
 }

api/src/main/java/me/lucko/luckperms/api/manager/CachedDataManager.java

@@ -0,0 +1,53 @@
+/*
+ * This file is part of LuckPerms, licensed under the MIT License.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy
+ *  of this software and associated documentation files (the "Software"), to deal
+ *  in the Software without restriction, including without limitation the rights
+ *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ *  copies of the Software, and to permit persons to whom the Software is
+ *  furnished to do so, subject to the following conditions:
+ *
+ *  The above copyright notice and this permission notice shall be included in all
+ *  copies or substantial portions of the Software.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+package me.lucko.luckperms.api.manager;
+
+import me.lucko.luckperms.api.Group;
+import me.lucko.luckperms.api.User;
+import me.lucko.luckperms.api.caching.CachedData;
+
+/**
+ * Represents an object responsible for managing {@link CachedData} instances.
+ *
+ * @since 4.5
+ */
+public interface CachedDataManager {
+
+    /**
+     * Invalidate the {@link CachedData} instances for all loaded {@link User}s.
+     *
+     * @see CachedData#invalidate()
+     */
+    void invalidateAllUserCaches();
+
+    /**
+     * Invalidate the {@link CachedData} instances for all loaded {@link Group}s.
+     *
+     * @see CachedData#invalidate()
+     */
+    void invalidateAllGroupCaches();
+
+}

api/src/main/java/me/lucko/luckperms/api/manager/GroupManager.java

@@ -26,18 +26,32 @@
 package me.lucko.luckperms.api.manager;
 
 import me.lucko.luckperms.api.Group;
+import me.lucko.luckperms.api.HeldPermission;
 import me.lucko.luckperms.api.Storage;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+import java.util.List;
 import java.util.Optional;
 import java.util.Set;
 import java.util.concurrent.CompletableFuture;
-
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
+import java.util.concurrent.Executor;
+import java.util.function.Consumer;
 
 /**
  * Represents the object responsible for managing {@link Group} instances.
  *
+ * <p>All blocking methods return {@link CompletableFuture}s, which will be
+ * populated with the result once the data has been loaded/saved asynchronously.
+ * Care should be taken when using such methods to ensure that the main server
+ * thread is not blocked.</p>
+ *
+ * <p>Methods such as {@link CompletableFuture#get()} and equivalent should
+ * <strong>not</strong> be called on the main server thread. If you need to use
+ * the result of these operations on the main server thread, register a
+ * callback using {@link CompletableFuture#thenAcceptAsync(Consumer, Executor)}.</p>
+ *
  * @since 4.0
  */
 public interface GroupManager {
@@ -60,8 +74,7 @@ public interface GroupManager {
      * @throws NullPointerException if the name is null
      * @since 4.1
      */
-    @Nonnull
-    CompletableFuture<Group> createAndLoadGroup(@Nonnull String name);
+    @NonNull CompletableFuture<Group> createAndLoadGroup(@NonNull String name);
 
     /**
      * Loads a group from the plugin's storage provider into memory.
@@ -81,8 +94,7 @@ public interface GroupManager {
      * @throws NullPointerException if the name is null
      * @since 4.1
      */
-    @Nonnull
-    CompletableFuture<Optional<Group>> loadGroup(@Nonnull String name);
+    @NonNull CompletableFuture<Optional<Group>> loadGroup(@NonNull String name);
 
     /**
      * Saves a group's data back to the plugin's storage provider.
@@ -101,8 +113,7 @@ public interface GroupManager {
      * @throws IllegalStateException if the group instance was not obtained from LuckPerms.
      * @since 4.1
      */
-    @Nonnull
-    CompletableFuture<Void> saveGroup(@Nonnull Group group);
+    @NonNull CompletableFuture<Void> saveGroup(@NonNull Group group);
 
     /**
      * Permanently deletes a group from the plugin's storage provider.
@@ -113,15 +124,13 @@ public interface GroupManager {
      * <p>Unlike the method in {@link Storage}, when a group cannot be deleted,
      * the future will be {@link CompletableFuture completed exceptionally}.</p>
      *
-     *
      * @param group the group to delete
      * @return a future to encapsulate the operation.
      * @throws NullPointerException  if group is null
      * @throws IllegalStateException if the group instance was not obtained from LuckPerms.
      * @since 4.1
      */
-    @Nonnull
-    CompletableFuture<Void> deleteGroup(@Nonnull Group group);
+    @NonNull CompletableFuture<Void> deleteGroup(@NonNull Group group);
 
     /**
      * Loads all groups into memory.
@@ -135,8 +144,17 @@ public interface GroupManager {
      * @return a future to encapsulate the operation.
      * @since 4.1
      */
-    @Nonnull
-    CompletableFuture<Void> loadAllGroups();
+    @NonNull CompletableFuture<Void> loadAllGroups();
+
+    /**
+     * Searches for a list of groups with a given permission.
+     *
+     * @param permission the permission to search for
+     * @return a list of held permissions, or null if the operation failed
+     * @throws NullPointerException if the permission is null
+     * @since 4.2
+     */
+    @NonNull CompletableFuture<List<HeldPermission<String>>> getWithPermission(@NonNull String permission);
 
     /**
      * Gets a loaded group.
@@ -145,8 +163,7 @@ public interface GroupManager {
      * @return a {@link Group} object, if one matching the name exists, or null if not
      * @throws NullPointerException if the name is null
      */
-    @Nullable
-    Group getGroup(@Nonnull String name);
+    @Nullable Group getGroup(@NonNull String name);
 
     /**
      * Gets a loaded group.
@@ -157,8 +174,7 @@ public interface GroupManager {
      * @return an optional {@link Group} object
      * @throws NullPointerException if the name is null
      */
-    @Nonnull
-    default Optional<Group> getGroupOpt(@Nonnull String name) {
+    default @NonNull Optional<Group> getGroupOpt(@NonNull String name) {
         return Optional.ofNullable(getGroup(name));
     }
 
@@ -167,8 +183,7 @@ public interface GroupManager {
      *
      * @return a {@link Set} of {@link Group} objects
      */
-    @Nonnull
-    Set<Group> getLoadedGroups();
+    @NonNull Set<Group> getLoadedGroups();
 
     /**
      * Check if a group is loaded in memory
@@ -177,6 +192,6 @@ public interface GroupManager {
      * @return true if the group is loaded
      * @throws NullPointerException if the name is null
      */
-    boolean isLoaded(@Nonnull String name);
+    boolean isLoaded(@NonNull String name);
 
 }

api/src/main/java/me/lucko/luckperms/api/manager/TrackManager.java

@@ -28,16 +28,28 @@ package me.lucko.luckperms.api.manager;
 import me.lucko.luckperms.api.Storage;
 import me.lucko.luckperms.api.Track;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
 import java.util.Optional;
 import java.util.Set;
 import java.util.concurrent.CompletableFuture;
-
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
+import java.util.concurrent.Executor;
+import java.util.function.Consumer;
 
 /**
  * Represents the object responsible for managing {@link Track} instances.
  *
+ * <p>All blocking methods return {@link CompletableFuture}s, which will be
+ * populated with the result once the data has been loaded/saved asynchronously.
+ * Care should be taken when using such methods to ensure that the main server
+ * thread is not blocked.</p>
+ *
+ * <p>Methods such as {@link CompletableFuture#get()} and equivalent should
+ * <strong>not</strong> be called on the main server thread. If you need to use
+ * the result of these operations on the main server thread, register a
+ * callback using {@link CompletableFuture#thenAcceptAsync(Consumer, Executor)}.</p>
+ *
  * @since 4.0
  */
 public interface TrackManager {
@@ -60,8 +72,7 @@ public interface TrackManager {
      * @throws NullPointerException if the name is null
      * @since 4.1
      */
-    @Nonnull
-    CompletableFuture<Track> createAndLoadTrack(@Nonnull String name);
+    @NonNull CompletableFuture<Track> createAndLoadTrack(@NonNull String name);
 
     /**
      * Loads a track from the plugin's storage provider into memory.
@@ -81,8 +92,7 @@ public interface TrackManager {
      * @throws NullPointerException if the name is null
      * @since 4.1
      */
-    @Nonnull
-    CompletableFuture<Optional<Track>> loadTrack(@Nonnull String name);
+    @NonNull CompletableFuture<Optional<Track>> loadTrack(@NonNull String name);
 
     /**
      * Saves a track's data back to the plugin's storage provider.
@@ -101,8 +111,7 @@ public interface TrackManager {
      * @throws IllegalStateException if the track instance was not obtained from LuckPerms.
      * @since 4.1
      */
-    @Nonnull
-    CompletableFuture<Void> saveTrack(@Nonnull Track track);
+    @NonNull CompletableFuture<Void> saveTrack(@NonNull Track track);
 
     /**
      * Permanently deletes a track from the plugin's storage provider.
@@ -113,15 +122,13 @@ public interface TrackManager {
      * <p>Unlike the method in {@link Storage}, when a track cannot be deleted,
      * the future will be {@link CompletableFuture completed exceptionally}.</p>
      *
-     *
      * @param track the track to delete
      * @return a future to encapsulate the operation.
      * @throws NullPointerException  if track is null
      * @throws IllegalStateException if the track instance was not obtained from LuckPerms.
      * @since 4.1
      */
-    @Nonnull
-    CompletableFuture<Void> deleteTrack(@Nonnull Track track);
+    @NonNull CompletableFuture<Void> deleteTrack(@NonNull Track track);
 
     /**
      * Loads all tracks into memory.
@@ -135,8 +142,7 @@ public interface TrackManager {
      * @return a future to encapsulate the operation.
      * @since 4.1
      */
-    @Nonnull
-    CompletableFuture<Void> loadAllTracks();
+    @NonNull CompletableFuture<Void> loadAllTracks();
 
     /**
      * Gets a loaded track.
@@ -145,8 +151,7 @@ public interface TrackManager {
      * @return a {@link Track} object, if one matching the name exists, or null if not
      * @throws NullPointerException if the name is null
      */
-    @Nullable
-    Track getTrack(@Nonnull String name);
+    @Nullable Track getTrack(@NonNull String name);
 
     /**
      * Gets a loaded track.
@@ -157,8 +162,7 @@ public interface TrackManager {
      * @return an optional {@link Track} object
      * @throws NullPointerException if the name is null
      */
-    @Nonnull
-    default Optional<Track> getTrackOpt(@Nonnull String name) {
+    default @NonNull Optional<Track> getTrackOpt(@NonNull String name) {
         return Optional.ofNullable(getTrack(name));
     }
 
@@ -167,8 +171,7 @@ public interface TrackManager {
      *
      * @return a {@link Set} of {@link Track} objects
      */
-    @Nonnull
-    Set<Track> getLoadedTracks();
+    @NonNull Set<Track> getLoadedTracks();
 
     /**
      * Check if a track is loaded in memory
@@ -177,6 +180,6 @@ public interface TrackManager {
      * @return true if the track is loaded
      * @throws NullPointerException if the name is null
      */
-    boolean isLoaded(@Nonnull String name);
+    boolean isLoaded(@NonNull String name);
 
 }

api/src/main/java/me/lucko/luckperms/api/manager/UserManager.java

@@ -25,16 +25,21 @@
 
 package me.lucko.luckperms.api.manager;
 
+import me.lucko.luckperms.api.HeldPermission;
+import me.lucko.luckperms.api.PlayerSaveResult;
 import me.lucko.luckperms.api.Storage;
 import me.lucko.luckperms.api.User;
 
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+import java.util.List;
 import java.util.Optional;
 import java.util.Set;
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
-
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
+import java.util.concurrent.Executor;
+import java.util.function.Consumer;
 
 /**
  * Represents the object responsible for managing {@link User} instances.
@@ -42,6 +47,16 @@ import javax.annotation.Nullable;
  * <p>Note that User instances are automatically loaded for online players.
  * It's likely that offline players will not have an instance pre-loaded.</p>
  *
+ * <p>All blocking methods return {@link CompletableFuture}s, which will be
+ * populated with the result once the data has been loaded/saved asynchronously.
+ * Care should be taken when using such methods to ensure that the main server
+ * thread is not blocked.</p>
+ *
+ * <p>Methods such as {@link CompletableFuture#get()} and equivalent should
+ * <strong>not</strong> be called on the main server thread. If you need to use
+ * the result of these operations on the main server thread, register a
+ * callback using {@link CompletableFuture#thenAcceptAsync(Consumer, Executor)}.</p>
+ *
  * @since 4.0
  */
 public interface UserManager {
@@ -56,14 +71,13 @@ public interface UserManager {
      * <p>Unlike the method in {@link Storage}, when a user cannot be loaded,
      * the future will be {@link CompletableFuture completed exceptionally}.</p>
      *
-     * @param uuid the uuid of the user
+     * @param uuid     the uuid of the user
      * @param username the username, if known
      * @return the resultant user
      * @throws NullPointerException if the uuid is null
      * @since 4.1
      */
-    @Nonnull
-    CompletableFuture<User> loadUser(@Nonnull UUID uuid, @Nullable String username);
+    @NonNull CompletableFuture<User> loadUser(@NonNull UUID uuid, @Nullable String username);
 
     /**
      * Loads a user from the plugin's storage provider into memory.
@@ -80,11 +94,34 @@ public interface UserManager {
      * @throws NullPointerException if the uuid is null
      * @since 4.1
      */
-    @Nonnull
-    default CompletableFuture<User> loadUser(@Nonnull UUID uuid) {
+    default @NonNull CompletableFuture<User> loadUser(@NonNull UUID uuid) {
         return loadUser(uuid, null);
     }
 
+    /**
+     * Uses the LuckPerms cache to find a uuid for the given username.
+     *
+     * <p>This lookup is case insensitive.</p>
+     *
+     * @param username the username
+     * @return a uuid, could be null
+     * @throws NullPointerException     if either parameters are null
+     * @throws IllegalArgumentException if the username is invalid
+     * @since 4.2
+     */
+    @NonNull CompletableFuture<UUID> lookupUuid(@NonNull String username);
+
+    /**
+     * Uses the LuckPerms cache to find a username for the given uuid.
+     *
+     * @param uuid the uuid
+     * @return a username, could be null
+     * @throws NullPointerException     if either parameters are null
+     * @throws IllegalArgumentException if the username is invalid
+     * @since 4.2
+     */
+    @NonNull CompletableFuture<String> lookupUsername(@NonNull UUID uuid);
+
     /**
      * Saves a user's data back to the plugin's storage provider.
      *
@@ -102,8 +139,39 @@ public interface UserManager {
      * @throws IllegalStateException if the user instance was not obtained from LuckPerms.
      * @since 4.1
      */
-    @Nonnull
-    CompletableFuture<Void> saveUser(@Nonnull User user);
+    @NonNull CompletableFuture<Void> saveUser(@NonNull User user);
+
+    /**
+     * Saves data about a player to the uuid caching system.
+     *
+     * @param uuid     the users mojang unique id
+     * @param username the users username
+     * @return the result of the operation.
+     * @throws NullPointerException     if either parameters are null
+     * @throws IllegalArgumentException if the username is invalid
+     * @since 4.2
+     */
+    @NonNull CompletableFuture<PlayerSaveResult> savePlayerData(@NonNull UUID uuid, @NonNull String username);
+
+    /**
+     * Gets a set all "unique" user UUIDs.
+     *
+     * <p>"Unique" meaning the user isn't just a member of the "default" group.</p>
+     *
+     * @return a set of uuids
+     * @since 4.2
+     */
+    @NonNull CompletableFuture<Set<UUID>> getUniqueUsers();
+
+    /**
+     * Searches for a list of users with a given permission.
+     *
+     * @param permission the permission to search for
+     * @return a list of held permissions
+     * @throws NullPointerException if the permission is null
+     * @since 4.2
+     */
+    @NonNull CompletableFuture<List<HeldPermission<UUID>>> getWithPermission(@NonNull String permission);
 
     /**
      * Gets a loaded user.
@@ -112,8 +180,7 @@ public interface UserManager {
      * @return a {@link User} object, if one matching the uuid is loaded, or null if not
      * @throws NullPointerException if the uuid is null
      */
-    @Nullable
-    User getUser(@Nonnull UUID uuid);
+    @Nullable User getUser(@NonNull UUID uuid);
 
     /**
      * Gets a loaded user.
@@ -122,8 +189,7 @@ public interface UserManager {
      * @return an optional {@link User} object
      * @throws NullPointerException if the uuid is null
      */
-    @Nonnull
-    default Optional<User> getUserOpt(@Nonnull UUID uuid) {
+    default @NonNull Optional<User> getUserOpt(@NonNull UUID uuid) {
         return Optional.ofNullable(getUser(uuid));
     }
 
@@ -134,8 +200,7 @@ public interface UserManager {
      * @return a {@link User} object, if one matching the uuid is loaded, or null if not
      * @throws NullPointerException if the name is null
      */
-    @Nullable
-    User getUser(@Nonnull String name);
+    @Nullable User getUser(@NonNull String name);
 
     /**
      * Gets a loaded user.
@@ -144,8 +209,7 @@ public interface UserManager {
      * @return an optional {@link User} object
      * @throws NullPointerException if the name is null
      */
-    @Nonnull
-    default Optional<User> getUserOpt(@Nonnull String name) {
+    default @NonNull Optional<User> getUserOpt(@NonNull String name) {
         return Optional.ofNullable(getUser(name));
     }
 
@@ -154,8 +218,7 @@ public interface UserManager {
      *
      * @return a {@link Set} of {@link User} objects
      */
-    @Nonnull
-    Set<User> getLoadedUsers();
+    @NonNull Set<User> getLoadedUsers();
 
     /**
      * Check if a user is loaded in memory
@@ -164,7 +227,7 @@ public interface UserManager {
      * @return true if the user is loaded
      * @throws NullPointerException if the uuid is null
      */
-    boolean isLoaded(@Nonnull UUID uuid);
+    boolean isLoaded(@NonNull UUID uuid);
 
     /**
      * Unload a user from the internal storage, if they're not currently online.
@@ -172,6 +235,6 @@ public interface UserManager {
      * @param user the user to unload
      * @throws NullPointerException if the user is null
      */
-    void cleanupUser(@Nonnull User user);
+    void cleanupUser(@NonNull User user);
 
 }

api/src/main/java/me/lucko/luckperms/api/messenger/IncomingMessageConsumer.java

@@ -28,11 +28,11 @@ package me.lucko.luckperms.api.messenger;
 import me.lucko.luckperms.api.messenger.message.Message;
 import me.lucko.luckperms.api.messenger.message.OutgoingMessage;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Encapsulates the LuckPerms system which accepts incoming {@link Message}s
- * from implementations of {@link MessengerProvider}.
+ * from implementations of {@link Messenger}.
  *
  * @since 4.1
  */
@@ -52,7 +52,7 @@ public interface IncomingMessageConsumer {
      * @param message the message
      * @return true if the message was accepted by the plugin
      */
-    boolean consumeIncomingMessage(@Nonnull Message message);
+    boolean consumeIncomingMessage(@NonNull Message message);
 
     /**
      * Consumes a message in an encoded string format.
@@ -73,6 +73,6 @@ public interface IncomingMessageConsumer {
      * @param encodedString the encoded string
      * @return true if the message was accepted by the plugin
      */
-    boolean consumeIncomingMessageAsString(@Nonnull String encodedString);
+    boolean consumeIncomingMessageAsString(@NonNull String encodedString);
 
 }

api/src/main/java/me/lucko/luckperms/api/messenger/Messenger.java

@@ -28,7 +28,7 @@ package me.lucko.luckperms.api.messenger;
 import me.lucko.luckperms.api.messenger.message.Message;
 import me.lucko.luckperms.api.messenger.message.OutgoingMessage;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Represents an object which dispatches {@link OutgoingMessage}s.
@@ -45,12 +45,18 @@ public interface Messenger extends AutoCloseable {
      * of the interfaces extending {@link Message} in the
      * 'api.messenger.message.type' package.</p>
      *
+     * <p>3rd party implementations are encouraged to implement this method with consideration
+     * that new types may be added in the future.</p>
+     *
      * <p>This call is always made async.</p>
      *
      * @param outgoingMessage the outgoing message
      */
-    void sendOutgoingMessage(@Nonnull OutgoingMessage outgoingMessage);
+    void sendOutgoingMessage(@NonNull OutgoingMessage outgoingMessage);
 
+    /**
+     * Performs the necessary action to gracefully shutdown the messenger.
+     */
     @Override
     default void close() {
 

api/src/main/java/me/lucko/luckperms/api/messenger/MessengerProvider.java

@@ -27,7 +27,7 @@ package me.lucko.luckperms.api.messenger;
 
 import me.lucko.luckperms.api.LuckPermsApi;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Represents a provider for {@link Messenger} instances.
@@ -35,8 +35,8 @@ import javax.annotation.Nonnull;
  * <p>Users wishing to provide their own implementation for the plugins
  * "Messaging Service" should implement and register this interface.</p>
  *
- * @since 4.1
  * @see LuckPermsApi#registerMessengerProvider(MessengerProvider)
+ * @since 4.1
  */
 public interface MessengerProvider {
 
@@ -45,8 +45,7 @@ public interface MessengerProvider {
      *
      * @return the provider name
      */
-    @Nonnull
-    String getName();
+    @NonNull String getName();
 
     /**
      * Creates and returns a new {@link Messenger} instance, which passes
@@ -59,7 +58,6 @@ public interface MessengerProvider {
      *                                incoming messages to
      * @return a new messenger agent instance
      */
-    @Nonnull
-    Messenger obtain(@Nonnull IncomingMessageConsumer incomingMessageConsumer);
+    @NonNull Messenger obtain(@NonNull IncomingMessageConsumer incomingMessageConsumer);
 
 }

api/src/main/java/me/lucko/luckperms/api/messenger/message/Message.java

@@ -27,9 +27,9 @@ package me.lucko.luckperms.api.messenger.message;
 
 import me.lucko.luckperms.api.messenger.Messenger;
 
-import java.util.UUID;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
-import javax.annotation.Nonnull;
+import java.util.UUID;
 
 /**
  * Represents a message sent received via a {@link Messenger}.
@@ -46,7 +46,6 @@ public interface Message {
      *
      * @return the id of the message
      */
-    @Nonnull
-    UUID getId();
+    @NonNull UUID getId();
 
 }

api/src/main/java/me/lucko/luckperms/api/messenger/message/OutgoingMessage.java

@@ -27,7 +27,7 @@ package me.lucko.luckperms.api.messenger.message;
 
 import me.lucko.luckperms.api.messenger.IncomingMessageConsumer;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Represents an outgoing {@link Message}.
@@ -56,7 +56,6 @@ public interface OutgoingMessage extends Message {
      *
      * @return an encoded string form of the message
      */
-    @Nonnull
-    String asEncodedString();
+    @NonNull String asEncodedString();
 
 }

api/src/main/java/me/lucko/luckperms/api/messenger/message/type/LogMessage.java

@@ -28,7 +28,7 @@ package me.lucko.luckperms.api.messenger.message.type;
 import me.lucko.luckperms.api.LogEntry;
 import me.lucko.luckperms.api.messenger.message.Message;
 
-import javax.annotation.Nonnull;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Represents an "log" message.
@@ -44,7 +44,6 @@ public interface LogMessage extends Message {
      *
      * @return the log entry
      */
-    @Nonnull
-    LogEntry getLogEntry();
+    @NonNull LogEntry getLogEntry();
 
 }

api/src/main/java/me/lucko/luckperms/api/messenger/message/type/UserUpdateMessage.java

@@ -27,9 +27,9 @@ package me.lucko.luckperms.api.messenger.message.type;
 
 import me.lucko.luckperms.api.messenger.message.Message;
 
-import java.util.UUID;
+import org.checkerframework.checker.nullness.qual.NonNull;
 
-import javax.annotation.Nonnull;
+import java.util.UUID;
 
 /**
  * Represents an "user update" message.
@@ -45,7 +45,6 @@ public interface UserUpdateMessage extends Message {
      *
      * @return the user
      */
-    @Nonnull
-    UUID getUser();
+    @NonNull UUID getUser();
 
 }