- * Note: This method is potentially very heavily blocking. It should not ever be called on the + * Match an existing {@link OfflinePlayer}. If the name is a {@link UUID#toString() UUID string}, this will only + * return the user if they have actually played on the server before, unlike {@link Bukkit#getOfflinePlayer(UUID)}. + * + *
This method is potentially very heavily blocking. It should not ever be called on the
* main thread, and if it is, a stack trace will be displayed alerting server owners to the
* call.
*
- * @param name the name of the Player
- * @return the OfflinePlayer with the closest matching name or null if no players have ever logged in
+ * @param name the string to match
+ * @return the user with the closest matching name
*/
default @Nullable OfflinePlayer matchPlayer(@NotNull String name) {
@@ -168,7 +225,7 @@ public interface IOpenInv {
if (Bukkit.getServer().isPrimaryThread()) {
this.getLogger().warning("Call to OpenInv#matchPlayer made on the main thread!");
this.getLogger().warning("This can cause the server to hang, potentially severely.");
- this.getLogger().log(Level.WARNING, new Throwable("Current stack trace"), () -> "Current stack trace");
+ this.getLogger().log(Level.WARNING, "Current stack trace", new Throwable("Current stack trace"));
}
OfflinePlayer player;
@@ -176,32 +233,38 @@ public interface IOpenInv {
try {
UUID uuid = UUID.fromString(name);
player = Bukkit.getOfflinePlayer(uuid);
- // Ensure player is a real player, otherwise return null
+ // Ensure player is an existing player.
if (player.hasPlayedBefore() || player.isOnline()) {
return player;
}
+ // Return null otherwise.
+ return null;
} catch (IllegalArgumentException ignored) {
// Not a UUID
}
+ // Exact online match first.
player = Bukkit.getServer().getPlayerExact(name);
if (player != null) {
return player;
}
+ // Exact offline match second - ensure offline access works when matchable users are online.
player = Bukkit.getServer().getOfflinePlayer(name);
if (player.hasPlayedBefore()) {
return player;
}
+ // Inexact online match.
player = Bukkit.getServer().getPlayer(name);
if (player != null) {
return player;
}
+ // Finally, inexact offline match.
float bestMatch = 0;
for (OfflinePlayer offline : Bukkit.getServer().getOfflinePlayers()) {
if (offline.getName() == null) {
@@ -226,20 +289,7 @@ public interface IOpenInv {
}
/**
- * Open an ISpecialInventory for a Player.
- *
- * @param player the Player
- * @param inventory the ISpecialInventory
- * @return the InventoryView for the opened ISpecialInventory
- */
- @Nullable InventoryView openInventory(@NotNull Player player, @NotNull ISpecialInventory inventory);
-
- /**
- * Check the configuration value for whether or not OpenInv displays a notification to the user
- * when a container is activated with AnyChest.
- *
- * @return true unless configured otherwise
- * @deprecated OpenInv uses action bar chat for notifications. Whether or not they show is based on language settings.
+ * @deprecated OpenInv uses action bar chat for notifications. Whether they show is based on language settings.
*/
@Deprecated(forRemoval = true)
default boolean notifyAnyChest() {
@@ -288,28 +338,9 @@ public interface IOpenInv {
default void retainPlayer(@NotNull Player player, @NotNull Plugin plugin) {}
/**
- * Sets a player's AnyChest setting.
+ * Forcibly close inventories of and unload any cached data for a user.
*
- * @param offline the OfflinePlayer
- * @param status the status
- * @throws IllegalStateException if the server version is unsupported
- */
- void setPlayerAnyChestStatus(@NotNull OfflinePlayer offline, boolean status);
-
- /**
- * Sets a player's SilentChest setting.
- *
- * @param offline the OfflinePlayer
- * @param status the status
- * @throws IllegalStateException if the server version is unsupported
- */
- void setPlayerSilentChestStatus(@NotNull OfflinePlayer offline, boolean status);
-
- /**
- * Forcibly unload a cached Player's data.
- *
- * @param offline the OfflinePlayer to unload
- * @throws IllegalStateException if the server version is unsupported
+ * @param offline the {@link OfflinePlayer} to unload
*/
void unload(@NotNull OfflinePlayer offline);
diff --git a/api/src/main/java/com/lishid/openinv/internal/IAnySilentContainer.java b/api/src/main/java/com/lishid/openinv/internal/IAnySilentContainer.java
index 0fd2379..8c59530 100644
--- a/api/src/main/java/com/lishid/openinv/internal/IAnySilentContainer.java
+++ b/api/src/main/java/com/lishid/openinv/internal/IAnySilentContainer.java
@@ -33,39 +33,38 @@ import org.jetbrains.annotations.NotNull;
public interface IAnySilentContainer {
/**
- * Opens the container at the given coordinates for the Player. If you do not want blocked
- * containers to open, be sure to check {@link #isAnyContainerNeeded(Block)}
- * first.
+ * Forcibly open the container at the given coordinates for the Player. This will open blocked containers! Be sure
+ * to check {@link #isAnyContainerNeeded(Block)} first if that is not desirable.
*
- * @param player the Player opening the container
- * @param silent whether the container's noise is to be silenced
- * @param block the Block
+ * @param player the {@link Player} opening the container
+ * @param silent whether the container's noise is to be silenced
+ * @param block the {@link Block} of the container
* @return true if the container can be opened
*/
boolean activateContainer(@NotNull Player player, boolean silent, @NotNull Block block);
/**
- * Closes the Player's currently open container silently, if necessary.
+ * Perform operations required to close the current container silently.
*
- * @param player the Player closing a container
+ * @param player the {@link Player} closing a container
*/
void deactivateContainer(@NotNull Player player);
/**
- * @deprecated use {@link #isAnyContainerNeeded(Block)}
* @param player the player opening the container
- * @param block the block
+ * @param block the {@link Block} of the container
* @return true if the container is blocked
+ * @deprecated use {@link #isAnyContainerNeeded(Block)}
*/
- @Deprecated
+ @Deprecated(forRemoval = true, since = "4.1.9")
default boolean isAnyContainerNeeded(@NotNull Player player, @NotNull Block block) {
return isAnyContainerNeeded(block);
}
/**
- * Checks if the container at the given coordinates is blocked.
+ * Check if the container at the given coordinates is blocked.
*
- * @param block the Block
+ * @param block the {@link Block} of the container
* @return true if the container is blocked
*/
default boolean isAnyContainerNeeded(@NotNull Block block) {
@@ -82,8 +81,8 @@ public interface IAnySilentContainer {
}
// Shulker boxes require 1/2 a block clear in the direction they open.
- if (blockState instanceof ShulkerBox) {
- if (isShulkerBlocked((ShulkerBox) blockState)) {
+ if (blockState instanceof ShulkerBox shulker) {
+ if (isShulkerBlocked(shulker)) {
return true;
}
}
@@ -97,11 +96,10 @@ public interface IAnySilentContainer {
}
BlockData blockData = block.getBlockData();
- if (!(blockData instanceof Chest) || ((Chest) blockData).getType() == Chest.Type.SINGLE) {
+ if (!(blockData instanceof Chest chest) || ((Chest) blockData).getType() == Chest.Type.SINGLE) {
return false;
}
- Chest chest = (Chest) blockData;
int ordinal = (chest.getFacing().ordinal() + 4 + (chest.getType() == Chest.Type.RIGHT ? -1 : 1)) % 4;
BlockFace relativeFace = BlockFace.values()[ordinal];
org.bukkit.block.Block relative = block.getRelative(relativeFace);
@@ -111,11 +109,10 @@ public interface IAnySilentContainer {
}
BlockData relativeData = relative.getBlockData();
- if (!(relativeData instanceof Chest)) {
+ if (!(relativeData instanceof Chest relativeChest)) {
return false;
}
- Chest relativeChest = (Chest) relativeData;
if (relativeChest.getFacing() != chest.getFacing()
|| relativeChest.getType() != (chest.getType() == Chest.Type.RIGHT ? Chest.Type.LEFT : Chest.Type.RIGHT)) {
return false;
@@ -124,25 +121,31 @@ public interface IAnySilentContainer {
return isChestBlocked(relative);
}
- boolean isShulkerBlocked(ShulkerBox block);
+ /**
+ * Check if a {@link ShulkerBox} cannot be opened under ordinary circumstances.
+ *
+ * @param shulkerBox the shulker box container
+ * @return whether the container is blocked
+ */
+ boolean isShulkerBlocked(@NotNull ShulkerBox shulkerBox);
/**
- * Determine whether or not a chest is blocked.
+ * Check if a chest cannot be opened under ordinary circumstances.
*
* @param chest the chest block
- * @return true if the chest block cannot be opened under ordinary circumstances
+ * @return whether the container is blocked
*/
- default boolean isChestBlocked(Block chest) {
+ default boolean isChestBlocked(@NotNull Block chest) {
org.bukkit.block.Block relative = chest.getRelative(0, 1, 0);
return relative.getType().isOccluding()
|| chest.getWorld().getNearbyEntities(BoundingBox.of(relative), entity -> entity instanceof Cat).size() > 0;
}
/**
- * Checks if the given block is a container which can be unblocked or silenced.
+ * Check if the given {@link Block} is a container which can be unblocked or silenced.
*
- * @param block the BlockState
- * @return true if the Block is a supported container
+ * @param block the potential container
+ * @return true if the type is a supported container
*/
default boolean isAnySilentContainer(@NotNull Block block) {
if (block.getType() == Material.ENDER_CHEST) {
diff --git a/api/src/main/java/com/lishid/openinv/internal/IInventoryAccess.java b/api/src/main/java/com/lishid/openinv/internal/IInventoryAccess.java
index baa76a0..7f29a07 100644
--- a/api/src/main/java/com/lishid/openinv/internal/IInventoryAccess.java
+++ b/api/src/main/java/com/lishid/openinv/internal/IInventoryAccess.java
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2011-2021 lishid. All rights reserved.
+ * Copyright (C) 2011-2022 lishid. All rights reserved.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
@@ -16,49 +16,47 @@
package com.lishid.openinv.internal;
+import com.lishid.openinv.util.InventoryAccess;
import org.bukkit.inventory.Inventory;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
-@Deprecated
+/**
+ * @deprecated Use static {@link InventoryAccess} methods.
+ */
+@Deprecated(forRemoval = true)
public interface IInventoryAccess {
/**
- * Gets an ISpecialEnderChest from an Inventory or null if the Inventory is not backed by an
- * ISpecialEnderChest.
- *
- * @param inventory the Inventory
- * @return the ISpecialEnderChest or null
+ * @deprecated Use static {@link InventoryAccess} methods.
*/
- @Deprecated
- @Nullable ISpecialEnderChest getSpecialEnderChest(@NotNull Inventory inventory);
+ @Deprecated(forRemoval = true)
+ default @Nullable ISpecialEnderChest getSpecialEnderChest(@NotNull Inventory inventory) {
+ return InventoryAccess.getEnderChest(inventory);
+ }
/**
- * Gets an ISpecialPlayerInventory from an Inventory or null if the Inventory is not backed by
- * an ISpecialPlayerInventory.
- *
- * @param inventory the Inventory
- * @return the ISpecialPlayerInventory or null
+ * @deprecated Use static {@link InventoryAccess} methods.
*/
- @Deprecated
- @Nullable ISpecialPlayerInventory getSpecialPlayerInventory(@NotNull Inventory inventory);
+ @Deprecated(forRemoval = true)
+ default @Nullable ISpecialPlayerInventory getSpecialPlayerInventory(@NotNull Inventory inventory) {
+ return InventoryAccess.getPlayerInventory(inventory);
+ }
/**
- * Check if an Inventory is an ISpecialEnderChest implementation.
- *
- * @param inventory the Inventory
- * @return true if the Inventory is backed by an ISpecialEnderChest
+ * @deprecated Use static {@link InventoryAccess} methods.
*/
- @Deprecated
- boolean isSpecialEnderChest(@NotNull Inventory inventory);
+ @Deprecated(forRemoval = true)
+ default boolean isSpecialEnderChest(@NotNull Inventory inventory) {
+ return InventoryAccess.isEnderChest(inventory);
+ }
/**
- * Check if an Inventory is an ISpecialPlayerInventory implementation.
- *
- * @param inventory the Inventory
- * @return true if the Inventory is backed by an ISpecialPlayerInventory
+ * @deprecated Use static {@link InventoryAccess} methods.
*/
- @Deprecated
- boolean isSpecialPlayerInventory(@NotNull Inventory inventory);
+ @Deprecated(forRemoval = true)
+ default boolean isSpecialPlayerInventory(@NotNull Inventory inventory) {
+ return InventoryAccess.isPlayerInventory(inventory);
+ }
}
diff --git a/api/src/main/java/com/lishid/openinv/internal/ISpecialEnderChest.java b/api/src/main/java/com/lishid/openinv/internal/ISpecialEnderChest.java
index 4f86486..e46cc80 100644
--- a/api/src/main/java/com/lishid/openinv/internal/ISpecialEnderChest.java
+++ b/api/src/main/java/com/lishid/openinv/internal/ISpecialEnderChest.java
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2011-2021 lishid. All rights reserved.
+ * Copyright (C) 2011-2022 lishid. All rights reserved.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
@@ -16,6 +16,9 @@
package com.lishid.openinv.internal;
+/**
+ * An {@link ISpecialInventory} representing an ender chest.
+ */
public interface ISpecialEnderChest extends ISpecialInventory {
}
diff --git a/api/src/main/java/com/lishid/openinv/internal/ISpecialInventory.java b/api/src/main/java/com/lishid/openinv/internal/ISpecialInventory.java
index dc94ce4..270557b 100644
--- a/api/src/main/java/com/lishid/openinv/internal/ISpecialInventory.java
+++ b/api/src/main/java/com/lishid/openinv/internal/ISpecialInventory.java
@@ -21,40 +21,43 @@ import org.bukkit.entity.Player;
import org.bukkit.inventory.Inventory;
import org.jetbrains.annotations.NotNull;
+/**
+ * Interface defining behavior for special inventories backed by other inventories' content listings.
+ */
public interface ISpecialInventory {
/**
- * Gets the Inventory associated with this ISpecialInventory.
+ * Get the {@link Inventory} associated with this {@code ISpecialInventory}.
*
- * @return the Inventory
+ * @return the Bukkit inventory
*/
@NotNull Inventory getBukkitInventory();
/**
- * Sets the Player associated with this ISpecialInventory online.
+ * Set the owning {@link Player} instance to a newly-joined user.
*
- * @param player the Player coming online
+ * @param player the user coming online
*/
void setPlayerOnline(@NotNull Player player);
/**
- * Sets the Player associated with this ISpecialInventory offline.
+ * Mark the owner of the inventory offline.
*/
void setPlayerOffline();
/**
- * Gets whether this ISpecialInventory is in use.
+ * Get whether the inventory is being viewed by any users.
*
- * @return true if the ISpecialInventory is in use
+ * @return true if the inventory is being viewed
*/
default boolean isInUse() {
return !getBukkitInventory().getViewers().isEmpty();
}
/**
- * Gets the Player associated with this ISpecialInventory.
+ * Get the {@link Player} who owns the inventory.
*
- * @return the HumanEntity
+ * @return the {@link HumanEntity} who owns the inventory
*/
@NotNull HumanEntity getPlayer();
diff --git a/api/src/main/java/com/lishid/openinv/internal/ISpecialPlayerInventory.java b/api/src/main/java/com/lishid/openinv/internal/ISpecialPlayerInventory.java
index 412656c..7c78734 100644
--- a/api/src/main/java/com/lishid/openinv/internal/ISpecialPlayerInventory.java
+++ b/api/src/main/java/com/lishid/openinv/internal/ISpecialPlayerInventory.java
@@ -21,7 +21,7 @@ import org.bukkit.entity.HumanEntity;
import org.bukkit.inventory.Inventory;
/**
- * Interface defining behavior specific to a player inventory.
+ * An {@link ISpecialInventory} representing a player inventory.
*/
public interface ISpecialPlayerInventory extends ISpecialInventory {
diff --git a/api/src/main/java/com/lishid/openinv/util/InventoryAccess.java b/api/src/main/java/com/lishid/openinv/util/InventoryAccess.java
index 1de0d85..60032a4 100644
--- a/api/src/main/java/com/lishid/openinv/util/InventoryAccess.java
+++ b/api/src/main/java/com/lishid/openinv/util/InventoryAccess.java
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2011-2021 lishid. All rights reserved.
+ * Copyright (C) 2011-2022 lishid. All rights reserved.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
@@ -26,7 +26,7 @@ import org.bukkit.inventory.Inventory;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
-public class InventoryAccess implements IInventoryAccess {
+public final class InventoryAccess implements IInventoryAccess {
private static Class craftInventory = null;
private static Method getInventory = null;
@@ -35,16 +35,14 @@ public class InventoryAccess implements IInventoryAccess {
String packageName = Bukkit.getServer().getClass().getPackage().getName();
try {
craftInventory = Class.forName(packageName + ".inventory.CraftInventory");
- } catch (ClassNotFoundException ignored) {}
- try {
getInventory = craftInventory.getDeclaredMethod("getInventory");
- } catch (NoSuchMethodException ignored) {}
+ } catch (ClassNotFoundException | NoSuchMethodException ignored) {}
}
/**
* @deprecated use {@link #isUsable()}
*/
- @Deprecated
+ @Deprecated(forRemoval = true)
public static boolean isUseable() {
return isUsable();
}
@@ -53,25 +51,51 @@ public class InventoryAccess implements IInventoryAccess {
return craftInventory != null && getInventory != null;
}
+ /**
+ * Check if an {@link Inventory} is an {@link ISpecialPlayerInventory} implementation.
+ *
+ * @param inventory the Bukkit inventory
+ * @return true if backed by the correct implementation
+ */
public static boolean isPlayerInventory(@NotNull Inventory inventory) {
return getPlayerInventory(inventory) != null;
}
+ /**
+ * Get the {@link ISpecialPlayerInventory} backing an {@link Inventory}. Returns {@code null} if the inventory is
+ * not backed by the correct class.
+ *
+ * @param inventory the Bukkit inventory
+ * @return the backing implementation if available
+ */
public static @Nullable ISpecialPlayerInventory getPlayerInventory(@NotNull Inventory inventory) {
return getSpecialInventory(ISpecialPlayerInventory.class, inventory);
}
+ /**
+ * Check if an {@link Inventory} is an {@link ISpecialEnderChest} implementation.
+ *
+ * @param inventory the Bukkit inventory
+ * @return true if backed by the correct implementation
+ */
public static boolean isEnderChest(@NotNull Inventory inventory) {
return getEnderChest(inventory) != null;
}
+ /**
+ * Get the {@link ISpecialEnderChest} backing an {@link Inventory}. Returns {@code null} if the inventory is
+ * not backed by the correct class.
+ *
+ * @param inventory the Bukkit inventory
+ * @return the backing implementation if available
+ */
public static @Nullable ISpecialEnderChest getEnderChest(@NotNull Inventory inventory) {
return getSpecialInventory(ISpecialEnderChest.class, inventory);
}
private static