EpicKnarvik97/PlotSquared
EpicKnarvik97/PlotSquared
1
0
Fork 0
mirror of https://github.com/IntellectualSites/PlotSquared.git synced 2024-11-22 21:26:45 +01:00
Code Issues Projects Releases Wiki Activity

PlotAPI doc and code cleaning

Browse Source
This commit is contained in:
MattBDev 2016-03-29 14:35:40 -04:00
parent 6ebfd426c3
commit d0622eb87d
1 changed files with 123 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

234
Bukkit/src/main/java/com/intellectualcrafters/plot/api/PlotAPI.java
View File

@ -1,4 +1,3 @@
package com.intellectualcrafters.plot.api; package com.intellectualcrafters.plot.api;
import com.intellectualcrafters.configuration.file.YamlConfiguration; import com.intellectualcrafters.configuration.file.YamlConfiguration;
@ -33,42 +32,39 @@ import java.util.UUID;
/** /**
* PlotSquared API. * PlotSquared API.
* <br> * @version 3.3.1
* @version API 3.3.1
* <br>
* Useful classes:<br>
* @see BukkitUtil
* @see PlotPlayer
* @see Plot
* @see com.intellectualcrafters.plot.object.Location
* @see PlotArea
* @see PS
*/ */
public class PlotAPI { public class PlotAPI {
/** /**
* Permission that allows for admin access, this permission node will allow the player to use any part of the * Permission that allows for admin access, this permission node will allow
* plugin, without limitations. * the player to use any part of the plugin, without limitations.
* @deprecated Use C.PERMISSION_ADMIN instead * @deprecated Use C.PERMISSION_ADMIN instead
*/ */
@Deprecated @Deprecated
public static final String ADMIN_PERMISSION = C.PERMISSION_ADMIN.s(); public static final String ADMIN_PERMISSION = C.PERMISSION_ADMIN.s();
/** /**
* @deprecated Use new PlotAPI() instead * Deprecated, does nothing.
* @param plugin not needed
* @deprecated Not needed
*/ */
@Deprecated @Deprecated
public PlotAPI(JavaPlugin plugin) { public PlotAPI(JavaPlugin plugin) {
} }
/** /**
* @see PS * Default Constructor that does nothing.
*
* @deprecated Use this class if you just want to do a few simple things.<br>
* - It will remain stable for future versions of the plugin
* - The PlotPlayer and Plot class should be considered relatively safe
* - For more advanced/intensive tasks you should consider using other classes
* *
* @deprecated Use this class if you just want to do a few simple things
* <ul>
* <li>It will remain stable for future versions
* of the plugin</li>
* <li>The PlotPlayer and Plot class should be considered
* relatively safe</li>
* <li>For more advanced/intensive tasks you should consider
* using other classes</li>
* </ul>
* *
*/ */
@Deprecated @Deprecated
@ -108,6 +104,7 @@ public class PlotAPI {
} }
/** /**
* Returns the PlotSquared configurations file.
* @return main configuration * @return main configuration
* *
* @see PS#config * @see PS#config
@ -117,6 +114,7 @@ public class PlotAPI {
} }
/** /**
* Get the PlotSquared storage file.
* @return storage configuration * @return storage configuration
* *
* @see PS#storage * @see PS#storage
@ -126,8 +124,7 @@ public class PlotAPI {
} }
/** /**
* Get the main class for this plugin <br> - Contains a lot of fields and methods - not very well organized <br> * Get the main class for this plugin. Only use this if you really need it.
* Only use this if you really need it
* *
* @return PlotSquared PlotSquared Main Class * @return PlotSquared PlotSquared Main Class
* *
@ -138,12 +135,14 @@ public class PlotAPI {
} }
/** /**
* ChunkManager class contains several useful methods<br> * ChunkManager class contains several useful methods.
* - Chunk deletion<br> * <ul>
* - Moving or copying regions<br> * <li>Chunk deletion</li>
* - plot swapping<br> * <li>Moving or copying regions</li>
* - Entity tracking<br> * <li>Plot swapping</li>
* - region regeneration<br> * <li>Entity Tracking</li>
* <li>Region Regeneration</li>
* </ul>
* *
* @return ChunkManager * @return ChunkManager
* *
@ -162,7 +161,8 @@ public class PlotAPI {
} }
/** /**
* UUIDWrapper class has basic methods for getting UUIDS (it's recommended to use the UUIDHandler class instead) * UUIDWrapper class has basic methods for getting UUIDS. It's recommended
* to use the UUIDHandler class instead.
* *
* @return UUIDWrapper * @return UUIDWrapper
* *
@ -178,7 +178,7 @@ public class PlotAPI {
* *
* @return FlagManager * @return FlagManager
* *
* @see com.intellectualcrafters.plot.flag.FlagManager * @deprecated Use {@link FlagManager} directly
*/ */
@Deprecated @Deprecated
public FlagManager getFlagManager() { public FlagManager getFlagManager() {
@ -187,11 +187,9 @@ public class PlotAPI {
/** /**
* Do not use this. Instead use MainUtil.[method] in your code. * Do not use this. Instead use MainUtil.[method] in your code.
* - Basic plot management stuff
* *
* @return MainUtil * @return MainUtil
* * @deprecated Use {@link MainUtil} directly
* @see MainUtil
*/ */
@Deprecated @Deprecated
public MainUtil getMainUtil() { public MainUtil getMainUtil() {
@ -200,11 +198,11 @@ public class PlotAPI {
/** /**
* Do not use this. Instead use C.PERMISSION_[method] in your code. * Do not use this. Instead use C.PERMISSION_[method] in your code.
* - Basic permission management stuff
* *
* @return Array of strings * @return Array of strings
* *
* @see com.intellectualcrafters.plot.util.Permissions * @see com.intellectualcrafters.plot.util.Permissions
* @deprecated Use {@link C} to list all the permissions
*/ */
@Deprecated @Deprecated
public String[] getPermissions() { public String[] getPermissions() {
@ -218,7 +216,8 @@ public class PlotAPI {
} }
/** /**
* SchematicHandler class contains methods related to pasting, reading and writing schematics * SchematicHandler class contains methods related to pasting, reading
* and writing schematics.
* *
* @return SchematicHandler * @return SchematicHandler
* *
@ -232,8 +231,7 @@ public class PlotAPI {
* Use C.[caption] instead * Use C.[caption] instead
* *
* @return C * @return C
* * @deprecated Use {@link C}
* @see com.intellectualcrafters.plot.config.C
*/ */
@Deprecated @Deprecated
public C[] getCaptions() { public C[] getCaptions() {
@ -241,7 +239,8 @@ public class PlotAPI {
} }
/** /**
* Get the plot manager for a world. - Most of these methods can be accessed through the MainUtil * Get the plot manager for a world. Most of these methods can be accessed
* through the MainUtil.
* *
* @param world Which manager to get * @param world Which manager to get
* *
@ -258,6 +257,11 @@ public class PlotAPI {
return getPlotManager(world.getName()); return getPlotManager(world.getName());
} }
/**
* Get a list of PlotAreas in the world.
* @param world The world to check for plot areas
* @return A set of PlotAreas
*/
public Set<PlotArea> getPlotAreas(World world) { public Set<PlotArea> getPlotAreas(World world) {
if (world == null) { if (world == null) {
return new HashSet<>(); return new HashSet<>();
@ -266,10 +270,10 @@ public class PlotAPI {
} }
/** /**
* Get the plot manager for a world. - Contains useful low level methods for plot merging, clearing, and * Get the plot manager for a world. Contains useful low level methods for
* tessellation * plot merging, clearing, and tessellation.
* *
* @param world * @param world The world
* *
* @return PlotManager * @return PlotManager
* *
@ -291,12 +295,13 @@ public class PlotAPI {
} }
/** /**
* Get the settings for a world (settings bundled in PlotArea class) - You will need to downcast for the specific * Get the settings for a world (settings bundled in PlotArea class). You
* settings a Generator has. e.g. DefaultPlotWorld class implements PlotArea * will need to downcast for the specific settings a Generator has. e.g.
* DefaultPlotWorld class implements PlotArea
* *
* @param world (to get settings of) * @param world The World
* *
* @return PlotArea class for that world ! will return null if not a plot world world * @return The {@link PlotArea} for the world or null if not in plotworld
* *
* @see #getPlotAreas(World) * @see #getPlotAreas(World)
* @see com.intellectualcrafters.plot.object.PlotArea * @see com.intellectualcrafters.plot.object.PlotArea
@ -310,11 +315,11 @@ public class PlotAPI {
} }
/** /**
* Get the settings for a world (settings bundled in PlotArea class) * Get the settings for a world.
* *
* @param world (to get settings of) * @param world The world
* *
* @return PlotArea class for that world ! will return null if not a plot world world * @return The {@link PlotArea} for the world or null if not in plotworld
* *
* @see PS#getPlotArea(String, String) * @see PS#getPlotArea(String, String)
* @see com.intellectualcrafters.plot.object.PlotArea * @see com.intellectualcrafters.plot.object.PlotArea
@ -340,17 +345,16 @@ public class PlotAPI {
* Send a message to a player. * Send a message to a player.
* *
* @param player Player that will receive the message * @param player Player that will receive the message
* @param c (Caption) * @param caption Caption
* *
* @see MainUtil#sendMessage(PlotPlayer, C, String...) * @see MainUtil#sendMessage(PlotPlayer, C, String...)
* com.intellectualcrafters.plot.config.C, String...)
*/ */
public void sendMessage(Player player, C c) { public void sendMessage(Player player, C caption) {
MainUtil.sendMessage(BukkitUtil.getPlayer(player), c); MainUtil.sendMessage(BukkitUtil.getPlayer(player), caption);
} }
/** /**
* Send a message to a player. - Supports color codes * Send a message to a player. Supports color codes.
* *
* @param player Player that will receive the message * @param player Player that will receive the message
* @param string The message * @param string The message
@ -362,30 +366,30 @@ public class PlotAPI {
} }
/** /**
* Send a message to the console. - Supports color codes * Send a message to the console. Supports color codes.
* *
* @param msg Message that should be sent to the console * @param message Message that should be sent to the console
* *
* @see MainUtil#sendConsoleMessage(C, String...) * @see MainUtil#sendConsoleMessage(C, String...)
*/ */
public void sendConsoleMessage(String msg) { public void sendConsoleMessage(String message) {
PS.log(msg); PS.log(message);
} }
/** /**
* Send a message to the console * Send a message to the console.
* *
* @param c (Caption) * @param caption The caption
* *
* @see #sendConsoleMessage(String) * @see #sendConsoleMessage(String)
* @see com.intellectualcrafters.plot.config.C * @see com.intellectualcrafters.plot.config.C
*/ */
public void sendConsoleMessage(C c) { public void sendConsoleMessage(C caption) {
sendConsoleMessage(c.s()); sendConsoleMessage(caption.s());
} }
/** /**
* Register a flag for use in plots * Register a flag for use in plots.
* *
* @param flag Flag that should be registered * @param flag Flag that should be registered
* *
@ -397,7 +401,7 @@ public class PlotAPI {
} }
/** /**
* get all the currently registered flags * get all the currently registered flags.
* *
* @return array of Flag[] * @return array of Flag[]
* *
@ -412,8 +416,8 @@ public class PlotAPI {
* Get a plot based on the ID. * Get a plot based on the ID.
* *
* @param world World in which the plot is located * @param world World in which the plot is located
* @param x Plot Location X Co-ord * @param x The PlotID x coordinate
* @param z Plot Location Z Co-ord * @param z The PlotID y coordinate
* *
* @return plot, null if ID is wrong * @return plot, null if ID is wrong
* *
@ -434,17 +438,17 @@ public class PlotAPI {
/** /**
* Get a plot based on the location. * Get a plot based on the location.
* *
* @param l The location that you want to to retrieve the plot from * @param location The location to retrieve the plot from
* *
* @return plot if found, otherwise it creates a temporary plot- * @return plot if found, otherwise it creates a temporary plot
* *
* @see Plot * @see Plot
*/ */
public Plot getPlot(Location l) { public Plot getPlot(Location location) {
if (l == null) { if (location == null) {
return null; return null;
} }
return BukkitUtil.getLocation(l).getPlot(); return BukkitUtil.getLocation(location).getPlot();
} }
/** /**
@ -465,7 +469,7 @@ public class PlotAPI {
* Check whether or not a player has a plot. * Check whether or not a player has a plot.
* *
* @param player Player that you want to check for * @param player Player that you want to check for
* * @param world The world to check
* @return true if player has a plot, false if not. * @return true if player has a plot, false if not.
* *
* @see #getPlots(World, Player, boolean) * @see #getPlots(World, Player, boolean)
@ -478,9 +482,10 @@ public class PlotAPI {
/** /**
* Get all plots for the player. * Get all plots for the player.
* *
* @param world * @param world The world to retrieve plots from
* @param player The player to search for * @param player The player to search for
* @param justOwner should we just search for owner? Or with rights? * @param justOwner should we just search for owner? Or with rights?
* @return An array of plots for the player
*/ */
@Deprecated @Deprecated
public Plot[] getPlots(World world, Player player, boolean justOwner) { public Plot[] getPlots(World world, Player player, boolean justOwner) {
@ -530,9 +535,9 @@ public class PlotAPI {
} }
/** /**
* Get if plot world * Get if plotworld.
* *
* @param world (to check if plot world) * @param world The world to check
* *
* @return boolean (if plot world or not) * @return boolean (if plot world or not)
* *
@ -544,9 +549,9 @@ public class PlotAPI {
} }
/** /**
* Get plot locations * Get plot locations.
* *
* @param p Plot that you want to get the locations for * @param plot Plot to get the locations for
* *
* @return [0] = bottomLc, [1] = topLoc, [2] = home * @return [0] = bottomLc, [1] = topLoc, [2] = home
* *
@ -555,27 +560,30 @@ public class PlotAPI {
* @see Plot * @see Plot
*/ */
@Deprecated @Deprecated
public Location[] getLocations(Plot p) { public Location[] getLocations(Plot plot) {
return new Location[]{BukkitUtil.getLocation(p.getBottom()), BukkitUtil.getLocation(p.getTop()), BukkitUtil.getLocation(p.getHome())}; Location bukkitBottom = BukkitUtil.getLocation(plot.getCorners()[0]);
Location bukkitTop = BukkitUtil.getLocation(plot.getCorners()[1]);
Location bukkitHome = BukkitUtil.getLocation(plot.getHome());
return new Location[]{bukkitBottom, bukkitTop, bukkitHome};
} }
/** /**
* Get home location * Get home location.
* *
* @param p Plot that you want to get the location for * @param plot Plot that you want to get the location for
* *
* @return plot bottom location * @return plot bottom location
* *
* @see Plot * @see Plot
*/ */
public Location getHomeLocation(Plot p) { public Location getHomeLocation(Plot plot) {
return BukkitUtil.getLocation(p.getHome()); return BukkitUtil.getLocation(plot.getHome());
} }
/** /**
* Get Bottom Location (min, min, min) * Get Bottom Location (min, min, min).
* *
* @param p Plot that you want to get the location for * @param plot Plot that you want to get the location for
* *
* @return plot bottom location * @return plot bottom location
* *
@ -584,14 +592,14 @@ public class PlotAPI {
* @see Plot * @see Plot
*/ */
@Deprecated @Deprecated
public Location getBottomLocation(Plot p) { public Location getBottomLocation(Plot plot) {
return BukkitUtil.getLocation(p.getBottom()); return BukkitUtil.getLocation(plot.getBottom());
} }
/** /**
* Get Top Location (max, max, max) * Get Top Location (max, max, max).
* *
* @param p Plot that you want to get the location for * @param plot Plot that you want to get the location for
* *
* @return plot top location * @return plot top location
* *
@ -600,12 +608,12 @@ public class PlotAPI {
* @see Plot * @see Plot
*/ */
@Deprecated @Deprecated
public Location getTopLocation(Plot p) { public Location getTopLocation(Plot plot) {
return BukkitUtil.getLocation(p.getTop()); return BukkitUtil.getLocation(plot.getTop());
} }
/** /**
* Check whether or not a player is in a plot * Check whether or not a player is in a plot.
* *
* @param player who we're checking for * @param player who we're checking for
* *
@ -617,7 +625,7 @@ public class PlotAPI {
} }
/** /**
* Register a subcommand * Register a subcommand.
* @deprecated Command registration is done on object creation * @deprecated Command registration is done on object creation
* @param c SubCommand, that we want to register * @param c SubCommand, that we want to register
* @see com.intellectualcrafters.plot.commands.SubCommand * @see com.intellectualcrafters.plot.commands.SubCommand
@ -628,7 +636,7 @@ public class PlotAPI {
} }
/** /**
* Get the PlotSquared class * Get the PlotSquared class.
* *
* @return PlotSquared Class * @return PlotSquared Class
* *
@ -639,7 +647,7 @@ public class PlotAPI {
} }
/** /**
* Get the player plot count * Get the player plot count.
* *
* @param world Specify the world we want to select the plots from * @param world Specify the world we want to select the plots from
* @param player Player, for whom we're getting the plot count * @param player Player, for whom we're getting the plot count
@ -655,7 +663,7 @@ public class PlotAPI {
} }
/** /**
* Get a collection containing the players plots * Get a collection containing the players plots.
* *
* @param world Specify the world we want to select the plots from * @param world Specify the world we want to select the plots from
* @param player Player, for whom we're getting the plots * @param player Player, for whom we're getting the plots
@ -674,9 +682,9 @@ public class PlotAPI {
} }
/** /**
* Get the numbers of plots, which the player is able to build in * Get the numbers of plots, which the player is able to build in.
* *
* @param player Player, for whom we're getting the plots (trusted, member and owner) * @param player Player, for whom we're getting the plots
* *
* @return the number of allowed plots * @return the number of allowed plots
* *
@ -687,50 +695,54 @@ public class PlotAPI {
} }
/** /**
* Get the PlotPlayer for a player<br> * Get the PlotPlayer for a player. The PlotPlayer is usually cached and
* - The PlotPlayer is usually cached and will provide useful functions relating to players * will provide useful functions relating to players.
* *
* @see PlotPlayer#wrap(Object) * @see PlotPlayer#wrap(Object)
* *
* @param player * @param player The player to wrap
* @return * @return A PlotPlayer
*/ */
public PlotPlayer wrapPlayer(Player player) { public PlotPlayer wrapPlayer(Player player) {
return PlotPlayer.wrap(player); return PlotPlayer.wrap(player);
} }
/** /**
* Get the PlotPlayer for a UUID (Please note that PlotSquared can be configured to provide different UUIDs than bukkit) * Get the PlotPlayer for a UUID.
*
* <p><i>Please note that PlotSquared can be configured to provide
* different UUIDs than bukkit</i></p>
* *
* @see PlotPlayer#wrap(Object) * @see PlotPlayer#wrap(Object)
* *
* @param uuid * @param uuid The uuid of the player to wrap
* @return * @return A PlotPlayer
*/ */
public PlotPlayer wrapPlayer(UUID uuid) { public PlotPlayer wrapPlayer(UUID uuid) {
return PlotPlayer.wrap(uuid); return PlotPlayer.wrap(uuid);
} }
/** /**
* Get the PlotPlayer for a username * Get the PlotPlayer for a username.
* *
* @see PlotPlayer#wrap(Object) * @see PlotPlayer#wrap(Object)
* *
* @param player * @param player The player to wrap
* @return * @return The PlotPlayer
*/ */
public PlotPlayer wrapPlayer(String player) { public PlotPlayer wrapPlayer(String player) {
return PlotPlayer.wrap(player); return PlotPlayer.wrap(player);
} }
/** /**
* Get the PlotPlayer for an offline player<br> * Get the PlotPlayer for an offline player.
* Note that this will work if the player is offline, however not all functionality will work * <p>Note that this will work if the player is offline, however not all
* functionality will work</p>
* *
* @see PlotPlayer#wrap(Object) * @see PlotPlayer#wrap(Object)
* *
* @param player * @param player The player to wrap
* @return * @return The PlotPlayer
*/ */
public PlotPlayer wrapPlayer(OfflinePlayer player) { public PlotPlayer wrapPlayer(OfflinePlayer player) {
return PlotPlayer.wrap(player); return PlotPlayer.wrap(player);