Paper/patches/api/0172-Fix-Spigot-annotation-mistakes.patch
Nassim Jahnke efd47e3a68
Updated Upstream (Bukkit/CraftBukkit/Spigot) (#9188)
* Updated Upstream (Bukkit/CraftBukkit/Spigot)

Upstream has released updates that appear to apply and compile correctly.
This update has not been tested by PaperMC and as with ANY update, please do your own testing

Bukkit Changes:
2fcba9b2 SPIGOT-7347: Add missing documentation and details to ShapedRecipe
c278419d PR-854: Move getHighestBlockYAt methods from World to RegionAccessor
201399fb PR-853: Add API for directly setting Display transformation matrices
ecfa559a PR-849: Add InventoryView#setTitle
653d7edb SPIGOT-519: Add TNTPrimeEvent
22fccc09 PR-846: Add method to get chunk load level
a070a52c PR-844: Add methods to convert Vector to and from JOML vectors
cc7111fe PR-276: Add accessors to Wither's invulnerability ticks
777d24e9 SPIGOT-7209: Accessors and events for player's exp cooldown
ccb2d01b SPIGOT-6308: Deprecate the location name property of map items
cd04a31b PR-780: Add PlayerSpawnChangeEvent
7d1f5b64 SPIGOT-6780: Improve documentation for World#spawnFallingBlock
5696668a SPIGOT-6885: Add test and easier to debug code for reference in yaml configuration comments
2e13cff7 PR-589: Expand the FishHook API
2c7d3da5 PR-279: Minor edits to various Javadocs

CraftBukkit Changes:
01b2e1af4 SPIGOT-7346: Disallow players from executing commands after disconnecting
7fe5ee022 PR-1186: Move getHighestBlockYAt methods from World to RegionAccessor
bcc85ef67 PR-1185: Add API for directly setting Display transformation matrices
a7cfc778f PR-1176: Add InventoryView#setTitle
563d42226 SPIGOT-519: Add TNTPrimeEvent
ccbc6abca Add test for Chunk.LoadLevel mirroring
2926e0513 PR-1171: Add method to get chunk load level
63cad7f84 PR-375: Add accessors to Wither's invulnerability ticks
bfd8b1ac8 SPIGOT-7209: Accessors and events for player's exp cooldown
f92a41c39 PR-1181: Consolidate Location conversion code
10f866759 SPIGOT-6308: Deprecate the location name property of map items
82f7b658a PR-1095: Add PlayerSpawnChangeEvent
b421af7e4 PR-808: Expand the FishHook API
598ad7b3f Increase outdated build delay

Spigot Changes:
d1bd3bd2 Rebuild patches
e4265cc8 SPIGOT-7297: Entity Tracking Range option for Display entities

* Work around javac bug

* Call PlayerSpawnChangeEvent

* Updated Upstream (Bukkit/CraftBukkit/Spigot)

Upstream has released updates that appear to apply and compile correctly.
This update has not been tested by PaperMC and as with ANY update, please do your own testing

Bukkit Changes:
2fcba9b2 SPIGOT-7347: Add missing documentation and details to ShapedRecipe
c278419d PR-854: Move getHighestBlockYAt methods from World to RegionAccessor
201399fb PR-853: Add API for directly setting Display transformation matrices

CraftBukkit Changes:
01b2e1af4 SPIGOT-7346: Disallow players from executing commands after disconnecting
7fe5ee022 PR-1186: Move getHighestBlockYAt methods from World to RegionAccessor
bcc85ef67 PR-1185: Add API for directly setting Display transformation matrices

Spigot Changes:
7da74dae Rebuild patches
2023-05-12 13:10:08 +02:00

900 lines
42 KiB
Diff

From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
From: Aikar <aikar@aikar.co>
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 c02b663ab711daa06de054a92f09485231824458..befbbefc97abbac819f4034e3df62f8437844c39 100644
--- a/src/main/java/org/bukkit/Bukkit.java
+++ b/src/main/java/org/bukkit/Bukkit.java
@@ -1200,10 +1200,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);
@@ -1749,7 +1747,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 20978b269a7757a561d6b872cc77898b44bbd272..2b9a117804a8ca54b47e51e23359bd6e01087641 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 fb23fce97a1930b968b76fa9ff4fbbb452768096..20cc192e89562e1455ec3eacc15593c4eed89907 100644
--- a/src/main/java/org/bukkit/Material.java
+++ b/src/main/java/org/bukkit/Material.java
@@ -4578,11 +4578,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;
}
@@ -4653,8 +4653,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<? extends MaterialData> 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 dbc22807a33606f8fe326cc2f5f755fee5edc7aa..1416918d1924b362a688635823484f16e6adf125 100644
--- a/src/main/java/org/bukkit/NamespacedKey.java
+++ b/src/main/java/org/bukkit/NamespacedKey.java
@@ -73,12 +73,14 @@ public final class NamespacedKey implements net.kyori.adventure.key.Key, com.des
/**
* Create a key in a specific namespace.
+ * <p>
+ * For most plugin related code, you should prefer using the
+ * {@link NamespacedKey#NamespacedKey(Plugin, String)} constructor.
*
* @param namespace namespace
* @param key key
- * @deprecated should never be used by plugins, for internal use only!!
+ * @see #NamespacedKey(Plugin, String)
*/
- @Deprecated
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/Registry.java b/src/main/java/org/bukkit/Registry.java
index 3e5d6fd08bcc66593d7669104705436f6dfb20fc..4a3c42f9c480c53f935d09bcc3656259c755661d 100644
--- a/src/main/java/org/bukkit/Registry.java
+++ b/src/main/java/org/bukkit/Registry.java
@@ -248,8 +248,11 @@ public interface Registry<T extends Keyed> extends Iterable<T> {
*
* @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 20f9384c30f46e11631a7f79c48915bf55762858..291abd48c3c8af0807bce312c18d8cf287c1f8cf 100644
--- a/src/main/java/org/bukkit/Server.java
+++ b/src/main/java/org/bukkit/Server.java
@@ -1001,10 +1001,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);
@@ -1467,7 +1465,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 4587b866d3d3bcd0080f072245d46f719d61f767..d667ac100f1bf11f4a8f9e8c53887a86e890ac6f 100644
--- a/src/main/java/org/bukkit/World.java
+++ b/src/main/java/org/bukkit/World.java
@@ -396,9 +396,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);
/**
@@ -2111,8 +2110,10 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
* @return The spawned {@link FallingBlock} instance
* @throws IllegalArgumentException if {@link Location} or {@link
* MaterialData} are null or {@link Material} of the {@link MaterialData} is not a block
+ * @deprecated use {@link #spawnFallingBlock(Location, BlockData)}
*/
@NotNull
+ @Deprecated // Paper
public FallingBlock spawnFallingBlock(@NotNull Location location, @NotNull MaterialData data) throws IllegalArgumentException;
/**
diff --git a/src/main/java/org/bukkit/block/BlockState.java b/src/main/java/org/bukkit/block/BlockState.java
index 631cbf2be51040eee00aa39a39c5ec4003f91843..3147e278eac674ed21d714bbe318b135c0a6b408 100644
--- a/src/main/java/org/bukkit/block/BlockState.java
+++ b/src/main/java/org/bukkit/block/BlockState.java
@@ -35,8 +35,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();
/**
@@ -131,7 +133,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/entity/Enderman.java b/src/main/java/org/bukkit/entity/Enderman.java
index 821c690f8a32918bdb284ffec4af98f411f76ccc..94f3a8c4bf8cf14263d34d866db66728e98dfdb0 100644
--- a/src/main/java/org/bukkit/entity/Enderman.java
+++ b/src/main/java/org/bukkit/entity/Enderman.java
@@ -25,15 +25,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/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 94fad96f8fd57314c571b6396f44cd9d91254cfc..b4c41ab64ef35ac0d172c041d97e8fe9b3eb8aa6 100644
--- a/src/main/java/org/bukkit/entity/LivingEntity.java
+++ b/src/main/java/org/bukkit/entity/LivingEntity.java
@@ -640,7 +640,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 <!-- Paper - future note: should wait a mojang input client/server side -->
*/
+ @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 c854860c13912f9a8707eb825cca23763d1323a6..a523fca4baab447181ef91df67fa69b24e010149 100644
--- a/src/main/java/org/bukkit/entity/Projectile.java
+++ b/src/main/java/org/bukkit/entity/Projectile.java
@@ -29,7 +29,9 @@ public interface Projectile extends Entity {
* If a small fireball does not bounce it will set the target on fire.
*
* @return true if it should bounce.
+ * @deprecated Does not do anything
*/
+ @Deprecated(forRemoval = true) // Paper
public boolean doesBounce();
/**
@@ -37,6 +39,8 @@ public interface Projectile extends Entity {
* something.
*
* @param doesBounce whether or not it should bounce.
+ * @deprecated Does not do anything
*/
+ @Deprecated(forRemoval = true) // Paper
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/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/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/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<T extends 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<FurnaceRecipe> {
*
* @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<ItemStack> {
*
* @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<ItemStack> {
* @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<ItemStack> {
*
* @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<ItemStack> {
* @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/ItemFactory.java b/src/main/java/org/bukkit/inventory/ItemFactory.java
index 349da0065ddf000cacdc259fab0f2c759332e9ad..abf95d917eca248ff3f5a5caa008c1c87fa1e029 100644
--- a/src/main/java/org/bukkit/inventory/ItemFactory.java
+++ b/src/main/java/org/bukkit/inventory/ItemFactory.java
@@ -26,7 +26,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 c2d224b6472a65cd362e1ab55ce7e3d0b5a3befc..833322283bdddc16524ddb56aaa481bf36881eeb 100644
--- a/src/main/java/org/bukkit/inventory/ShapedRecipe.java
+++ b/src/main/java/org/bukkit/inventory/ShapedRecipe.java
@@ -112,8 +112,10 @@ public class ShapedRecipe implements Recipe, Keyed {
* @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());
}
@@ -191,7 +193,9 @@ public class ShapedRecipe implements Recipe, Keyed {
* 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<Character, ItemStack> getIngredientMap() {
HashMap<Character, ItemStack> result = new HashMap<Character, ItemStack>();
diff --git a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
index 8bf26da12dcb03f22f842a57798948d5513c227d..e5a2febc26a2b0aca0b83c48cd35ccdea1e6a222 100644
--- a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
+++ b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
@@ -53,8 +53,10 @@ public class ShapelessRecipe implements Recipe, Keyed {
*
* @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);
}
@@ -90,8 +92,10 @@ public class ShapelessRecipe implements Recipe, Keyed {
* @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());
}
@@ -208,8 +212,10 @@ public class ShapelessRecipe implements Recipe, Keyed {
*
* @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());
}
@@ -236,8 +242,10 @@ public class ShapelessRecipe implements Recipe, Keyed {
* @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());
}
@@ -298,7 +306,9 @@ public class ShapelessRecipe implements Recipe, Keyed {
* 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<ItemStack> getIngredientList() {
ArrayList<ItemStack> result = new ArrayList<ItemStack>(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/ItemMeta.java b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
index 55e9dc5d1d87fbc9d0dabbb7bd59584fe2c5f379..5c1ca0e47f0ac1525c3d37b55f52874878f44c28 100644
--- a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
+++ b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
@@ -74,8 +74,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();
/**
@@ -84,16 +86,20 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
* Plugins should check that hasLocalizedName() returns <code>true</code>
* 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/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 {
/**