feat(api): introduce a way to get viewers of a bossbar

Co-authored-by: KingOfSquares <[email protected]>

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

@@ -29,6 +29,7 @@
 import java.util.function.Predicate;
 import java.util.stream.Collector;
 import net.kyori.adventure.bossbar.BossBar;
+import net.kyori.adventure.bossbar.BossBarViewer;
 import net.kyori.adventure.chat.ChatType;
 import net.kyori.adventure.chat.SignedMessage;
 import net.kyori.adventure.identity.Identified;
@@ -83,6 +84,7 @@
  * and any new methods will be stubbed by default.</p>
  *
  * @see ForwardingAudience
+ * @see BossBarViewer
  * @since 4.0.0
  */
 public interface Audience extends Pointered {

api/src/main/java/net/kyori/adventure/bossbar/BossBar.java

@@ -24,6 +24,7 @@
 package net.kyori.adventure.bossbar;
 
 import java.util.Set;
+import net.kyori.adventure.audience.Audience;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.ComponentLike;
 import net.kyori.adventure.util.Index;
@@ -379,6 +380,43 @@ default float percent() {
   @Contract("_ -> this")
   @NotNull BossBar removeListener(final @NotNull Listener listener);
 
+  /**
+   * Gets an unmodifiable view of the viewers of this bossbar.
+   *
+   * <p>The returned value may be empty if this method is unsupported.</p>
+   *
+   * @return an unmodifiable view of the viewers of this bossbar
+   * @since 4.14.0
+   */
+  @UnmodifiableView
+  @NotNull Iterable<? extends BossBarViewer> viewers();
+
+  /**
+   * Show this bossbar to {@code viewer}.
+   *
+   * @param viewer the viewer
+   * @return the bossbar
+   * @see Audience#showBossBar(BossBar)
+   * @since 4.14.0
+   */
+  default @NotNull BossBar addViewer(final @NotNull Audience viewer) {
+    viewer.showBossBar(this);
+    return this;
+  }
+
+  /**
+   * Hide this bossbar from {@code viewer}.
+   *
+   * @param viewer the viewer
+   * @return the bossbar
+   * @see Audience#hideBossBar(BossBar)
+   * @since 4.14.0
+   */
+  default @NotNull BossBar removeViewer(final @NotNull Audience viewer) {
+    viewer.hideBossBar(this);
+    return this;
+  }
+
   /**
    * A listener for changes that happen on a {@link BossBar}.
    *

api/src/main/java/net/kyori/adventure/bossbar/BossBarImpl.java

@@ -266,6 +266,14 @@ public boolean hasFlag(final @NotNull Flag flag) {
     return this;
   }
 
+  @Override
+  public @NotNull Iterable<? extends BossBarViewer> viewers() {
+    if (this.implementation != null) {
+      return this.implementation.viewers();
+    }
+    return Collections.emptyList();
+  }
+
   private void forEachListener(final @NotNull Consumer<Listener> consumer) {
     for (final Listener listener : this.listeners) {
       consumer.accept(listener);

api/src/main/java/net/kyori/adventure/bossbar/BossBarImplementation.java

@@ -23,6 +23,7 @@
  */
 package net.kyori.adventure.bossbar;
 
+import java.util.Collections;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
@@ -47,6 +48,17 @@ public interface BossBarImplementation {
     return BossBarImpl.ImplementationAccessor.get(bar, type);
   }
 
+  /**
+   * Gets the viewers of this bossbar.
+   *
+   * @return the viewers of this bossbar
+   * @since 4.14.0
+   */
+  @ApiStatus.Internal
+  default @NotNull Iterable<? extends BossBarViewer> viewers() {
+    return Collections.emptyList();
+  }
+
   /**
    * A {@link BossBarImplementation} service provider.
    *

api/src/main/java/net/kyori/adventure/bossbar/BossBarViewer.java

@@ -0,0 +1,43 @@
+/*
+ * This file is part of adventure, licensed under the MIT License.
+ *
+ * Copyright (c) 2017-2023 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.bossbar;
+
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.UnmodifiableView;
+
+/**
+ * Something that can view a {@link BossBar}.
+ *
+ * @since 4.14.0
+ */
+public interface BossBarViewer {
+  /**
+   * Gets an unmodifiable view of all known currently active bossbars.
+   *
+   * @return an unmodifiable view of all known currently active bossbars
+   * @since 4.14.0
+   */
+  @UnmodifiableView
+  @NotNull Iterable<? extends BossBar> activeBossBars();
+}