diff --git a/pom.xml b/pom.xml index 946f72a..e7d8a0b 100644 --- a/pom.xml +++ b/pom.xml @@ -177,6 +177,14 @@ + + + org.jetbrains + annotations + 23.0.0 + + provided + org.junit.jupiter diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/DataStore.java b/src/main/java/me/ryanhamshire/GriefPrevention/DataStore.java index 078ebc5..a7c2f2b 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/DataStore.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/DataStore.java @@ -19,10 +19,10 @@ package me.ryanhamshire.GriefPrevention; import com.google.common.io.Files; +import me.ryanhamshire.GriefPrevention.events.ClaimResizeEvent; import me.ryanhamshire.GriefPrevention.events.ClaimCreatedEvent; import me.ryanhamshire.GriefPrevention.events.ClaimDeletedEvent; import me.ryanhamshire.GriefPrevention.events.ClaimExtendEvent; -import me.ryanhamshire.GriefPrevention.events.ClaimModifiedEvent; import me.ryanhamshire.GriefPrevention.events.ClaimTransferEvent; import org.bukkit.Bukkit; import org.bukkit.ChatColor; @@ -1440,7 +1440,7 @@ public abstract class DataStore newClaim.greaterBoundaryCorner = new Location(world, newx2, newy2, newz2); //call event here to check if it has been cancelled - ClaimModifiedEvent event = new ClaimModifiedEvent(oldClaim, newClaim, player); + ClaimResizeEvent event = new ClaimResizeEvent(oldClaim, newClaim, player); Bukkit.getPluginManager().callEvent(event); //return here if event is cancelled @@ -1462,7 +1462,15 @@ public abstract class DataStore } //ask the datastore to try and resize the claim, this checks for conflicts with other claims - CreateClaimResult result = GriefPrevention.instance.dataStore.resizeClaim(playerData.claimResizing, newx1, newx2, newy1, newy2, newz1, newz2, player); + CreateClaimResult result = GriefPrevention.instance.dataStore.resizeClaim( + playerData.claimResizing, + newClaim.getLesserBoundaryCorner().getBlockX(), + newClaim.getGreaterBoundaryCorner().getBlockX(), + newClaim.getLesserBoundaryCorner().getBlockY(), + newClaim.getGreaterBoundaryCorner().getBlockY(), + newClaim.getLesserBoundaryCorner().getBlockZ(), + newClaim.getGreaterBoundaryCorner().getBlockZ(), + player); if (result.succeeded) { diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/GriefPrevention.java b/src/main/java/me/ryanhamshire/GriefPrevention/GriefPrevention.java index a9176a7..acac585 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/GriefPrevention.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/GriefPrevention.java @@ -1591,9 +1591,8 @@ public class GriefPrevention extends JavaPlugin } //dropping permissions - for (int i = 0; i < playerData.getClaims().size(); i++) - { - claim = playerData.getClaims().get(i); + for (Claim targetClaim : event.getClaims()) { + claim = targetClaim; //if untrusting "all" drop all permissions if (clearPermissions) @@ -1656,7 +1655,7 @@ public class GriefPrevention extends JavaPlugin return true; } - claim.clearPermissions(); + event.getClaims().forEach(Claim::clearPermissions); GriefPrevention.sendMessage(player, TextMode.Success, Messages.ClearPermissionsOneClaim); } @@ -1685,8 +1684,7 @@ public class GriefPrevention extends JavaPlugin return true; } - claim.dropPermission(idToDrop); - claim.managers.remove(idToDrop); + event.getClaims().forEach(targetClaim -> targetClaim.dropPermission(event.getIdentifier())); //beautify for output if (args[0].equals("public")) @@ -3054,7 +3052,7 @@ public class GriefPrevention extends JavaPlugin } //apply changes - for (Claim currentClaim : targetClaims) + for (Claim currentClaim : event.getClaims()) { if (permissionLevel == null) { diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/AccrueClaimBlocksEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/AccrueClaimBlocksEvent.java index b884175..9d7f3a0 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/AccrueClaimBlocksEvent.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/AccrueClaimBlocksEvent.java @@ -1,66 +1,68 @@ package me.ryanhamshire.GriefPrevention.events; import org.bukkit.entity.Player; -import org.bukkit.event.Event; +import org.bukkit.event.Cancellable; import org.bukkit.event.HandlerList; +import org.bukkit.event.player.PlayerEvent; +import org.jetbrains.annotations.NotNull; /** - * Called when GP is about to deliver claim blocks to a player (~every 10 minutes) + * An {@link org.bukkit.event.Event Event} called when a {@link Player} is about to receive claim blocks. + * GriefPrevention calls this event 6 times hourly, once every 10 minutes. * - * @author RoboMWM - * 11/15/2016. + * @author RoboMWM on 11/15/2016 */ -public class AccrueClaimBlocksEvent extends Event +public class AccrueClaimBlocksEvent extends PlayerEvent implements Cancellable { - // Custom Event Requirements - private static final HandlerList handlers = new HandlerList(); - public static HandlerList getHandlerList() - { - return handlers; - } - - @Override - public HandlerList getHandlers() - { - return handlers; - } - - private final Player player; private int blocksToAccrue; - private boolean isIdle = false; - private boolean cancelled = false; + private boolean isIdle; /** - * @param player Player receiving accruals - * @param blocksToAccrue Blocks to accrue + * Construct a new {@code AccrueClaimBlocksEvent}. + * + *

Note that this event was designed for simple internal usage. Because of that, + * it is assumed GriefPrevention is handling block delivery at its standard rate of + * 6 times per hour. + *
To achieve a specific number of blocks to accrue, either multiply in advance or set + * using {@link #setBlocksToAccrue(int)} after construction. + * + * @param player the {@link Player} receiving accruals + * @param blocksToAccruePerHour the number of claim blocks to accrue multiplied by 6 + * @see #setBlocksToAccruePerHour(int) * @deprecated Use {@link #AccrueClaimBlocksEvent(Player, int, boolean)} instead */ - public AccrueClaimBlocksEvent(Player player, int blocksToAccrue) + @Deprecated + public AccrueClaimBlocksEvent(@NotNull Player player, int blocksToAccruePerHour) { - this.player = player; - this.blocksToAccrue = blocksToAccrue / 6; + this(player, blocksToAccruePerHour, false); } /** - * @param player Player receiving accruals - * @param blocksToAccrue Blocks to accrue - * @param isIdle Whether player is detected as idle + * Construct a new {@code AccrueClaimBlocksEvent}. + * + *

Note that this event was designed for simple internal usage. Because of that, + * it is assumed GriefPrevention is handling block delivery at its standard rate of + * 6 times per hour. + *
To achieve a specific number of blocks to accrue, either multiply in advance or set + * using {@link #setBlocksToAccrue(int)} after construction. + * + * @param player the {@link Player} receiving accruals + * @param blocksToAccruePerHour the number of claim blocks to accrue multiplied by 6 + * @param isIdle whether player is detected as idle + * @see #setBlocksToAccruePerHour(int) */ - public AccrueClaimBlocksEvent(Player player, int blocksToAccrue, boolean isIdle) + public AccrueClaimBlocksEvent(@NotNull Player player, int blocksToAccruePerHour, boolean isIdle) { - this.player = player; - this.blocksToAccrue = blocksToAccrue / 6; + super(player); + this.blocksToAccrue = blocksToAccruePerHour / 6; this.isIdle = isIdle; } - public Player getPlayer() - { - return this.player; - } - /** - * @return amount of claim blocks GP will deliver to the player for this 10 minute interval + * Get the number of claim blocks that will be delivered to the {@link Player}. + * + * @return the number of new claim blocks */ public int getBlocksToAccrue() { @@ -68,20 +70,7 @@ public class AccrueClaimBlocksEvent extends Event } /** - * @return whether the player was detected as idle (used for idle accrual percentage) - */ - public boolean isIdle() - { - return this.isIdle; - } - - public boolean isCancelled() - { - return this.cancelled; - } - - /** - * Modify the amount of claim blocks to deliver to the player for this 10 minute interval + * Set the number of claim blocks to be delivered to the {@link Player}. * * @param blocksToAccrue blocks to deliver */ @@ -91,18 +80,65 @@ public class AccrueClaimBlocksEvent extends Event } /** - * Similar to setBlocksToAccrue(int), but automatically converting from a per-hour rate value to a 10-minute rate value + * Set the number of blocks to accrue per hour. This assumes GriefPrevention is + * handling block delivery at its standard rate of 6 times per hour. * * @param blocksToAccruePerHour the per-hour rate of blocks to deliver + * @see #setBlocksToAccrue(int) */ - public void setBlocksToAccruePerHour(int blocksToAccruePerHour) { this.blocksToAccrue = blocksToAccruePerHour / 6; } - public void setCancelled(boolean cancel) + /** + * Get whether the {@link Player} is idle. This can be used to modify accrual rate + * for players who are inactive. + * + * @return whether the {@code Player} is idle + */ + public boolean isIdle() { - this.cancelled = cancel; + return this.isIdle; } + + /** + * Set whether the {@link Player} is idle. + * + * @param idle whether the {@code Player} is idle + */ + public void setIdle(boolean idle) + { + isIdle = idle; + } + + // Listenable event requirements + private static final HandlerList HANDLERS = new HandlerList(); + + public static HandlerList getHandlerList() + { + return HANDLERS; + } + + @Override + public @NotNull HandlerList getHandlers() + { + return HANDLERS; + } + + // Cancellable requirements + private boolean cancelled = false; + + @Override + public boolean isCancelled() + { + return cancelled; + } + + @Override + public void setCancelled(boolean cancelled) + { + this.cancelled = cancelled; + } + } diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimChangeEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimChangeEvent.java new file mode 100644 index 0000000..3bd745b --- /dev/null +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimChangeEvent.java @@ -0,0 +1,85 @@ +package me.ryanhamshire.GriefPrevention.events; + +import me.ryanhamshire.GriefPrevention.Claim; +import org.bukkit.event.Cancellable; +import org.bukkit.event.Event; +import org.bukkit.event.HandlerList; +import org.jetbrains.annotations.NotNull; + +/** + * An {@link Event} called when a {@link Claim} is changed. + * + *

If cancelled, the resulting changes will not be made. + * + *

Note that the {@link #getTo() new claim} will not necessarily be added to the datastore! Most implementations + * apply changes to the {@link #getFrom() existing claim} for better compatibility with add-ons holding instances. + * Additionally, while the new claim is modifiable, modifications will not necessarily be respected by implementations. + */ +public class ClaimChangeEvent extends Event implements Cancellable +{ + + private final @NotNull Claim from; + private final @NotNull Claim to; + + /** + * Construct a new {@code ClaimChangeEvent}. + * + * @param from the original {@link Claim} + * @param to the resulting {@code Claim} + */ + public ClaimChangeEvent(@NotNull Claim from, @NotNull Claim to) + { + this.from = from; + this.to = to; + } + + /** + * Get the original unmodified {@link Claim}. + * + * @return the initial {@code Claim} + */ + public @NotNull Claim getFrom() + { + return from; + } + + /** + * Get the resulting {@link Claim} after any changes have been applied. + * + * @return the resulting {@code Claim} + */ + public @NotNull Claim getTo() + { + return to; + } + + // Listenable event requirements + private static final HandlerList HANDLERS = new HandlerList(); + + public static HandlerList getHandlerList() + { + return HANDLERS; + } + + @Override + public @NotNull HandlerList getHandlers() + { + return HANDLERS; + } + + // Cancellable requirements + private boolean cancelled = false; + + @Override + public boolean isCancelled() + { + return cancelled; + } + + @Override + public void setCancelled(boolean cancelled) + { + this.cancelled = cancelled; + } + +} diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimCreatedEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimCreatedEvent.java index 72e02b0..b81f0ef 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimCreatedEvent.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimCreatedEvent.java @@ -3,44 +3,62 @@ package me.ryanhamshire.GriefPrevention.events; import me.ryanhamshire.GriefPrevention.Claim; import org.bukkit.command.CommandSender; import org.bukkit.event.Cancellable; -import org.bukkit.event.Event; import org.bukkit.event.HandlerList; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; /** - * This Event is thrown when a claim is created but before it is saved. If it is cancelled the claim will not be saved - * however the player will not recieved information as to why it was cancelled. - *

- * Created by Narimm on 5/08/2018. + * An {@link org.bukkit.event.Event Event} called when a {@link Claim} is created. + * + *

If cancelled, the resulting {@code Claim} will not be saved. + * The creator will not be notified why creation was cancelled, if they are notified at all. + * + * @author Narimm on 5/08/2018. */ - -public class ClaimCreatedEvent extends Event implements Cancellable +public class ClaimCreatedEvent extends ClaimEvent implements Cancellable { - private static final HandlerList handlers = new HandlerList(); + private final @Nullable CommandSender creator; - public static HandlerList getHandlerList() + /** + * Construct a new {@code ClaimCreatedEvent}. + * + * @param claim the {@link Claim} being created + * @param creator the {@link CommandSender} causing creation + */ + public ClaimCreatedEvent(@NotNull Claim claim, @Nullable CommandSender creator) { - return handlers; - } - - private final Claim claim; - - private final CommandSender creator; - - private boolean cancelled = false; - - public ClaimCreatedEvent(Claim claim, CommandSender creator) - { - this.claim = claim; + super(claim); this.creator = creator; } - @Override - public HandlerList getHandlers() + /** + * Get the {@link CommandSender} creating the {@link Claim}. + * + * @return the actor causing creation + */ + public @Nullable CommandSender getCreator() { - return handlers; + return creator; } + // Listenable event requirements + private static final HandlerList HANDLERS = new HandlerList(); + + public static HandlerList getHandlerList() + { + return HANDLERS; + } + + @Override + public @NotNull HandlerList getHandlers() + { + return HANDLERS; + } + + // Cancellable requirements + private boolean cancelled = false; + @Override public boolean isCancelled() { @@ -48,28 +66,9 @@ public class ClaimCreatedEvent extends Event implements Cancellable } @Override - public void setCancelled(boolean b) + public void setCancelled(boolean cancelled) { - this.cancelled = b; + this.cancelled = cancelled; } - /** - * The Claim - * - * @return Claim - */ - public Claim getClaim() - { - return claim; - } - - /** - * The actor creating the claim - * - * @return the CommandSender - */ - public CommandSender getCreator() - { - return creator; - } } diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimDeletedEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimDeletedEvent.java index 421f735..f073c60 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimDeletedEvent.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimDeletedEvent.java @@ -1,46 +1,41 @@ package me.ryanhamshire.GriefPrevention.events; import me.ryanhamshire.GriefPrevention.Claim; -import org.bukkit.event.Event; import org.bukkit.event.HandlerList; +import org.jetbrains.annotations.NotNull; /** - * This event gets called whenever a claim is going to be deleted. This event is - * not called when a claim is resized. + * An {@link org.bukkit.event.Event Event} called when a {@link Claim} is deleted. + * + *

This event is not called when a claim is resized. * * @author Tux2 */ -public class ClaimDeletedEvent extends Event +public class ClaimDeletedEvent extends ClaimEvent { - // Custom Event Requirements - private static final HandlerList handlers = new HandlerList(); + /** + * Construct a new {@code ClaimDeletedEvent}. + * + * @param claim the {@link Claim} being deleted + */ + public ClaimDeletedEvent(@NotNull Claim claim) + { + super(claim); + } + + // Listenable event requirements + private static final HandlerList HANDLERS = new HandlerList(); public static HandlerList getHandlerList() { - return handlers; - } - - private final Claim claim; - - public ClaimDeletedEvent(Claim claim) - { - this.claim = claim; - } - - /** - * Gets the claim to be deleted. - * - * @return - */ - public Claim getClaim() - { - return claim; + return HANDLERS; } @Override - public HandlerList getHandlers() + public @NotNull HandlerList getHandlers() { - return handlers; + return HANDLERS; } + } \ No newline at end of file diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimEvent.java new file mode 100644 index 0000000..fdad909 --- /dev/null +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimEvent.java @@ -0,0 +1,35 @@ +package me.ryanhamshire.GriefPrevention.events; + +import me.ryanhamshire.GriefPrevention.Claim; +import org.bukkit.event.Event; +import org.jetbrains.annotations.NotNull; + +/** + * An {@link Event} involving a {@link Claim}. + */ +public abstract class ClaimEvent extends Event +{ + + private final @NotNull Claim claim; + + /** + * Construct a new {@code ClaimEvent}. + * + * @param claim the {@link Claim} involved + */ + protected ClaimEvent(@NotNull Claim claim) + { + this.claim = claim; + } + + /** + * Get the {@link Claim} involved. + * + * @return the {@code Claim} + */ + public final @NotNull Claim getClaim() + { + return this.claim; + } + +} diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimExpirationEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimExpirationEvent.java index 8d1c4d7..8b144db 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimExpirationEvent.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimExpirationEvent.java @@ -2,42 +2,48 @@ package me.ryanhamshire.GriefPrevention.events; import me.ryanhamshire.GriefPrevention.Claim; import org.bukkit.event.Cancellable; -import org.bukkit.event.Event; import org.bukkit.event.HandlerList; +import org.jetbrains.annotations.NotNull; -//if cancelled, the claim will not be deleted -public class ClaimExpirationEvent extends Event implements Cancellable +/** + * An {@link org.bukkit.event.Event Event} for when a {@link Claim} is deleted due to owner inactivity. + * + *

If cancelled, deletion will be prevented. + */ +public class ClaimExpirationEvent extends ClaimEvent implements Cancellable { - private static final HandlerList handlers = new HandlerList(); - private boolean cancelled = false; + + /** + * Construct a new {@code ClaimExpirationEvent}. + * + * @param claim the {@link Claim} expiring + */ + public ClaimExpirationEvent(@NotNull Claim claim) + { + super(claim); + } + + // Listenable event requirements + private static final HandlerList HANDLERS = new HandlerList(); public static HandlerList getHandlerList() { - return handlers; - } - - Claim claim; - - public ClaimExpirationEvent(Claim claim) - { - this.claim = claim; - } - - public Claim getClaim() - { - return this.claim; + return HANDLERS; } @Override - public HandlerList getHandlers() + public @NotNull HandlerList getHandlers() { - return handlers; + return HANDLERS; } + // Cancellable requirements + private boolean cancelled = false; + @Override public boolean isCancelled() { - return this.cancelled; + return cancelled; } @Override @@ -45,4 +51,5 @@ public class ClaimExpirationEvent extends Event implements Cancellable { this.cancelled = cancelled; } + } \ No newline at end of file diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimExtendEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimExtendEvent.java index cf6a648..f6ec86f 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimExtendEvent.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimExtendEvent.java @@ -1,58 +1,62 @@ package me.ryanhamshire.GriefPrevention.events; import me.ryanhamshire.GriefPrevention.Claim; -import org.bukkit.event.Cancellable; -import org.bukkit.event.Event; -import org.bukkit.event.HandlerList; +import org.jetbrains.annotations.NotNull; /** - * A cancellable event which is called when a claim's depth (lower y bound) is about to be extended. + * An {@link org.bukkit.event.Event Event} for when a {@link Claim Claim's} depth (lower Y bound) is to be extended. + * + *

Note that changes to the {@link #getTo() new claim} other than {@link #setNewDepth(int) setting new depth} will + * not be respected. + * * @author FrankHeijden */ -public class ClaimExtendEvent extends Event implements Cancellable +public class ClaimExtendEvent extends ClaimChangeEvent { - private static final HandlerList handlers = new HandlerList(); - public static HandlerList getHandlerList() + /** + * Construct a new {@code ClaimExtendEvent}. + * + * @param claim the {@link Claim} extending downwards + * @param newDepth the new depth of the {@code Claim} + */ + public ClaimExtendEvent(@NotNull Claim claim, int newDepth) { - return handlers; + super(claim, new Claim(claim)); + this.getTo().getLesserBoundaryCorner().setY(newDepth); } - private final Claim claim; - private final int newDepth; - private boolean cancelled; - - public ClaimExtendEvent(Claim claim, int newDepth) + /** + * Get the resulting {@link Claim} after modification. + * + * @return the resulting {@code Claim} + * @deprecated Use {@link #getTo() getTo} instead. + */ + @Deprecated + public @NotNull Claim getClaim() { - this.claim = claim; - this.newDepth = newDepth; - } - - @Override - public HandlerList getHandlers() - { - return handlers; - } - - public Claim getClaim() - { - return claim; + return getTo(); } + /** + * Get the new lowest depth that the {@link Claim} will encompass in the Y axis. + * + * @return the new depth + */ public int getNewDepth() { - return newDepth; + return getTo().getLesserBoundaryCorner().getBlockY(); } - @Override - public boolean isCancelled() - { - return cancelled; + /** + * Set the new lowest depth that the {@link Claim} will encompass in the Y axis. + * + *

Note that this value is not necessarily final - it will be modified to respect configuration and world limits. + * + * @param newDepth the new depth + */ + public void setNewDepth(int newDepth) { + getTo().getLesserBoundaryCorner().setY(newDepth); } - @Override - public void setCancelled(boolean cancelled) - { - this.cancelled = cancelled; - } } diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimInspectionEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimInspectionEvent.java index 944e99a..d40afd3 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimInspectionEvent.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimInspectionEvent.java @@ -6,35 +6,32 @@ import org.bukkit.entity.Player; import org.bukkit.event.Cancellable; import org.bukkit.event.HandlerList; import org.bukkit.event.player.PlayerEvent; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; import java.util.Collection; import java.util.Collections; /** - * Event is called whenever a user inspects a block using the inspection tool. + * An {@link org.bukkit.event.Event Event} called when a {@link Player} uses the claim inspection tool. + * * @author FrankHeijden */ public class ClaimInspectionEvent extends PlayerEvent implements Cancellable { - private static final HandlerList handlers = new HandlerList(); - public static HandlerList getHandlerList() - { - return handlers; - } - - private final Collection claims; - private final Block inspectedBlock; + private final @NotNull Collection claims; + private final @Nullable Block inspectedBlock; private final boolean inspectingNearbyClaims; - private boolean cancelled; /** - * Constructs a new ClaimInspectionEvent with a player and claim instance. - * @param player The player actor - * @param inspectedBlock The inspected block - * @param claim The claim involved + * Construct a new {@code ClaimInspectionEvent} for a {@link Player} inspecting a {@link Block}. + * + * @param player the inspecting {@code Player} + * @param inspectedBlock the inspected {@code Block} + * @param claim the {@link Claim} present or {@code null} if not claimed */ - public ClaimInspectionEvent(Player player, Block inspectedBlock, Claim claim) + public ClaimInspectionEvent(@NotNull Player player, @NotNull Block inspectedBlock, @Nullable Claim claim) { super(player); @@ -45,19 +42,24 @@ public class ClaimInspectionEvent extends PlayerEvent implements Cancellable } else { - this.claims = null; + this.claims = Collections.emptyList(); } this.inspectingNearbyClaims = false; } /** - * Constructs a new ClaimInspectionEvent with a player, list of claims and boolean flag inspectingNearbyClaims. - * @param player The player actor - * @param inspectedBlock The inspected block - * @param claims The list of claims involved - * @param inspectingNearbyClaims Whether or not the user is inspecting nearby claims ("shift-clicking") + * Construct a new {@code ClaimInspectionEvent}. + * + * @param player the inspecting {@link Player} + * @param inspectedBlock the inspected {@link Block} or {@code null} if no block was clicked + * @param claims a {@link Collection} of all claims inspected + * @param inspectingNearbyClaims whether the user is inspecting nearby claims ("shift-clicking") */ - public ClaimInspectionEvent(Player player, Block inspectedBlock, Collection claims, boolean inspectingNearbyClaims) + public ClaimInspectionEvent( + @NotNull Player player, + @Nullable Block inspectedBlock, + @NotNull Collection claims, + boolean inspectingNearbyClaims) { super(player); this.inspectedBlock = inspectedBlock; @@ -65,27 +67,53 @@ public class ClaimInspectionEvent extends PlayerEvent implements Cancellable this.inspectingNearbyClaims = inspectingNearbyClaims; } - public Block getInspectedBlock() + /** + * Get the inspected {@link Block}. May be {@code null} if inspecting nearby claims. + * + * @return the inspected {@code Block} or {@code null} if no block was clicked + */ + public @Nullable Block getInspectedBlock() { return inspectedBlock; } - public Collection getClaims() + /** + * Get a {@link Collection} of the claims being inspected. + * + * @return the inspected claims + */ + public @NotNull Collection getClaims() { return claims; } + /** + * Check if nearby claims are being inspected. + * + * @return whether the user is inspecting nearby claims + */ public boolean isInspectingNearbyClaims() { return inspectingNearbyClaims; } - @Override - public HandlerList getHandlers() + // Listenable event requirements + private static final HandlerList HANDLERS = new HandlerList(); + + public static HandlerList getHandlerList() { - return handlers; + return HANDLERS; } + @Override + public @NotNull HandlerList getHandlers() + { + return HANDLERS; + } + + // Cancellable requirements + private boolean cancelled = false; + @Override public boolean isCancelled() { @@ -97,4 +125,5 @@ public class ClaimInspectionEvent extends PlayerEvent implements Cancellable { this.cancelled = cancelled; } + } diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimModifiedEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimModifiedEvent.java index 4505606..5aef5ed 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimModifiedEvent.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimModifiedEvent.java @@ -3,84 +3,59 @@ package me.ryanhamshire.GriefPrevention.events; import me.ryanhamshire.GriefPrevention.Claim; import org.bukkit.command.CommandSender; -import org.bukkit.event.Cancellable; import org.bukkit.event.Event; -import org.bukkit.event.HandlerList; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; /** - * This Event is thrown when a claim is changed....it is not modifiable or cancellable and only serves as a notification - * a claim has changed. The CommandSender can be null in the event that the modification is called by the plugin itself. - * Created by Narimm on 5/08/2018. + * @deprecated replaced by more descriptive {@link ClaimResizeEvent} and generic {@link ClaimChangeEvent} + * + * An {@link Event} for when a {@link Claim} is changed. + * + *

If cancelled, the resulting changes will not be made. + * + * @author Narimm on 5/08/2018. */ -public class ClaimModifiedEvent extends Event implements Cancellable +@Deprecated +public class ClaimModifiedEvent extends ClaimChangeEvent { - private static final HandlerList handlers = new HandlerList(); + private final @Nullable CommandSender modifier; - public static HandlerList getHandlerList() + /** + * Construct a new {@code ClaimModifiedEvent}. + * + *

Note that the actor causing modification may not be present if done by plugins. + * + * @param from the unmodified {@link Claim} + * @param to the resulting {@code Claim} + * @param modifier the {@link CommandSender} causing modification + */ + public ClaimModifiedEvent(@NotNull Claim from, @NotNull Claim to, @Nullable CommandSender modifier) { - return handlers; - } - - private final Claim from; - private final Claim to; - private final CommandSender modifier; - private boolean cancelled; - - public ClaimModifiedEvent(Claim from, Claim to, CommandSender modifier) - { - this.from = from; - this.to = to; + super(from, to); this.modifier = modifier; } - @Override - public HandlerList getHandlers() - { - return handlers; - } - /** - * The claim + * Get the resulting {@link Claim} after modification. * - * @return the claim - * @deprecated Use the {@link #getTo() getTo} method. + * @return the resulting {@code Claim} + * @deprecated Use {@link #getTo()} instead. */ @Deprecated - public Claim getClaim() + public @NotNull Claim getClaim() { - return to; - } - - public Claim getFrom() - { - return from; - } - - public Claim getTo() - { - return to; + return getTo(); } /** - * The actor making the change...can be null + * Get the {@link CommandSender} modifying the {@link Claim}. May be {@code null} if caused by a plugin. * - * @return the CommandSender or null + * @return the actor causing creation */ - public CommandSender getModifier() + public @Nullable CommandSender getModifier() { return modifier; } - - @Override - public boolean isCancelled() - { - return cancelled; - } - - @Override - public void setCancelled(boolean cancelled) - { - this.cancelled = cancelled; - } } diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimPermissionCheckEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimPermissionCheckEvent.java index 3bde918..a23d4b3 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimPermissionCheckEvent.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimPermissionCheckEvent.java @@ -4,143 +4,176 @@ import me.ryanhamshire.GriefPrevention.Claim; import me.ryanhamshire.GriefPrevention.ClaimPermission; import org.bukkit.Bukkit; import org.bukkit.entity.Player; +import org.bukkit.event.Cancellable; import org.bukkit.event.Event; import org.bukkit.event.HandlerList; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; import java.util.UUID; import java.util.function.Supplier; /** - * This event is called when a {@link Claim} requires a specific level of trust. - * If the denial reason is null, the trust requirements are met and the action is allowed. + * An {@link Event} called when a {@link Claim} requires a specific level of trust. + * If the denial reason is {@code null}, the trust requirements are met and the action is allowed. */ -public class ClaimPermissionCheckEvent extends Event +public class ClaimPermissionCheckEvent extends ClaimEvent implements Cancellable { - private static final HandlerList handlers = new HandlerList(); - - private final Player checkedPlayer; - private final UUID checkedUUID; - private final Claim claim; - private final ClaimPermission requiredPermission; - private final Event triggeringEvent; - private Supplier denial; + private final @Nullable Player checkedPlayer; + private final @NotNull UUID checkedUUID; + private final @NotNull ClaimPermission requiredPermission; + private final @Nullable Event triggeringEvent; /** - * Constructor for a ClaimPermissionCheckEvent. + * Construct a new {@code ClaimPermissionCheckEvent}. * - * @param checked the Player being checked for permissions - * @param claim the Claim in which permissions are being checked - * @param required the ClaimPermission level required - * @param triggeringEvent the Event triggering the permission check + * @param checked the {@link Player} being checked for permissions + * @param claim the {@link Claim} in which permissions are being checked + * @param required the {@link ClaimPermission} level required + * @param triggeringEvent the {@link Event} triggering the permission check */ - public ClaimPermissionCheckEvent(Player checked, Claim claim, ClaimPermission required, Event triggeringEvent) + public ClaimPermissionCheckEvent( + @NotNull Player checked, + @NotNull Claim claim, + @NotNull ClaimPermission required, + @Nullable Event triggeringEvent) { this(checked, checked.getUniqueId(), claim, required, triggeringEvent); } /** - * Constructor for a ClaimPermissionCheckEvent. + * Construct a new {@code ClaimPermissionCheckEvent}. * - * @param checked the UUID being checked for permissions - * @param claim the Claim in which permissions are being checked - * @param required the ClaimPermission level required - * @param triggeringEvent the Event triggering the permission check + * @param checked the {@link UUID} being checked for permissions + * @param claim the {@link Claim} in which permissions are being checked + * @param required the {@link ClaimPermission} level required + * @param triggeringEvent the {@link Event} triggering the permission check */ - public ClaimPermissionCheckEvent(UUID checked, Claim claim, ClaimPermission required, Event triggeringEvent) + public ClaimPermissionCheckEvent( + @NotNull UUID checked, + @NotNull Claim claim, + @NotNull ClaimPermission required, + @Nullable Event triggeringEvent) { this(Bukkit.getPlayer(checked), checked, claim, required, triggeringEvent); } - private ClaimPermissionCheckEvent(Player checkedPlayer, UUID checkedUUID, Claim claim, ClaimPermission required, Event triggeringEvent) + private ClaimPermissionCheckEvent( + @Nullable Player checkedPlayer, + @NotNull UUID checkedUUID, + @NotNull Claim claim, + @NotNull ClaimPermission required, + @Nullable Event triggeringEvent) { + super(claim); this.checkedPlayer = checkedPlayer; this.checkedUUID = checkedUUID; - this.claim = claim; this.requiredPermission = required; this.triggeringEvent = triggeringEvent; } /** - * Returns the Player being checked for permission if online. + * Get the {@link Player} being checked for permission if online. * - * @return the Player being checked or null if offline + * @return the {@code Player} being checked or null if offline */ - public Player getCheckedPlayer() + public @Nullable Player getCheckedPlayer() { return checkedPlayer; } /** - * Returns the UUID being checked for permission. + * Get the {@link UUID} being checked for permission. * - * @return the UUID being checked for permission + * @return the {@code UUID} being checked for permission */ - public UUID getCheckedUUID() + public @NotNull UUID getCheckedUUID() { return checkedUUID; } /** - * Returns the Claim in which permission is being checked. + * Get the {@link ClaimPermission} being checked for. * - * @return the Claim in which permission is being checked + * @return the {@code ClaimPermission} being checked for */ - public Claim getClaim() - { - return claim; - } - - /** - * Returns the ClaimPermission being checked for. - * - * @return the ClaimPermission being checked for - */ - public ClaimPermission getRequiredPermission() + public @NotNull ClaimPermission getRequiredPermission() { return requiredPermission; } /** - * Returns the Event causing this event to fire. + * Get the {@link Event} causing this {@code ClaimPermissionCheckEvent} to fire. * - * @return the Event triggering this event or null if none was provided + * @return the triggering {@code Event} or null if none was provided */ - public Event getTriggeringEvent() + public @Nullable Event getTriggeringEvent() { return triggeringEvent; } + // Cancellable requirements + private @Nullable Supplier cancelReason = null; + + @Override + public boolean isCancelled() + { + return cancelReason != null; + } + /** - * Returns the reason the ClaimPermission check failed. + * @deprecated If cancelling, {@link #setDenialReason(Supplier)} is preferred. + * + * @param cancelled whether the event is cancelled + */ + @Override + @Deprecated + public void setCancelled(boolean cancelled) + { + if (!cancelled) + { + this.cancelReason = null; + } + else + { + this.cancelReason = () -> ""; + } + } + + /** + * Get the reason the ClaimPermission check failed. * If the check did not fail, the message will be null. * * @return the denial reason or null if permission is granted */ - public Supplier getDenialReason() + public @Nullable Supplier getDenialReason() { - return denial; + return cancelReason; } /** - * Sets the reason for denial. + * Set the reason for denial. * * @param denial the denial reason */ - public void setDenialReason(Supplier denial) + public void setDenialReason(@Nullable Supplier denial) { - this.denial = denial; + this.cancelReason = denial; } - @Override - public HandlerList getHandlers() - { - return handlers; - } + // Listenable event requirements + private static final HandlerList HANDLERS = new HandlerList(); public static HandlerList getHandlerList() { - return handlers; + return HANDLERS; + } + + @Override + public @NotNull HandlerList getHandlers() + { + return HANDLERS; } } diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimResizeEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimResizeEvent.java new file mode 100644 index 0000000..5cc89a3 --- /dev/null +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimResizeEvent.java @@ -0,0 +1,28 @@ +package me.ryanhamshire.GriefPrevention.events; + +import me.ryanhamshire.GriefPrevention.Claim; +import org.bukkit.command.CommandSender; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; + +/** + * An {@link org.bukkit.event.Event Event} called when a {@link Claim} is resized. + */ +public class ClaimResizeEvent extends ClaimModifiedEvent +{ + + /** + * Construct a new {@code ClaimResizeEvent}. + * + *

The actor causing modification may not be present if done by plugins. + * + * @param from the unmodified {@link Claim} + * @param to the resulting {@code Claim} + * @param modifier the {@link CommandSender} causing modification + */ + public ClaimResizeEvent(@NotNull Claim from, @NotNull Claim to, @Nullable CommandSender modifier) + { + super(from, to, modifier); + } + +} diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimTransferEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimTransferEvent.java index f234343..897f471 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimTransferEvent.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/ClaimTransferEvent.java @@ -2,44 +2,74 @@ package me.ryanhamshire.GriefPrevention.events; import me.ryanhamshire.GriefPrevention.Claim; import org.bukkit.event.Cancellable; -import org.bukkit.event.Event; import org.bukkit.event.HandlerList; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; import java.util.UUID; /** - * This Event is thrown when a claim is being transferred. If it is cancelled the claim will not be transferred. - *

- * Created by bertek41 on 30/10/2021. + * An {@link org.bukkit.event.Event Event} called when a {@link Claim} is transferred. + * If cancelled, the resulting changes will not be made. + * + * @author bertek41 on 10/30/2021 */ -public class ClaimTransferEvent extends Event implements Cancellable +public class ClaimTransferEvent extends ClaimEvent implements Cancellable { - private static final HandlerList handlers = new HandlerList(); + private @Nullable UUID newOwner; - public static HandlerList getHandlerList() - { - return handlers; - } - - private final Claim claim; - - private UUID newOwner; - - private boolean cancelled = false; - - public ClaimTransferEvent(Claim claim, UUID newOwner) { - this.claim = claim; + /** + * Construct a new {@code ClaimTransferEvent}. + * + * @param claim the {@link Claim} being transferred + * @param newOwner the {@link UUID} of the new owner + */ + public ClaimTransferEvent(@NotNull Claim claim, @Nullable UUID newOwner) { + super(claim); this.newOwner = newOwner; } - @Override - public HandlerList getHandlers() + /** + * Get the {@link UUID} of the new owner of the claim. + * This may be {@code null} to indicate an administrative claim. + * + * @return the {@code UUID} of the new owner + */ + public @Nullable UUID getNewOwner() { - return handlers; + return newOwner; } + /** + * Set the {@link UUID} of the new owner of the claim. + * This may be {@code null} to indicate an administrative claim. + * + * @param newOwner the {@code UUID} of the new owner + */ + public void setNewOwner(@Nullable UUID newOwner) + { + this.newOwner = newOwner; + } + + // Listenable event requirements + private static final HandlerList HANDLERS = new HandlerList(); + + public static HandlerList getHandlerList() + { + return HANDLERS; + } + + @Override + public @NotNull HandlerList getHandlers() + { + return HANDLERS; + } + + // Cancellable requirements + private boolean cancelled = false; + @Override public boolean isCancelled() { @@ -52,33 +82,4 @@ public class ClaimTransferEvent extends Event implements Cancellable this.cancelled = cancelled; } - /** - * The Claim - * - * @return {@link Claim} - */ - public Claim getClaim() - { - return claim; - } - - /** - * New owner of the claim - * - * @return the {@link java.util.UUID} of new owner or null - */ - public UUID getNewOwner() - { - return newOwner; - } - - /** - * Sets the new owner of the claim - * - * @param {@link java.util.UUID} newOwner can be null - */ - public void setNewOwner(UUID newOwner) - { - this.newOwner = newOwner; - } } diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/MultiClaimEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/MultiClaimEvent.java new file mode 100644 index 0000000..03da8d4 --- /dev/null +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/MultiClaimEvent.java @@ -0,0 +1,41 @@ +package me.ryanhamshire.GriefPrevention.events; + +import me.ryanhamshire.GriefPrevention.Claim; +import org.bukkit.event.Event; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; + +import java.util.Collection; +import java.util.HashSet; + +/** + * An {@link Event} involving multiple {@link Claim Claims}. + */ +public abstract class MultiClaimEvent extends Event +{ + + private final @NotNull Collection claims; + + public MultiClaimEvent(@Nullable Collection claims) + { + if (claims == null) + { + this.claims = new HashSet<>(); + } + else + { + this.claims = new HashSet<>(claims); + } + } + + /** + * Get all affected claims. + * + * @return the affected claims + */ + public @NotNull Collection getClaims() + { + return claims; + } + +} diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/PlayerKickBanEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/PlayerKickBanEvent.java index f22a4f4..3787411 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/PlayerKickBanEvent.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/PlayerKickBanEvent.java @@ -1,89 +1,108 @@ package me.ryanhamshire.GriefPrevention.events; import org.bukkit.entity.Player; -import org.bukkit.event.Event; +import org.bukkit.event.Cancellable; import org.bukkit.event.HandlerList; +import org.bukkit.event.player.PlayerEvent; +import org.jetbrains.annotations.NotNull; /** - * Called when GP is about to kick or ban a player + * An {@link org.bukkit.event.Event Event} called when GriefPrevention kicks or bans a {@link Player}. * - * @author BillyGalbreath - * 03/10/2017. + * @author BillyGalbreath on 03/10/2017 */ -public class PlayerKickBanEvent extends Event +public class PlayerKickBanEvent extends PlayerEvent implements Cancellable { - private static final HandlerList handlers = new HandlerList(); - public static HandlerList getHandlerList() - { - return handlers; - } - - @Override - public HandlerList getHandlers() - { - return handlers; - } - - private final Player player; - private final String reason; - private final String source; + private final @NotNull String reason; + private final @NotNull String source; private final boolean ban; - private boolean cancelled = false; /** - * @param player Player getting kicked and/or banned - * @param reason Reason message for kick/ban - * @param source What caused the kick/ban - * @param ban True if player is getting banned + * Construct a new {@code PlayerKickBanEvent}. + * + * @param player the affected {@link Player} + * @param reason the reason for the kick/ban + * @param source the source of the kick/ban + * @param ban whether the {@code Player} will be banned */ - public PlayerKickBanEvent(Player player, String reason, String source, boolean ban) + public PlayerKickBanEvent(Player player, @NotNull String reason, @NotNull String source, boolean ban) { - this.player = player; + super(player); this.reason = reason; this.source = source; this.ban = ban; } /** - * @return player getting kicked/banned + * Get the reason why the {@link Player} is being kicked. + * + * @return the reason why the target is being kicked */ - public Player getPlayer() - { - return this.player; - } - - /** - * @return reason player is getting kicked/banned - */ - public String getReason() + public @NotNull String getReason() { return this.reason; } /** - * @return source that is kicking/banning the player + * Get the source of the kick. + * + * @return the source of the kick */ - public String getSource() + public @NotNull String getSource() { return this.source; } /** - * @return is player getting banned + * Get whether the {@link Player} will also be banned. + * + * @return whether the target will be banned */ + public boolean isBan() + { + return ban; + } + + /** + * Get whether the {@link Player} will also be banned. + * + * @deprecated use {@link #isBan()} + * @return whether the target will be banned + */ + @Deprecated public boolean getBan() { - return this.ban; + return this.isBan(); } + // Listenable event requirements + private static final HandlerList HANDLERS = new HandlerList(); + + public static HandlerList getHandlerList() + { + return HANDLERS; + } + + @Override + public @NotNull HandlerList getHandlers() + { + return HANDLERS; + } + + // Cancellable requirements + private boolean cancelled = false; + + @Override public boolean isCancelled() { - return this.cancelled; + return cancelled; } - public void setCancelled(boolean cancel) + @Override + public void setCancelled(boolean cancelled) { - this.cancelled = cancel; + this.cancelled = cancelled; } + } diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/PreventBlockBreakEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/PreventBlockBreakEvent.java index 07bb4fc..fee8190 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/PreventBlockBreakEvent.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/PreventBlockBreakEvent.java @@ -4,39 +4,57 @@ import org.bukkit.event.Cancellable; import org.bukkit.event.Event; import org.bukkit.event.HandlerList; import org.bukkit.event.block.BlockBreakEvent; +import org.jetbrains.annotations.NotNull; -//if cancelled, GriefPrevention will allow a block to be broken which it would not have otherwise +/** + * An {@link Event} called when GriefPrevention prevents a {@link BlockBreakEvent}. + * If cancelled, GriefPrevention will allow the event to complete normally. + */ public class PreventBlockBreakEvent extends Event implements Cancellable { - private static final HandlerList handlers = new HandlerList(); - private boolean cancelled = false; - private final BlockBreakEvent innerEvent; + private final @NotNull BlockBreakEvent innerEvent; - public static HandlerList getHandlerList() - { - return handlers; - } - - public PreventBlockBreakEvent(BlockBreakEvent innerEvent) + /** + * Construct a new {@code PreventBlockBreakEvent}. + * + * @param innerEvent the inner {@link BlockBreakEvent} + */ + public PreventBlockBreakEvent(@NotNull BlockBreakEvent innerEvent) { this.innerEvent = innerEvent; } - public BlockBreakEvent getInnerEvent() + /** + * Get the {@link BlockBreakEvent} being cancelled by GriefPrevention. + * + * @return the inner {@code BlockBreakEvent} + */ + public @NotNull BlockBreakEvent getInnerEvent() { return this.innerEvent; } - @Override - public HandlerList getHandlers() + // Listenable event requirements + private static final HandlerList HANDLERS = new HandlerList(); + + public static HandlerList getHandlerList() { - return handlers; + return HANDLERS; } + @Override + public @NotNull HandlerList getHandlers() + { + return HANDLERS; + } + + // Cancellable requirements + private boolean cancelled = false; + @Override public boolean isCancelled() { - return this.cancelled; + return cancelled; } @Override @@ -44,4 +62,5 @@ public class PreventBlockBreakEvent extends Event implements Cancellable { this.cancelled = cancelled; } + } \ No newline at end of file diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/PreventPvPEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/PreventPvPEvent.java index c408e3d..490e1c2 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/PreventPvPEvent.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/PreventPvPEvent.java @@ -4,60 +4,76 @@ import me.ryanhamshire.GriefPrevention.Claim; import org.bukkit.entity.Entity; import org.bukkit.entity.Player; import org.bukkit.event.Cancellable; -import org.bukkit.event.Event; import org.bukkit.event.HandlerList; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; -//if cancelled, GriefPrevention will not cancel the PvP event it's processing. -public class PreventPvPEvent extends Event implements Cancellable +/** + * An {@link org.bukkit.event.Event Event} called when GriefPrevention prevents PvP combat. + * If cancelled, GriefPrevention will allow the event to complete normally. + */ +public class PreventPvPEvent extends ClaimEvent implements Cancellable { - private static final HandlerList handlers = new HandlerList(); - private boolean cancelled = false; - public static HandlerList getHandlerList() + private final @Nullable Player attacker; + private final @NotNull Entity defender; + + /** + * Construct a new {@code PreventPvPEvent}. + * + * @param claim the {@link Claim} in which the attack is occurring + * @param attacker the attacking {@link Player} + * @param defender the {@link Entity} being attacked + */ + public PreventPvPEvent(@NotNull Claim claim, @Nullable Player attacker, @NotNull Entity defender) { - return handlers; - } - - Claim claim; - Player attacker; - Entity defender; - - public PreventPvPEvent(Claim claim, Player attacker, Entity defender) - { - this.claim = claim; + super(claim); this.attacker = attacker; this.defender = defender; } - public Claim getClaim() - { - return this.claim; - } - - public Player getAttacker() + /** + * Get the attacking {@link Player}. May be {@code null} for damage from area of effect clouds and similar. + * + * @return the attacker + */ + public @Nullable Player getAttacker() { return attacker; } /** - * @return The defender -- almost in all cases a player, unless the attacker damages a Tamable (pet), - * in which case the pet is returned. + * Get the {@link Entity} being attacked. This may be a {@link Player} + * or {@link org.bukkit.entity.Tameable Tameable}. + * + * @return the {@code Entity} being attacked */ - public Entity getDefender() + public @NotNull Entity getDefender() { return defender; } - @Override - public HandlerList getHandlers() + // Listenable event requirements + private static final HandlerList HANDLERS = new HandlerList(); + + public static HandlerList getHandlerList() { - return handlers; + return HANDLERS; } + @Override + public @NotNull HandlerList getHandlers() + { + return HANDLERS; + } + + // Cancellable requirements + private boolean cancelled = false; + @Override public boolean isCancelled() { - return this.cancelled; + return cancelled; } @Override @@ -65,4 +81,5 @@ public class PreventPvPEvent extends Event implements Cancellable { this.cancelled = cancelled; } + } \ No newline at end of file diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/ProtectDeathDropsEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/ProtectDeathDropsEvent.java index 5f20789..2000512 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/ProtectDeathDropsEvent.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/ProtectDeathDropsEvent.java @@ -4,40 +4,59 @@ import me.ryanhamshire.GriefPrevention.Claim; import org.bukkit.event.Cancellable; import org.bukkit.event.Event; import org.bukkit.event.HandlerList; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; -//if cancelled, GriefPrevention will not protect items dropped by a player on death +/** + * An {@link Event} called when GriefPrevention protects items after a death. + * If cancelled, GriefPrevention will allow the event to complete normally. + */ public class ProtectDeathDropsEvent extends Event implements Cancellable { - private static final HandlerList handlers = new HandlerList(); - private boolean cancelled = false; - public static HandlerList getHandlerList() - { - return handlers; - } + private final @Nullable Claim claim; - Claim claim; - - public ProtectDeathDropsEvent(Claim claim) + /** + * Construct a new {@code ProtectDeathDropsEvent}. + * + * @param claim the claim in which the death occurred + */ + public ProtectDeathDropsEvent(@Nullable Claim claim) { this.claim = claim; } - public Claim getClaim() + /** + * Get the claim in which the death occurred. May be {@code null}. + * + * @return the claim in which the death occurred + */ + public @Nullable Claim getClaim() { return this.claim; } - @Override - public HandlerList getHandlers() + // Listenable event requirements + private static final HandlerList HANDLERS = new HandlerList(); + + public static HandlerList getHandlerList() { - return handlers; + return HANDLERS; } + @Override + public @NotNull HandlerList getHandlers() + { + return HANDLERS; + } + + // Cancellable requirements + private boolean cancelled = false; + @Override public boolean isCancelled() { - return this.cancelled; + return cancelled; } @Override @@ -45,4 +64,5 @@ public class ProtectDeathDropsEvent extends Event implements Cancellable { this.cancelled = cancelled; } + } \ No newline at end of file diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/SaveTrappedPlayerEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/SaveTrappedPlayerEvent.java index bd776b2..24b2d7f 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/SaveTrappedPlayerEvent.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/SaveTrappedPlayerEvent.java @@ -3,53 +3,71 @@ package me.ryanhamshire.GriefPrevention.events; import me.ryanhamshire.GriefPrevention.Claim; import org.bukkit.Location; import org.bukkit.event.Cancellable; -import org.bukkit.event.Event; import org.bukkit.event.HandlerList; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; -//if destination field is set, then GriefPrevention will send the player to that location instead of searching for one -public class SaveTrappedPlayerEvent extends Event implements Cancellable +/** + * An {@link org.bukkit.event.Event Event} called when a user is rescued from a {@link Claim}. + */ +public class SaveTrappedPlayerEvent extends ClaimEvent implements Cancellable { - private static final HandlerList handlers = new HandlerList(); - private boolean cancelled = false; - private Location destination = null; - public static HandlerList getHandlerList() + private @Nullable Location destination = null; + + /** + * Construct a new {@code ClaimChangeEvent}. + * + * @param claim {@link Claim} the user is to be rescued from + */ + public SaveTrappedPlayerEvent(@NotNull Claim claim) { - return handlers; + super(claim); } - Claim claim; - - public SaveTrappedPlayerEvent(Claim claim) - { - this.claim = claim; - } - - public Location getDestination() + /** + * Get the destination that the user will be sent to. This is {@code null} by default, + * indicating that GriefPrevention will search for a safe location. + * + * @return the destination to send the {@code Player} to + */ + public @Nullable Location getDestination() { return destination; } - public void setDestination(Location destination) + /** + * Set the destination that the user will be sent to. If {@code null}, + * GriefPrevention will search for a location. + * + * @param destination the destination to send the {@code Player} to + */ + public void setDestination(@Nullable Location destination) { this.destination = destination; } - public Claim getClaim() + // Listenable event requirements + private static final HandlerList HANDLERS = new HandlerList(); + + public static HandlerList getHandlerList() { - return this.claim; + return HANDLERS; } @Override - public HandlerList getHandlers() + public @NotNull HandlerList getHandlers() { - return handlers; + return HANDLERS; } + // Cancellable requirements + private boolean cancelled = false; + @Override public boolean isCancelled() { - return this.cancelled; + return cancelled; } @Override @@ -57,4 +75,5 @@ public class SaveTrappedPlayerEvent extends Event implements Cancellable { this.cancelled = cancelled; } + } \ No newline at end of file diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/TrustChangedEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/TrustChangedEvent.java index 30b329c..5199db2 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/TrustChangedEvent.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/TrustChangedEvent.java @@ -4,93 +4,95 @@ import me.ryanhamshire.GriefPrevention.Claim; import me.ryanhamshire.GriefPrevention.ClaimPermission; import org.bukkit.entity.Player; import org.bukkit.event.Cancellable; -import org.bukkit.event.Event; import org.bukkit.event.HandlerList; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; -import java.util.ArrayList; +import java.util.Collections; import java.util.List; /** - * This event is thrown when the trust is changed in one or more claims + * An {@link org.bukkit.event.Event Event} called when a {@link Player} modifies + * {@link ClaimPermission permissions} in one or more {@link Claim claims}. * * @author roinujnosde */ -public class TrustChangedEvent extends Event implements Cancellable +public class TrustChangedEvent extends MultiClaimEvent implements Cancellable { - private static final HandlerList handlers = new HandlerList(); - - private final Player changer; - private final List claims; - private final ClaimPermission claimPermission; + private final @NotNull Player changer; + private final @Nullable ClaimPermission claimPermission; private final boolean given; - private final String identifier; - private boolean cancelled; + private final @NotNull String identifier; - public TrustChangedEvent(Player changer, List claims, ClaimPermission claimPermission, boolean given, - String identifier) + /** + * Construct a new {@code TrustChangedEvent} for several {@link Claim claims}. + * + * @param changer the {@link Player} causing the trust changes + * @param claims the affected {@code Claims} + * @param claimPermission the new {@link ClaimPermission} to assign or {@code null} if trust is removed + * @param given whether trust is being given or taken + * @param identifier the identifier whose trust is being affected + */ + public TrustChangedEvent( + @NotNull Player changer, + @Nullable List claims, + @Nullable ClaimPermission claimPermission, + boolean given, + @NotNull String identifier) { - super(); + super(claims); this.changer = changer; - this.claims = claims; this.claimPermission = claimPermission; this.given = given; this.identifier = identifier; } - public TrustChangedEvent(Player changer, Claim claim, ClaimPermission claimPermission, boolean given, String identifier) - { - this.changer = changer; - claims = new ArrayList<>(); - claims.add(claim); - this.claimPermission = claimPermission; - this.given = given; - this.identifier = identifier; - } - - @Override - public HandlerList getHandlers() - { - return handlers; - } - - public static HandlerList getHandlerList() - { - return handlers; - } - /** - * Gets who made the change + * Construct a new {@code TrustChangedEvent} for a single {@link Claim}. + * + * @param changer the {@link Player} causing the trust changes + * @param claim the affected {@code Claim} + * @param claimPermission the new {@link ClaimPermission} to assign or {@code null} if trust is removed + * @param given whether trust is being given or taken + * @param identifier the identifier whose trust is being affected + */ + public TrustChangedEvent( + @NotNull Player changer, + @NotNull Claim claim, + @Nullable ClaimPermission claimPermission, + boolean given, + @NotNull String identifier) + { + super(Collections.singleton(claim)); + this.changer = changer; + this.claimPermission = claimPermission; + this.given = given; + this.identifier = identifier; + } + + /** + * Get the {@link Player} who made the change. * * @return the changer */ - public Player getChanger() + public @NotNull Player getChanger() { return changer; } /** - * Gets the changed claims - * - * @return the changed claims - */ - public List getClaims() - { - return claims; - } - - /** - * Gets the claim permission (null if the permission is being taken) + * Get the {@link ClaimPermission} assigned or {@code null} if permission is being removed. * * @return the claim permission */ - public ClaimPermission getClaimPermission() + public @Nullable ClaimPermission getClaimPermission() { return claimPermission; } /** - * Checks if the trust is being given + * Check if trust is being given or taken. * * @return true if given, false if taken */ @@ -100,16 +102,33 @@ public class TrustChangedEvent extends Event implements Cancellable } /** - * Gets the identifier of the receiver of this action - * Can be: "public", "all", a UUID, a permission + * Get the identifier of the receiver of this action. + * Possible values: "public", "all", a {@link java.util.UUID UUID} in string form, a permission * * @return the identifier */ - public String getIdentifier() + public @NotNull String getIdentifier() { return identifier; } + // Listenable event requirements + private static final HandlerList HANDLERS = new HandlerList(); + + public static HandlerList getHandlerList() + { + return HANDLERS; + } + + @Override + public @NotNull HandlerList getHandlers() + { + return HANDLERS; + } + + // Cancellable requirements + private boolean cancelled = false; + @Override public boolean isCancelled() { @@ -121,4 +140,5 @@ public class TrustChangedEvent extends Event implements Cancellable { this.cancelled = cancelled; } + } diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/VisualizationEvent.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/VisualizationEvent.java index c50c31c..0c5c4c2 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/VisualizationEvent.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/VisualizationEvent.java @@ -5,28 +5,33 @@ import me.ryanhamshire.GriefPrevention.Visualization; import org.bukkit.entity.Player; import org.bukkit.event.HandlerList; import org.bukkit.event.player.PlayerEvent; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; +import org.jetbrains.annotations.Unmodifiable; import java.util.Collection; import java.util.Collections; +import java.util.HashSet; /** - * Called when GriefPrevention is sending claim visuals to a player + * An {@link org.bukkit.event.Event Event} called when a {@link Player} receives {@link Claim} visuals. */ public class VisualizationEvent extends PlayerEvent { - private static final HandlerList handlers = new HandlerList(); - private final Visualization visualization; - private final Collection claims; + + private final @Nullable Visualization visualization; + private final @NotNull @Unmodifiable Collection claims; private final boolean showSubdivides; private final boolean visualizingNearbyClaims; /** - * New visualization being sent to player + * Construct a new {@code VisualizationEvent} for a single {@link Claim} and its children. * - * @param player Player receiving visuals - * @param claim The claim being visualized (with subdivides), or null if visuals being removed + * @param player the {@link Player} receiving visuals + * @param visualization the {@link Visualization} to send + * @param claim the {@code Claim} being visualized with subdivisions */ - public VisualizationEvent(Player player, Visualization visualization, Claim claim) + public VisualizationEvent(@NotNull Player player, @Nullable Visualization visualization, @NotNull Claim claim) { super(player); this.visualization = visualization; @@ -36,56 +41,60 @@ public class VisualizationEvent extends PlayerEvent } /** - * New visualization being sent to player + * Construct a new {@code VisualizationEvent} for multiple {@link Claim Claims}. * - * @param player Player receiving visuals - * @param claims Claims being visualized (without subdivides) + * @param player the {@link Player} receiving visuals + * @param visualization the {@link Visualization} to send + * @param claims the {@code Claims} being visualized without subdivisions */ - public VisualizationEvent(Player player, Visualization visualization, Collection claims) + public VisualizationEvent(@NotNull Player player, @Nullable Visualization visualization, @NotNull Collection claims) { this(player, visualization, claims, false); } /** - * New visualization being sent to player + * Construct a new {@code VisualizationEvent} for multiple {@link Claim Claims}. * - * @param player Player receiving visuals - * @param claims Claims being visualized (without subdivides) - * @param visualizingNearbyClaims If the event is called on nearby claims (shift inspecting) + * @param player the {@link Player} receiving visuals + * @param visualization the {@link Visualization} to send + * @param claims the {@code Claims} being visualized without subdivisions + * @param visualizingNearbyClaims whether the visualization includes area claims or just the target location */ - public VisualizationEvent(Player player, Visualization visualization, Collection claims, boolean visualizingNearbyClaims) + public VisualizationEvent(@NotNull Player player, @Nullable Visualization visualization, @NotNull Collection claims, boolean visualizingNearbyClaims) { super(player); this.visualization = visualization; - this.claims = claims; + this.claims = Collections.unmodifiableCollection(new HashSet<>(claims)); this.showSubdivides = false; this.visualizingNearbyClaims = visualizingNearbyClaims; } /** - * Get the visualization, or null if visualization being removed + * Get the {@link Visualization}. May be {@code null} if being removed. * - * @return The visualization object + * @return the {@code Visualization} object */ - public Visualization getVisualization() + public @Nullable Visualization getVisualization() { return visualization; } /** - * Get the claims being visualized, or an empty list if visualization being removed + * Get the {@link Claim Claims} displayed by the {@link Visualization}. * - * @return Claims being visualized + *

The {@link Collection} is unmodifiable, manipulation is not allowed. + * + * @return an unmodifiable {@code Collection} of {@code Claims} */ - public Collection getClaims() + public @NotNull @Unmodifiable Collection getClaims() { return claims; } /** - * Check if subdivide claims are being shown + * Check whether {@link Claim} subdivisions (children) are being displayed. * - * @return True if subdivide claims are being shown + * @return true if subdivisions are displayed */ public boolean showSubdivides() { @@ -93,22 +102,28 @@ public class VisualizationEvent extends PlayerEvent } /** - * Check if event was called through shift-inspecting with the inspection tool. - * @return True if shift-inspecting + * Check whether the {@link Player} is visualizing nearby {@link Claim Claims} + * or just the target location. + * + * @return true if nearby {@code Claims} are displayed */ public boolean isVisualizingNearbyClaims() { return visualizingNearbyClaims; } - @Override - public HandlerList getHandlers() - { - return handlers; - } + // Listenable event requirements + private static final HandlerList HANDLERS = new HandlerList(); public static HandlerList getHandlerList() { - return handlers; + return HANDLERS; } + + @Override + public @NotNull HandlerList getHandlers() + { + return HANDLERS; + } + } diff --git a/src/main/java/me/ryanhamshire/GriefPrevention/events/package-info.java b/src/main/java/me/ryanhamshire/GriefPrevention/events/package-info.java index f28cc05..03e1a8e 100644 --- a/src/main/java/me/ryanhamshire/GriefPrevention/events/package-info.java +++ b/src/main/java/me/ryanhamshire/GriefPrevention/events/package-info.java @@ -1,9 +1,4 @@ /** - * @author Ryan - * @author Ryan - */ -/** - * @author Ryan - * + * Contains all of GriefPrevention's {@link org.bukkit.event.Event Event} implementations for use by add-ons. */ package me.ryanhamshire.GriefPrevention.events; \ No newline at end of file