Audience Keys

api/src/main/java/net/kyori/adventure/audience/Audience.java

@@ -24,17 +24,20 @@
 package net.kyori.adventure.audience;
 
 import java.util.Arrays;
+import java.util.UUID;
 import java.util.stream.Collector;
 import net.kyori.adventure.bossbar.BossBar;
 import net.kyori.adventure.identity.Identity;
 import net.kyori.adventure.inventory.Book;
+import net.kyori.adventure.key.Key;
 import net.kyori.adventure.sound.Sound;
 import net.kyori.adventure.sound.SoundStop;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.ComponentLike;
 import net.kyori.adventure.title.Title;
 import net.kyori.adventure.identity.Identified;
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
  * A receiver of Minecraft media.
@@ -78,6 +81,23 @@
  * @since 4.0.0
  */
 public interface Audience {
+  /**
+   * A display name.
+   *
+   * <p>Commonly (but not always) available for audiences which are a player.</p>
+   *
+   * @since 4.8.0
+   */
+  AudienceKey<Component> DISPLAY_NAME = AudienceKey.audienceKey(Component.class, Key.key("adventure", "display_name"));
+  /**
+   * A uuid.
+   *
+   * <p>Commonly (but not always) available for audiences which are a world, entity, or player.</p>
+   *
+   * @since 4.8.0
+   */
+  AudienceKey<UUID> UUID = AudienceKey.audienceKey(UUID.class, Key.key("adventure", "uuid"));
+
   /**
    * Gets an audience that does nothing.
    *
@@ -133,6 +153,18 @@ public interface Audience {
     return Audiences.COLLECTOR;
   }
 
+  /**
+   * Gets the value of {@code key}.
+   *
+   * @param key the key
+   * @param <T> the type
+   * @return the value
+   * @since 4.8.0
+   */
+  default <T> @Nullable T get(final @NonNull AudienceKey<T> key) {
+    return null;
+  }
+
   /**
    * Sends a chat message with a {@link Identity#nil() nil} identity to this {@link Audience}.
    *

api/src/main/java/net/kyori/adventure/audience/AudienceKey.java

@@ -0,0 +1,64 @@
+/*
+ * This file is part of adventure, licensed under the MIT License.
+ *
+ * Copyright (c) 2017-2021 KyoriPowered
+ *
+ * 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 net.kyori.adventure.audience;
+
+import net.kyori.adventure.key.Key;
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * An audience key.
+ *
+ * @param <T> the type
+ * @since 4.8.0
+ */
+public interface AudienceKey<T> {
+  /**
+   * Creates an audience key.
+   *
+   * @param type the type
+   * @param key the key
+   * @param <T> the type
+   * @return the audience key
+   * @since 4.8.0
+   */
+  static <T> @NonNull AudienceKey<T> audienceKey(final @NonNull Class<T> type, final @NonNull Key key) {
+    return new AudienceKeyImpl<>(type, key);
+  }
+
+  /**
+   * Gets the type.
+   *
+   * @return the type
+   * @since 4.8.0
+   */
+  @NonNull Class<T> type();
+
+  /**
+   * Gets the key.
+   *
+   * @return the key
+   * @since 4.8.0
+   */
+  @NonNull Key key();
+}

api/src/main/java/net/kyori/adventure/audience/AudienceKeyImpl.java

@@ -0,0 +1,63 @@
+/*
+ * This file is part of adventure, licensed under the MIT License.
+ *
+ * Copyright (c) 2017-2021 KyoriPowered
+ *
+ * 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 net.kyori.adventure.audience;
+
+import net.kyori.adventure.key.Key;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+final class AudienceKeyImpl<T> implements AudienceKey<T> {
+  private final Class<T> type;
+  private final Key key;
+
+  AudienceKeyImpl(final Class<T> type, final Key key) {
+    this.type = type;
+    this.key = key;
+  }
+
+  @Override
+  public @NonNull Class<T> type() {
+    return this.type;
+  }
+
+  @Override
+  public @NonNull Key key() {
+    return this.key;
+  }
+
+  @Override
+  public boolean equals(final @Nullable Object other) {
+    if(this == other) return true;
+    if(other == null || this.getClass() != other.getClass()) return false;
+    final AudienceKeyImpl<?> that = (AudienceKeyImpl<?>) other;
+    return this.type.equals(that.type) && this.key.equals(that.key);
+  }
+
+  @Override
+  public int hashCode() {
+    int result = this.type.hashCode();
+    result = (31 * result) + this.key.hashCode();
+    return result;
+  }
+}