From c912624df1a3c1f6ba0fb723f7bea0138aaf1fda Mon Sep 17 00:00:00 2001 From: EpicKnarvik97 Date: Fri, 19 Feb 2021 12:06:23 +0100 Subject: [PATCH] Adds comments to all custom events Adds full comments to every class implementing StarGateEvent Adds another abstract event StargatePlayerEvent which reduces code duplication --- .../stargate/event/StargateAccessEvent.java | 39 +++---- .../stargate/event/StargateActivateEvent.java | 105 ++++++++++++------ .../stargate/event/StargateCloseEvent.java | 44 ++++++-- .../stargate/event/StargateCreateEvent.java | 85 +++++++++++--- .../event/StargateDeactivateEvent.java | 28 ++++- .../stargate/event/StargateDestroyEvent.java | 43 +++---- .../stargate/event/StargateEvent.java | 16 ++- .../stargate/event/StargateOpenEvent.java | 71 +++++++----- .../stargate/event/StargatePlayerEvent.java | 33 ++++++ .../stargate/event/StargatePortalEvent.java | 53 +++++---- 10 files changed, 344 insertions(+), 173 deletions(-) create mode 100644 src/main/java/net/knarcraft/stargate/event/StargatePlayerEvent.java diff --git a/src/main/java/net/knarcraft/stargate/event/StargateAccessEvent.java b/src/main/java/net/knarcraft/stargate/event/StargateAccessEvent.java index 919ff6d..71f2fe8 100644 --- a/src/main/java/net/knarcraft/stargate/event/StargateAccessEvent.java +++ b/src/main/java/net/knarcraft/stargate/event/StargateAccessEvent.java @@ -3,24 +3,18 @@ package net.knarcraft.stargate.event; import net.knarcraft.stargate.Portal; import org.bukkit.entity.Player; import org.bukkit.event.HandlerList; +import org.jetbrains.annotations.NotNull; +/** + * This event should be called whenever a player attempts to access a stargate + */ @SuppressWarnings("unused") -public class StargateAccessEvent extends StargateEvent { +public class StargateAccessEvent extends StargatePlayerEvent { - private final Player player; private boolean deny; private static final HandlerList handlers = new HandlerList(); - - /** - * Gets a handler-list containing all event handlers - * @return

A handler-list with all event handlers

- */ - public static HandlerList getHandlerList() { - return handlers; - } - /** * Instantiates a new stargate access event * @param player

The player involved in the vent

@@ -28,9 +22,8 @@ public class StargateAccessEvent extends StargateEvent { * @param deny

Whether the event should be denied

*/ public StargateAccessEvent(Player player, Portal portal, boolean deny) { - super("StargateAccessEvent", portal); - - this.player = player; + super("StargateAccessEvent", portal, player); + this.deny = deny; } @@ -51,15 +44,17 @@ public class StargateAccessEvent extends StargateEvent { } /** - * Gets the player involved in this stargate access event - * @return

The player involved in this event

+ * Gets a handler-list containing all event handlers + * @return

A handler-list with all event handlers

*/ - public Player getPlayer() { - return this.player; - } - - @Override - public @org.jetbrains.annotations.NotNull HandlerList getHandlers() { + public static HandlerList getHandlerList() { return handlers; } + + @Override + @NotNull + public HandlerList getHandlers() { + return handlers; + } + } diff --git a/src/main/java/net/knarcraft/stargate/event/StargateActivateEvent.java b/src/main/java/net/knarcraft/stargate/event/StargateActivateEvent.java index 085c622..3f522a7 100644 --- a/src/main/java/net/knarcraft/stargate/event/StargateActivateEvent.java +++ b/src/main/java/net/knarcraft/stargate/event/StargateActivateEvent.java @@ -5,51 +5,84 @@ import org.bukkit.entity.Player; import org.bukkit.event.HandlerList; import org.jetbrains.annotations.NotNull; -import java.util.ArrayList; +import java.util.List; -public class StargateActivateEvent extends StargateEvent { +/** + * This event should be called whenever a player activates a stargate + *

Activation of a stargate happens when a player right-clicks the sign of a stargate.

+ */ +@SuppressWarnings("unused") +public class StargateActivateEvent extends StargatePlayerEvent { - private final Player player; - private ArrayList destinations; + private List destinations; private String destination; private static final HandlerList handlers = new HandlerList(); + /** + * Instantiates a new stargate activate event + * + * @param portal

The activated portal

+ * @param player

The player activating the portal

+ * @param destinations

The destinations available to the player using the portal

+ * @param destination

The chosen destination to activate

+ */ + public StargateActivateEvent(Portal portal, Player player, List destinations, String destination) { + super("StargatActivateEvent", portal, player); + + this.destinations = destinations; + this.destination = destination; + } + + /** + * Gets the destinations available for the portal + * + * @return

The destinations available for the portal

+ */ + public List getDestinations() { + return destinations; + } + + /** + * Sets the destinations available to the player using the portal + * + * @param destinations

The new list of available destinations

+ */ + public void setDestinations(List destinations) { + this.destinations = destinations; + } + + /** + * Gets the chosen destination to activate + * + * @return

The chosen destination to activate

+ */ + public String getDestination() { + return destination; + } + + /** + * Sets (changes) the chosen destination to activate + * + * @param destination

The new destination to activate

+ */ + public void setDestination(String destination) { + this.destination = destination; + } + + /** + * Gets a handler-list containing all event handlers + * + * @return

A handler-list with all event handlers

+ */ + public static HandlerList getHandlerList() { + return handlers; + } + + @Override @NotNull public HandlerList getHandlers() { return handlers; } - public static HandlerList getHandlerList() { - return handlers; - } - - public StargateActivateEvent(Portal portal, Player player, ArrayList destinations, String destination) { - super("StargatActivateEvent", portal); - - this.player = player; - this.destinations = destinations; - this.destination = destination; - } - - public Player getPlayer() { - return player; - } - - public ArrayList getDestinations() { - return destinations; - } - - public void setDestinations(ArrayList destinations) { - this.destinations = destinations; - } - - public String getDestination() { - return destination; - } - - public void setDestination(String destination) { - this.destination = destination; - } - } diff --git a/src/main/java/net/knarcraft/stargate/event/StargateCloseEvent.java b/src/main/java/net/knarcraft/stargate/event/StargateCloseEvent.java index 070a4b3..a5e5ace 100644 --- a/src/main/java/net/knarcraft/stargate/event/StargateCloseEvent.java +++ b/src/main/java/net/knarcraft/stargate/event/StargateCloseEvent.java @@ -4,33 +4,59 @@ import net.knarcraft.stargate.Portal; import org.bukkit.event.HandlerList; import org.jetbrains.annotations.NotNull; +/** + * This event should be called whenever a stargate is closed + */ +@SuppressWarnings("unused") public class StargateCloseEvent extends StargateEvent { private boolean force; private static final HandlerList handlers = new HandlerList(); - @NotNull - public HandlerList getHandlers() { - return handlers; - } - - public static HandlerList getHandlerList() { - return handlers; - } - + /** + * Instantiates a new stargate closing event + * + * @param portal

The portal to close

+ * @param force

Whether to force the gate to close, even if set as always-on

+ */ public StargateCloseEvent(Portal portal, boolean force) { super("StargateCloseEvent", portal); this.force = force; } + /** + * Gets whether to force the stargate to close + * + * @return

Whether to force the stargate to close

+ */ public boolean getForce() { return force; } + /** + * Sets whether the stargate should be forced to close + * + * @param force

Whether the stargate should be forced to close

+ */ public void setForce(boolean force) { this.force = force; } + /** + * Gets a handler-list containing all event handlers + * + * @return

A handler-list with all event handlers

+ */ + public static HandlerList getHandlerList() { + return handlers; + } + + @NotNull + @Override + public HandlerList getHandlers() { + return handlers; + } + } diff --git a/src/main/java/net/knarcraft/stargate/event/StargateCreateEvent.java b/src/main/java/net/knarcraft/stargate/event/StargateCreateEvent.java index bba2060..bd23679 100644 --- a/src/main/java/net/knarcraft/stargate/event/StargateCreateEvent.java +++ b/src/main/java/net/knarcraft/stargate/event/StargateCreateEvent.java @@ -5,9 +5,12 @@ import org.bukkit.entity.Player; import org.bukkit.event.HandlerList; import org.jetbrains.annotations.NotNull; -public class StargateCreateEvent extends StargateEvent { +/** + * This event should be called whenever a stargate is created + */ +@SuppressWarnings("unused") +public class StargateCreateEvent extends StargatePlayerEvent { - private final Player player; private boolean deny; private String denyReason; private final String[] lines; @@ -15,54 +18,102 @@ public class StargateCreateEvent extends StargateEvent { private static final HandlerList handlers = new HandlerList(); - @NotNull - public HandlerList getHandlers() { - return handlers; - } - - public static HandlerList getHandlerList() { - return handlers; - } - + /** + * Instantiates a new stargate creation event + * + * @param player

Thg player creating the stargate

+ * @param portal

The created portal

+ * @param lines

The lines of the sign creating the star gate

+ * @param deny

Whether to deny the creation of the new gate

+ * @param denyReason

The reason stargate creation was denied

+ * @param cost

The cost of creating the new star gate

+ */ public StargateCreateEvent(Player player, Portal portal, String[] lines, boolean deny, String denyReason, int cost) { - super("StargateCreateEvent", portal); - this.player = player; + super("StargateCreateEvent", portal, player); this.lines = lines; this.deny = deny; this.denyReason = denyReason; this.cost = cost; } - public Player getPlayer() { - return player; - } - + /** + * Gets a given line from the sign creating the star gate + * + * @param index

The line number to get

+ * @return

The text on the given line

+ * @throws IndexOutOfBoundsException

If given a line index less than zero or above three

+ */ public String getLine(int index) throws IndexOutOfBoundsException { return lines[index]; } + /** + * Gets whether the stargate creation should be denied + * + * @return

Whether the stargate creation should be denied

+ */ public boolean getDeny() { return deny; } + /** + * Sets whether the stargate creation should be denied + * + * @param deny

Whether the stargate creation should be denied

+ */ public void setDeny(boolean deny) { this.deny = deny; } + /** + * Gets the reason the stargate creation was denied + * + * @return

The reason the stargate creation was denied

+ */ public String getDenyReason() { return denyReason; } + /** + * Sets the reason the stargate creation was denied + * + * @param denyReason

The new reason why the stargate creation was denied

+ */ public void setDenyReason(String denyReason) { this.denyReason = denyReason; } + /** + * Gets the cost of creating the stargate + * + * @return

The cost of creating the stargate

+ */ public int getCost() { return cost; } + /** + * Sets the cost of creating the stargate + * + * @param cost

The new cost of creating the stargate

+ */ public void setCost(int cost) { this.cost = cost; } + /** + * Gets a handler-list containing all event handlers + * + * @return

A handler-list with all event handlers

+ */ + public static HandlerList getHandlerList() { + return handlers; + } + + @NotNull + @Override + public HandlerList getHandlers() { + return handlers; + } + } diff --git a/src/main/java/net/knarcraft/stargate/event/StargateDeactivateEvent.java b/src/main/java/net/knarcraft/stargate/event/StargateDeactivateEvent.java index 922e68f..4b3e68e 100644 --- a/src/main/java/net/knarcraft/stargate/event/StargateDeactivateEvent.java +++ b/src/main/java/net/knarcraft/stargate/event/StargateDeactivateEvent.java @@ -4,21 +4,37 @@ import net.knarcraft.stargate.Portal; import org.bukkit.event.HandlerList; import org.jetbrains.annotations.NotNull; +/** + * This event should be called whenever a stargate is deactivated + *

A deactivation is usually caused by no activity for a set amount of time.

+ */ +@SuppressWarnings("unused") public class StargateDeactivateEvent extends StargateEvent { private static final HandlerList handlers = new HandlerList(); - @NotNull - public HandlerList getHandlers() { - return handlers; + /** + * Instantiates a new stargate deactivation event + * + * @param portal

The portal which was deactivated

+ */ + public StargateDeactivateEvent(Portal portal) { + super("StargatDeactivateEvent", portal); } + /** + * Gets a handler-list containing all event handlers + * + * @return

A handler-list with all event handlers

+ */ public static HandlerList getHandlerList() { return handlers; } - public StargateDeactivateEvent(Portal portal) { - super("StargatDeactivateEvent", portal); - + @NotNull + @Override + public HandlerList getHandlers() { + return handlers; } + } diff --git a/src/main/java/net/knarcraft/stargate/event/StargateDestroyEvent.java b/src/main/java/net/knarcraft/stargate/event/StargateDestroyEvent.java index 9d4f965..ffbf716 100644 --- a/src/main/java/net/knarcraft/stargate/event/StargateDestroyEvent.java +++ b/src/main/java/net/knarcraft/stargate/event/StargateDestroyEvent.java @@ -8,28 +8,15 @@ import org.jetbrains.annotations.NotNull; /** * This event represents an event where a star gate is destroyed or attempted to be destroyed */ -public class StargateDestroyEvent extends StargateEvent { +@SuppressWarnings("unused") +public class StargateDestroyEvent extends StargatePlayerEvent { - private final Player player; private boolean deny; private String denyReason; private int cost; private static final HandlerList handlers = new HandlerList(); - @NotNull - public HandlerList getHandlers() { - return handlers; - } - - /** - * Gets a handler-list containing all event handlers - * @return

A handler-list with all event handlers

- */ - public static HandlerList getHandlerList() { - return handlers; - } - /** * Instantiates a new Stargate Destroy Event * @param portal

The portal destroyed

@@ -39,21 +26,12 @@ public class StargateDestroyEvent extends StargateEvent { * @param cost

The cost of destroying the portal

*/ public StargateDestroyEvent(Portal portal, Player player, boolean deny, String denyMsg, int cost) { - super("StargateDestroyEvent", portal); - this.player = player; + super("StargateDestroyEvent", portal, player); this.deny = deny; this.denyReason = denyMsg; this.cost = cost; } - /** - * Gets the player causing the destroy event - * @return

The player causing the destroy event

- */ - public Player getPlayer() { - return player; - } - /** * Gets whether this event should be denied * @return

Whether this event should be denied

@@ -102,4 +80,19 @@ public class StargateDestroyEvent extends StargateEvent { this.cost = cost; } + /** + * Gets a handler-list containing all event handlers + * + * @return

A handler-list with all event handlers

+ */ + public static HandlerList getHandlerList() { + return handlers; + } + + @NotNull + @Override + public HandlerList getHandlers() { + return handlers; + } + } diff --git a/src/main/java/net/knarcraft/stargate/event/StargateEvent.java b/src/main/java/net/knarcraft/stargate/event/StargateEvent.java index 1dbc915..f87ed1f 100644 --- a/src/main/java/net/knarcraft/stargate/event/StargateEvent.java +++ b/src/main/java/net/knarcraft/stargate/event/StargateEvent.java @@ -10,15 +10,23 @@ import org.bukkit.event.Event; @SuppressWarnings("unused") public abstract class StargateEvent extends Event implements Cancellable { - protected final Portal portal; - protected boolean cancelled; + private final Portal portal; + private boolean cancelled; - public StargateEvent(String event, Portal portal) { + /** + * Instantiates a new stargate event + * @param event

UNUSED

+ * @param portal

The portal involved in this stargate event

+ */ + StargateEvent(String event, Portal portal) { this.portal = portal; this.cancelled = false; } - + /** + * Gets the portal involved in this stargate event + * @return

The portal involved in this stargate event

+ */ public Portal getPortal() { return portal; } diff --git a/src/main/java/net/knarcraft/stargate/event/StargateOpenEvent.java b/src/main/java/net/knarcraft/stargate/event/StargateOpenEvent.java index 75a3bf4..360bb98 100644 --- a/src/main/java/net/knarcraft/stargate/event/StargateOpenEvent.java +++ b/src/main/java/net/knarcraft/stargate/event/StargateOpenEvent.java @@ -5,44 +5,55 @@ import org.bukkit.entity.Player; import org.bukkit.event.HandlerList; import org.jetbrains.annotations.NotNull; -public class StargateOpenEvent extends StargateEvent { +/** + * This event should be called whenever a player opens a stargate + */ +public class StargateOpenEvent extends StargatePlayerEvent { - private final Player player; private boolean force; private static final HandlerList handlers = new HandlerList(); + /** + * Instantiates a new stargate open event + * @param player

The player opening the stargate

+ * @param portal

The portal opened

+ * @param force

Whether to force the portal open

+ */ + public StargateOpenEvent(Player player, Portal portal, boolean force) { + super("StargateOpenEvent", portal, player); + + this.force = force; + } + + /** + * Gets whether the portal should be forced open + * @return

Whether the portal should be forced open

+ */ + public boolean getForce() { + return force; + } + + /** + * Sets whether the portal should be forced open + * @param force

Whether the portal should be forced open

+ */ + public void setForce(boolean force) { + this.force = force; + } + + /** + * Gets a handler-list containing all event handlers + * @return

A handler-list with all event handlers

+ */ + public static HandlerList getHandlerList() { + return handlers; + } + + @Override @NotNull public HandlerList getHandlers() { return handlers; } - public static HandlerList getHandlerList() { - return handlers; - } - - public StargateOpenEvent(Player player, Portal portal, boolean force) { - super("StargateOpenEvent", portal); - - this.player = player; - this.force = force; - } - - /** - * Return the player than opened the gate. - * - * @return player than opened the gate - */ - public Player getPlayer() { - return player; - } - - public boolean getForce() { - return force; - } - - public void setForce(boolean force) { - this.force = force; - } - } diff --git a/src/main/java/net/knarcraft/stargate/event/StargatePlayerEvent.java b/src/main/java/net/knarcraft/stargate/event/StargatePlayerEvent.java new file mode 100644 index 0000000..2dcf77b --- /dev/null +++ b/src/main/java/net/knarcraft/stargate/event/StargatePlayerEvent.java @@ -0,0 +1,33 @@ +package net.knarcraft.stargate.event; + +import net.knarcraft.stargate.Portal; +import org.bukkit.entity.Player; + +/** + * An abstract event describing any stargate event where a player is involved + */ +public abstract class StargatePlayerEvent extends StargateEvent { + + private final Player player; + + /** + * Instantiates a new stargate player event + * + * @param event

UNUSED

+ * @param portal

The portal involved in this stargate event

+ */ + StargatePlayerEvent(String event, Portal portal, Player player) { + super(event, portal); + this.player = player; + } + + /** + * Gets the player creating the star gate + * + * @return

The player creating the star gate

+ */ + public Player getPlayer() { + return player; + } + +} diff --git a/src/main/java/net/knarcraft/stargate/event/StargatePortalEvent.java b/src/main/java/net/knarcraft/stargate/event/StargatePortalEvent.java index 3b46461..6e7191a 100644 --- a/src/main/java/net/knarcraft/stargate/event/StargatePortalEvent.java +++ b/src/main/java/net/knarcraft/stargate/event/StargatePortalEvent.java @@ -6,38 +6,29 @@ import org.bukkit.entity.Player; import org.bukkit.event.HandlerList; import org.jetbrains.annotations.NotNull; -public class StargatePortalEvent extends StargateEvent { +/** + * This event should be called whenever a player teleports through a stargate + */ +@SuppressWarnings("unused") +public class StargatePortalEvent extends StargatePlayerEvent { - private final Player player; private final Portal destination; private Location exit; private static final HandlerList handlers = new HandlerList(); - @NotNull - public HandlerList getHandlers() { - return handlers; - } - - public static HandlerList getHandlerList() { - return handlers; - } - - public StargatePortalEvent(Player player, Portal portal, Portal dest, Location exit) { - super("StargatePortalEvent", portal); - - this.player = player; - this.destination = dest; - this.exit = exit; - } - /** - * Return the player that went through the gate. - * - * @return player that went through the gate + * Instantiates a new stargate portal event + * @param player

The player teleporting

+ * @param portal

The portal the player entered from

+ * @param destination

The destination the player should exit from

+ * @param exit

The exit location of the destination portal the user will be teleported to

*/ - public Player getPlayer() { - return player; + public StargatePortalEvent(Player player, Portal portal, Portal destination, Location exit) { + super("StargatePortalEvent", portal, player); + + this.destination = destination; + this.exit = exit; } /** @@ -65,4 +56,18 @@ public class StargatePortalEvent extends StargateEvent { this.exit = loc; } + /** + * Gets a handler-list containing all event handlers + * @return

A handler-list with all event handlers

+ */ + public static HandlerList getHandlerList() { + return handlers; + } + + @Override + @NotNull + public HandlerList getHandlers() { + return handlers; + } + }