minster586/OpenInv
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 36 Wiki Activity

Slightly improve API, bump version to 3.2.0 for release

Browse Source 
Methods are now properly annotated @Nullable when they may return null. More descriptive exceptions are thrown when issues occur instead of just returning null.
This commit is contained in:
Jikoo
2017-06-08 18:36:01 -04:00
parent 01f147b13c
commit 96c59f163d
35 changed files with 530 additions and 508 deletions
Download Patch File Download Diff File Expand all files Collapse all files

233
api/src/main/java/com/lishid/openinv/IOpenInv.java
View File

@@ -1,5 +1,7 @@
package com.lishid.openinv;
import javax.annotation.Nullable;
import com.lishid.openinv.internal.IAnySilentContainer;
import com.lishid.openinv.internal.IInventoryAccess;
import com.lishid.openinv.internal.ISpecialEnderChest;
@@ -11,145 +13,172 @@ import org.bukkit.plugin.Plugin;
/**
* Interface defining behavior for the OpenInv plugin.
*
*
* @author Jikoo
*/
public interface IOpenInv {
/**
* Checks if the server version is supported by OpenInv.
*
* @return true if the server version is supported
*/
public boolean isSupportedVersion();
/**
* Gets the active IInventoryAccess implementation. May return null if the server version is
* unsupported.
*
* @return the IInventoryAccess
*/
public IInventoryAccess getInventoryAccess();
/**
* Gets the active ISilentContainer implementation. May return null if the server version is
* unsupported.
*
* @return the ISilentContainer
*/
public IAnySilentContainer getAnySilentContainer();
/**
* Gets an ISpecialPlayerInventory for the given Player.
*
* @param player the Player
* @param online true if the Player is currently online
* @return the ISpecialPlayerInventory
*/
public ISpecialPlayerInventory getInventory(Player player, boolean online);
/**
* Gets an ISpecialEnderChest for the given Player.
*
* @param player the Player
* @param online true if the Player is currently online
* @return the ISpecialEnderChest
*/
public ISpecialEnderChest getEnderChest(Player player, boolean online);
/**
* Forcibly unload a cached Player's data.
*
* @param player the OfflinePlayer to unload
*/
public void unload(OfflinePlayer player);
/**
* Check the configuration value for whether or not OpenInv saves player data when unloading
* players. This is exclusively for users who do not allow editing of inventories, only viewing,
* and wish to prevent any possibility of bugs such as lishid#40. If true, OpenInv will not ever
* save any edits made to players.
*
*
* @return false unless configured otherwise
*/
public boolean disableSaving();
/**
* Check the configuration value for whether or not OpenInv displays a notification to the user
* when a container is activated with SilentChest.
*
* @return true unless configured otherwise
* Gets the active ISilentContainer implementation. May return null if the server version is
* unsupported.
*
* @return the ISilentContainer
* @throws IllegalStateException if the server version is unsupported
*/
public boolean notifySilentChest();
public IAnySilentContainer getAnySilentContainer();
/**
* Check the configuration value for whether or not OpenInv displays a notification to the user
* when a container is activated with AnyChest.
*
* @return true unless configured otherwise
* Gets an ISpecialEnderChest for the given Player. Returns null if the ISpecialEnderChest could
* not be instantiated.
*
* @deprecated Use {@link IOpenInv#getSpecialEnderChest(Player, boolean)}
* @param player the Player
* @param online true if the Player is currently online
* @return the ISpecialEnderChest
* @throws IllegalStateException if the server version is unsupported
*/
public boolean notifyAnyChest();
@Deprecated
@Nullable
public ISpecialEnderChest getEnderChest(Player player, boolean online);
/**
* Gets a player's SilentChest setting.
*
* @param player the OfflinePlayer
* @return true if SilentChest is enabled
* Gets an ISpecialPlayerInventory for the given Player. Returns null if the
* ISpecialPlayerInventory could not be instantiated.
*
* @deprecated Use {@link IOpenInv#getSpecialInventory(Player, boolean)}
* @param player the Player
* @param online true if the Player is currently online
* @return the ISpecialPlayerInventory
* @throws IllegalStateException if the server version is unsupported
*/
public boolean getPlayerSilentChestStatus(OfflinePlayer player);
@Deprecated
@Nullable
public ISpecialPlayerInventory getInventory(Player player, boolean online);
/**
* Sets a player's SilentChest setting.
*
* @param player the OfflinePlayer
* @param status the status
* Gets the active IInventoryAccess implementation. May return null if the server version is
* unsupported.
*
* @return the IInventoryAccess
* @throws IllegalStateException if the server version is unsupported
*/
public void setPlayerSilentChestStatus(OfflinePlayer player, boolean status);
public IInventoryAccess getInventoryAccess();
/**
* Gets the provided player's AnyChest setting.
*
*
* @param player the OfflinePlayer
* @return true if AnyChest is enabled
* @throws IllegalStateException if the server version is unsupported
*/
public boolean getPlayerAnyChestStatus(OfflinePlayer player);
/**
* Sets a player's AnyChest setting.
*
* @param player the OfflinePlayer
* @param status the status
*/
public void setPlayerAnyChestStatus(OfflinePlayer player, boolean status);
/**
* Gets a unique identifier by which the OfflinePlayer can be referenced. Using the value
* returned to look up a Player will generally be much faster for later implementations.
*
*
* @param offline the OfflinePlayer
* @return the identifier
* @throws IllegalStateException if the server version is unsupported
*/
public String getPlayerID(OfflinePlayer offline);
/**
* Gets a player's SilentChest setting.
*
* @param player the OfflinePlayer
* @return true if SilentChest is enabled
* @throws IllegalStateException if the server version is unsupported
*/
public boolean getPlayerSilentChestStatus(OfflinePlayer player);
/**
* Gets an ISpecialEnderChest for the given Player.
*
* @param player the Player
* @param online true if the Player is currently online
* @return the ISpecialEnderChest
* @throws IllegalStateException if the server version is unsupported
* @throws InstantiationException if the ISpecialEnderChest could not be instantiated
*/
public ISpecialEnderChest getSpecialEnderChest(Player player, boolean online) throws InstantiationException;
/**
* Gets an ISpecialPlayerInventory for the given Player.
*
* @param player the Player
* @param online true if the Player is currently online
* @return the ISpecialPlayerInventory
* @throws IllegalStateException if the server version is unsupported
* @throws InstantiationException if the ISpecialPlayerInventory could not be instantiated
*/
public ISpecialPlayerInventory getSpecialInventory(Player player, boolean online) throws InstantiationException;
/**
* Checks if the server version is supported by OpenInv.
*
* @return true if the server version is supported
*/
public boolean isSupportedVersion();
/**
* Load a Player from an OfflinePlayer. May return null under some circumstances.
*
* @param offline the OfflinePlayer to load a Player for
* @return the Player, or null
* @throws IllegalStateException if the server version is unsupported
*/
@Nullable
public Player loadPlayer(final OfflinePlayer offline);
/**
* Get an OfflinePlayer by name.
* <p>
* Note: This method is potentially very heavily blocking. It should not ever be called on the
* main thread, and if it is, a stack trace will be displayed alerting server owners to the
* call.
*
*
* @param name the name of the Player
* @return the OfflinePlayer with the closest matching name or null if no players have ever logged in
*/
@Nullable
public OfflinePlayer matchPlayer(String name);
/**
* Load a Player from an OfflinePlayer. May return null under some circumstances.
*
* @param offline the OfflinePlayer to load a Player for
* @return the Player
* Check the configuration value for whether or not OpenInv displays a notification to the user
* when a container is activated with AnyChest.
*
* @return true unless configured otherwise
*/
public Player loadPlayer(final OfflinePlayer offline);
public boolean notifyAnyChest();
/**
* Check the configuration value for whether or not OpenInv displays a notification to the user
* when a container is activated with SilentChest.
*
* @return true unless configured otherwise
*/
public boolean notifySilentChest();
/**
* Mark a Player as no longer in use by a Plugin to allow OpenInv to remove it from the cache
* when eligible.
*
* @param player the Player
* @param plugin the Plugin no longer holding a reference to the Player
* @throws IllegalStateException if the server version is unsupported
*/
public void releasePlayer(Player player, Plugin plugin);
/**
* Mark a Player as in use by a Plugin to prevent it from being removed from the cache. Used to
@@ -169,19 +198,37 @@ public interface IOpenInv {
* {@link #disableSaving()} returns false. If you are making changes that OpenInv does not cause
* to persist when a Player logs in as noted above, it is suggested that you manually call
* {@link Player#saveData()} when releasing your reference to ensure your changes persist.
*
*
* @param player the Player
* @param plugin the Plugin holding the reference to the Player
* @throws IllegalStateException if the server version is unsupported
*/
public void retainPlayer(Player player, Plugin plugin);
/**
* Mark a Player as no longer in use by a Plugin to allow OpenInv to remove it from the cache
* when eligible.
*
* @param player the Player
* @param plugin the Plugin no longer holding a reference to the Player
* Sets a player's AnyChest setting.
*
* @param player the OfflinePlayer
* @param status the status
* @throws IllegalStateException if the server version is unsupported
*/
public void releasePlayer(Player player, Plugin plugin);
public void setPlayerAnyChestStatus(OfflinePlayer player, boolean status);
/**
* Sets a player's SilentChest setting.
*
* @param player the OfflinePlayer
* @param status the status
* @throws IllegalStateException if the server version is unsupported
*/
public void setPlayerSilentChestStatus(OfflinePlayer player, boolean status);
/**
* Forcibly unload a cached Player's data.
*
* @param player the OfflinePlayer to unload
* @throws IllegalStateException if the server version is unsupported
*/
public void unload(OfflinePlayer player);
}