From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001 From: Aikar Date: Sun, 24 Mar 2019 18:39:01 -0400 Subject: [PATCH] Fix Spigot annotation mistakes while some of these may of been true, they are extreme cases and cause a ton of noise to plugin developers. These do not help plugin developers if they bring moise noise than value. diff --git a/src/main/java/org/bukkit/Bukkit.java b/src/main/java/org/bukkit/Bukkit.java index 3ad64a11c1e67cce5e49c34d389888060bf2a962..cb0ad65e4e30c3604d655bb75c7b26a7bf4227d7 100644 --- a/src/main/java/org/bukkit/Bukkit.java +++ b/src/main/java/org/bukkit/Bukkit.java @@ -837,9 +837,8 @@ public final class Bukkit { * * @param id the id of the map to get * @return a map view if it exists, or null otherwise - * @deprecated Magic value */ - @Deprecated + //@Deprecated // Paper - Not a magic value @Nullable public static MapView getMap(int id) { return server.getMap(id); @@ -1231,10 +1230,8 @@ public final class Bukkit { * @param name the name the player to retrieve * @return an offline player * @see #getOfflinePlayer(java.util.UUID) - * @deprecated Persistent storage of users should be by UUID as names are no longer - * unique past a single session. */ - @Deprecated + // @Deprecated // Paper @NotNull public static OfflinePlayer getOfflinePlayer(@NotNull String name) { return server.getOfflinePlayer(name); @@ -1825,7 +1822,7 @@ public final class Bukkit { * * @return the scoreboard manager or null if no worlds are loaded. */ - @Nullable + @NotNull // Paper public static ScoreboardManager getScoreboardManager() { return server.getScoreboardManager(); } diff --git a/src/main/java/org/bukkit/GrassSpecies.java b/src/main/java/org/bukkit/GrassSpecies.java index f9c9ae463aacd593e3aa9caf037ea1e23d56c780..f8ae143acbf586d5279b44f7311ca97f3ae4ead2 100644 --- a/src/main/java/org/bukkit/GrassSpecies.java +++ b/src/main/java/org/bukkit/GrassSpecies.java @@ -6,7 +6,9 @@ import org.jetbrains.annotations.Nullable; /** * Represents the different types of grass. + * @deprecated use {@link org.bukkit.block.data.BlockData} */ +@Deprecated // Paper public enum GrassSpecies { /** diff --git a/src/main/java/org/bukkit/Location.java b/src/main/java/org/bukkit/Location.java index 8508aa2c6fb7c9f41f3d185f5228c86dd3b8b627..f7564581c18425c903e54f949728dd3742ca7bf2 100644 --- a/src/main/java/org/bukkit/Location.java +++ b/src/main/java/org/bukkit/Location.java @@ -46,7 +46,7 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm * @param y The y-coordinate of this new location * @param z The z-coordinate of this new location */ - public Location(@Nullable final World world, final double x, final double y, final double z) { + public Location(@UndefinedNullability final World world, final double x, final double y, final double z) { // Paper this(world, x, y, z, 0, 0); } @@ -60,7 +60,7 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm * @param yaw The absolute rotation on the x-plane, in degrees * @param pitch The absolute rotation on the y-plane, in degrees */ - public Location(@Nullable final World world, final double x, final double y, final double z, final float yaw, final float pitch) { + public Location(@UndefinedNullability final World world, final double x, final double y, final double z, final float yaw, final float pitch) { // Paper if (world != null) { this.world = new WeakReference<>(world); } @@ -102,7 +102,7 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm * @throws IllegalArgumentException when world is unloaded * @see #isWorldLoaded() */ - @Nullable + @UndefinedNullability // Paper public World getWorld() { if (this.world == null) { return null; diff --git a/src/main/java/org/bukkit/Material.java b/src/main/java/org/bukkit/Material.java index d56d899ca7737b537ea55c13a384888a873f5da3..cbec3b145a44ceee20823ae0e9c8162b15726189 100644 --- a/src/main/java/org/bukkit/Material.java +++ b/src/main/java/org/bukkit/Material.java @@ -4468,11 +4468,11 @@ public enum Material implements Keyed, Translatable { } /** - * Do not use for any reason. + * Checks if this constant is a legacy material. * * @return legacy status */ - @Deprecated + // @Deprecated // Paper - this is useful, don't deprecate public boolean isLegacy() { return legacy; } @@ -4543,8 +4543,10 @@ public enum Material implements Keyed, Translatable { * Gets the MaterialData class associated with this Material * * @return MaterialData associated with this Material + * @deprecated use {@link #createBlockData()} */ @NotNull + @Deprecated // Paper public Class getData() { Preconditions.checkArgument(legacy, "Cannot get data class of Modern Material"); return ctor.getDeclaringClass(); diff --git a/src/main/java/org/bukkit/NamespacedKey.java b/src/main/java/org/bukkit/NamespacedKey.java index 6fa219aef009f8dfb8a2b1e5ee0603b18cf3d0f5..8ac72cb0b05e2c493d98310f2e87c3714d15c5e3 100644 --- a/src/main/java/org/bukkit/NamespacedKey.java +++ b/src/main/java/org/bukkit/NamespacedKey.java @@ -74,12 +74,14 @@ public final class NamespacedKey implements net.kyori.adventure.key.Key, com.des /** * Create a key in a specific namespace. + *

+ * For most plugin related code, you should prefer using the + * {@link NamespacedKey#NamespacedKey(Plugin, String)} constructor. * * @param namespace namespace * @param key key - * @apiNote should never be used by plugins, for internal use only!! + * @see #NamespacedKey(Plugin, String) */ - @ApiStatus.Internal public NamespacedKey(@NotNull String namespace, @NotNull String key) { Preconditions.checkArgument(namespace != null && isValidNamespace(namespace), "Invalid namespace. Must be [a-z0-9._-]: %s", namespace); Preconditions.checkArgument(key != null && isValidKey(key), "Invalid key. Must be [a-z0-9/._-]: %s", key); diff --git a/src/main/java/org/bukkit/NetherWartsState.java b/src/main/java/org/bukkit/NetherWartsState.java index f43209cf7b752c26718c303ca8c3e1c7d9912ad3..f0094e6fb05e526736629ad3181c8d2c16ba6ca4 100644 --- a/src/main/java/org/bukkit/NetherWartsState.java +++ b/src/main/java/org/bukkit/NetherWartsState.java @@ -1,5 +1,11 @@ package org.bukkit; +// Paper start +/** + * @deprecated use {@link org.bukkit.block.data.BlockData} and {@link org.bukkit.block.data.Ageable} + */ +@Deprecated +// Paper end public enum NetherWartsState { /** diff --git a/src/main/java/org/bukkit/Particle.java b/src/main/java/org/bukkit/Particle.java index 81bd12c8addcee754c71e5e030c729c7e096fb4c..6992600d6cff9ed0a30d37ac4dc5dc0e56ecb2c7 100644 --- a/src/main/java/org/bukkit/Particle.java +++ b/src/main/java/org/bukkit/Particle.java @@ -54,7 +54,9 @@ public enum Particle implements Keyed { BLOCK_CRACK("block", BlockData.class), /** * Uses {@link BlockData} as DataType + * @deprecated use {@link #BLOCK_CRACK} */ + @Deprecated // Paper BLOCK_DUST("block", BlockData.class, false), WATER_DROP("rain"), MOB_APPEARANCE("elder_guardian"), @@ -138,15 +140,21 @@ public enum Particle implements Keyed { // ----- Legacy Separator ----- /** * Uses {@link MaterialData} as DataType + * @deprecated {@link MaterialData} is deprecated API */ + @Deprecated // Paper LEGACY_BLOCK_CRACK(null, MaterialData.class, false), /** * Uses {@link MaterialData} as DataType + * @deprecated {@link MaterialData} is deprecated API */ + @Deprecated // Paper LEGACY_BLOCK_DUST(null, MaterialData.class, false), /** * Uses {@link MaterialData} as DataType + * @deprecated {@link MaterialData} is deprecated API */ + @Deprecated // Paper LEGACY_FALLING_DUST(null, MaterialData.class, false); private final NamespacedKey key; diff --git a/src/main/java/org/bukkit/Registry.java b/src/main/java/org/bukkit/Registry.java index c373614a865d6df8a2fe265497cf0b5f074490b0..8e0f985e8a6af728376a85eef998f7881e50786c 100644 --- a/src/main/java/org/bukkit/Registry.java +++ b/src/main/java/org/bukkit/Registry.java @@ -197,14 +197,14 @@ public interface Registry extends Iterable { * * @see TrimMaterial */ - @ApiStatus.Experimental + //@ApiStatus.Experimental // Paper Registry TRIM_MATERIAL = Bukkit.getRegistry(TrimMaterial.class); /** * Trim patterns. * * @see TrimPattern */ - @ApiStatus.Experimental + //@ApiStatus.Experimental // Paper Registry TRIM_PATTERN = Bukkit.getRegistry(TrimPattern.class); /** * Villager profession. @@ -286,8 +286,11 @@ public interface Registry extends Iterable { * * @param input non-null input * @return registered object or null if does not exist + * @deprecated this method's behavior is broken and not useful. If you want to get an object + * based on its vanilla name, or a key, wrap it in a {@link NamespacedKey} object and use {@link #get(NamespacedKey)} */ @Nullable + @Deprecated(forRemoval = true) // Paper default T match(@NotNull String input) { Preconditions.checkArgument(input != null, "input must not be null"); diff --git a/src/main/java/org/bukkit/SandstoneType.java b/src/main/java/org/bukkit/SandstoneType.java index 6277451c3c6c551078c237cd767b6d70c4f585ea..10f5cfb1885833a1d2c1027c03974da45ab28e2f 100644 --- a/src/main/java/org/bukkit/SandstoneType.java +++ b/src/main/java/org/bukkit/SandstoneType.java @@ -6,7 +6,9 @@ import org.jetbrains.annotations.Nullable; /** * Represents the three different types of Sandstone + * @deprecated use {@link org.bukkit.block.data.BlockData} */ +@Deprecated // Paper public enum SandstoneType { CRACKED(0x0), GLYPHED(0x1), diff --git a/src/main/java/org/bukkit/Server.java b/src/main/java/org/bukkit/Server.java index 3c09a5e08c2641502b7171f27d28d92d02ed39d0..49877944a385b22e5de66b4e33056ee3f592fcd7 100644 --- a/src/main/java/org/bukkit/Server.java +++ b/src/main/java/org/bukkit/Server.java @@ -703,9 +703,8 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi * * @param id the id of the map to get * @return a map view if it exists, or null otherwise - * @deprecated Magic value */ - @Deprecated + //@Deprecated // Paper - Not a magic value @Nullable public MapView getMap(int id); @@ -1034,10 +1033,8 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi * @param name the name the player to retrieve * @return an offline player * @see #getOfflinePlayer(java.util.UUID) - * @deprecated Persistent storage of users should be by UUID as names are no longer - * unique past a single session. */ - @Deprecated + // @Deprecated // Paper @NotNull public OfflinePlayer getOfflinePlayer(@NotNull String name); @@ -1537,7 +1534,7 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi * * @return the scoreboard manager or null if no worlds are loaded. */ - @Nullable + @NotNull // Paper ScoreboardManager getScoreboardManager(); /** diff --git a/src/main/java/org/bukkit/UndefinedNullability.java b/src/main/java/org/bukkit/UndefinedNullability.java index 4d4265c237179470e1fd017721a8dd595f114013..3babc9df26276300392d3f92ee6e317c33643b0b 100644 --- a/src/main/java/org/bukkit/UndefinedNullability.java +++ b/src/main/java/org/bukkit/UndefinedNullability.java @@ -14,6 +14,7 @@ import org.jetbrains.annotations.ApiStatus; * suggests a bad API design. */ @Retention(RetentionPolicy.CLASS) +@java.lang.annotation.Documented // Paper @ApiStatus.Internal @Deprecated public @interface UndefinedNullability { diff --git a/src/main/java/org/bukkit/Vibration.java b/src/main/java/org/bukkit/Vibration.java index e455eb21abf121dc6ff10ff8a13dd06f67096a8f..bbc01e7c192ae6689c301670047ff114306c57cb 100644 --- a/src/main/java/org/bukkit/Vibration.java +++ b/src/main/java/org/bukkit/Vibration.java @@ -13,6 +13,14 @@ public class Vibration { private final Destination destination; private final int arrivalTime; + // Paper start + public Vibration(@NotNull Destination destination, @NotNull int arrivalTime) { + this.destination = destination; + this.arrivalTime = arrivalTime; + this.origin = new Location(null, 0, 0, 0); // Dummy origin because getter expects null + } + + @Deprecated(forRemoval = true) // Paper end public Vibration(@NotNull Location origin, @NotNull Destination destination, int arrivalTime) { this.origin = origin; this.destination = destination; @@ -22,9 +30,11 @@ public class Vibration { /** * Get the origin of the vibration. * + * @deprecated unused as of 1.19 * @return origin */ @NotNull + @Deprecated(forRemoval = true) // Paper public Location getOrigin() { return origin; } diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java index df511007ca4b3b5df04abfa6b7f1c4de636407fc..dea26b0bd6e1dccb7b043a7395e7958461e270ee 100644 --- a/src/main/java/org/bukkit/World.java +++ b/src/main/java/org/bukkit/World.java @@ -416,9 +416,8 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient * @param z Z-coordinate of the chunk * @return Whether the chunk was actually refreshed * - * @deprecated This method is not guaranteed to work suitably across all client implementations. */ - @Deprecated + //@Deprecated // Paper public boolean refreshChunk(int x, int z); /** @@ -3708,6 +3707,10 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient // Paper end - view distance api // Spigot start + /** + * @deprecated Unsupported api + */ + @Deprecated // Paper public class Spigot { /** @@ -3716,8 +3719,12 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient * @param loc The location to strike lightning * @param isSilent Whether this strike makes no sound * @return The lightning entity. + * @deprecated The lightning strike sound has been moved into the client and + * this doesn't prevent the sound being played. Use the regular (non spigot) methods instead + * for a consistent behavior. */ @NotNull + @Deprecated // Paper public LightningStrike strikeLightning(@NotNull Location loc, boolean isSilent) { throw new UnsupportedOperationException("Not supported yet."); } @@ -3728,14 +3735,22 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient * @param loc The location to strike lightning * @param isSilent Whether this strike makes no sound * @return The lightning entity. + * @deprecated The lightning strike sound has been moved into the client and + * this doesn't prevent the sound being played. Use the regular (non spigot) methods instead + * for a consistent behavior. */ @NotNull + @Deprecated // Paper public LightningStrike strikeLightningEffect(@NotNull Location loc, boolean isSilent) { throw new UnsupportedOperationException("Not supported yet."); } } + /** + * @deprecated Unsupported api + */ @NotNull + @Deprecated // Paper Spigot spigot(); // Spigot end diff --git a/src/main/java/org/bukkit/block/Block.java b/src/main/java/org/bukkit/block/Block.java index 78f6cc1a8a8de05aec6f551f8a5f425944f0ffa3..653a83b7ceb5cec1d92aed5250ae50e714fe5f9f 100644 --- a/src/main/java/org/bukkit/block/Block.java +++ b/src/main/java/org/bukkit/block/Block.java @@ -517,7 +517,7 @@ public interface Block extends Metadatable, Translatable { * @return a list of dropped items for this type of block */ @NotNull - Collection getDrops(@NotNull ItemStack tool, @Nullable Entity entity); + Collection getDrops(@Nullable ItemStack tool, @Nullable Entity entity); // Paper /** * Returns if the given item is a preferred choice to break this Block. diff --git a/src/main/java/org/bukkit/block/BlockState.java b/src/main/java/org/bukkit/block/BlockState.java index 7c5438fa92053cdbd7a01483a9baa4d48df07b24..a4f0a5270693e1c4af4fad827fa0a2ce753e07b5 100644 --- a/src/main/java/org/bukkit/block/BlockState.java +++ b/src/main/java/org/bukkit/block/BlockState.java @@ -36,8 +36,10 @@ public interface BlockState extends Metadatable { * Gets the metadata for this block state. * * @return block specific metadata + * @deprecated use {@link #getBlockData()} */ @NotNull + @Deprecated // Paper MaterialData getData(); /** @@ -141,7 +143,9 @@ public interface BlockState extends Metadatable { * Sets the metadata for this block state. * * @param data New block specific metadata + * @deprecated use {@link #setBlockData(BlockData)} */ + @Deprecated // Paper void setData(@NotNull MaterialData data); /** diff --git a/src/main/java/org/bukkit/block/BrushableBlock.java b/src/main/java/org/bukkit/block/BrushableBlock.java index 4bd127b3646307398e0c937c3e36ab671235b72b..f2557a87f468ee20c2d276dbfc0e9a976656c75c 100644 --- a/src/main/java/org/bukkit/block/BrushableBlock.java +++ b/src/main/java/org/bukkit/block/BrushableBlock.java @@ -15,7 +15,7 @@ public interface BrushableBlock extends Lootable, TileState { * * @return the item */ - @Nullable + @org.jetbrains.annotations.NotNull // Paper public ItemStack getItem(); /** diff --git a/src/main/java/org/bukkit/entity/Enderman.java b/src/main/java/org/bukkit/entity/Enderman.java index 605af1a9fc48602643aec57dd14e8c4ab657a0bc..b3085c7ff8b3e96083d209f6612c006578773c24 100644 --- a/src/main/java/org/bukkit/entity/Enderman.java +++ b/src/main/java/org/bukkit/entity/Enderman.java @@ -26,15 +26,19 @@ public interface Enderman extends Monster { * Gets the id and data of the block that the Enderman is carrying. * * @return MaterialData containing the id and data of the block + * @deprecated use {@link #getCarriedBlock()} */ @NotNull + @Deprecated // Paper public MaterialData getCarriedMaterial(); /** * Sets the id and data of the block that the Enderman is carrying. * * @param material data to set the carried block to + * @deprecated use {@link #setCarriedBlock(BlockData)} */ + @Deprecated // Paper public void setCarriedMaterial(@NotNull MaterialData material); /** diff --git a/src/main/java/org/bukkit/entity/LightningStrike.java b/src/main/java/org/bukkit/entity/LightningStrike.java index c49628f2638da68e1ec126e53c8b7c74b0d81b22..8dc433baba7060df5cfe6fc10210a5a27287987d 100644 --- a/src/main/java/org/bukkit/entity/LightningStrike.java +++ b/src/main/java/org/bukkit/entity/LightningStrike.java @@ -84,20 +84,31 @@ public interface LightningStrike extends Entity { public void setCausingPlayer(@Nullable Player player); // Spigot start + /** + * @deprecated Unsupported api + */ + @Deprecated // Paper public class Spigot extends Entity.Spigot { - /* + /** * Returns whether the strike is silent. * * @return whether the strike is silent. + * @deprecated The lightning strike sound has been moved into the client and + * this can't predict if the sound will be played or not accurately. */ + @Deprecated // Paper public boolean isSilent() { throw new UnsupportedOperationException("Not supported yet."); } } + /** + * @deprecated Unsupported api + */ @NotNull @Override + @Deprecated // Paper Spigot spigot(); // Spigot end } diff --git a/src/main/java/org/bukkit/entity/LingeringPotion.java b/src/main/java/org/bukkit/entity/LingeringPotion.java index f124b35ec76e6cb6a1a0dc464005087043c3efd0..f50aaddf8582be55fd4860ad374d8f2206991897 100644 --- a/src/main/java/org/bukkit/entity/LingeringPotion.java +++ b/src/main/java/org/bukkit/entity/LingeringPotion.java @@ -3,6 +3,8 @@ package org.bukkit.entity; /** * Represents a thrown lingering potion bottle * - * @deprecated lingering status depends on only on the potion item. + * @deprecated should not be used for anything, use {@link ThrownPotion} and + * set the potion via the methods there. */ +@Deprecated(forRemoval = true) // Paper public interface LingeringPotion extends ThrownPotion { } diff --git a/src/main/java/org/bukkit/entity/LivingEntity.java b/src/main/java/org/bukkit/entity/LivingEntity.java index 79fdb183887cb8153254f6ac84a981a7ffcb561c..373b3ad6b3f94655289155914aec8294cd4f2fb2 100644 --- a/src/main/java/org/bukkit/entity/LivingEntity.java +++ b/src/main/java/org/bukkit/entity/LivingEntity.java @@ -664,7 +664,9 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource * This may have unexpected results if the entity is not in water. * * @param swimming True if the entity is swimming. + * @deprecated This does nothing and is immediately reverted by the server, in the next tick */ + @Deprecated // Paper public void setSwimming(boolean swimming); /** diff --git a/src/main/java/org/bukkit/entity/Minecart.java b/src/main/java/org/bukkit/entity/Minecart.java index 95c79c5fa0c4e30201f887da6467ce5f81c8a255..7f9c4d4b430a3f0276461346ff2621bacf864075 100644 --- a/src/main/java/org/bukkit/entity/Minecart.java +++ b/src/main/java/org/bukkit/entity/Minecart.java @@ -101,7 +101,9 @@ public interface Minecart extends Vehicle { * Passing a null value will set the minecart to have no display block. * * @param material the material to set as display block. + * @deprecated use {@link #setDisplayBlockData(BlockData)} */ + @Deprecated // Paper public void setDisplayBlock(@Nullable MaterialData material); /** @@ -109,8 +111,10 @@ public interface Minecart extends Vehicle { * This function will return the type AIR if none is set. * * @return the block displayed by this minecart. + * @deprecated use {@link #getDisplayBlockData()} */ @NotNull + @Deprecated // Paper public MaterialData getDisplayBlock(); /** diff --git a/src/main/java/org/bukkit/entity/Projectile.java b/src/main/java/org/bukkit/entity/Projectile.java index 906b33b7569fff5dd78258f9765e879180a52834..06e3ad9cd8f39de0ef6ead794df1492415bc4302 100644 --- a/src/main/java/org/bukkit/entity/Projectile.java +++ b/src/main/java/org/bukkit/entity/Projectile.java @@ -29,7 +29,7 @@ public interface Projectile extends Entity { * @return true if it should bounce. * @deprecated does not do anything */ - @Deprecated + @Deprecated(forRemoval = true) public boolean doesBounce(); /** @@ -39,6 +39,6 @@ public interface Projectile extends Entity { * @param doesBounce whether or not it should bounce. * @deprecated does not do anything */ - @Deprecated + @Deprecated(forRemoval = true) public void setBounce(boolean doesBounce); } diff --git a/src/main/java/org/bukkit/entity/SplashPotion.java b/src/main/java/org/bukkit/entity/SplashPotion.java index 9cb08fe7201a9f91e88c7b1ee22c17889a7bf1c3..c0fcfccdf476106b48e626a099658c04244ebff8 100644 --- a/src/main/java/org/bukkit/entity/SplashPotion.java +++ b/src/main/java/org/bukkit/entity/SplashPotion.java @@ -3,7 +3,8 @@ package org.bukkit.entity; /** * Represents a thrown splash potion bottle * - * @deprecated splash status depends on only on the potion item. + * @deprecated should not be used for anything, use {@link ThrownPotion} and + * set the potion via the methods there. */ -@Deprecated +@Deprecated(forRemoval = true) // Paper public interface SplashPotion extends ThrownPotion { } diff --git a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java index e9a6e5be5f33a342f7e5c496f0f1c64b2f302ace..f0db59a556deaefefbdaca121585c0fd199c13c2 100644 --- a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java +++ b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java @@ -23,7 +23,7 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab private boolean cancelled; private final Player enchanter; - public PrepareItemEnchantEvent(@NotNull final Player enchanter, @NotNull InventoryView view, @NotNull final Block table, @NotNull final ItemStack item, @NotNull final EnchantmentOffer[] offers, final int bonus) { + public PrepareItemEnchantEvent(@NotNull final Player enchanter, @NotNull InventoryView view, @NotNull final Block table, @NotNull final ItemStack item, @org.jetbrains.annotations.Nullable final EnchantmentOffer @NotNull [] offers, final int bonus) { // Paper - offers can contain null values super(view); this.enchanter = enchanter; this.table = table; @@ -68,6 +68,7 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab * @return experience level costs offered * @deprecated Use {@link #getOffers()} instead of this method */ + @Deprecated // Paper @NotNull public int[] getExpLevelCostsOffered() { int[] levelOffers = new int[offers.length]; @@ -85,8 +86,7 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab * * @return list of available enchantment offers */ - @NotNull - public EnchantmentOffer[] getOffers() { + public @org.jetbrains.annotations.Nullable EnchantmentOffer @NotNull [] getOffers() { // Paper offers can contain null values return offers; } diff --git a/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java b/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java index 090ec6f96ca9b7f760389994da988c44c32b9976..e6b4d4c1722bf4a11744a421d09646b22745b138 100644 --- a/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java +++ b/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java @@ -10,7 +10,7 @@ import org.jetbrains.annotations.Nullable; * LivingEntity's. */ public class EntityTargetLivingEntityEvent extends EntityTargetEvent { - public EntityTargetLivingEntityEvent(@NotNull final Entity entity, @Nullable final LivingEntity target, @Nullable final TargetReason reason) { + public EntityTargetLivingEntityEvent(@NotNull final Entity entity, @Nullable final LivingEntity target, @NotNull final TargetReason reason) { // Paper super(entity, target, reason); } diff --git a/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java b/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java index e1123295b9511a2c610a1baf7195638f7f3e64c4..273ae8e5da0a858d3b82d1b0f5992318ff49f145 100644 --- a/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java +++ b/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java @@ -24,6 +24,14 @@ public class EntityToggleSwimEvent extends EntityEvent implements Cancellable { return cancel; } + /** + * @deprecated This does nothing, the server and the client doesn't work + * correctly when the server try to bypass this. A current workaround + * exists. If you want to cancel the switch from the ground state to the + * swimming state you need to disable the sprinting flag for the player after + * the cancel action. + */ + @Deprecated // Paper @Override public void setCancelled(boolean cancel) { this.cancel = cancel; diff --git a/src/main/java/org/bukkit/event/entity/ProjectileHitEvent.java b/src/main/java/org/bukkit/event/entity/ProjectileHitEvent.java index 775e3223aa5054f1883403e50c8f2241d97b1285..5d4817d2a3b709f1a1a1162309a1c923bd09cc1d 100644 --- a/src/main/java/org/bukkit/event/entity/ProjectileHitEvent.java +++ b/src/main/java/org/bukkit/event/entity/ProjectileHitEvent.java @@ -19,22 +19,27 @@ public class ProjectileHitEvent extends EntityEvent implements Cancellable { private final BlockFace hitFace; private boolean cancel = false; + @Deprecated @io.papermc.paper.annotation.DoNotUse // Paper public ProjectileHitEvent(@NotNull final Projectile projectile) { - this(projectile, null, null); + this(projectile, null, null, null); // Paper } + @Deprecated @io.papermc.paper.annotation.DoNotUse // Paper public ProjectileHitEvent(@NotNull final Projectile projectile, @Nullable Entity hitEntity) { - this(projectile, hitEntity, null); + this(projectile, hitEntity, null, null); // Paper } + @Deprecated @io.papermc.paper.annotation.DoNotUse // Paper public ProjectileHitEvent(@NotNull final Projectile projectile, @Nullable Block hitBlock) { - this(projectile, null, hitBlock); + this(projectile, null, hitBlock, null); // Paper } + @Deprecated @io.papermc.paper.annotation.DoNotUse // Paper public ProjectileHitEvent(@NotNull final Projectile projectile, @Nullable Entity hitEntity, @Nullable Block hitBlock) { this(projectile, hitEntity, hitBlock, null); } + @org.jetbrains.annotations.ApiStatus.Internal // Paper public ProjectileHitEvent(@NotNull final Projectile projectile, @Nullable Entity hitEntity, @Nullable Block hitBlock, @Nullable BlockFace hitFace) { super(projectile); this.hitEntity = hitEntity; diff --git a/src/main/java/org/bukkit/event/entity/SpawnerSpawnEvent.java b/src/main/java/org/bukkit/event/entity/SpawnerSpawnEvent.java index 9353f0d09272404f42167ab8b7ad83a03620c436..f3ec8f67328b266defb31a44a36d31401d5e9371 100644 --- a/src/main/java/org/bukkit/event/entity/SpawnerSpawnEvent.java +++ b/src/main/java/org/bukkit/event/entity/SpawnerSpawnEvent.java @@ -12,12 +12,19 @@ import org.jetbrains.annotations.NotNull; public class SpawnerSpawnEvent extends EntitySpawnEvent { private final CreatureSpawner spawner; - public SpawnerSpawnEvent(@NotNull final Entity spawnee, @NotNull final CreatureSpawner spawner) { + public SpawnerSpawnEvent(@NotNull final Entity spawnee, @org.jetbrains.annotations.Nullable final CreatureSpawner spawner) { // Paper super(spawnee); this.spawner = spawner; } - @NotNull + /** + * Gets the spawner tile state, or null + * when the entity is spawned from a minecart + * spawner. + * + * @return the spawner tile state + */ + @org.jetbrains.annotations.Nullable // Paper public CreatureSpawner getSpawner() { return spawner; } diff --git a/src/main/java/org/bukkit/event/hanging/HangingBreakByEntityEvent.java b/src/main/java/org/bukkit/event/hanging/HangingBreakByEntityEvent.java index 68517811f63838bdad41073ee26be82f95042a8e..454885e47611edd707358ddfe0a01b7acf9ad5c8 100644 --- a/src/main/java/org/bukkit/event/hanging/HangingBreakByEntityEvent.java +++ b/src/main/java/org/bukkit/event/hanging/HangingBreakByEntityEvent.java @@ -11,22 +11,21 @@ import org.jetbrains.annotations.Nullable; public class HangingBreakByEntityEvent extends HangingBreakEvent { private final Entity remover; - public HangingBreakByEntityEvent(@NotNull final Hanging hanging, @Nullable final Entity remover) { + public HangingBreakByEntityEvent(@NotNull final Hanging hanging, @NotNull final Entity remover) { // Paper this(hanging, remover, HangingBreakEvent.RemoveCause.ENTITY); } - public HangingBreakByEntityEvent(@NotNull final Hanging hanging, @Nullable final Entity remover, @NotNull final HangingBreakEvent.RemoveCause cause) { + public HangingBreakByEntityEvent(@NotNull final Hanging hanging, @NotNull final Entity remover, @NotNull final HangingBreakEvent.RemoveCause cause) { // Paper super(hanging, cause); this.remover = remover; } /** * Gets the entity that removed the hanging entity. - * May be null, for example when broken by an explosion. * * @return the entity that removed the hanging entity */ - @Nullable + @NotNull // Paper public Entity getRemover() { return remover; } diff --git a/src/main/java/org/bukkit/event/inventory/HopperInventorySearchEvent.java b/src/main/java/org/bukkit/event/inventory/HopperInventorySearchEvent.java index 80a0a4ad813d6453b30273d25942e6612bb05c1b..18bb808e73c7a78f367ccdb44d5fe12bc54672cb 100644 --- a/src/main/java/org/bukkit/event/inventory/HopperInventorySearchEvent.java +++ b/src/main/java/org/bukkit/event/inventory/HopperInventorySearchEvent.java @@ -34,7 +34,7 @@ public class HopperInventorySearchEvent extends BlockEvent { DESTINATION; } - public HopperInventorySearchEvent(@NotNull Inventory inventory, @NotNull ContainerType containerType, @NotNull Block hopper, @NotNull Block searchBlock) { + public HopperInventorySearchEvent(@Nullable Inventory inventory, @NotNull ContainerType containerType, @NotNull Block hopper, @NotNull Block searchBlock) { // Paper super(hopper); this.inventory = inventory; this.containerType = containerType; diff --git a/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java index fe58058f9b5d29388d48115cc81dc48ab08c58c1..ac67a4e321f43d1ede09dafe2daa1f07de8a923f 100644 --- a/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java +++ b/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java @@ -85,7 +85,7 @@ public class InventoryClickEvent extends InventoryInteractEvent { * * @return the cursor ItemStack */ - @Nullable + @NotNull // Paper - fix nullability public ItemStack getCursor() { return getView().getCursor(); } diff --git a/src/main/java/org/bukkit/event/player/PlayerBedLeaveEvent.java b/src/main/java/org/bukkit/event/player/PlayerBedLeaveEvent.java index 1cb70b5c8776863f44f1c4cdde152c35cb51edb5..f09b378508fcc6299e7cb40f174028f6f88ba067 100644 --- a/src/main/java/org/bukkit/event/player/PlayerBedLeaveEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerBedLeaveEvent.java @@ -43,7 +43,10 @@ public class PlayerBedLeaveEvent extends PlayerEvent implements Cancellable { * {@link Player#setBedSpawnLocation(Location)}. * * @return true if the spawn location will be changed + * @deprecated the respawn point is now set when the player enter the bed and + * this option doesn't work since MC 1.15. */ + @Deprecated(forRemoval = true) // Paper - Unused public boolean shouldSetSpawnLocation() { return setBedSpawn; } @@ -59,7 +62,10 @@ public class PlayerBedLeaveEvent extends PlayerEvent implements Cancellable { * {@link Player#setBedSpawnLocation(Location)}. * * @param setBedSpawn true to change the new spawn location + * @deprecated the respawn point is now set when the player enter the bed and + * this option doesn't work since MC 1.15. */ + @Deprecated(forRemoval = true) // Paper - Unused public void setSpawnLocation(boolean setBedSpawn) { this.setBedSpawn = setBedSpawn; } diff --git a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java index 1b2267f4e8ebded198773ec80e2bff2c861c7084..1a58734d919fae247eeb85dd785fd59990856505 100644 --- a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java @@ -78,7 +78,7 @@ public class PlayerMoveEvent extends PlayerEvent implements Cancellable { * * @return Location the player moved to */ - @Nullable + @NotNull // Paper public Location getTo() { return to; } diff --git a/src/main/java/org/bukkit/event/raid/RaidSpawnWaveEvent.java b/src/main/java/org/bukkit/event/raid/RaidSpawnWaveEvent.java index cd58dd7de781823804701fc023706e805c0142a8..1b8bb5241efcf4a90fd098f2000f8394072dca4a 100644 --- a/src/main/java/org/bukkit/event/raid/RaidSpawnWaveEvent.java +++ b/src/main/java/org/bukkit/event/raid/RaidSpawnWaveEvent.java @@ -19,7 +19,7 @@ public class RaidSpawnWaveEvent extends RaidEvent { private final List raiders; private final Raider leader; - public RaidSpawnWaveEvent(@NotNull Raid raid, @NotNull World world, @Nullable Raider leader, @NotNull List raiders) { + public RaidSpawnWaveEvent(@NotNull Raid raid, @NotNull World world, @NotNull Raider leader, @NotNull List raiders) { // Paper super(raid, world); this.raiders = raiders; this.leader = leader; @@ -30,7 +30,7 @@ public class RaidSpawnWaveEvent extends RaidEvent { * * @return {@link Raider} */ - @Nullable + @NotNull // Paper public Raider getPatrolLeader() { return leader; } diff --git a/src/main/java/org/bukkit/event/vehicle/VehicleEntityCollisionEvent.java b/src/main/java/org/bukkit/event/vehicle/VehicleEntityCollisionEvent.java index 6bafc62e2235a6b783cbf96f4dabeeaf02bd5178..50c762d777ac90a05772501a28cacff8fd3f5126 100644 --- a/src/main/java/org/bukkit/event/vehicle/VehicleEntityCollisionEvent.java +++ b/src/main/java/org/bukkit/event/vehicle/VehicleEntityCollisionEvent.java @@ -36,18 +36,22 @@ public class VehicleEntityCollisionEvent extends VehicleCollisionEvent implement this.cancelled = cancel; } + @Deprecated(forRemoval = true) // Paper - Unused public boolean isPickupCancelled() { return cancelledPickup; } + @Deprecated(forRemoval = true) // Paper - Unused public void setPickupCancelled(boolean cancel) { cancelledPickup = cancel; } + @Deprecated(forRemoval = true) // Paper - Unused public boolean isCollisionCancelled() { return cancelledCollision; } + @Deprecated(forRemoval = true) // Paper - Unused public void setCollisionCancelled(boolean cancel) { cancelledCollision = cancel; } diff --git a/src/main/java/org/bukkit/generator/ChunkGenerator.java b/src/main/java/org/bukkit/generator/ChunkGenerator.java index c0b749a5bbf4980d01fed74768bb61909b579cb9..7e7a53b41013f1bf8956c0e278820f18d77b2f0d 100644 --- a/src/main/java/org/bukkit/generator/ChunkGenerator.java +++ b/src/main/java/org/bukkit/generator/ChunkGenerator.java @@ -656,7 +656,9 @@ public abstract class ChunkGenerator { * @param y the y location in the chunk from minHeight (inclusive) - maxHeight (exclusive) * @param z the z location in the chunk from 0-15 inclusive * @param material the type to set the block to + * @deprecated use {@link #setBlock(int, int, int, BlockData)} */ + @Deprecated // Paper public void setBlock(int x, int y, int z, @NotNull MaterialData material); /** @@ -700,7 +702,9 @@ public abstract class ChunkGenerator { * @param yMax maximum y location (exclusive) in the chunk to set * @param zMax maximum z location (exclusive) in the chunk to set * @param material the type to set the blocks to + * @deprecated use {@link #setRegion(int, int, int, int, int, int, BlockData)} */ + @Deprecated // Paper public void setRegion(int xMin, int yMin, int zMin, int xMax, int yMax, int zMax, @NotNull MaterialData material); /** @@ -741,8 +745,10 @@ public abstract class ChunkGenerator { * @param y the y location in the chunk from minHeight (inclusive) - maxHeight (exclusive) * @param z the z location in the chunk from 0-15 inclusive * @return the type and data of the block or the MaterialData for air if x, y or z are outside the chunk's bounds + * @deprecated use {@link #getBlockData(int, int, int)} */ @NotNull + @Deprecated // Paper public MaterialData getTypeAndData(int x, int y, int z); /** diff --git a/src/main/java/org/bukkit/inventory/CookingRecipe.java b/src/main/java/org/bukkit/inventory/CookingRecipe.java index 571652ba8843a9493f1843523e24145baa958637..f7fa79393aef40027446b78bac8e9490cfafd8bc 100644 --- a/src/main/java/org/bukkit/inventory/CookingRecipe.java +++ b/src/main/java/org/bukkit/inventory/CookingRecipe.java @@ -68,7 +68,9 @@ public abstract class CookingRecipe implements Recipe, * Get the input material. * * @return The input material. + * @deprecated Use {@link #getInputChoice()} instead for more complete data. */ + @Deprecated // Paper @NotNull public ItemStack getInput() { return this.ingredient.getItemStack(); diff --git a/src/main/java/org/bukkit/inventory/CraftingInventory.java b/src/main/java/org/bukkit/inventory/CraftingInventory.java index df81bac9ecff697f98941e5c8490e10391e90090..a32977ba3ba60a1c9aee6e469d5d6cd1887c55a2 100644 --- a/src/main/java/org/bukkit/inventory/CraftingInventory.java +++ b/src/main/java/org/bukkit/inventory/CraftingInventory.java @@ -21,8 +21,7 @@ public interface CraftingInventory extends Inventory { * * @return The contents. Individual entries may be null. */ - @NotNull - ItemStack[] getMatrix(); + @Nullable ItemStack @NotNull [] getMatrix(); // Paper - make array elements nullable instead array /** * Set the item in the result slot of the crafting inventory. @@ -38,7 +37,7 @@ public interface CraftingInventory extends Inventory { * @throws IllegalArgumentException if the length of contents is greater * than the size of the crafting matrix. */ - void setMatrix(@NotNull ItemStack[] contents); + void setMatrix(@Nullable ItemStack @NotNull [] contents); // Paper - make array elements nullable instead array /** * Get the current recipe formed on the crafting inventory, if any. diff --git a/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java index c69904f3ee7f3a41d6cebcd401abf8385dfbf868..62c1c3f01fd58db39f635eee415fcbc19fb36ec9 100644 --- a/src/main/java/org/bukkit/inventory/EntityEquipment.java +++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java @@ -511,6 +511,6 @@ public interface EntityEquipment { * * @return the entity this EntityEquipment belongs to */ - @Nullable + @NotNull // Paper Entity getHolder(); } diff --git a/src/main/java/org/bukkit/inventory/FurnaceRecipe.java b/src/main/java/org/bukkit/inventory/FurnaceRecipe.java index 1d442dc16cbb0fed21714d47007f3f11e30c57d4..af8f7b88edf0fa790edcf16356a030c4834f531e 100644 --- a/src/main/java/org/bukkit/inventory/FurnaceRecipe.java +++ b/src/main/java/org/bukkit/inventory/FurnaceRecipe.java @@ -67,8 +67,10 @@ public class FurnaceRecipe extends CookingRecipe { * * @param input The input material. * @return The changed recipe, so you can chain calls. + * @deprecated use {@link #setInputChoice(RecipeChoice)} */ @NotNull + @Deprecated public FurnaceRecipe setInput(@NotNull MaterialData input) { return setInput(input.getItemType(), input.getData()); } diff --git a/src/main/java/org/bukkit/inventory/Inventory.java b/src/main/java/org/bukkit/inventory/Inventory.java index f1a48eab1a357ae64545e1f1dc941c383cff8707..466d1bd7089b76f48f953e1a51c611ecd93dcd54 100644 --- a/src/main/java/org/bukkit/inventory/Inventory.java +++ b/src/main/java/org/bukkit/inventory/Inventory.java @@ -161,8 +161,7 @@ public interface Inventory extends Iterable { * * @return An array of ItemStacks from the inventory. Individual items may be null. */ - @NotNull - public ItemStack[] getContents(); + public @Nullable ItemStack @NotNull [] getContents(); // Paper - make array elements nullable instead array /** * Completely replaces the inventory's contents. Removes all existing @@ -173,7 +172,7 @@ public interface Inventory extends Iterable { * @throws IllegalArgumentException If the array has more items than the * inventory. */ - public void setContents(@NotNull ItemStack[] items) throws IllegalArgumentException; + public void setContents(@Nullable ItemStack @NotNull [] items) throws IllegalArgumentException; // Paper - make array elements nullable instead array /** * Return the contents from the section of the inventory where items can @@ -186,8 +185,7 @@ public interface Inventory extends Iterable { * * @return inventory storage contents. Individual items may be null. */ - @NotNull - public ItemStack[] getStorageContents(); + public @Nullable ItemStack @NotNull [] getStorageContents(); // Paper - make array elements nullable instead array /** * Put the given ItemStacks into the storage slots @@ -196,7 +194,7 @@ public interface Inventory extends Iterable { * @throws IllegalArgumentException If the array has more items than the * inventory. */ - public void setStorageContents(@NotNull ItemStack[] items) throws IllegalArgumentException; + public void setStorageContents(@Nullable ItemStack @NotNull [] items) throws IllegalArgumentException; // Paper - make array elements nullable instead array /** * Checks if the inventory contains any ItemStacks with the given diff --git a/src/main/java/org/bukkit/inventory/InventoryView.java b/src/main/java/org/bukkit/inventory/InventoryView.java index 002acfbdce1db10f7ba1b6a013e678f504ac6e69..aac9180fa3bcbdb0c17dcf96c86647b54ccc28c3 100644 --- a/src/main/java/org/bukkit/inventory/InventoryView.java +++ b/src/main/java/org/bukkit/inventory/InventoryView.java @@ -210,10 +210,10 @@ public abstract class InventoryView { /** * Get the item on the cursor of one of the viewing players. * - * @return The item on the player's cursor, or null if they aren't holding - * one. + * @return The item on the player's cursor, or an empty stack + * if they aren't holding one. */ - @Nullable + @NotNull // Paper - fix nullability public final ItemStack getCursor() { return getPlayer().getItemOnCursor(); } diff --git a/src/main/java/org/bukkit/inventory/ItemFactory.java b/src/main/java/org/bukkit/inventory/ItemFactory.java index d641a8293f3acd465d5fdde8507046647cb6c568..74aa058e0dee7ae858a2a1d0a48e3bb9093a53ea 100644 --- a/src/main/java/org/bukkit/inventory/ItemFactory.java +++ b/src/main/java/org/bukkit/inventory/ItemFactory.java @@ -28,7 +28,7 @@ public interface ItemFactory { * @return a new ItemMeta that could be applied to an item stack of the * specified material */ - @Nullable + @org.bukkit.UndefinedNullability // Paper ItemMeta getItemMeta(@NotNull final Material material); /** diff --git a/src/main/java/org/bukkit/inventory/ItemStack.java b/src/main/java/org/bukkit/inventory/ItemStack.java index 83a0631a80db156ace1d977df71d5fc653b70bb6..60a25898fb17c467ffae05039fcd4d3b154a99ff 100644 --- a/src/main/java/org/bukkit/inventory/ItemStack.java +++ b/src/main/java/org/bukkit/inventory/ItemStack.java @@ -8,6 +8,7 @@ import java.util.Map; import org.bukkit.Bukkit; import org.bukkit.Material; import org.bukkit.Translatable; +import org.bukkit.UndefinedNullability; import org.bukkit.Utility; import org.bukkit.configuration.serialization.ConfigurationSerializable; import org.bukkit.enchantments.Enchantment; @@ -68,6 +69,7 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, Translat * @param damage durability / damage * @deprecated see {@link #setDurability(short)} */ + @Deprecated // Paper public ItemStack(@NotNull final Material type, final int amount, final short damage) { this(type, amount, damage, null); } @@ -169,8 +171,10 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, Translat * Gets the MaterialData for this stack of items * * @return MaterialData for this item + * @deprecated cast to {@link org.bukkit.inventory.meta.BlockDataMeta} and use {@link org.bukkit.inventory.meta.BlockDataMeta#getBlockData(Material)} */ @Nullable + @Deprecated // Paper public MaterialData getData() { Material mat = Bukkit.getUnsafe().toLegacy(getType()); if (data == null && mat != null && mat.getData() != null) { @@ -184,7 +188,9 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, Translat * Sets the MaterialData for this stack of items * * @param data New MaterialData for this item + * @deprecated cast to {@link org.bukkit.inventory.meta.BlockDataMeta} and use {@link org.bukkit.inventory.meta.BlockDataMeta#setBlockData(org.bukkit.block.data.BlockData)} */ + @Deprecated // Paper public void setData(@Nullable MaterialData data) { if (data == null) { this.data = data; @@ -546,7 +552,7 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, Translat * * @return a copy of the current ItemStack's ItemData */ - @Nullable + @UndefinedNullability // Paper public ItemMeta getItemMeta() { return this.meta == null ? Bukkit.getItemFactory().getItemMeta(this.type) : this.meta.clone(); } diff --git a/src/main/java/org/bukkit/inventory/PlayerInventory.java b/src/main/java/org/bukkit/inventory/PlayerInventory.java index 5461f7fa75f5a065bb333b4a113640b5fe1e3825..c4d657727e508cb941320730a9d3aa5486712ef3 100644 --- a/src/main/java/org/bukkit/inventory/PlayerInventory.java +++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java @@ -14,8 +14,7 @@ public interface PlayerInventory extends Inventory { * * @return All the ItemStacks from the armor slots. Individual items can be null. */ - @NotNull - public ItemStack[] getArmorContents(); + public @Nullable ItemStack @NotNull [] getArmorContents(); // Paper - make array elements nullable instead array /** * Get all additional ItemStacks stored in this inventory. @@ -26,8 +25,7 @@ public interface PlayerInventory extends Inventory { * * @return All additional ItemStacks. Individual items can be null. */ - @NotNull - public ItemStack[] getExtraContents(); + public @Nullable ItemStack @NotNull [] getExtraContents(); // Paper - make array elements nullable instead array /** * Return the ItemStack from the helmet slot @@ -104,9 +102,9 @@ public interface PlayerInventory extends Inventory { * * @param slot the slot to get the ItemStack * - * @return the ItemStack in the given slot or null if there is not one + * @return the ItemStack in the given slot */ - @Nullable + @NotNull // Paper public ItemStack getItem(@NotNull EquipmentSlot slot); /** diff --git a/src/main/java/org/bukkit/inventory/ShapedRecipe.java b/src/main/java/org/bukkit/inventory/ShapedRecipe.java index 97d5d9c6347bc401e3f4ab7c0ba1391ad5b0449a..da878c6d4928ddbc16b50ace86d992685a2b7873 100644 --- a/src/main/java/org/bukkit/inventory/ShapedRecipe.java +++ b/src/main/java/org/bukkit/inventory/ShapedRecipe.java @@ -100,8 +100,10 @@ public class ShapedRecipe extends CraftingRecipe { * @param ingredient The ingredient. * @return The changed recipe, so you can chain calls. * @throws IllegalArgumentException if the {@code key} does not appear in the shape. + * @deprecated use {@link #setIngredient(char, RecipeChoice)} */ @NotNull + @Deprecated // Paper public ShapedRecipe setIngredient(char key, @NotNull MaterialData ingredient) { return setIngredient(key, ingredient.getItemType(), ingredient.getData()); } @@ -179,7 +181,9 @@ public class ShapedRecipe extends CraftingRecipe { * Get a copy of the ingredients map. * * @return The mapping of character to ingredients. + * @deprecated Use {@link #getChoiceMap()} instead for more complete data. */ + @Deprecated // Paper @NotNull public Map getIngredientMap() { HashMap result = new HashMap(); diff --git a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java index b8ac602cd2718d615ec243ce648951a1a46c26ec..beb798482479c58a8628c314b510ab6349576ce8 100644 --- a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java +++ b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java @@ -43,8 +43,10 @@ public class ShapelessRecipe extends CraftingRecipe { * * @param ingredient The ingredient to add. * @return The changed recipe, so you can chain calls. + * @deprecated use {@link #addIngredient(RecipeChoice)} */ @NotNull + @Deprecated public ShapelessRecipe addIngredient(@NotNull MaterialData ingredient) { return addIngredient(1, ingredient); } @@ -80,8 +82,10 @@ public class ShapelessRecipe extends CraftingRecipe { * @param count How many to add (can't be more than 9!) * @param ingredient The ingredient to add. * @return The changed recipe, so you can chain calls. + * @deprecated use {@link #addIngredient(int, Material)} */ @NotNull + @Deprecated // Paper public ShapelessRecipe addIngredient(int count, @NotNull MaterialData ingredient) { return addIngredient(count, ingredient.getItemType(), ingredient.getData()); } @@ -198,8 +202,10 @@ public class ShapelessRecipe extends CraftingRecipe { * * @param ingredient The ingredient to remove * @return The changed recipe. + * @deprecated use {@link #removeIngredient(Material)} */ @NotNull + @Deprecated // Paper public ShapelessRecipe removeIngredient(@NotNull MaterialData ingredient) { return removeIngredient(ingredient.getItemType(), ingredient.getData()); } @@ -226,8 +232,10 @@ public class ShapelessRecipe extends CraftingRecipe { * @param count The number of copies to remove. * @param ingredient The ingredient to remove. * @return The changed recipe. + * @deprecated use {@link #removeIngredient(int, Material)} */ @NotNull + @Deprecated // Paper public ShapelessRecipe removeIngredient(int count, @NotNull MaterialData ingredient) { return removeIngredient(count, ingredient.getItemType(), ingredient.getData()); } @@ -277,7 +285,9 @@ public class ShapelessRecipe extends CraftingRecipe { * Get the list of ingredients used for this recipe. * * @return The input list + * @deprecated Use {@link #getChoiceList()} instead for more complete data. */ + @Deprecated // Paper @NotNull public List getIngredientList() { ArrayList result = new ArrayList(ingredients.size()); diff --git a/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java b/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java index 597a18a767b68b47e81454b7d44613c7178c1366..bc3440eb72127824b3961fbdae583bb61385f65e 100644 --- a/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java +++ b/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java @@ -57,7 +57,9 @@ public class StonecuttingRecipe implements Recipe, Keyed { * Get the input material. * * @return The input material. + * @deprecated Use {@link #getInputChoice()} instead for more complete data. */ + @Deprecated // Paper @NotNull public ItemStack getInput() { return this.ingredient.getItemStack(); diff --git a/src/main/java/org/bukkit/inventory/meta/ColorableArmorMeta.java b/src/main/java/org/bukkit/inventory/meta/ColorableArmorMeta.java index 5ccae862dbac393805a47fe26c18a2f33f1e140d..72281899817c5c140cdca2afff75fbcebd942532 100644 --- a/src/main/java/org/bukkit/inventory/meta/ColorableArmorMeta.java +++ b/src/main/java/org/bukkit/inventory/meta/ColorableArmorMeta.java @@ -6,7 +6,7 @@ import org.jetbrains.annotations.NotNull; /** * Represents armor that an entity can equip and can also be colored. */ -@ApiStatus.Experimental +//@ApiStatus.Experimental // Paper public interface ColorableArmorMeta extends ArmorMeta, LeatherArmorMeta { @Override diff --git a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java index 46ac120ed51274a2084719387e35e517981bbf4b..420a91a834016d3af95efd79ca92ae45c4f081c4 100644 --- a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java +++ b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java @@ -75,8 +75,10 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste /** * Checks for existence of a localized name. * + * @deprecated Use {@link ItemMeta#displayName()} and check if it is instanceof a {@link net.kyori.adventure.text.TranslatableComponent}. * @return true if this has a localized name */ + @Deprecated // Paper - Deprecate old localized API boolean hasLocalizedName(); /** @@ -85,16 +87,20 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste * Plugins should check that hasLocalizedName() returns true * before calling this method. * + * @deprecated Use {@link ItemMeta#displayName()} and cast it to a {@link net.kyori.adventure.text.TranslatableComponent}. No longer used by the client. * @return the localized name that is set */ + @Deprecated // Paper - Deprecate old localized API @NotNull String getLocalizedName(); /** * Sets the localized name. * + * @deprecated Use {@link ItemMeta#displayName(Component)} with a {@link net.kyori.adventure.text.TranslatableComponent}. No longer used by the client. * @param name the name to set */ + @Deprecated // Paper - Deprecate old localized API void setLocalizedName(@Nullable String name); /** diff --git a/src/main/java/org/bukkit/inventory/meta/MapMeta.java b/src/main/java/org/bukkit/inventory/meta/MapMeta.java index 32055a8890425e0b819930f3059da5ea9dfca553..26a336dade83baee97d20eb39a058925659f5777 100644 --- a/src/main/java/org/bukkit/inventory/meta/MapMeta.java +++ b/src/main/java/org/bukkit/inventory/meta/MapMeta.java @@ -16,13 +16,8 @@ public interface MapMeta extends ItemMeta { * * @return true if this has a map ID number. * @see #hasMapView() - * @deprecated These methods are poor API: They rely on the caller to pass - * in an only an integer property, and have poorly defined implementation - * behavior if that integer is not a valid map (the current implementation - * for example will generate a new map with a different ID). The xxxMapView - * family of methods should be used instead. */ - @Deprecated + //@Deprecated // Paper boolean hasMapId(); /** @@ -34,13 +29,8 @@ public interface MapMeta extends ItemMeta { * * @return the map ID that is set * @see #getMapView() - * @deprecated These methods are poor API: They rely on the caller to pass - * in an only an integer property, and have poorly defined implementation - * behavior if that integer is not a valid map (the current implementation - * for example will generate a new map with a different ID). The xxxMapView - * family of methods should be used instead. */ - @Deprecated + //@Deprecated // Paper int getMapId(); /** diff --git a/src/main/java/org/bukkit/material/Openable.java b/src/main/java/org/bukkit/material/Openable.java index 0ae54f973d11df74abb3105cf9226afb130b4f33..597036bad6bc61b4aa63a61b45e886dd74a0b7f6 100644 --- a/src/main/java/org/bukkit/material/Openable.java +++ b/src/main/java/org/bukkit/material/Openable.java @@ -1,5 +1,6 @@ package org.bukkit.material; +@Deprecated // Paper public interface Openable { /** diff --git a/src/main/java/org/bukkit/material/Redstone.java b/src/main/java/org/bukkit/material/Redstone.java index 3e46603f8cd38041394e0e1baf788d9009b3ffc7..b15c141f1db07296bb349f11c6f39b0fbe53e7b1 100644 --- a/src/main/java/org/bukkit/material/Redstone.java +++ b/src/main/java/org/bukkit/material/Redstone.java @@ -3,6 +3,7 @@ package org.bukkit.material; /** * Indicated a Material that may carry or create a Redstone current */ +@Deprecated // Paper public interface Redstone { /** diff --git a/src/main/java/org/bukkit/material/Step.java b/src/main/java/org/bukkit/material/Step.java index 9f502e7ee05d0512e190a1722cc112ece068c4e2..10c0465cf58d680bfa9a0f9233f94e8b6d5a9b93 100644 --- a/src/main/java/org/bukkit/material/Step.java +++ b/src/main/java/org/bukkit/material/Step.java @@ -78,6 +78,7 @@ public class Step extends TexturedMaterial { * * @deprecated Magic value */ + @Deprecated // Paper @Override protected int getTextureIndex() { return getData() & 0x7; diff --git a/src/main/java/org/bukkit/material/types/MushroomBlockTexture.java b/src/main/java/org/bukkit/material/types/MushroomBlockTexture.java index 0ea9c6b2420a0f990bd1fdf50fc015e37a7060d8..e99644eae1c662b117aa19060d2484aca19fe0a4 100644 --- a/src/main/java/org/bukkit/material/types/MushroomBlockTexture.java +++ b/src/main/java/org/bukkit/material/types/MushroomBlockTexture.java @@ -7,7 +7,9 @@ import org.jetbrains.annotations.Nullable; /** * Represents the different textured blocks of mushroom. + * @deprecated use BlockData */ +@Deprecated // Paper public enum MushroomBlockTexture { /** diff --git a/src/test/java/org/bukkit/materials/MaterialDataTest.java b/src/test/java/org/bukkit/materials/MaterialDataTest.java index 8d78435cc42a9e668b2d4d674b79b4094c3bd1b1..24a8ce4387b897c717b55405f363ffafff45894d 100644 --- a/src/test/java/org/bukkit/materials/MaterialDataTest.java +++ b/src/test/java/org/bukkit/materials/MaterialDataTest.java @@ -22,6 +22,7 @@ import org.bukkit.material.WoodenStep; import org.bukkit.material.types.MushroomBlockTexture; import org.junit.jupiter.api.Test; +@Deprecated // Paper public class MaterialDataTest { @Test