Upstream/Paper
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2025-02-12 02:21:54 +01:00
Code Issues Projects Releases Wiki Activity

Pulling all pending Bukkit-JavaDoc changes

Browse Source 
A special thanks goes to @aerouk for almost all of the changes found here.

By: Wesley Wolfe <weswolf@aol.com>
This commit is contained in:
Bukkit/Spigot 2013-12-15 01:07:43 -05:00
parent 800679913f
commit bb50f1a774
310 changed files with 4218 additions and 2904 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
paper-api/src/main/java/org/bukkit/Achievement.java
View File

@ -40,7 +40,8 @@ public enum Achievement {
; ;
/** /**
* The offset used to distinguish Achievements and Statistics * The offset used to distinguish Achievements and Statistics.
*
* @deprecated Magic value * @deprecated Magic value
*/ */
@Deprecated @Deprecated

16
paper-api/src/main/java/org/bukkit/BlockChangeDelegate.java
View File

@ -8,8 +8,11 @@ package org.bukkit;
public interface BlockChangeDelegate { public interface BlockChangeDelegate {
/** /**
* Set a block type at the specified coordinates without doing all world updates and notifications. * Set a block type at the specified coordinates without doing all world
* It is safe to have this call World.setTypeId, but it may be slower than World.setRawTypeId. * updates and notifications.
* <p>
* It is safe to have this call World.setTypeId, but it may be slower than
* World.setRawTypeId.
* *
* @param x X coordinate * @param x X coordinate
* @param y Y coordinate * @param y Y coordinate
@ -22,8 +25,11 @@ public interface BlockChangeDelegate {
public boolean setRawTypeId(int x, int y, int z, int typeId); public boolean setRawTypeId(int x, int y, int z, int typeId);
/** /**
* Set a block type and data at the specified coordinates without doing all world updates and notifications. * Set a block type and data at the specified coordinates without doing
* It is safe to have this call World.setTypeId, but it may be slower than World.setRawTypeId. * all world updates and notifications.
* <p>
* It is safe to have this call World.setTypeId, but it may be slower than
* World.setRawTypeId.
* *
* @param x X coordinate * @param x X coordinate
* @param y Y coordinate * @param y Y coordinate
@ -38,6 +44,7 @@ public interface BlockChangeDelegate {
/** /**
* Set a block type at the specified coordinates. * Set a block type at the specified coordinates.
* <p>
* This method cannot call World.setRawTypeId, a full update is needed. * This method cannot call World.setRawTypeId, a full update is needed.
* *
* @param x X coordinate * @param x X coordinate
@ -52,6 +59,7 @@ public interface BlockChangeDelegate {
/** /**
* Set a block type and data at the specified coordinates. * Set a block type and data at the specified coordinates.
* <p>
* This method cannot call World.setRawTypeId, a full update is needed. * This method cannot call World.setRawTypeId, a full update is needed.
* *
* @param x X coordinate * @param x X coordinate

3
paper-api/src/main/java/org/bukkit/Bukkit.java
View File

@ -574,7 +574,8 @@ public final class Bukkit {
} }
/** /**
* @see Server#createInventory(InventoryHolder owner, int size, String title) * @see Server#createInventory(InventoryHolder owner, int size, String
* title)
*/ */
public static Inventory createInventory(InventoryHolder owner, int size, String title) { public static Inventory createInventory(InventoryHolder owner, int size, String title) {
return server.createInventory(owner, size, title); return server.createInventory(owner, size, title);

17
paper-api/src/main/java/org/bukkit/ChatColor.java
View File

@ -101,8 +101,8 @@ public enum ChatColor {
RESET('r', 0x15); RESET('r', 0x15);
/** /**
* The special character which prefixes all chat colour codes. Use this if you need to dynamically * The special character which prefixes all chat colour codes. Use this if
* convert colour codes from your custom format. * you need to dynamically convert colour codes from your custom format.
*/ */
public static final char COLOR_CHAR = '\u00A7'; public static final char COLOR_CHAR = '\u00A7';
private static final Pattern STRIP_COLOR_PATTERN = Pattern.compile("(?i)" + String.valueOf(COLOR_CHAR) + "[0-9A-FK-OR]"); private static final Pattern STRIP_COLOR_PATTERN = Pattern.compile("(?i)" + String.valueOf(COLOR_CHAR) + "[0-9A-FK-OR]");
@ -157,7 +157,8 @@ public enum ChatColor {
* Gets the color represented by the specified color code * Gets the color represented by the specified color code
* *
* @param code Code to check * @param code Code to check
* @return Associative {@link org.bukkit.ChatColor} with the given code, or null if it doesn't exist * @return Associative {@link org.bukkit.ChatColor} with the given code,
* or null if it doesn't exist
*/ */
public static ChatColor getByChar(char code) { public static ChatColor getByChar(char code) {
return BY_CHAR.get(code); return BY_CHAR.get(code);
@ -167,7 +168,8 @@ public enum ChatColor {
* Gets the color represented by the specified color code * Gets the color represented by the specified color code
* *
* @param code Code to check * @param code Code to check
* @return Associative {@link org.bukkit.ChatColor} with the given code, or null if it doesn't exist * @return Associative {@link org.bukkit.ChatColor} with the given code,
* or null if it doesn't exist
*/ */
public static ChatColor getByChar(String code) { public static ChatColor getByChar(String code) {
Validate.notNull(code, "Code cannot be null"); Validate.notNull(code, "Code cannot be null");
@ -191,9 +193,10 @@ public enum ChatColor {
} }
/** /**
* Translates a string using an alternate color code character into a string that uses the internal * Translates a string using an alternate color code character into a
* ChatColor.COLOR_CODE color code character. The alternate color code character will only be replaced * string that uses the internal ChatColor.COLOR_CODE color code
* if it is immediately followed by 0-9, A-F, a-f, K-O, k-o, R or r. * character. The alternate color code character will only be replaced if
* it is immediately followed by 0-9, A-F, a-f, K-O, k-o, R or r.
* *
* @param altColorChar The alternate color code character to replace. Ex: & * @param altColorChar The alternate color code character to replace. Ex: &
* @param textToTranslate Text containing the alternate color code character. * @param textToTranslate Text containing the alternate color code character.

15
paper-api/src/main/java/org/bukkit/Chunk.java
View File

@ -50,9 +50,12 @@ public interface Chunk {
/** /**
* Capture thread-safe read-only snapshot of chunk data * Capture thread-safe read-only snapshot of chunk data
* *
* @param includeMaxblocky - if true, snapshot includes per-coordinate maximum Y values * @param includeMaxblocky - if true, snapshot includes per-coordinate
* @param includeBiome - if true, snapshot includes per-coordinate biome type * maximum Y values
* @param includeBiomeTempRain - if true, snapshot includes per-coordinate raw biome temperature and rainfall * @param includeBiome - if true, snapshot includes per-coordinate biome
* type
* @param includeBiomeTempRain - if true, snapshot includes per-coordinate
* raw biome temperature and rainfall
* @return ChunkSnapshot * @return ChunkSnapshot
*/ */
ChunkSnapshot getChunkSnapshot(boolean includeMaxblocky, boolean includeBiome, boolean includeBiomeTempRain); ChunkSnapshot getChunkSnapshot(boolean includeMaxblocky, boolean includeBiome, boolean includeBiomeTempRain);
@ -81,7 +84,8 @@ public interface Chunk {
/** /**
* Loads the chunk. * Loads the chunk.
* *
* @param generate Whether or not to generate a chunk if it doesn't already exist * @param generate Whether or not to generate a chunk if it doesn't
* already exist
* @return true if the chunk has loaded successfully, otherwise false * @return true if the chunk has loaded successfully, otherwise false
*/ */
boolean load(boolean generate); boolean load(boolean generate);
@ -97,7 +101,8 @@ public interface Chunk {
* Unloads and optionally saves the Chunk * Unloads and optionally saves the Chunk
* *
* @param save Controls whether the chunk is saved * @param save Controls whether the chunk is saved
* @param safe Controls whether to unload the chunk when players are nearby * @param safe Controls whether to unload the chunk when players are
* nearby
* @return true if the chunk has unloaded successfully, otherwise false * @return true if the chunk has unloaded successfully, otherwise false
*/ */
boolean unload(boolean save, boolean safe); boolean unload(boolean save, boolean safe);

9
paper-api/src/main/java/org/bukkit/ChunkSnapshot.java
View File

@ -3,8 +3,10 @@ package org.bukkit;
import org.bukkit.block.Biome; import org.bukkit.block.Biome;
/** /**
* Represents a static, thread-safe snapshot of chunk of blocks * Represents a static, thread-safe snapshot of chunk of blocks.
* Purpose is to allow clean, efficient copy of a chunk data to be made, and then handed off for processing in another thread (e.g. map rendering) * <p>
* Purpose is to allow clean, efficient copy of a chunk data to be made, and
* then handed off for processing in another thread (e.g. map rendering)
*/ */
public interface ChunkSnapshot { public interface ChunkSnapshot {
@ -64,7 +66,8 @@ public interface ChunkSnapshot {
int getBlockSkyLight(int x, int y, int z); int getBlockSkyLight(int x, int y, int z);
/** /**
* Get light level emitted by block at corresponding coordinate in the chunk * Get light level emitted by block at corresponding coordinate in the
* chunk
* *
* @param x 0-15 * @param x 0-15
* @param y 0-127 * @param y 0-127

5
paper-api/src/main/java/org/bukkit/CoalType.java
View File

@ -32,10 +32,9 @@ public enum CoalType {
/** /**
* Gets the type of coal with the given data value * Gets the type of coal with the given data value
* *
* @param data * @param data Data value to fetch
* Data value to fetch
* @return The {@link CoalType} representing the given value, or null if * @return The {@link CoalType} representing the given value, or null if
* it doesn't exist * it doesn't exist
* @deprecated Magic value * @deprecated Magic value
*/ */
@Deprecated @Deprecated

25
paper-api/src/main/java/org/bukkit/Color.java
View File

@ -9,8 +9,9 @@ import org.bukkit.configuration.serialization.SerializableAs;
import com.google.common.collect.ImmutableMap; import com.google.common.collect.ImmutableMap;
/** /**
* A container for a color palette. This class is immutable; the set methods return a new color. * A container for a color palette. This class is immutable; the set methods
* The color names listed as fields are HTML4 standards, but subject to change. * return a new color. The color names listed as fields are HTML4 standards,
* but subject to change.
*/ */
@SerializableAs("Color") @SerializableAs("Color")
public final class Color implements ConfigurationSerializable { public final class Color implements ConfigurationSerializable {
@ -132,11 +133,13 @@ public final class Color implements ConfigurationSerializable {
} }
/** /**
* Creates a new color object from an integer that contains the red, green, and blue bytes in the lowest order 24 bits. * Creates a new color object from an integer that contains the red,
* green, and blue bytes in the lowest order 24 bits.
* *
* @param rgb the integer storing the red, green, and blue values * @param rgb the integer storing the red, green, and blue values
* @return a new color object for specified values * @return a new color object for specified values
* @throws IllegalArgumentException if any data is in the highest order 8 bits * @throws IllegalArgumentException if any data is in the highest order 8
* bits
*/ */
public static Color fromRGB(int rgb) throws IllegalArgumentException { public static Color fromRGB(int rgb) throws IllegalArgumentException {
Validate.isTrue((rgb >> 24) == 0, "Extrenuous data in: ", rgb); Validate.isTrue((rgb >> 24) == 0, "Extrenuous data in: ", rgb);
@ -144,11 +147,13 @@ public final class Color implements ConfigurationSerializable {
} }
/** /**
* Creates a new color object from an integer that contains the blue, green, and red bytes in the lowest order 24 bits. * Creates a new color object from an integer that contains the blue,
* green, and red bytes in the lowest order 24 bits.
* *
* @param bgr the integer storing the blue, green, and red values * @param bgr the integer storing the blue, green, and red values
* @return a new color object for specified values * @return a new color object for specified values
* @throws IllegalArgumentException if any data is in the highest order 8 bits * @throws IllegalArgumentException if any data is in the highest order 8
* bits
*/ */
public static Color fromBGR(int bgr) throws IllegalArgumentException { public static Color fromBGR(int bgr) throws IllegalArgumentException {
Validate.isTrue((bgr >> 24) == 0, "Extrenuous data in: ", bgr); Validate.isTrue((bgr >> 24) == 0, "Extrenuous data in: ", bgr);
@ -239,8 +244,8 @@ public final class Color implements ConfigurationSerializable {
} }
/** /**
* Creates a new color with its RGB components changed as if it was dyed with the colors passed in, replicating * Creates a new color with its RGB components changed as if it was dyed
* vanilla workbench dyeing * with the colors passed in, replicating vanilla workbench dyeing
* *
* @param colors The DyeColors to dye with * @param colors The DyeColors to dye with
* @return A new color with the changed rgb components * @return A new color with the changed rgb components
@ -258,8 +263,8 @@ public final class Color implements ConfigurationSerializable {
} }
/** /**
* Creates a new color with its RGB components changed as if it was dyed with the colors passed in, replicating * Creates a new color with its RGB components changed as if it was dyed
* vanilla workbench dyeing * with the colors passed in, replicating vanilla workbench dyeing
* *
* @param colors The colors to dye with * @param colors The colors to dye with
* @return A new color with the changed rgb components * @return A new color with the changed rgb components

5
paper-api/src/main/java/org/bukkit/CropState.java
View File

@ -63,10 +63,9 @@ public enum CropState {
/** /**
* Gets the CropState with the given data value * Gets the CropState with the given data value
* *
* @param data * @param data Data value to fetch
* Data value to fetch
* @return The {@link CropState} representing the given value, or null if * @return The {@link CropState} representing the given value, or null if
* it doesn't exist * it doesn't exist
* @deprecated Magic value * @deprecated Magic value
*/ */
@Deprecated @Deprecated

16
paper-api/src/main/java/org/bukkit/Difficulty.java
View File

@ -9,22 +9,27 @@ import com.google.common.collect.Maps;
*/ */
public enum Difficulty { public enum Difficulty {
/** /**
* Players regain health over time, hostile mobs don't spawn, the hunger bar does not deplete. * Players regain health over time, hostile mobs don't spawn, the hunger
* bar does not deplete.
*/ */
PEACEFUL(0), PEACEFUL(0),
/** /**
* Hostile mobs spawn, enemies deal less damage than on normal difficulty, the hunger bar does deplete and starving deals up to 5 hearts of damage. (Default value) * Hostile mobs spawn, enemies deal less damage than on normal difficulty,
* the hunger bar does deplete and starving deals up to 5 hearts of
* damage. (Default value)
*/ */
EASY(1), EASY(1),
/** /**
* Hostile mobs spawn, enemies deal normal amounts of damage, the hunger bar does deplete and starving deals up to 9.5 hearts of damage. * Hostile mobs spawn, enemies deal normal amounts of damage, the hunger
* bar does deplete and starving deals up to 9.5 hearts of damage.
*/ */
NORMAL(2), NORMAL(2),
/** /**
* Hostile mobs spawn, enemies deal greater damage than on normal difficulty, the hunger bar does deplete and starving can kill players. * Hostile mobs spawn, enemies deal greater damage than on normal
* difficulty, the hunger bar does deplete and starving can kill players.
*/ */
HARD(3); HARD(3);
@ -50,7 +55,8 @@ public enum Difficulty {
* Gets the Difficulty represented by the specified value * Gets the Difficulty represented by the specified value
* *
* @param value Value to check * @param value Value to check
* @return Associative {@link Difficulty} with the given value, or null if it doesn't exist * @return Associative {@link Difficulty} with the given value, or null if
* it doesn't exist
* @deprecated Magic value * @deprecated Magic value
*/ */
@Deprecated @Deprecated

21
paper-api/src/main/java/org/bukkit/DyeColor.java
View File

@ -94,7 +94,8 @@ public enum DyeColor {
* Gets the associated (wool) data value representing this color. * Gets the associated (wool) data value representing this color.
* *
* @return A byte containing the (wool) data value of this color * @return A byte containing the (wool) data value of this color
* @deprecated The name is misleading. It would imply {@link Material#INK_SACK} but uses {@link Material#WOOL} * @deprecated The name is misleading. It would imply {@link
* Material#INK_SACK} but uses {@link Material#WOOL}
* @see #getWoolData() * @see #getWoolData()
* @see #getDyeData() * @see #getDyeData()
*/ */
@ -149,8 +150,10 @@ public enum DyeColor {
* Gets the DyeColor with the given (wool) data value. * Gets the DyeColor with the given (wool) data value.
* *
* @param data (wool) data value to fetch * @param data (wool) data value to fetch
* @return The {@link DyeColor} representing the given value, or null if it doesn't exist * @return The {@link DyeColor} representing the given value, or null if
* @deprecated The name is misleading. It would imply {@link Material#INK_SACK} but uses {@link Material#WOOL} * it doesn't exist
* @deprecated The name is misleading. It would imply {@link
* Material#INK_SACK} but uses {@link Material#WOOL}
* @see #getByDyeData(byte) * @see #getByDyeData(byte)
* @see #getByWoolData(byte) * @see #getByWoolData(byte)
*/ */
@ -163,7 +166,8 @@ public enum DyeColor {
* Gets the DyeColor with the given wool data value. * Gets the DyeColor with the given wool data value.
* *
* @param data Wool data value to fetch * @param data Wool data value to fetch
* @return The {@link DyeColor} representing the given value, or null if it doesn't exist * @return The {@link DyeColor} representing the given value, or null if
* it doesn't exist
* @see #getByDyeData(byte) * @see #getByDyeData(byte)
* @deprecated Magic value * @deprecated Magic value
*/ */
@ -180,7 +184,8 @@ public enum DyeColor {
* Gets the DyeColor with the given dye data value. * Gets the DyeColor with the given dye data value.
* *
* @param data Dye data value to fetch * @param data Dye data value to fetch
* @return The {@link DyeColor} representing the given value, or null if it doesn't exist * @return The {@link DyeColor} representing the given value, or null if
* it doesn't exist
* @see #getByWoolData(byte) * @see #getByWoolData(byte)
* @deprecated Magic value * @deprecated Magic value
*/ */
@ -197,7 +202,8 @@ public enum DyeColor {
* Gets the DyeColor with the given color value * Gets the DyeColor with the given color value
* *
* @param color Color value to get the dye by * @param color Color value to get the dye by
* @return The {@link DyeColor} representing the given value, or null if it doesn't exist * @return The {@link DyeColor} representing the given value, or null if
* it doesn't exist
*/ */
public static DyeColor getByColor(final Color color) { public static DyeColor getByColor(final Color color) {
return BY_COLOR.get(color); return BY_COLOR.get(color);
@ -207,7 +213,8 @@ public enum DyeColor {
* Gets the DyeColor with the given firework color value * Gets the DyeColor with the given firework color value
* *
* @param color Color value to get dye by * @param color Color value to get dye by
* @return The {@link DyeColor} representing the given value, or null if it doesn't exist * @return The {@link DyeColor} representing the given value, or null if
* it doesn't exist
*/ */
public static DyeColor getByFireworkColor(final Color color) { public static DyeColor getByFireworkColor(final Color color) {
return BY_FIREWORK.get(color); return BY_FIREWORK.get(color);

6
paper-api/src/main/java/org/bukkit/Effect.java
View File

@ -68,7 +68,8 @@ public enum Effect {
*/ */
STEP_SOUND(2001, Type.SOUND, Material.class), STEP_SOUND(2001, Type.SOUND, Material.class),
/** /**
* Visual effect of a splash potion breaking. Needs potion data value as additional info. * Visual effect of a splash potion breaking. Needs potion data value as
* additional info.
*/ */
POTION_BREAK(2002, Type.VISUAL, Potion.class), POTION_BREAK(2002, Type.VISUAL, Potion.class),
/** /**
@ -114,7 +115,8 @@ public enum Effect {
} }
/** /**
* @return The class which represents data for this effect, or null if none * @return The class which represents data for this effect, or null if
* none
*/ */
public Class<?> getData() { public Class<?> getData() {
return this.data; return this.data;

3
paper-api/src/main/java/org/bukkit/EntityEffect.java
View File

@ -69,7 +69,8 @@ public enum EntityEffect {
* Gets the EntityEffect with the given data value * Gets the EntityEffect with the given data value
* *
* @param data Data value to fetch * @param data Data value to fetch
* @return The {@link EntityEffect} representing the given value, or null if it doesn't exist * @return The {@link EntityEffect} representing the given value, or null
* if it doesn't exist
* @deprecated Magic value * @deprecated Magic value
*/ */
@Deprecated @Deprecated

25
paper-api/src/main/java/org/bukkit/FireworkEffect.java
View File

@ -142,7 +142,8 @@ public final class FireworkEffect implements ConfigurationSerializable {
* @param colors The colors to add * @param colors The colors to add
* @return This object, for chaining * @return This object, for chaining
* @throws IllegalArgumentException If colors is null * @throws IllegalArgumentException If colors is null
* @throws IllegalArgumentException If any color is null (may be thrown after changes have occurred) * @throws IllegalArgumentException If any color is null (may be
* thrown after changes have occurred)
*/ */
public Builder withColor(Color...colors) throws IllegalArgumentException { public Builder withColor(Color...colors) throws IllegalArgumentException {
Validate.notNull(colors, "Cannot have null colors"); Validate.notNull(colors, "Cannot have null colors");
@ -162,10 +163,12 @@ public final class FireworkEffect implements ConfigurationSerializable {
/** /**
* Add several primary colors to the firework effect. * Add several primary colors to the firework effect.
* *
* @param colors An iterable object whose iterator yields the desired colors * @param colors An iterable object whose iterator yields the desired
* colors
* @return This object, for chaining * @return This object, for chaining
* @throws IllegalArgumentException If colors is null * @throws IllegalArgumentException If colors is null
* @throws IllegalArgumentException If any color is null (may be thrown after changes have occurred) * @throws IllegalArgumentException If any color is null (may be
* thrown after changes have occurred)
*/ */
public Builder withColor(Iterable<?> colors) throws IllegalArgumentException { public Builder withColor(Iterable<?> colors) throws IllegalArgumentException {
Validate.notNull(colors, "Cannot have null colors"); Validate.notNull(colors, "Cannot have null colors");
@ -187,7 +190,8 @@ public final class FireworkEffect implements ConfigurationSerializable {
* @param color The color to add * @param color The color to add
* @return This object, for chaining * @return This object, for chaining
* @throws IllegalArgumentException If colors is null * @throws IllegalArgumentException If colors is null
* @throws IllegalArgumentException If any color is null (may be thrown after changes have occurred) * @throws IllegalArgumentException If any color is null (may be
* thrown after changes have occurred)
*/ */
public Builder withFade(Color color) throws IllegalArgumentException { public Builder withFade(Color color) throws IllegalArgumentException {
Validate.notNull(color, "Cannot have null color"); Validate.notNull(color, "Cannot have null color");
@ -207,7 +211,8 @@ public final class FireworkEffect implements ConfigurationSerializable {
* @param colors The colors to add * @param colors The colors to add
* @return This object, for chaining * @return This object, for chaining
* @throws IllegalArgumentException If colors is null * @throws IllegalArgumentException If colors is null
* @throws IllegalArgumentException If any color is null (may be thrown after changes have occurred) * @throws IllegalArgumentException If any color is null (may be
* thrown after changes have occurred)
*/ */
public Builder withFade(Color...colors) throws IllegalArgumentException { public Builder withFade(Color...colors) throws IllegalArgumentException {
Validate.notNull(colors, "Cannot have null colors"); Validate.notNull(colors, "Cannot have null colors");
@ -231,10 +236,12 @@ public final class FireworkEffect implements ConfigurationSerializable {
/** /**
* Add several fade colors to the firework effect. * Add several fade colors to the firework effect.
* *
* @param colors An iterable object whose iterator yields the desired colors * @param colors An iterable object whose iterator yields the desired
* colors
* @return This object, for chaining * @return This object, for chaining
* @throws IllegalArgumentException If colors is null * @throws IllegalArgumentException If colors is null
* @throws IllegalArgumentException If any color is null (may be thrown after changes have occurred) * @throws IllegalArgumentException If any color is null (may be
* thrown after changes have occurred)
*/ */
public Builder withFade(Iterable<?> colors) throws IllegalArgumentException { public Builder withFade(Iterable<?> colors) throws IllegalArgumentException {
Validate.notNull(colors, "Cannot have null colors"); Validate.notNull(colors, "Cannot have null colors");
@ -255,7 +262,9 @@ public final class FireworkEffect implements ConfigurationSerializable {
} }
/** /**
* Create a {@link FireworkEffect} from the current contents of this builder. * Create a {@link FireworkEffect} from the current contents of this
* builder.
* <p>
* To successfully build, you must have specified at least one color. * To successfully build, you must have specified at least one color.
* *
* @return The representative firework effect * @return The representative firework effect

9
paper-api/src/main/java/org/bukkit/GameMode.java
View File

@ -7,11 +7,13 @@ import org.bukkit.entity.HumanEntity;
import com.google.common.collect.Maps; import com.google.common.collect.Maps;
/** /**
* Represents the various type of game modes that {@link HumanEntity}s may have * Represents the various type of game modes that {@link HumanEntity}s may
* have
*/ */
public enum GameMode { public enum GameMode {
/** /**
* Creative mode may fly, build instantly, become invulnerable and create free items. * Creative mode may fly, build instantly, become invulnerable and create
* free items.
*/ */
CREATIVE(1), CREATIVE(1),
@ -47,7 +49,8 @@ public enum GameMode {
* Gets the GameMode represented by the specified value * Gets the GameMode represented by the specified value
* *
* @param value Value to check * @param value Value to check
* @return Associative {@link GameMode} with the given value, or null if it doesn't exist * @return Associative {@link GameMode} with the given value, or null if
* it doesn't exist
* @deprecated Magic value * @deprecated Magic value
*/ */
@Deprecated @Deprecated

7
paper-api/src/main/java/org/bukkit/GrassSpecies.java
View File

@ -43,10 +43,9 @@ public enum GrassSpecies {
/** /**
* Gets the GrassSpecies with the given data value * Gets the GrassSpecies with the given data value
* *
* @param data * @param data Data value to fetch
* Data value to fetch * @return The {@link GrassSpecies} representing the given value, or null
* @return The {@link GrassSpecies} representing the given value, or null if * if it doesn't exist
* it doesn't exist
* @deprecated Magic value * @deprecated Magic value
*/ */
@Deprecated @Deprecated

12
paper-api/src/main/java/org/bukkit/Instrument.java
View File

@ -11,19 +11,23 @@ public enum Instrument {
*/ */
PIANO(0x0), PIANO(0x0),
/** /**
* Bass drum is normally played when a note block is on top of a stone-like block * Bass drum is normally played when a note block is on top of a
* stone-like block
*/ */
BASS_DRUM(0x1), BASS_DRUM(0x1),
/** /**
* Snare drum is normally played when a note block is on top of a sandy block. * Snare drum is normally played when a note block is on top of a sandy
* block.
*/ */
SNARE_DRUM(0x2), SNARE_DRUM(0x2),
/** /**
* Sticks are normally played when a note block is on top of a glass block. * Sticks are normally played when a note block is on top of a glass
* block.
*/ */
STICKS(0x3), STICKS(0x3),
/** /**
* Bass guitar is normally played when a note block is on top of a wooden block. * Bass guitar is normally played when a note block is on top of a wooden
* block.
*/ */
BASS_GUITAR(0x4); BASS_GUITAR(0x4);

32
paper-api/src/main/java/org/bukkit/Location.java
View File

@ -390,12 +390,12 @@ public class Location implements Cloneable {
} }
/** /**
* Gets the magnitude of the location, defined as sqrt(x^2+y^2+z^2). The value * Gets the magnitude of the location, defined as sqrt(x^2+y^2+z^2). The
* of this method is not cached and uses a costly square-root function, so * value of this method is not cached and uses a costly square-root
* do not repeatedly call this method to get the location's magnitude. NaN * function, so do not repeatedly call this method to get the location's
* will be returned if the inner result of the sqrt() function overflows, * magnitude. NaN will be returned if the inner result of the sqrt()
* which will be caused if the length is too long. Not world-aware and * function overflows, which will be caused if the length is too long. Not
* orientation independent. * world-aware and orientation independent.
* *
* @see Vector * @see Vector
* @return the magnitude * @return the magnitude
@ -416,11 +416,11 @@ public class Location implements Cloneable {
} }
/** /**
* Get the distance between this location and another. The value * Get the distance between this location and another. The value of this
* of this method is not cached and uses a costly square-root function, so * method is not cached and uses a costly square-root function, so do not
* do not repeatedly call this method to get the location's magnitude. NaN * repeatedly call this method to get the location's magnitude. NaN will
* will be returned if the inner result of the sqrt() function overflows, * be returned if the inner result of the sqrt() function overflows, which
* which will be caused if the distance is too long. * will be caused if the distance is too long.
* *
* @see Vector * @see Vector
* @param o The other location * @param o The other location
@ -452,8 +452,8 @@ public class Location implements Cloneable {
} }
/** /**
* Performs scalar multiplication, multiplying all components with a scalar. * Performs scalar multiplication, multiplying all components with a
* Not world-aware. * scalar. Not world-aware.
* *
* @param m The factor * @param m The factor
* @see Vector * @see Vector
@ -531,7 +531,8 @@ public class Location implements Cloneable {
/** /**
* Constructs a new {@link Vector} based on this Location * Constructs a new {@link Vector} based on this Location
* *
* @return New Vector containing the coordinates represented by this Location * @return New Vector containing the coordinates represented by this
* Location
*/ */
public Vector toVector() { public Vector toVector() {
return new Vector(x, y, z); return new Vector(x, y, z);
@ -547,7 +548,8 @@ public class Location implements Cloneable {
} }
/** /**
* Safely converts a double (location coordinate) to an int (block coordinate) * Safely converts a double (location coordinate) to an int (block
* coordinate)
* *
* @param loc Precise coordinate * @param loc Precise coordinate
* @return Block coordinate * @return Block coordinate

14
paper-api/src/main/java/org/bukkit/Material.java
View File

@ -495,8 +495,8 @@ public enum Material {
} }
/** /**
* Constructs a new MaterialData relevant for this Material, with the given * Constructs a new MaterialData relevant for this Material, with the
* initial data * given initial data
* *
* @param raw Initial data to construct the MaterialData with * @param raw Initial data to construct the MaterialData with
* @return New MaterialData with the given data * @return New MaterialData with the given data
@ -582,6 +582,7 @@ public enum Material {
/** /**
* Attempts to get the Material with the given name. * Attempts to get the Material with the given name.
* <p>
* This is a normal lookup, names must be the precise name they are given * This is a normal lookup, names must be the precise name they are given
* in the enum. * in the enum.
* *
@ -594,8 +595,10 @@ public enum Material {
/** /**
* Attempts to match the Material with the given name. * Attempts to match the Material with the given name.
* This is a match lookup; names will be converted to uppercase, then stripped * <p>
* of special characters in an attempt to format it like the enum. * This is a match lookup; names will be converted to uppercase, then
* stripped of special characters in an attempt to format it like the
* enum.
* <p> * <p>
* Using this for match by ID is deprecated. * Using this for match by ID is deprecated.
* *
@ -641,7 +644,8 @@ public enum Material {
} }
/** /**
* Check if the material is a block and solid (cannot be passed through by a player) * Check if the material is a block and solid (cannot be passed through by
* a player)
* *
* @return True if this material is a block and solid * @return True if this material is a block and solid
*/ */

41
paper-api/src/main/java/org/bukkit/NetherWartsState.java
View File

@ -1,20 +1,21 @@
package org.bukkit; package org.bukkit;
public enum NetherWartsState { public enum NetherWartsState {
/**
* State when first seeded /**
*/ * State when first seeded
SEEDED, */
/** SEEDED,
* First growth stage /**
*/ * First growth stage
STAGE_ONE, */
/** STAGE_ONE,
* Second growth stage /**
*/ * Second growth stage
STAGE_TWO, */
/** STAGE_TWO,
* Ready to harvest /**
*/ * Ready to harvest
RIPE; */
} RIPE;
}

13
paper-api/src/main/java/org/bukkit/Note.java
View File

@ -76,7 +76,8 @@ public class Note {
* *
* @param id the id of the tone. * @param id the id of the tone.
* @return if the tone id is the sharped id of the tone. * @return if the tone id is the sharped id of the tone.
* @throws IllegalArgumentException if neither the tone nor the semitone have the id. * @throws IllegalArgumentException if neither the tone nor the
* semitone have the id.
* @deprecated Magic value * @deprecated Magic value
*/ */
@Deprecated @Deprecated
@ -121,8 +122,8 @@ public class Note {
/** /**
* Creates a new note. * Creates a new note.
* *
* @param note Internal note id. {@link #getId()} always return this value. * @param note Internal note id. {@link #getId()} always return this
* The value has to be in the interval [0;&nbsp;24]. * value. The value has to be in the interval [0;&nbsp;24].
*/ */
public Note(int note) { public Note(int note) {
Validate.isTrue(note >= 0 && note <= 24, "The note value has to be between 0 and 24."); Validate.isTrue(note >= 0 && note <= 24, "The note value has to be between 0 and 24.");
@ -134,7 +135,8 @@ public class Note {
* Creates a new note. * Creates a new note.
* *
* @param octave The octave where the note is in. Has to be 0 - 2. * @param octave The octave where the note is in. Has to be 0 - 2.
* @param tone The tone within the octave. If the octave is 2 the note has to be F#. * @param tone The tone within the octave. If the octave is 2 the note has
* to be F#.
* @param sharped Set if the tone is sharped (e.g. for F#). * @param sharped Set if the tone is sharped (e.g. for F#).
*/ */
public Note(int octave, Tone tone, boolean sharped) { public Note(int octave, Tone tone, boolean sharped) {
@ -166,7 +168,8 @@ public class Note {
* Creates a new note for a sharp tone, such as A-sharp. * Creates a new note for a sharp tone, such as A-sharp.
* *
* @param octave The octave where the note is in. Has to be 0 - 2. * @param octave The octave where the note is in. Has to be 0 - 2.
* @param tone The tone within the octave. If the octave is 2 the note has to be F#. * @param tone The tone within the octave. If the octave is 2 the note has
* to be F#.
* @return The new note. * @return The new note.
*/ */
public static Note sharp(int octave, Tone tone) { public static Note sharp(int octave, Tone tone) {

20
paper-api/src/main/java/org/bukkit/OfflinePlayer.java
View File

@ -60,20 +60,24 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
public Player getPlayer(); public Player getPlayer();
/** /**
* Gets the first date and time that this player was witnessed on this server. * Gets the first date and time that this player was witnessed on this
* server.
* <p> * <p>
* If the player has never played before, this will return 0. Otherwise, it will be * If the player has never played before, this will return 0. Otherwise,
* the amount of milliseconds since midnight, January 1, 1970 UTC. * it will be the amount of milliseconds since midnight, January 1, 1970
* UTC.
* *
* @return Date of first log-in for this player, or 0 * @return Date of first log-in for this player, or 0
*/ */
public long getFirstPlayed(); public long getFirstPlayed();
/** /**
* Gets the last date and time that this player was witnessed on this server. * Gets the last date and time that this player was witnessed on this
* server.
* <p> * <p>
* If the player has never played before, this will return 0. Otherwise, it will be * If the player has never played before, this will return 0. Otherwise,
* the amount of milliseconds since midnight, January 1, 1970 UTC. * it will be the amount of milliseconds since midnight, January 1, 1970
* UTC.
* *
* @return Date of last log-in for this player, or 0 * @return Date of last log-in for this player, or 0
*/ */
@ -87,8 +91,8 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
public boolean hasPlayedBefore(); public boolean hasPlayedBefore();
/** /**
* Gets the Location where the player will spawn at their bed, null if they * Gets the Location where the player will spawn at their bed, null if
* have not slept in one or their current bed spawn is invalid. * they have not slept in one or their current bed spawn is invalid.
* *
* @return Bed Spawn Location if bed exists, otherwise null. * @return Bed Spawn Location if bed exists, otherwise null.
*/ */

1
paper-api/src/main/java/org/bukkit/PortalType.java
View File

@ -4,6 +4,7 @@ package org.bukkit;
* Represents various types of portals that can be made in a world. * Represents various types of portals that can be made in a world.
*/ */
public enum PortalType { public enum PortalType {
/** /**
* This is a Nether portal, made of obsidian. * This is a Nether portal, made of obsidian.
*/ */

1
paper-api/src/main/java/org/bukkit/Rotation.java
View File

@ -2,6 +2,7 @@ package org.bukkit;
/** /**
* An enum to specify a rotation based orientation, like that on a clock. * An enum to specify a rotation based orientation, like that on a clock.
* <p>
* It represents how something is viewed, as opposed to cardinal directions. * It represents how something is viewed, as opposed to cardinal directions.
*/ */
public enum Rotation { public enum Rotation {

7
paper-api/src/main/java/org/bukkit/SandstoneType.java
View File

@ -33,10 +33,9 @@ public enum SandstoneType {
/** /**
* Gets the type of sandstone with the given data value * Gets the type of sandstone with the given data value
* *
* @param data * @param data Data value to fetch
* Data value to fetch * @return The {@link SandstoneType} representing the given value, or null
* @return The {@link SandstoneType} representing the given value, or null if * if it doesn't exist
* it doesn't exist
* @deprecated Magic value * @deprecated Magic value
*/ */
@Deprecated @Deprecated

130
paper-api/src/main/java/org/bukkit/Server.java
View File

@ -41,14 +41,16 @@ import org.bukkit.inventory.meta.ItemMeta;
public interface Server extends PluginMessageRecipient { public interface Server extends PluginMessageRecipient {
/** /**
* Used for all administrative messages, such as an operator using a command. * Used for all administrative messages, such as an operator using a
* command.
* <p> * <p>
* For use in {@link #broadcast(java.lang.String, java.lang.String)} * For use in {@link #broadcast(java.lang.String, java.lang.String)}
*/ */
public static final String BROADCAST_CHANNEL_ADMINISTRATIVE = "bukkit.broadcast.admin"; public static final String BROADCAST_CHANNEL_ADMINISTRATIVE = "bukkit.broadcast.admin";
/** /**
* Used for all announcement messages, such as informing users that a player has joined. * Used for all announcement messages, such as informing users that a
* player has joined.
* <p> * <p>
* For use in {@link #broadcast(java.lang.String, java.lang.String)} * For use in {@link #broadcast(java.lang.String, java.lang.String)}
*/ */
@ -104,9 +106,11 @@ public interface Server extends PluginMessageRecipient {
public int getViewDistance(); public int getViewDistance();
/** /**
* Get the IP that this server is bound to or empty string if not specified * Get the IP that this server is bound to or empty string if not
* specified
* *
* @return The IP string that this server is bound to, otherwise empty string * @return The IP string that this server is bound to, otherwise empty
* string
*/ */
public String getIp(); public String getIp();
@ -118,8 +122,8 @@ public interface Server extends PluginMessageRecipient {
public String getServerName(); public String getServerName();
/** /**
* Get an ID of this server. The ID is a simple generally alphanumeric * Get an ID of this server. The ID is a simple generally alphanumeric ID
* ID that can be used for uniquely identifying this server. * that can be used for uniquely identifying this server.
* *
* @return The ID of this server * @return The ID of this server
*/ */
@ -182,7 +186,8 @@ public interface Server extends PluginMessageRecipient {
/** /**
* Broadcast a message to all players. * Broadcast a message to all players.
* <p> * <p>
* This is the same as calling {@link #broadcast(java.lang.String, java.lang.String)} to {@link #BROADCAST_CHANNEL_USERS} * This is the same as calling {@link #broadcast(java.lang.String,
* java.lang.String)} to {@link #BROADCAST_CHANNEL_USERS}
* *
* @param message the message * @param message the message
* @return the number of players * @return the number of players
@ -190,8 +195,8 @@ public interface Server extends PluginMessageRecipient {
public int broadcastMessage(String message); public int broadcastMessage(String message);
/** /**
* Gets the name of the update folder. The update folder is used to safely update * Gets the name of the update folder. The update folder is used to safely
* plugins at the right moment on a plugin load. * update plugins at the right moment on a plugin load.
* <p> * <p>
* The update folder name is relative to the plugins folder. * The update folder name is relative to the plugins folder.
* *
@ -219,13 +224,15 @@ public interface Server extends PluginMessageRecipient {
* <p> * <p>
* <b>Example Usage:</b> * <b>Example Usage:</b>
* <ul> * <ul>
* <li>A value of 1 will mean the server will attempt to spawn monsters every tick. * <li>A value of 1 will mean the server will attempt to spawn monsters
* <li>A value of 400 will mean the server will attempt to spawn monsters every 400th tick. * every tick.
* <li>A value of 400 will mean the server will attempt to spawn monsters
* every 400th tick.
* <li>A value below 0 will be reset back to Minecraft's default. * <li>A value below 0 will be reset back to Minecraft's default.
* </ul> * </ul>
* <p> * <p>
* <b>Note:</b> * <b>Note:</b> If set to 0, animal spawning will be disabled. We
* If set to 0, animal spawning will be disabled. We recommend using spawn-animals to control this instead. * recommend using spawn-animals to control this instead.
* <p> * <p>
* Minecraft default: 400. * Minecraft default: 400.
* *
@ -238,13 +245,15 @@ public interface Server extends PluginMessageRecipient {
* <p> * <p>
* <b>Example Usage:</b> * <b>Example Usage:</b>
* <ul> * <ul>
* <li>A value of 1 will mean the server will attempt to spawn monsters every tick. * <li>A value of 1 will mean the server will attempt to spawn monsters
* <li>A value of 400 will mean the server will attempt to spawn monsters every 400th tick. * every tick.
* <li>A value of 400 will mean the server will attempt to spawn monsters
* every 400th tick.
* <li>A value below 0 will be reset back to Minecraft's default. * <li>A value below 0 will be reset back to Minecraft's default.
* </ul> * </ul>
* <p> * <p>
* <b>Note:</b> * <b>Note:</b> If set to 0, monsters spawning will be disabled. We
* If set to 0, monsters spawning will be disabled. We recommend using spawn-monsters to control this instead. * recommend using spawn-monsters to control this instead.
* <p> * <p>
* Minecraft default: 1. * Minecraft default: 1.
* *
@ -274,8 +283,8 @@ public interface Server extends PluginMessageRecipient {
* Attempts to match any players with the given name, and returns a list * Attempts to match any players with the given name, and returns a list
* of all possibly matches * of all possibly matches
* <p> * <p>
* This list is not sorted in any particular order. If an exact match is found, * This list is not sorted in any particular order. If an exact match is
* the returned list will only contain a single result. * found, the returned list will only contain a single result.
* *
* @param name Name to match * @param name Name to match
* @return List of all possible players * @return List of all possible players
@ -311,7 +320,8 @@ public interface Server extends PluginMessageRecipient {
public List<World> getWorlds(); public List<World> getWorlds();
/** /**
* Creates or loads a world with the given name using the specified options. * Creates or loads a world with the given name using the specified
* options.
* <p> * <p>
* If the world is already loaded, it will just return the equivalent of * If the world is already loaded, it will just return the equivalent of
* getWorld(creator.name()). * getWorld(creator.name()).
@ -404,12 +414,14 @@ public interface Server extends PluginMessageRecipient {
* @param sender The apparent sender of the command * @param sender The apparent sender of the command
* @param commandLine command + arguments. Example: "test abc 123" * @param commandLine command + arguments. Example: "test abc 123"
* @return returns false if no target is found. * @return returns false if no target is found.
* @throws CommandException Thrown when the executor for the given command fails with an unhandled exception * @throws CommandException Thrown when the executor for the given command
* fails with an unhandled exception
*/ */
public boolean dispatchCommand(CommandSender sender, String commandLine) throws CommandException; public boolean dispatchCommand(CommandSender sender, String commandLine) throws CommandException;
/** /**
* Populates a given {@link ServerConfig} with values attributes to this server * Populates a given {@link ServerConfig} with values attributes to this
* server
* *
* @param config ServerConfig to populate * @param config ServerConfig to populate
*/ */
@ -419,13 +431,14 @@ public interface Server extends PluginMessageRecipient {
* Adds a recipe to the crafting manager. * Adds a recipe to the crafting manager.
* *
* @param recipe The recipe to add. * @param recipe The recipe to add.
* @return True if the recipe was added, false if it wasn't for some reason. * @return True if the recipe was added, false if it wasn't for some
* reason.
*/ */
public boolean addRecipe(Recipe recipe); public boolean addRecipe(Recipe recipe);
/** /**
* Get a list of all recipes for a given item. The stack size is ignored in comparisons. * Get a list of all recipes for a given item. The stack size is ignored
* If the durability is -1, it will match any data value. * in comparisons. If the durability is -1, it will match any data value.
* *
* @param result The item whose recipes you want * @param result The item whose recipes you want
* @return The list of recipes * @return The list of recipes
@ -494,8 +507,11 @@ public interface Server extends PluginMessageRecipient {
/** /**
* Gets whether to use vanilla (false) or exact behaviour (true). * Gets whether to use vanilla (false) or exact behaviour (true).
* *
* Vanilla behaviour: check for collisions and move the player if needed. * <ul>
* Exact behaviour: spawn players exactly where they should be. * <li>Vanilla behaviour: check for collisions and move the player if
* needed.
* <li>Exact behaviour: spawn players exactly where they should be.
* </ul>
* *
* @return Whether to use vanilla (false) or exact behaviour (true). * @return Whether to use vanilla (false) or exact behaviour (true).
*/ */
@ -507,7 +523,8 @@ public interface Server extends PluginMessageRecipient {
public void shutdown(); public void shutdown();
/** /**
* Broadcasts the specified message to every user with the given permission * Broadcasts the specified message to every user with the given
* permission
* *
* @param message Message to broadcast * @param message Message to broadcast
* @param permission Permission the users must have to receive the broadcast * @param permission Permission the users must have to receive the broadcast
@ -516,9 +533,11 @@ public interface Server extends PluginMessageRecipient {
public int broadcast(String message, String permission); public int broadcast(String message, String permission);
/** /**
* Gets the player by the given name, regardless if they are offline or online. * Gets the player by the given name, regardless if they are offline or
* online.
* <p> * <p>
* This will return an object even if the player does not exist. To this method, all players will exist. * This will return an object even if the player does not exist. To this
* method, all players will exist.
* *
* @param name Name of the player to retrieve * @param name Name of the player to retrieve
* @return OfflinePlayer object * @return OfflinePlayer object
@ -575,8 +594,8 @@ public interface Server extends PluginMessageRecipient {
public void setDefaultGameMode(GameMode mode); public void setDefaultGameMode(GameMode mode);
/** /**
* Gets the {@link ConsoleCommandSender} that may be used as an input source * Gets the {@link ConsoleCommandSender} that may be used as an input
* for this server. * source for this server.
* *
* @return The Console CommandSender * @return The Console CommandSender
*/ */
@ -611,20 +630,23 @@ public interface Server extends PluginMessageRecipient {
public HelpMap getHelpMap(); public HelpMap getHelpMap();
/** /**
* Creates an empty inventory of the specified type. If the type is {@link InventoryType#CHEST}, * Creates an empty inventory of the specified type. If the type is {@link
* the new inventory has a size of 27; otherwise the new inventory has the normal size for * InventoryType#CHEST}, the new inventory has a size of 27; otherwise the
* its type. * new inventory has the normal size for its type.
* *
* @param owner The holder of the inventory; can be null if there's no holder. * @param owner The holder of the inventory; can be null if there's no
* holder.
* @param type The type of inventory to create. * @param type The type of inventory to create.
* @return The new inventory. * @return The new inventory.
*/ */
Inventory createInventory(InventoryHolder owner, InventoryType type); Inventory createInventory(InventoryHolder owner, InventoryType type);
/** /**
* Creates an empty inventory of type {@link InventoryType#CHEST} with the specified size. * Creates an empty inventory of type {@link InventoryType#CHEST} with the
* specified size.
* *
* @param owner The holder of the inventory; can be null if there's no holder. * @param owner The holder of the inventory; can be null if there's no
* holder.
* @param size The size of inventory to create; must be a multiple of 9. * @param size The size of inventory to create; must be a multiple of 9.
* @return The new inventory. * @return The new inventory.
* @throws IllegalArgumentException If the size is not a multiple of 9. * @throws IllegalArgumentException If the size is not a multiple of 9.
@ -632,46 +654,54 @@ public interface Server extends PluginMessageRecipient {
Inventory createInventory(InventoryHolder owner, int size); Inventory createInventory(InventoryHolder owner, int size);
/** /**
* Creates an empty inventory of type {@link InventoryType#CHEST} with the specified size and title. * Creates an empty inventory of type {@link InventoryType#CHEST} with the
* specified size and title.
* *
* @param owner The holder of the inventory; can be null if there's no holder. * @param owner The holder of the inventory; can be null if there's no
* holder.
* @param size The size of inventory to create; must be a multiple of 9. * @param size The size of inventory to create; must be a multiple of 9.
* @param title The title of the inventory, to be displayed when it is viewed. * @param title The title of the inventory, to be displayed when it is
* viewed.
* @return The new inventory. * @return The new inventory.
* @throws IllegalArgumentException If the size is not a multiple of 9. * @throws IllegalArgumentException If the size is not a multiple of 9.
*/ */
Inventory createInventory(InventoryHolder owner, int size, String title); Inventory createInventory(InventoryHolder owner, int size, String title);
/** /**
* Gets user-specified limit for number of monsters that can spawn in a chunk * Gets user-specified limit for number of monsters that can spawn in a
* chunk
* *
* @return The monster spawn limit * @return The monster spawn limit
*/ */
int getMonsterSpawnLimit(); int getMonsterSpawnLimit();
/** /**
* Gets user-specified limit for number of animals that can spawn in a chunk * Gets user-specified limit for number of animals that can spawn in a
* chunk
* *
* @return The animal spawn limit * @return The animal spawn limit
*/ */
int getAnimalSpawnLimit(); int getAnimalSpawnLimit();
/** /**
* Gets user-specified limit for number of water animals that can spawn in a chunk * Gets user-specified limit for number of water animals that can spawn in
* a chunk
* *
* @return The water animal spawn limit * @return The water animal spawn limit
*/ */
int getWaterAnimalSpawnLimit(); int getWaterAnimalSpawnLimit();
/** /**
* Gets user-specified limit for number of ambient mobs that can spawn in a chunk * Gets user-specified limit for number of ambient mobs that can spawn in
* a chunk
* *
* @return The ambient spawn limit * @return The ambient spawn limit
*/ */
int getAmbientSpawnLimit(); int getAmbientSpawnLimit();
/** /**
* Returns true if the current {@link Thread} is the server's primary thread * Returns true if the current {@link Thread} is the server's primary
* thread
*/ */
boolean isPrimaryThread(); boolean isPrimaryThread();
@ -723,16 +753,16 @@ public interface Server extends PluginMessageRecipient {
CachedServerIcon getServerIcon(); CachedServerIcon getServerIcon();
/** /**
* Loads an image from a file, and returns a cached image for the * Loads an image from a file, and returns a cached image for the specific
* specific server-icon. * server-icon.
* <p> * <p>
* Size and type are implementation defined. An incompatible file is * Size and type are implementation defined. An incompatible file is
* guaranteed to throw an implementation-defined {@link Exception}. * guaranteed to throw an implementation-defined {@link Exception}.
* *
* @param file the file to load the from * @param file the file to load the from
* @throws IllegalArgumentException if image is null * @throws IllegalArgumentException if image is null
* @throws Exception if the image does not meet current server * @throws Exception if the image does not meet current server server-icon
* server-icon specifications * specifications
* @return a cached server-icon that can be used for a {@link * @return a cached server-icon that can be used for a {@link
* ServerListPingEvent#setServerIcon(CachedServerIcon)} * ServerListPingEvent#setServerIcon(CachedServerIcon)}
*/ */

6
paper-api/src/main/java/org/bukkit/Sound.java
View File

@ -3,8 +3,10 @@ package org.bukkit;
/** /**
* An Enum of Sounds the server is able to send to players. * An Enum of Sounds the server is able to send to players.
* <p> * <p>
* WARNING: At any time, sounds may be added/removed from this Enum or even MineCraft itself! There is no guarantee the sounds will play. * WARNING: At any time, sounds may be added/removed from this Enum or even
* There is no guarantee values will not be removed from this Enum. As such, you should not depend on the ordinal values of this class. * MineCraft itself! There is no guarantee the sounds will play. There is no
* guarantee values will not be removed from this Enum. As such, you should
* not depend on the ordinal values of this class.
*/ */
public enum Sound { public enum Sound {
AMBIENCE_CAVE, AMBIENCE_CAVE,

6
paper-api/src/main/java/org/bukkit/Statistic.java
View File

@ -33,7 +33,8 @@ public enum Statistic {
/** /**
* Checks if this is a substatistic. * Checks if this is a substatistic.
* <p> * <p>
* A substatistic exists in mass for each block or item, depending on {@link #isBlock()} * A substatistic exists in mass for each block or item, depending on
* {@link #isBlock()}
* *
* @return true if this is a substatistic * @return true if this is a substatistic
*/ */
@ -42,7 +43,8 @@ public enum Statistic {
} }
/** /**
* Checks if this is a substatistic dealing with blocks (As opposed to items) * Checks if this is a substatistic dealing with blocks (As opposed to
* items)
* *
* @return true if this deals with blocks, false if with items * @return true if this deals with blocks, false if with items
*/ */

4
paper-api/src/main/java/org/bukkit/TreeSpecies.java
View File

@ -57,8 +57,8 @@ public enum TreeSpecies {
* Gets the TreeSpecies with the given data value * Gets the TreeSpecies with the given data value
* *
* @param data Data value to fetch * @param data Data value to fetch
* @return The {@link TreeSpecies} representing the given value, or null if * @return The {@link TreeSpecies} representing the given value, or null
* it doesn't exist * if it doesn't exist
* @deprecated Magic value * @deprecated Magic value
*/ */
@Deprecated @Deprecated

7
paper-api/src/main/java/org/bukkit/Utility.java
View File

@ -6,8 +6,11 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target; import java.lang.annotation.Target;
/** /**
* This annotation indicates a method (and sometimes constructor) will chain its internal operations. * This annotation indicates a method (and sometimes constructor) will chain
* This is solely meant for identifying methods that don't need to be overridden / handled manually. * its internal operations.
* <p>
* This is solely meant for identifying methods that don't need to be
* overridden / handled manually.
*/ */
@Target({ElementType.CONSTRUCTOR, ElementType.METHOD}) @Target({ElementType.CONSTRUCTOR, ElementType.METHOD})
@Retention(RetentionPolicy.SOURCE) @Retention(RetentionPolicy.SOURCE)

28
paper-api/src/main/java/org/bukkit/Warning.java
View File

@ -10,7 +10,9 @@ import com.google.common.collect.ImmutableMap;
/** /**
* This designates the warning state for a specific item. * This designates the warning state for a specific item.
* When the server settings dictate 'default' warnings, warnings are printed if the {@link #value()} is true. * <p>
* When the server settings dictate 'default' warnings, warnings are printed
* if the {@link #value()} is true.
*/ */
@Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.TYPE}) @Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME) @Retention(RetentionPolicy.RUNTIME)
@ -30,7 +32,8 @@ public @interface Warning {
*/ */
OFF, OFF,
/** /**
* Indicates each warning would default to the configured {@link Warning} annotation, or always if annotation not found. * Indicates each warning would default to the configured {@link
* Warning} annotation, or always if annotation not found.
*/ */
DEFAULT; DEFAULT;
@ -51,12 +54,16 @@ public @interface Warning {
.build(); .build();
/** /**
* This method checks the provided warning should be printed for this state * This method checks the provided warning should be printed for this
* state
* *
* @param warning The warning annotation added to a deprecated item * @param warning The warning annotation added to a deprecated item
* @return ON is always True<br> * @return <ul>
* OFF is always false<br> * <li>ON is always True
* DEFAULT is false if and only if annotation is not null and specifies false for {@link Warning#value()}, true otherwise. * <li>OFF is always false
* <li>DEFAULT is false if and only if annotation is not null and
* specifies false for {@link Warning#value()}, true otherwise.
* </ul>
*/ */
public boolean printFor(Warning warning) { public boolean printFor(Warning warning) {
if (this == DEFAULT) { if (this == DEFAULT) {
@ -66,10 +73,12 @@ public @interface Warning {
} }
/** /**
* This method returns the corresponding warning state for the given string value. * This method returns the corresponding warning state for the given
* string value.
* *
* @param value The string value to check * @param value The string value to check
* @return {@link #DEFAULT} if not found, or the respective WarningState * @return {@link #DEFAULT} if not found, or the respective
* WarningState
*/ */
public static WarningState value(final String value) { public static WarningState value(final String value) {
if (value == null) { if (value == null) {
@ -84,7 +93,8 @@ public @interface Warning {
} }
/** /**
* This sets if the deprecation warnings when registering events gets printed when the setting is in the default state. * This sets if the deprecation warnings when registering events gets
* printed when the setting is in the default state.
* *
* @return false normally, or true to encourage warning printout * @return false normally, or true to encourage warning printout
*/ */

1
paper-api/src/main/java/org/bukkit/WeatherType.java
View File

@ -4,6 +4,7 @@ package org.bukkit;
* An enum of all current weather types * An enum of all current weather types
*/ */
public enum WeatherType { public enum WeatherType {
/** /**
* Raining or snowing depending on biome. * Raining or snowing depending on biome.
*/ */

274
paper-api/src/main/java/org/bukkit/World.java
View File

@ -29,7 +29,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param y Y-coordinate of the block * @param y Y-coordinate of the block
* @param z Z-coordinate of the block * @param z Z-coordinate of the block
* @return Block at the given coordinates * @return Block at the given coordinates
* @see #getBlockTypeIdAt(int, int, int) Returns the current type ID of the block * @see #getBlockTypeIdAt(int, int, int) Returns the current type ID of
* the block
*/ */
public Block getBlockAt(int x, int y, int z); public Block getBlockAt(int x, int y, int z);
@ -38,7 +39,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* *
* @param location Location of the block * @param location Location of the block
* @return Block at the given location * @return Block at the given location
* @see #getBlockTypeIdAt(org.bukkit.Location) Returns the current type ID of the block * @see #getBlockTypeIdAt(org.bukkit.Location) Returns the current type ID
* of the block
*/ */
public Block getBlockAt(Location location); public Block getBlockAt(Location location);
@ -49,7 +51,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param y Y-coordinate of the block * @param y Y-coordinate of the block
* @param z Z-coordinate of the block * @param z Z-coordinate of the block
* @return Type ID of the block at the given coordinates * @return Type ID of the block at the given coordinates
* @see #getBlockAt(int, int, int) Returns a live Block object at the given location * @see #getBlockAt(int, int, int) Returns a live Block object at the
* given location
* @deprecated Magic value * @deprecated Magic value
*/ */
@Deprecated @Deprecated
@ -60,7 +63,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* *
* @param location Location of the block * @param location Location of the block
* @return Type ID of the block at the given location * @return Type ID of the block at the given location
* @see #getBlockAt(org.bukkit.Location) Returns a live Block object at the given location * @see #getBlockAt(org.bukkit.Location) Returns a live Block object at
* the given location
* @deprecated Magic value * @deprecated Magic value
*/ */
@Deprecated @Deprecated
@ -157,11 +161,13 @@ public interface World extends PluginMessageRecipient, Metadatable {
public boolean isChunkLoaded(int x, int z); public boolean isChunkLoaded(int x, int z);
/** /**
* Checks if the {@link Chunk} at the specified coordinates is loaded and in use by one or more players * Checks if the {@link Chunk} at the specified coordinates is loaded and
* in use by one or more players
* *
* @param x X-coordinate of the chunk * @param x X-coordinate of the chunk
* @param z Z-coordinate of the chunk * @param z Z-coordinate of the chunk
* @return true if the chunk is loaded and in use by one or more players, otherwise false * @return true if the chunk is loaded and in use by one or more players,
* otherwise false
*/ */
public boolean isChunkInUse(int x, int z); public boolean isChunkInUse(int x, int z);
@ -169,7 +175,9 @@ public interface World extends PluginMessageRecipient, Metadatable {
* Loads the {@link Chunk} at the specified coordinates * Loads the {@link Chunk} at the specified coordinates
* <p> * <p>
* If the chunk does not exist, it will be generated. * If the chunk does not exist, it will be generated.
* This method is analogous to {@link #loadChunk(int, int, boolean)} where generate is true. * <p>
* This method is analogous to {@link #loadChunk(int, int, boolean)} where
* generate is true.
* *
* @param x X-coordinate of the chunk * @param x X-coordinate of the chunk
* @param z Z-coordinate of the chunk * @param z Z-coordinate of the chunk
@ -181,7 +189,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* *
* @param x X-coordinate of the chunk * @param x X-coordinate of the chunk
* @param z Z-coordinate of the chunk * @param z Z-coordinate of the chunk
* @param generate Whether or not to generate a chunk if it doesn't already exist * @param generate Whether or not to generate a chunk if it doesn't
* already exist
* @return true if the chunk has loaded successfully, otherwise false * @return true if the chunk has loaded successfully, otherwise false
*/ */
public boolean loadChunk(int x, int z, boolean generate); public boolean loadChunk(int x, int z, boolean generate);
@ -189,7 +198,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
/** /**
* Safely unloads and saves the {@link Chunk} at the specified coordinates * Safely unloads and saves the {@link Chunk} at the specified coordinates
* <p> * <p>
* This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where safe and saveis true * This method is analogous to {@link #unloadChunk(int, int, boolean,
* boolean)} where safe and saveis true
* *
* @param chunk the chunk to unload * @param chunk the chunk to unload
* @return true if the chunk has unloaded successfully, otherwise false * @return true if the chunk has unloaded successfully, otherwise false
@ -199,7 +209,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
/** /**
* Safely unloads and saves the {@link Chunk} at the specified coordinates * Safely unloads and saves the {@link Chunk} at the specified coordinates
* <p> * <p>
* This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where safe and saveis true * This method is analogous to {@link #unloadChunk(int, int, boolean,
* boolean)} where safe and saveis true
* *
* @param x X-coordinate of the chunk * @param x X-coordinate of the chunk
* @param z Z-coordinate of the chunk * @param z Z-coordinate of the chunk
@ -208,9 +219,11 @@ public interface World extends PluginMessageRecipient, Metadatable {
public boolean unloadChunk(int x, int z); public boolean unloadChunk(int x, int z);
/** /**
* Safely unloads and optionally saves the {@link Chunk} at the specified coordinates * Safely unloads and optionally saves the {@link Chunk} at the specified
* coordinates
* <p> * <p>
* This method is analogous to {@link #unloadChunk(int, int, boolean, boolean)} where save is true * This method is analogous to {@link #unloadChunk(int, int, boolean,
* boolean)} where save is true
* *
* @param x X-coordinate of the chunk * @param x X-coordinate of the chunk
* @param z Z-coordinate of the chunk * @param z Z-coordinate of the chunk
@ -220,20 +233,24 @@ public interface World extends PluginMessageRecipient, Metadatable {
public boolean unloadChunk(int x, int z, boolean save); public boolean unloadChunk(int x, int z, boolean save);
/** /**
* Unloads and optionally saves the {@link Chunk} at the specified coordinates * Unloads and optionally saves the {@link Chunk} at the specified
* coordinates
* *
* @param x X-coordinate of the chunk * @param x X-coordinate of the chunk
* @param z Z-coordinate of the chunk * @param z Z-coordinate of the chunk
* @param save Controls whether the chunk is saved * @param save Controls whether the chunk is saved
* @param safe Controls whether to unload the chunk when players are nearby * @param safe Controls whether to unload the chunk when players are
* nearby
* @return true if the chunk has unloaded successfully, otherwise false * @return true if the chunk has unloaded successfully, otherwise false
*/ */
public boolean unloadChunk(int x, int z, boolean save, boolean safe); public boolean unloadChunk(int x, int z, boolean save, boolean safe);
/** /**
* Safely queues the {@link Chunk} at the specified coordinates for unloading * Safely queues the {@link Chunk} at the specified coordinates for
* unloading
* <p> * <p>
* This method is analogous to {@link #unloadChunkRequest(int, int, boolean)} where safe is true * This method is analogous to {@link #unloadChunkRequest(int, int,
* boolean)} where safe is true
* *
* @param x X-coordinate of the chunk * @param x X-coordinate of the chunk
* @param z Z-coordinate of the chunk * @param z Z-coordinate of the chunk
@ -312,7 +329,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* *
* @param loc Location to spawn the tree * @param loc Location to spawn the tree
* @param type Type of the tree to create * @param type Type of the tree to create
* @param delegate A class to call for each block changed as a result of this method * @param delegate A class to call for each block changed as a result of
* this method
* @return true if the tree was created successfully, otherwise false * @return true if the tree was created successfully, otherwise false
*/ */
public boolean generateTree(Location loc, TreeType type, BlockChangeDelegate delegate); public boolean generateTree(Location loc, TreeType type, BlockChangeDelegate delegate);
@ -331,8 +349,10 @@ public interface World extends PluginMessageRecipient, Metadatable {
* *
* @param loc The location to spawn the creature * @param loc The location to spawn the creature
* @param type The creature to spawn * @param type The creature to spawn
* @return Resulting LivingEntity of this method, or null if it was unsuccessful * @return Resulting LivingEntity of this method, or null if it was
* @deprecated Has issues spawning non LivingEntities. Use {@link #spawnEntity(Location, EntityType) spawnEntity} instead. * unsuccessful
* @deprecated Has issues spawning non LivingEntities. Use {@link
* #spawnEntity(Location, EntityType) spawnEntity} instead.
*/ */
@Deprecated @Deprecated
public LivingEntity spawnCreature(Location loc, EntityType type); public LivingEntity spawnCreature(Location loc, EntityType type);
@ -342,7 +362,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
* *
* @param loc The location to spawn the creature * @param loc The location to spawn the creature
* @param type The creature to spawn * @param type The creature to spawn
* @return Resulting LivingEntity of this method, or null if it was unsuccessful * @return Resulting LivingEntity of this method, or null if it was
* unsuccessful
*/ */
@Deprecated @Deprecated
public LivingEntity spawnCreature(Location loc, CreatureType type); public LivingEntity spawnCreature(Location loc, CreatureType type);
@ -378,27 +399,33 @@ public interface World extends PluginMessageRecipient, Metadatable {
public List<LivingEntity> getLivingEntities(); public List<LivingEntity> getLivingEntities();
/** /**
* Get a collection of all entities in this World matching the given class/interface * Get a collection of all entities in this World matching the given
* class/interface
* *
* @param classes The classes representing the types of entity to match * @param classes The classes representing the types of entity to match
* @return A List of all Entities currently residing in this world that match the given class/interface * @return A List of all Entities currently residing in this world that
* match the given class/interface
*/ */
@Deprecated @Deprecated
public <T extends Entity> Collection<T> getEntitiesByClass(Class<T>... classes); public <T extends Entity> Collection<T> getEntitiesByClass(Class<T>... classes);
/** /**
* Get a collection of all entities in this World matching the given class/interface * Get a collection of all entities in this World matching the given
* class/interface
* *
* @param cls The class representing the type of entity to match * @param cls The class representing the type of entity to match
* @return A List of all Entities currently residing in this world that match the given class/interface * @return A List of all Entities currently residing in this world that
* match the given class/interface
*/ */
public <T extends Entity> Collection<T> getEntitiesByClass(Class<T> cls); public <T extends Entity> Collection<T> getEntitiesByClass(Class<T> cls);
/** /**
* Get a collection of all entities in this World matching any of the given classes/interfaces * Get a collection of all entities in this World matching any of the
* given classes/interfaces
* *
* @param classes The classes representing the types of entity to match * @param classes The classes representing the types of entity to match
* @return A List of all Entities currently residing in this world that match one or more of the given classes/interfaces * @return A List of all Entities currently residing in this world that
* match one or more of the given classes/interfaces
*/ */
public Collection<Entity> getEntitiesByClasses(Class<?>... classes); public Collection<Entity> getEntitiesByClasses(Class<?>... classes);
@ -455,11 +482,12 @@ public interface World extends PluginMessageRecipient, Metadatable {
* <p> * <p>
* The relative time is analogous to hours * 1000 * The relative time is analogous to hours * 1000
* <p> * <p>
* Note that setting the relative time below the current relative time will * Note that setting the relative time below the current relative time
* actually move the clock forward a day. If you require to rewind time, please * will actually move the clock forward a day. If you require to rewind
* see setFullTime * time, please see {@link #setFullTime()}
* *
* @param time The new relative time to set the in-game time to (in hours*1000) * @param time The new relative time to set the in-game time to (in
* hours*1000)
* @see #setFullTime(long) Sets the absolute time of this world * @see #setFullTime(long) Sets the absolute time of this world
*/ */
public void setTime(long time); public void setTime(long time);
@ -552,8 +580,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
public boolean createExplosion(double x, double y, double z, float power); public boolean createExplosion(double x, double y, double z, float power);
/** /**
* Creates explosion at given coordinates with given power and optionally setting * Creates explosion at given coordinates with given power and optionally
* blocks on fire. * setting blocks on fire.
* *
* @param x X coordinate * @param x X coordinate
* @param y Y coordinate * @param y Y coordinate
@ -565,8 +593,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
public boolean createExplosion(double x, double y, double z, float power, boolean setFire); public boolean createExplosion(double x, double y, double z, float power, boolean setFire);
/** /**
* Creates explosion at given coordinates with given power and optionally setting * Creates explosion at given coordinates with given power and optionally
* blocks on fire or breaking blocks. * setting blocks on fire or breaking blocks.
* *
* @param x X coordinate * @param x X coordinate
* @param y Y coordinate * @param y Y coordinate
@ -588,8 +616,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
public boolean createExplosion(Location loc, float power); public boolean createExplosion(Location loc, float power);
/** /**
* Creates explosion at given coordinates with given power and optionally setting * Creates explosion at given coordinates with given power and optionally
* blocks on fire. * setting blocks on fire.
* *
* @param loc Location to blow up * @param loc Location to blow up
* @param power The power of explosion, where 4F is TNT * @param power The power of explosion, where 4F is TNT
@ -652,41 +680,48 @@ public interface World extends PluginMessageRecipient, Metadatable {
* @param clazz the class of the {@link Entity} to spawn * @param clazz the class of the {@link Entity} to spawn
* @param <T> the class of the {@link Entity} to spawn * @param <T> the class of the {@link Entity} to spawn
* @return an instance of the spawned {@link Entity} * @return an instance of the spawned {@link Entity}
* @throws IllegalArgumentException if either parameter is null or the {@link Entity} requested cannot be spawned * @throws IllegalArgumentException if either parameter is null or the
* {@link Entity} requested cannot be spawned
*/ */
public <T extends Entity> T spawn(Location location, Class<T> clazz) throws IllegalArgumentException; public <T extends Entity> T spawn(Location location, Class<T> clazz) throws IllegalArgumentException;
/** /**
* Spawn a {@link FallingBlock} entity at the given {@link Location} of the specified {@link Material}. * Spawn a {@link FallingBlock} entity at the given {@link Location} of
* The material dictates what is falling. When the FallingBlock hits the ground, it will place that block. * the specified {@link Material}. The material dictates what is falling.
* When the FallingBlock hits the ground, it will place that block.
* <p> * <p>
* The Material must be a block type, check with {@link Material#isBlock() material.isBlock()}. * The Material must be a block type, check with {@link Material#isBlock()
* The Material may not be air. * material.isBlock()}. The Material may not be air.
* *
* @param location The {@link Location} to spawn the FallingBlock * @param location The {@link Location} to spawn the FallingBlock
* @param material The block {@link Material} type * @param material The block {@link Material} type
* @param data The block data * @param data The block data
* @return The spawned {@link FallingBlock} instance * @return The spawned {@link FallingBlock} instance
* @throws IllegalArgumentException if {@link Location} or {@link Material} are null or {@link Material} is not a block * @throws IllegalArgumentException if {@link Location} or {@link
* Material} are null or {@link Material} is not a block
*/ */
public FallingBlock spawnFallingBlock(Location location, Material material, byte data) throws IllegalArgumentException; public FallingBlock spawnFallingBlock(Location location, Material material, byte data) throws IllegalArgumentException;
/** /**
* Spawn a {@link FallingBlock} entity at the given {@link Location} of the specified blockId (converted to {@link Material}) * Spawn a {@link FallingBlock} entity at the given {@link Location} of
* the specified blockId (converted to {@link Material})
* *
* @param location The {@link Location} to spawn the FallingBlock * @param location The {@link Location} to spawn the FallingBlock
* @param blockId The id of the intended material * @param blockId The id of the intended material
* @param blockData The block data * @param blockData The block data
* @return The spawned FallingBlock instance * @return The spawned FallingBlock instance
* @throws IllegalArgumentException if location is null, or blockId is invalid * @throws IllegalArgumentException if location is null, or blockId is
* invalid
* @see #spawnFallingBlock(org.bukkit.Location, org.bukkit.Material, byte) * @see #spawnFallingBlock(org.bukkit.Location, org.bukkit.Material, byte)
*/ */
public FallingBlock spawnFallingBlock(Location location, int blockId, byte blockData) throws IllegalArgumentException; public FallingBlock spawnFallingBlock(Location location, int blockId, byte blockData) throws IllegalArgumentException;
/** /**
* Plays an effect to all players within a default radius around a given location. * Plays an effect to all players within a default radius around a given
* location.
* *
* @param location the {@link Location} around which players must be to hear the sound * @param location the {@link Location} around which players must be to
* hear the sound
* @param effect the {@link Effect} * @param effect the {@link Effect}
* @param data a data bit needed for some effects * @param data a data bit needed for some effects
*/ */
@ -695,7 +730,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
/** /**
* Plays an effect to all players within a given radius around a location. * Plays an effect to all players within a given radius around a location.
* *
* @param location the {@link Location} around which players must be to hear the effect * @param location the {@link Location} around which players must be to
* hear the effect
* @param effect the {@link Effect} * @param effect the {@link Effect}
* @param data a data bit needed for some effects * @param data a data bit needed for some effects
* @param radius the radius around the location * @param radius the radius around the location
@ -703,9 +739,11 @@ public interface World extends PluginMessageRecipient, Metadatable {
public void playEffect(Location location, Effect effect, int data, int radius); public void playEffect(Location location, Effect effect, int data, int radius);
/** /**
* Plays an effect to all players within a default radius around a given location. * Plays an effect to all players within a default radius around a given
* location.
* *
* @param location the {@link Location} around which players must be to hear the sound * @param location the {@link Location} around which players must be to
* hear the sound
* @param effect the {@link Effect} * @param effect the {@link Effect}
* @param data a data bit needed for some effects * @param data a data bit needed for some effects
*/ */
@ -714,7 +752,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
/** /**
* Plays an effect to all players within a given radius around a location. * Plays an effect to all players within a given radius around a location.
* *
* @param location the {@link Location} around which players must be to hear the effect * @param location the {@link Location} around which players must be to
* hear the effect
* @param effect the {@link Effect} * @param effect the {@link Effect}
* @param data a data bit needed for some effects * @param data a data bit needed for some effects
* @param radius the radius around the location * @param radius the radius around the location
@ -722,13 +761,16 @@ public interface World extends PluginMessageRecipient, Metadatable {
public <T> void playEffect(Location location, Effect effect, T data, int radius); public <T> void playEffect(Location location, Effect effect, T data, int radius);
/** /**
* Get empty chunk snapshot (equivalent to all air blocks), optionally including valid biome * Get empty chunk snapshot (equivalent to all air blocks), optionally
* data. Used for representing an ungenerated chunk, or for fetching only biome data without loading a chunk. * including valid biome data. Used for representing an ungenerated chunk,
* or for fetching only biome data without loading a chunk.
* *
* @param x - chunk x coordinate * @param x - chunk x coordinate
* @param z - chunk z coordinate * @param z - chunk z coordinate
* @param includeBiome - if true, snapshot includes per-coordinate biome type * @param includeBiome - if true, snapshot includes per-coordinate biome
* @param includeBiomeTempRain - if true, snapshot includes per-coordinate raw biome temperature and rainfall * type
* @param includeBiomeTempRain - if true, snapshot includes per-coordinate
* raw biome temperature and rainfall
* @return The empty snapshot. * @return The empty snapshot.
*/ */
public ChunkSnapshot getEmptyChunkSnapshot(int x, int z, boolean includeBiome, boolean includeBiomeTempRain); public ChunkSnapshot getEmptyChunkSnapshot(int x, int z, boolean includeBiome, boolean includeBiomeTempRain);
@ -736,8 +778,10 @@ public interface World extends PluginMessageRecipient, Metadatable {
/** /**
* Sets the spawn flags for this. * Sets the spawn flags for this.
* *
* @param allowMonsters - if true, monsters are allowed to spawn in this world. * @param allowMonsters - if true, monsters are allowed to spawn in this
* @param allowAnimals - if true, animals are allowed to spawn in this world. * world.
* @param allowAnimals - if true, animals are allowed to spawn in this
* world.
*/ */
public void setSpawnFlags(boolean allowMonsters, boolean allowAnimals); public void setSpawnFlags(boolean allowMonsters, boolean allowAnimals);
@ -776,7 +820,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
/** /**
* Gets the temperature for the given block coordinates. * Gets the temperature for the given block coordinates.
* <p> * <p>
* It is safe to run this method when the block does not exist, it will not create the block. * It is safe to run this method when the block does not exist, it will
* not create the block.
* *
* @param x X coordinate of the block * @param x X coordinate of the block
* @param z Z coordinate of the block * @param z Z coordinate of the block
@ -787,7 +832,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
/** /**
* Gets the humidity for the given block coordinates. * Gets the humidity for the given block coordinates.
* <p> * <p>
* It is safe to run this method when the block does not exist, it will not create the block. * It is safe to run this method when the block does not exist, it will
* not create the block.
* *
* @param x X coordinate of the block * @param x X coordinate of the block
* @param z Z coordinate of the block * @param z Z coordinate of the block
@ -814,16 +860,19 @@ public interface World extends PluginMessageRecipient, Metadatable {
public int getSeaLevel(); public int getSeaLevel();
/** /**
* Gets whether the world's spawn area should be kept loaded into memory or not. * Gets whether the world's spawn area should be kept loaded into memory
* or not.
* *
* @return true if the world's spawn area will be kept loaded into memory. * @return true if the world's spawn area will be kept loaded into memory.
*/ */
public boolean getKeepSpawnInMemory(); public boolean getKeepSpawnInMemory();
/** /**
* Sets whether the world's spawn area should be kept loaded into memory or not. * Sets whether the world's spawn area should be kept loaded into memory
* or not.
* *
* @param keepLoaded if true then the world's spawn area will be kept loaded into memory. * @param keepLoaded if true then the world's spawn area will be kept
* loaded into memory.
*/ */
public void setKeepSpawnInMemory(boolean keepLoaded); public void setKeepSpawnInMemory(boolean keepLoaded);
@ -837,7 +886,8 @@ public interface World extends PluginMessageRecipient, Metadatable {
/** /**
* Sets whether or not the world will automatically save * Sets whether or not the world will automatically save
* *
* @param value true if the world should automatically save, otherwise false * @param value true if the world should automatically save, otherwise
* false
*/ */
public void setAutoSave(boolean value); public void setAutoSave(boolean value);
@ -879,17 +929,22 @@ public interface World extends PluginMessageRecipient, Metadatable {
/** /**
* Gets the world's ticks per animal spawns value * Gets the world's ticks per animal spawns value
* <p> * <p>
* This value determines how many ticks there are between attempts to spawn animals. * This value determines how many ticks there are between attempts to
* spawn animals.
* <p> * <p>
* <b>Example Usage:</b> * <b>Example Usage:</b>
* <ul> * <ul>
* <li>A value of 1 will mean the server will attempt to spawn animals in this world every tick. * <li>A value of 1 will mean the server will attempt to spawn animals in
* <li>A value of 400 will mean the server will attempt to spawn animals in this world every 400th tick. * this world every tick.
* <li>A value of 400 will mean the server will attempt to spawn animals
* in this world every 400th tick.
* <li>A value below 0 will be reset back to Minecraft's default. * <li>A value below 0 will be reset back to Minecraft's default.
* </ul> * </ul>
* <p> * <p>
* <b>Note:</b> * <b>Note:</b>
* If set to 0, animal spawning will be disabled for this world. We recommend using {@link #setSpawnFlags(boolean, boolean)} to control this instead. * If set to 0, animal spawning will be disabled for this world. We
* recommend using {@link #setSpawnFlags(boolean, boolean)} to control
* this instead.
* <p> * <p>
* Minecraft default: 400. * Minecraft default: 400.
* *
@ -900,38 +955,49 @@ public interface World extends PluginMessageRecipient, Metadatable {
/** /**
* Sets the world's ticks per animal spawns value * Sets the world's ticks per animal spawns value
* <p> * <p>
* This value determines how many ticks there are between attempts to spawn animals. * This value determines how many ticks there are between attempts to
* spawn animals.
* <p> * <p>
* <b>Example Usage:</b> * <b>Example Usage:</b>
* <ul> * <ul>
* <li>A value of 1 will mean the server will attempt to spawn animals in this world every tick. * <li>A value of 1 will mean the server will attempt to spawn animals in
* <li>A value of 400 will mean the server will attempt to spawn animals in this world every 400th tick. * this world every tick.
* <li>A value of 400 will mean the server will attempt to spawn animals
* in this world every 400th tick.
* <li>A value below 0 will be reset back to Minecraft's default. * <li>A value below 0 will be reset back to Minecraft's default.
* </ul> * </ul>
* <p> * <p>
* <b>Note:</b> * <b>Note:</b>
* If set to 0, animal spawning will be disabled for this world. We recommend using {@link #setSpawnFlags(boolean, boolean)} to control this instead. * If set to 0, animal spawning will be disabled for this world. We
* recommend using {@link #setSpawnFlags(boolean, boolean)} to control
* this instead.
* <p> * <p>
* Minecraft default: 400. * Minecraft default: 400.
* *
* @param ticksPerAnimalSpawns the ticks per animal spawns value you want to set the world to * @param ticksPerAnimalSpawns the ticks per animal spawns value you want
* to set the world to
*/ */
public void setTicksPerAnimalSpawns(int ticksPerAnimalSpawns); public void setTicksPerAnimalSpawns(int ticksPerAnimalSpawns);
/** /**
* Gets the world's ticks per monster spawns value * Gets the world's ticks per monster spawns value
* <p> * <p>
* This value determines how many ticks there are between attempts to spawn monsters. * This value determines how many ticks there are between attempts to
* spawn monsters.
* <p> * <p>
* <b>Example Usage:</b> * <b>Example Usage:</b>
* <ul> * <ul>
* <li>A value of 1 will mean the server will attempt to spawn monsters in this world every tick. * <li>A value of 1 will mean the server will attempt to spawn monsters in
* <li>A value of 400 will mean the server will attempt to spawn monsters in this world every 400th tick. * this world every tick.
* <li>A value of 400 will mean the server will attempt to spawn monsters
* in this world every 400th tick.
* <li>A value below 0 will be reset back to Minecraft's default. * <li>A value below 0 will be reset back to Minecraft's default.
* </ul> * </ul>
* <p> * <p>
* <b>Note:</b> * <b>Note:</b>
* If set to 0, monsters spawning will be disabled for this world. We recommend using {@link #setSpawnFlags(boolean, boolean)} to control this instead. * If set to 0, monsters spawning will be disabled for this world. We
* recommend using {@link #setSpawnFlags(boolean, boolean)} to control
* this instead.
* <p> * <p>
* Minecraft default: 1. * Minecraft default: 1.
* *
@ -942,80 +1008,95 @@ public interface World extends PluginMessageRecipient, Metadatable {
/** /**
* Sets the world's ticks per monster spawns value * Sets the world's ticks per monster spawns value
* <p> * <p>
* This value determines how many ticks there are between attempts to spawn monsters. * This value determines how many ticks there are between attempts to
* spawn monsters.
* <p> * <p>
* <b>Example Usage:</b> * <b>Example Usage:</b>
* <ul> * <ul>
* <li>A value of 1 will mean the server will attempt to spawn monsters in this world on every tick. * <li>A value of 1 will mean the server will attempt to spawn monsters in
* <li>A value of 400 will mean the server will attempt to spawn monsters in this world every 400th tick. * this world on every tick.
* <li>A value of 400 will mean the server will attempt to spawn monsters
* in this world every 400th tick.
* <li>A value below 0 will be reset back to Minecraft's default. * <li>A value below 0 will be reset back to Minecraft's default.
* </ul> * </ul>
* <p> * <p>
* <b>Note:</b> * <b>Note:</b>
* If set to 0, monsters spawning will be disabled for this world. We recommend using {@link #setSpawnFlags(boolean, boolean)} to control this instead. * If set to 0, monsters spawning will be disabled for this world. We
* recommend using {@link #setSpawnFlags(boolean, boolean)} to control
* this instead.
* <p> * <p>
* Minecraft default: 1. * Minecraft default: 1.
* *
* @param ticksPerMonsterSpawns the ticks per monster spawns value you want to set the world to * @param ticksPerMonsterSpawns the ticks per monster spawns value you
* want to set the world to
*/ */
public void setTicksPerMonsterSpawns(int ticksPerMonsterSpawns); public void setTicksPerMonsterSpawns(int ticksPerMonsterSpawns);
/** /**
* Gets limit for number of monsters that can spawn in a chunk in this world * Gets limit for number of monsters that can spawn in a chunk in this
* world
*
* @return The monster spawn limit * @return The monster spawn limit
*/ */
int getMonsterSpawnLimit(); int getMonsterSpawnLimit();
/** /**
* Sets the limit for number of monsters that can spawn in a chunk in this world * Sets the limit for number of monsters that can spawn in a chunk in this
* world
* <p> * <p>
* <b>Note:</b> * <b>Note:</b> If set to a negative number the world will use the
* If set to a negative number the world will use the server-wide spawn limit instead. * server-wide spawn limit instead.
*/ */
void setMonsterSpawnLimit(int limit); void setMonsterSpawnLimit(int limit);
/** /**
* Gets the limit for number of animals that can spawn in a chunk in this world * Gets the limit for number of animals that can spawn in a chunk in this
* world
* *
* @return The animal spawn limit * @return The animal spawn limit
*/ */
int getAnimalSpawnLimit(); int getAnimalSpawnLimit();
/** /**
* Sets the limit for number of animals that can spawn in a chunk in this world * Sets the limit for number of animals that can spawn in a chunk in this
* world
* <p> * <p>
* <b>Note:</b> * <b>Note:</b> If set to a negative number the world will use the
* If set to a negative number the world will use the server-wide spawn limit instead. * server-wide spawn limit instead.
*/ */
void setAnimalSpawnLimit(int limit); void setAnimalSpawnLimit(int limit);
/** /**
* Gets the limit for number of water animals that can spawn in a chunk in this world * Gets the limit for number of water animals that can spawn in a chunk in
* this world
* *
* @return The water animal spawn limit * @return The water animal spawn limit
*/ */
int getWaterAnimalSpawnLimit(); int getWaterAnimalSpawnLimit();
/** /**
* Sets the limit for number of water animals that can spawn in a chunk in this world * Sets the limit for number of water animals that can spawn in a chunk in
* this world
* <p> * <p>
* <b>Note:</b> * <b>Note:</b> If set to a negative number the world will use the
* If set to a negative number the world will use the server-wide spawn limit instead. * server-wide spawn limit instead.
*/ */
void setWaterAnimalSpawnLimit(int limit); void setWaterAnimalSpawnLimit(int limit);
/** /**
* Gets the limit for number of ambient mobs that can spawn in a chunk in this world * Gets the limit for number of ambient mobs that can spawn in a chunk in
* this world
* *
* @return The ambient spawn limit * @return The ambient spawn limit
*/ */
int getAmbientSpawnLimit(); int getAmbientSpawnLimit();
/** /**
* Sets the limit for number of ambient mobs that can spawn in a chunk in this world * Sets the limit for number of ambient mobs that can spawn in a chunk in
* this world
* <p> * <p>
* <b>Note:</b> * <b>Note:</b> If set to a negative number the world will use the
* If set to a negative number the world will use the server-wide spawn limit instead. * server-wide spawn limit instead.
*/ */
void setAmbientSpawnLimit(int limit); void setAmbientSpawnLimit(int limit);
@ -1074,6 +1155,7 @@ public interface World extends PluginMessageRecipient, Metadatable {
* Represents various map environment types that a world may be * Represents various map environment types that a world may be
*/ */
public enum Environment { public enum Environment {
/** /**
* Represents the "normal"/"surface world" map * Represents the "normal"/"surface world" map
*/ */

47
paper-api/src/main/java/org/bukkit/WorldCreator.java
View File

@ -141,8 +141,8 @@ public class WorldCreator {
/** /**
* Gets the generator that will be used to create or load the world. * Gets the generator that will be used to create or load the world.
* <p> * <p>
* This may be null, in which case the "natural" generator for this environment * This may be null, in which case the "natural" generator for this
* will be used. * environment will be used.
* *
* @return Chunk generator * @return Chunk generator
*/ */
@ -153,8 +153,8 @@ public class WorldCreator {
/** /**
* Sets the generator that will be used to create or load the world. * Sets the generator that will be used to create or load the world.
* <p> * <p>
* This may be null, in which case the "natural" generator for this environment * This may be null, in which case the "natural" generator for this
* will be used. * environment will be used.
* *
* @param generator Chunk generator * @param generator Chunk generator
* @return This object, for chaining * @return This object, for chaining
@ -168,11 +168,12 @@ public class WorldCreator {
/** /**
* Sets the generator that will be used to create or load the world. * Sets the generator that will be used to create or load the world.
* <p> * <p>
* This may be null, in which case the "natural" generator for this environment * This may be null, in which case the "natural" generator for this
* will be used. * environment will be used.
* <p> * <p>
* If the generator cannot be found for the given name, the natural environment generator * If the generator cannot be found for the given name, the natural
* will be used instead and a warning will be printed to the console. * environment generator will be used instead and a warning will be
* printed to the console.
* *
* @param generator Name of the generator to use, in "plugin:id" notation * @param generator Name of the generator to use, in "plugin:id" notation
* @return This object, for chaining * @return This object, for chaining
@ -186,14 +187,16 @@ public class WorldCreator {
/** /**
* Sets the generator that will be used to create or load the world. * Sets the generator that will be used to create or load the world.
* <p> * <p>
* This may be null, in which case the "natural" generator for this environment * This may be null, in which case the "natural" generator for this
* will be used. * environment will be used.
* <p> * <p>
* If the generator cannot be found for the given name, the natural environment generator * If the generator cannot be found for the given name, the natural
* will be used instead and a warning will be printed to the specified output * environment generator will be used instead and a warning will be
* printed to the specified output
* *
* @param generator Name of the generator to use, in "plugin:id" notation * @param generator Name of the generator to use, in "plugin:id" notation
* @param output {@link CommandSender} that will receive any error messages * @param output {@link CommandSender} that will receive any error
* messages
* @return This object, for chaining * @return This object, for chaining
*/ */
public WorldCreator generator(String generator, CommandSender output) { public WorldCreator generator(String generator, CommandSender output) {
@ -203,7 +206,8 @@ public class WorldCreator {
} }
/** /**
* Sets whether or not worlds created or loaded with this creator will have structures. * Sets whether or not worlds created or loaded with this creator will
* have structures.
* *
* @param generate Whether to generate structures * @param generate Whether to generate structures
* @return This object, for chaining * @return This object, for chaining
@ -226,8 +230,8 @@ public class WorldCreator {
/** /**
* Creates a world with the specified options. * Creates a world with the specified options.
* <p> * <p>
* If the world already exists, it will be loaded from disk and some options * If the world already exists, it will be loaded from disk and some
* may be ignored. * options may be ignored.
* *
* @return Newly created or loaded world * @return Newly created or loaded world
*/ */
@ -248,12 +252,13 @@ public class WorldCreator {
/** /**
* Attempts to get the {@link ChunkGenerator} with the given name. * Attempts to get the {@link ChunkGenerator} with the given name.
* <p> * <p>
* If the generator is not found, null will be returned and a message will be * If the generator is not found, null will be returned and a message will
* printed to the specified {@link CommandSender} explaining why. * be printed to the specified {@link CommandSender} explaining why.
* <p> * <p>
* The name must be in the "plugin:id" notation, or optionally just "plugin", * The name must be in the "plugin:id" notation, or optionally just
* where "plugin" is the safe-name of a plugin and "id" is an optional unique * "plugin", where "plugin" is the safe-name of a plugin and "id" is an
* identifier for the generator you wish to request from the plugin. * optional unique identifier for the generator you wish to request from
* the plugin.
* *
* @param world Name of the world this will be used for * @param world Name of the world this will be used for
* @param name Name of the generator to retrieve * @param name Name of the generator to retrieve

39
paper-api/src/main/java/org/bukkit/block/Block.java
View File

@ -11,9 +11,9 @@ import org.bukkit.metadata.Metadatable;
/** /**
* Represents a block. This is a live object, and only one Block may exist for * Represents a block. This is a live object, and only one Block may exist for
* any given location in a world. The state of the block may change concurrently * any given location in a world. The state of the block may change
* to your own handling of it; use block.getState() to get a snapshot state of a * concurrently to your own handling of it; use block.getState() to get a
* block which will not be modified. * snapshot state of a block which will not be modified.
*/ */
public interface Block extends Metadatable { public interface Block extends Metadatable {
@ -50,8 +50,8 @@ public interface Block extends Metadatable {
/** /**
* Gets the block at the given distance of the given face * Gets the block at the given distance of the given face
* <p> * <p>
* For example, the following method places water at 100,102,100; two blocks * For example, the following method places water at 100,102,100; two
* above 100,100,100. * blocks above 100,100,100.
* *
* <pre> * <pre>
* Block block = world.getBlockAt(100, 100, 100); * Block block = world.getBlockAt(100, 100, 100);
@ -91,7 +91,8 @@ public interface Block extends Metadatable {
/** /**
* Get the amount of light at this block from the sky. * Get the amount of light at this block from the sky.
* <p> * <p>
* Any light given from other sources (such as blocks like torches) will be ignored. * Any light given from other sources (such as blocks like torches) will
* be ignored.
* *
* @return Sky light level * @return Sky light level
*/ */
@ -142,8 +143,10 @@ public interface Block extends Metadatable {
Location getLocation(); Location getLocation();
/** /**
* Stores the location of the block in the provided Location object.<br /> * Stores the location of the block in the provided Location object.
* If the provided Location is null this method does nothing and returns null. * <p>
* If the provided Location is null this method does nothing and returns
* null.
* *
* @return The Location object provided or null * @return The Location object provided or null
*/ */
@ -237,8 +240,8 @@ public interface Block extends Metadatable {
* Captures the current state of this block. You may then cast that state * Captures the current state of this block. You may then cast that state
* into any accepted type, such as Furnace or Sign. * into any accepted type, such as Furnace or Sign.
* <p> * <p>
* The returned object will never be updated, and you are not guaranteed that * The returned object will never be updated, and you are not guaranteed
* (for example) a sign is still a sign after you capture its state. * that (for example) a sign is still a sign after you capture its state.
* *
* @return BlockState with the current state of this block. * @return BlockState with the current state of this block.
*/ */
@ -291,7 +294,8 @@ public interface Block extends Metadatable {
/** /**
* Returns the redstone power being provided to this block face * Returns the redstone power being provided to this block face
* *
* @param face the face of the block to query or BlockFace.SELF for the block itself * @param face the face of the block to query or BlockFace.SELF for the
* block itself
* @return The power level. * @return The power level.
*/ */
int getBlockPower(BlockFace face); int getBlockPower(BlockFace face);
@ -306,7 +310,8 @@ public interface Block extends Metadatable {
/** /**
* Checks if this block is empty. * Checks if this block is empty.
* <p> * <p>
* A block is considered empty when {@link #getType()} returns {@link Material#AIR}. * A block is considered empty when {@link #getType()} returns {@link
* Material#AIR}.
* *
* @return true if this block is empty * @return true if this block is empty
*/ */
@ -315,7 +320,9 @@ public interface Block extends Metadatable {
/** /**
* Checks if this block is liquid. * Checks if this block is liquid.
* <p> * <p>
* A block is considered liquid when {@link #getType()} returns {@link Material#WATER}, {@link Material#STATIONARY_WATER}, {@link Material#LAVA} or {@link Material#STATIONARY_LAVA}. * A block is considered liquid when {@link #getType()} returns {@link
* Material#WATER}, {@link Material#STATIONARY_WATER}, {@link
* Material#LAVA} or {@link Material#STATIONARY_LAVA}.
* *
* @return true if this block is liquid * @return true if this block is liquid
*/ */
@ -350,7 +357,8 @@ public interface Block extends Metadatable {
boolean breakNaturally(); boolean breakNaturally();
/** /**
* Breaks the block and spawns items as if a player had digged it with a specific tool * Breaks the block and spawns items as if a player had digged it with a
* specific tool
* *
* @param tool The tool or item in hand used for digging * @param tool The tool or item in hand used for digging
* @return true if the block was destroyed * @return true if the block was destroyed
@ -365,7 +373,8 @@ public interface Block extends Metadatable {
Collection<ItemStack> getDrops(); Collection<ItemStack> getDrops();
/** /**
* Returns a list of items which would drop by destroying this block with a specific tool * Returns a list of items which would drop by destroying this block with
* a specific tool
* *
* @param tool The tool or item in hand used for digging * @param tool The tool or item in hand used for digging
* @return a list of dropped items for this type of block * @return a list of dropped items for this type of block

50
paper-api/src/main/java/org/bukkit/block/BlockState.java
View File

@ -8,12 +8,13 @@ import org.bukkit.material.MaterialData;
import org.bukkit.metadata.Metadatable; import org.bukkit.metadata.Metadatable;
/** /**
* Represents a captured state of a block, which will not change automatically. * Represents a captured state of a block, which will not change
* automatically.
* <p> * <p>
* Unlike Block, which only one object can exist per coordinate, BlockState can * Unlike Block, which only one object can exist per coordinate, BlockState
* exist multiple times for any given Block. Note that another plugin may change * can exist multiple times for any given Block. Note that another plugin may
* the state of the block and you will not know, or they may change the block to * change the state of the block and you will not know, or they may change the
* another type entirely, causing your BlockState to become invalid. * block to another type entirely, causing your BlockState to become invalid.
*/ */
public interface BlockState extends Metadatable { public interface BlockState extends Metadatable {
@ -90,8 +91,10 @@ public interface BlockState extends Metadatable {
Location getLocation(); Location getLocation();
/** /**
* Stores the location of this block in the provided Location object.<br /> * Stores the location of this block in the provided Location object.
* If the provided Location is null this method does nothing and returns null. * <p>
* If the provided Location is null this method does nothing and returns
* null.
* *
* @return The Location object provided or null * @return The Location object provided or null
*/ */
@ -129,8 +132,8 @@ public interface BlockState extends Metadatable {
boolean setTypeId(int type); boolean setTypeId(int type);
/** /**
* Attempts to update the block represented by this state, setting it to the * Attempts to update the block represented by this state, setting it to
* new values as defined by this state. * the new values as defined by this state.
* <p> * <p>
* This has the same effect as calling update(false). That is to say, * This has the same effect as calling update(false). That is to say,
* this will not modify the state of a block if it is no longer the same * this will not modify the state of a block if it is no longer the same
@ -143,11 +146,11 @@ public interface BlockState extends Metadatable {
boolean update(); boolean update();
/** /**
* Attempts to update the block represented by this state, setting it to the * Attempts to update the block represented by this state, setting it to
* new values as defined by this state. * the new values as defined by this state.
* <p> * <p>
* This has the same effect as calling update(force, true). That is to say, * This has the same effect as calling update(force, true). That is to
* this will trigger a physics update to surrounding blocks. * say, this will trigger a physics update to surrounding blocks.
* *
* @param force true to forcefully set the state * @param force true to forcefully set the state
* @return true if the update was successful, otherwise false * @return true if the update was successful, otherwise false
@ -155,21 +158,22 @@ public interface BlockState extends Metadatable {
boolean update(boolean force); boolean update(boolean force);
/** /**
* Attempts to update the block represented by this state, setting it to the * Attempts to update the block represented by this state, setting it to
* new values as defined by this state. * the new values as defined by this state.
* <p> * <p>
* Unless force is true, this will not modify the state of a block if it is * Unless force is true, this will not modify the state of a block if it
* no longer the same type as it was when this state was taken. It will return * is no longer the same type as it was when this state was taken. It will
* false in this eventuality. * return false in this eventuality.
* <p> * <p>
* If force is true, it will set the type of the block to match the new state, * If force is true, it will set the type of the block to match the new
* set the state data and then return true. * state, set the state data and then return true.
* <p> * <p>
* If applyPhysics is true, it will trigger a physics update on surrounding * If applyPhysics is true, it will trigger a physics update on
* blocks which could cause them to update or disappear. * surrounding blocks which could cause them to update or disappear.
* *
* @param force true to forcefully set the state * @param force true to forcefully set the state
* @param applyPhysics false to cancel updating physics on surrounding blocks * @param applyPhysics false to cancel updating physics on surrounding
* blocks
* @return true if the update was successful, otherwise false * @return true if the update was successful, otherwise false
*/ */
boolean update(boolean force, boolean applyPhysics); boolean update(boolean force, boolean applyPhysics);

4
paper-api/src/main/java/org/bukkit/block/Chest.java
View File

@ -8,8 +8,8 @@ import org.bukkit.inventory.Inventory;
public interface Chest extends BlockState, ContainerBlock { public interface Chest extends BlockState, ContainerBlock {
/** /**
* Returns the chest's inventory. If this is a double chest, it returns just * Returns the chest's inventory. If this is a double chest, it returns
* the portion of the inventory linked to this half of the chest. * just the portion of the inventory linked to this half of the chest.
* *
* @return The inventory. * @return The inventory.
*/ */

1
paper-api/src/main/java/org/bukkit/block/ContainerBlock.java
View File

@ -4,6 +4,7 @@ import org.bukkit.inventory.InventoryHolder;
/** /**
* Indicates a block type that has inventory. * Indicates a block type that has inventory.
*
* @deprecated in favour of {@link InventoryHolder} * @deprecated in favour of {@link InventoryHolder}
*/ */
@Deprecated @Deprecated

3
paper-api/src/main/java/org/bukkit/block/DoubleChest.java
View File

@ -6,6 +6,9 @@ import org.bukkit.inventory.DoubleChestInventory;
import org.bukkit.inventory.Inventory; import org.bukkit.inventory.Inventory;
import org.bukkit.inventory.InventoryHolder; import org.bukkit.inventory.InventoryHolder;
/**
* Represents a double chest.
*/
public class DoubleChest implements InventoryHolder { public class DoubleChest implements InventoryHolder {
private DoubleChestInventory inventory; private DoubleChestInventory inventory;

1
paper-api/src/main/java/org/bukkit/block/PistonMoveReaction.java
View File

@ -4,6 +4,7 @@ import java.util.HashMap;
import java.util.Map; import java.util.Map;
public enum PistonMoveReaction { public enum PistonMoveReaction {
/** /**
* Indicates that the block can be pushed or pulled. * Indicates that the block can be pushed or pulled.
*/ */

47
paper-api/src/main/java/org/bukkit/command/Command.java
View File

@ -64,13 +64,14 @@ public abstract class Command {
} }
/** /**
* Executed on tab completion for this command, returning a list of options * Executed on tab completion for this command, returning a list of
* the player can tab through. * options the player can tab through.
* *
* @param sender Source object which is executing this command * @param sender Source object which is executing this command
* @param alias the alias being used * @param alias the alias being used
* @param args All arguments passed to the command, split via ' ' * @param args All arguments passed to the command, split via ' '
* @return a list of tab-completions for the specified arguments. This will never be null. List may be immutable. * @return a list of tab-completions for the specified arguments. This
* will never be null. List may be immutable.
* @throws IllegalArgumentException if sender, alias, or args is null * @throws IllegalArgumentException if sender, alias, or args is null
*/ */
public List<String> tabComplete(CommandSender sender, String alias, String[] args) throws IllegalArgumentException { public List<String> tabComplete(CommandSender sender, String alias, String[] args) throws IllegalArgumentException {
@ -108,7 +109,8 @@ public abstract class Command {
} }
/** /**
* Gets the permission required by users to be able to perform this command * Gets the permission required by users to be able to perform this
* command
* *
* @return Permission name, or null if none * @return Permission name, or null if none
*/ */
@ -117,7 +119,8 @@ public abstract class Command {
} }
/** /**
* Sets the permission required by users to be able to perform this command * Sets the permission required by users to be able to perform this
* command
* *
* @param permission Permission name or null * @param permission Permission name or null
*/ */
@ -126,9 +129,11 @@ public abstract class Command {
} }
/** /**
* Tests the given {@link CommandSender} to see if they can perform this command. * Tests the given {@link CommandSender} to see if they can perform this
* command.
* <p> * <p>
* If they do not have permission, they will be informed that they cannot do this. * If they do not have permission, they will be informed that they cannot
* do this.
* *
* @param target User to test * @param target User to test
* @return true if they can use it, otherwise false * @return true if they can use it, otherwise false
@ -150,7 +155,8 @@ public abstract class Command {
} }
/** /**
* Tests the given {@link CommandSender} to see if they can perform this command. * Tests the given {@link CommandSender} to see if they can perform this
* command.
* <p> * <p>
* No error is sent to the sender. * No error is sent to the sender.
* *
@ -181,12 +187,14 @@ public abstract class Command {
} }
/** /**
* Sets the label of this command * Sets the label of this command.
* If the command is currently registered the label change will only take effect after * <p>
* its been reregistered e.g. after a /reload * If the command is currently registered the label change will only take
* effect after its been re-registered e.g. after a /reload
* *
* @param name The command's name * @param name The command's name
* @return returns true if the name change happened instantly or false if it was scheduled for reregistration * @return returns true if the name change happened instantly or false if
* it was scheduled for re-registration
*/ */
public boolean setLabel(String name) { public boolean setLabel(String name) {
this.nextLabel = name; this.nextLabel = name;
@ -198,11 +206,12 @@ public abstract class Command {
} }
/** /**
* Registers this command to a CommandMap * Registers this command to a CommandMap.
* Once called it only allows changes the registered CommandMap * Once called it only allows changes the registered CommandMap
* *
* @param commandMap the CommandMap to register this command to * @param commandMap the CommandMap to register this command to
* @return true if the registration was successful (the current registered CommandMap was the passed CommandMap or null) false otherwise * @return true if the registration was successful (the current registered
* CommandMap was the passed CommandMap or null) false otherwise
*/ */
public boolean register(CommandMap commandMap) { public boolean register(CommandMap commandMap) {
if (allowChangesFrom(commandMap)) { if (allowChangesFrom(commandMap)) {
@ -214,10 +223,13 @@ public abstract class Command {
} }
/** /**
* Unregisters this command from the passed CommandMap applying any outstanding changes * Unregisters this command from the passed CommandMap applying any
* outstanding changes
* *
* @param commandMap the CommandMap to unregister * @param commandMap the CommandMap to unregister
* @return true if the unregistration was successfull (the current registered CommandMap was the passed CommandMap or null) false otherwise * @return true if the unregistration was successfull (the current
* registered CommandMap was the passed CommandMap or null) false
* otherwise
*/ */
public boolean unregister(CommandMap commandMap) { public boolean unregister(CommandMap commandMap) {
if (allowChangesFrom(commandMap)) { if (allowChangesFrom(commandMap)) {
@ -253,7 +265,8 @@ public abstract class Command {
} }
/** /**
* Returns a message to be displayed on a failed permission check for this command * Returns a message to be displayed on a failed permission check for this
* command
* *
* @return Permission check failed message * @return Permission check failed message
*/ */

6
paper-api/src/main/java/org/bukkit/command/CommandException.java
View File

@ -7,12 +7,14 @@ package org.bukkit.command;
public class CommandException extends RuntimeException { public class CommandException extends RuntimeException {
/** /**
* Creates a new instance of <code>CommandException</code> without detail message. * Creates a new instance of <code>CommandException</code> without detail
* message.
*/ */
public CommandException() {} public CommandException() {}
/** /**
* Constructs an instance of <code>CommandException</code> with the specified detail message. * Constructs an instance of <code>CommandException</code> with the
* specified detail message.
* *
* @param msg the detail message. * @param msg the detail message.
*/ */

72
paper-api/src/main/java/org/bukkit/command/CommandMap.java
View File

@ -6,37 +6,62 @@ public interface CommandMap {
/** /**
* Registers all the commands belonging to a certain plugin. * Registers all the commands belonging to a certain plugin.
* <p>
* Caller can use:- * Caller can use:-
* command.getName() to determine the label registered for this command * <ul>
* command.getAliases() to determine the aliases which where registered * <li>command.getName() to determine the label registered for this
* command
* <li>command.getAliases() to determine the aliases which where
* registered
* </ul>
* *
* @param fallbackPrefix a prefix which is prepended to each command with a ':' one or more times to make the command unique * @param fallbackPrefix a prefix which is prepended to each command with
* a ':' one or more times to make the command unique
* @param commands a list of commands to register * @param commands a list of commands to register
*/ */
public void registerAll(String fallbackPrefix, List<Command> commands); public void registerAll(String fallbackPrefix, List<Command> commands);
/** /**
* Registers a command. Returns true on success; false if name is already taken and fallback had to be used. * Registers a command. Returns true on success; false if name is already
* taken and fallback had to be used.
* <p>
* Caller can use:- * Caller can use:-
* command.getName() to determine the label registered for this command * <ul>
* command.getAliases() to determine the aliases which where registered * <li>command.getName() to determine the label registered for this
* command
* <li>command.getAliases() to determine the aliases which where
* registered
* </ul>
* *
* @param label the label of the command, without the '/'-prefix. * @param label the label of the command, without the '/'-prefix.
* @param fallbackPrefix a prefix which is prepended to the command with a ':' one or more times to make the command unique * @param fallbackPrefix a prefix which is prepended to the command with a
* ':' one or more times to make the command unique
* @param command the command to register * @param command the command to register
* @return true if command was registered with the passed in label, false otherwise, which indicates the fallbackPrefix was used one or more times * @return true if command was registered with the passed in label, false
* otherwise, which indicates the fallbackPrefix was used one or more
* times
*/ */
public boolean register(String label, String fallbackPrefix, Command command); public boolean register(String label, String fallbackPrefix, Command command);
/** /**
* Registers a command. Returns true on success; false if name is already taken and fallback had to be used. * Registers a command. Returns true on success; false if name is already
* taken and fallback had to be used.
* <p>
* Caller can use:- * Caller can use:-
* command.getName() to determine the label registered for this command * <ul>
* command.getAliases() to determine the aliases which where registered * <li>command.getName() to determine the label registered for this
* command
* <li>command.getAliases() to determine the aliases which where
* registered
* </ul>
* *
* @param fallbackPrefix a prefix which is prepended to the command with a ':' one or more times to make the command unique * @param fallbackPrefix a prefix which is prepended to the command with a
* @param command the command to register, from which label is determined from the command name * ':' one or more times to make the command unique
* @return true if command was registered with the passed in label, false otherwise, which indicates the fallbackPrefix was used one or more times * @param command the command to register, from which label is determined
* from the command name
* @return true if command was registered with the passed in label, false
* otherwise, which indicates the fallbackPrefix was used one or more
* times
*/ */
public boolean register(String fallbackPrefix, Command command); public boolean register(String fallbackPrefix, Command command);
@ -46,7 +71,8 @@ public interface CommandMap {
* @param sender The command's sender * @param sender The command's sender
* @param cmdLine command + arguments. Example: "/test abc 123" * @param cmdLine command + arguments. Example: "/test abc 123"
* @return returns false if no target is found, true otherwise. * @return returns false if no target is found, true otherwise.
* @throws CommandException Thrown when the executor for the given command fails with an unhandled exception * @throws CommandException Thrown when the executor for the given command
* fails with an unhandled exception
*/ */
public boolean dispatch(CommandSender sender, String cmdLine) throws CommandException; public boolean dispatch(CommandSender sender, String cmdLine) throws CommandException;
@ -59,18 +85,24 @@ public interface CommandMap {
* Gets the command registered to the specified name * Gets the command registered to the specified name
* *
* @param name Name of the command to retrieve * @param name Name of the command to retrieve
* @return Command with the specified name or null if a command with that label doesn't exist * @return Command with the specified name or null if a command with that
* label doesn't exist
*/ */
public Command getCommand(String name); public Command getCommand(String name);
/** /**
* Looks for the requested command and executes an appropriate tab-completer if found. This method will also tab-complete partial commands. * Looks for the requested command and executes an appropriate
* tab-completer if found. This method will also tab-complete partial
* commands.
* *
* @param sender The command's sender. * @param sender The command's sender.
* @param cmdLine The entire command string to tab-complete, excluding initial slash. * @param cmdLine The entire command string to tab-complete, excluding
* @return a list of possible tab-completions. This list may be immutable. Will be null if no matching command of which sender has permission. * initial slash.
* @throws CommandException Thrown when the tab-completer for the given command fails with an unhandled exception * @return a list of possible tab-completions. This list may be immutable.
* Will be null if no matching command of which sender has permission.
* @throws CommandException Thrown when the tab-completer for the given
* command fails with an unhandled exception
* @throws IllegalArgumentException if either sender or cmdLine are null * @throws IllegalArgumentException if either sender or cmdLine are null
*/ */
public List<String> tabComplete(CommandSender sender, String cmdLine) throws IllegalArgumentException; public List<String> tabComplete(CommandSender sender, String cmdLine) throws IllegalArgumentException;

21
paper-api/src/main/java/org/bukkit/command/PluginCommand.java
View File

@ -104,17 +104,20 @@ public final class PluginCommand extends Command implements PluginIdentifiableCo
} }
/** /**
* {@inheritDoc}<br> * {@inheritDoc}
* <br> * <p>
* Delegates to the tab completer if present.<br> * Delegates to the tab completer if present.
* If it is not present or returns null, will delegate to the current command * <p>
* executor if it implements {@link TabCompleter}. If a non-null list has not * If it is not present or returns null, will delegate to the current
* been found, will default to standard player name completion in * command executor if it implements {@link TabCompleter}. If a non-null
* {@link Command#tabComplete(CommandSender, String, String[])}.<br> * list has not been found, will default to standard player name
* <br> * completion in {@link
* Command#tabComplete(CommandSender, String, String[])}.
* <p>
* This method does not consider permissions. * This method does not consider permissions.
* *
* @throws CommandException if the completer or executor throw an exception during the process of tab-completing. * @throws CommandException if the completer or executor throw an
* exception during the process of tab-completing.
* @throws IllegalArgumentException if sender, alias, or args is null * @throws IllegalArgumentException if sender, alias, or args is null
*/ */
@Override @Override

9
paper-api/src/main/java/org/bukkit/command/PluginIdentifiableCommand.java
View File

@ -3,12 +3,13 @@ package org.bukkit.command;
import org.bukkit.plugin.Plugin; import org.bukkit.plugin.Plugin;
/** /**
* This interface is used by the help system to group commands into sub-indexes based * This interface is used by the help system to group commands into
* on the {@link Plugin} they are a part of. Custom command implementations will need to * sub-indexes based on the {@link Plugin} they are a part of. Custom command
* implement this interface to have a sub-index automatically generated on the plugin's * implementations will need to implement this interface to have a sub-index
* behalf. * automatically generated on the plugin's behalf.
*/ */
public interface PluginIdentifiableCommand { public interface PluginIdentifiableCommand {
/** /**
* Gets the owner of this PluginIdentifiableCommand. * Gets the owner of this PluginIdentifiableCommand.
* *

14
paper-api/src/main/java/org/bukkit/command/SimpleCommandMap.java
View File

@ -117,14 +117,18 @@ public class SimpleCommandMap implements CommandMap {
} }
/** /**
* Registers a command with the given name is possible, otherwise uses fallbackPrefix to create a unique name if its not an alias * Registers a command with the given name is possible, otherwise uses
* fallbackPrefix to create a unique name if its not an alias
* *
* @param label the name of the command, without the '/'-prefix. * @param label the name of the command, without the '/'-prefix.
* @param fallbackPrefix a prefix which is prepended to the command with a ':' one or more times to make the command unique * @param fallbackPrefix a prefix which is prepended to the command with a
* ':' one or more times to make the command unique
* @param command the command to register * @param command the command to register
* @return true if command was registered with the passed in label, false otherwise. * @return true if command was registered with the passed in label, false
* If isAlias was true a return of false indicates no command was registerd * otherwise. If isAlias was true a return of false indicates no
* If isAlias was false a return of false indicates the fallbackPrefix was used one or more times to create a unique name for the command * command was registered. If isAlias was false a return of false
* indicates the fallbackPrefix was used one or more times to create a
* unique name for the command
*/ */
private synchronized boolean register(String label, String fallbackPrefix, Command command, boolean isAlias) { private synchronized boolean register(String label, String fallbackPrefix, Command command, boolean isAlias) {
String lowerLabel = label.trim().toLowerCase(); String lowerLabel = label.trim().toLowerCase();

3
paper-api/src/main/java/org/bukkit/command/TabCommandExecutor.java
View File

@ -5,7 +5,8 @@ import java.util.List;
/** /**
* Represents a class which can handle command tab completion and commands * Represents a class which can handle command tab completion and commands
* *
* @deprecated Remains for plugins that would have implemented it even without functionality * @deprecated Remains for plugins that would have implemented it even without
* functionality
* @see TabExecutor * @see TabExecutor
*/ */
@Deprecated @Deprecated

6
paper-api/src/main/java/org/bukkit/command/TabCompleter.java
View File

@ -13,8 +13,10 @@ public interface TabCompleter {
* @param sender Source of the command * @param sender Source of the command
* @param command Command which was executed * @param command Command which was executed
* @param alias The alias used * @param alias The alias used
* @param args The arguments passed to the command, including final partial argument to be completed and command label * @param args The arguments passed to the command, including final
* @return A List of possible completions for the final argument, or null to default to the command executor * partial argument to be completed and command label
* @return A List of possible completions for the final argument, or null
* to default to the command executor
*/ */
public List<String> onTabComplete(CommandSender sender, Command command, String alias, String[] args); public List<String> onTabComplete(CommandSender sender, Command command, String alias, String[] args);
} }

3
paper-api/src/main/java/org/bukkit/command/TabExecutor.java
View File

@ -1,7 +1,8 @@
package org.bukkit.command; package org.bukkit.command;
/** /**
* This class is provided as a convenience to implement both TabCompleter and CommandExecutor. * This class is provided as a convenience to implement both TabCompleter and
* CommandExecutor.
*/ */
public interface TabExecutor extends TabCompleter, CommandExecutor { public interface TabExecutor extends TabCompleter, CommandExecutor {
} }

38
paper-api/src/main/java/org/bukkit/configuration/Configuration.java
View File

@ -9,11 +9,12 @@ public interface Configuration extends ConfigurationSection {
/** /**
* Sets the default value of the given path as provided. * Sets the default value of the given path as provided.
* <p> * <p>
* If no source {@link Configuration} was provided as a default collection, * If no source {@link Configuration} was provided as a default
* then a new {@link MemoryConfiguration} will be created to hold the new default * collection, then a new {@link MemoryConfiguration} will be created to
* value. * hold the new default value.
* <p> * <p>
* If value is null, the value will be removed from the default Configuration source. * If value is null, the value will be removed from the default
* Configuration source.
* *
* @param path Path of the value to set. * @param path Path of the value to set.
* @param value Value to set the default to. * @param value Value to set the default to.
@ -24,9 +25,9 @@ public interface Configuration extends ConfigurationSection {
/** /**
* Sets the default values of the given paths as provided. * Sets the default values of the given paths as provided.
* <p> * <p>
* If no source {@link Configuration} was provided as a default collection, * If no source {@link Configuration} was provided as a default
* then a new {@link MemoryConfiguration} will be created to hold the new default * collection, then a new {@link MemoryConfiguration} will be created to
* values. * hold the new default values.
* *
* @param defaults A map of Path->Values to add to defaults. * @param defaults A map of Path->Values to add to defaults.
* @throws IllegalArgumentException Thrown if defaults is null. * @throws IllegalArgumentException Thrown if defaults is null.
@ -36,13 +37,14 @@ public interface Configuration extends ConfigurationSection {
/** /**
* Sets the default values of the given paths as provided. * Sets the default values of the given paths as provided.
* <p> * <p>
* If no source {@link Configuration} was provided as a default collection, * If no source {@link Configuration} was provided as a default
* then a new {@link MemoryConfiguration} will be created to hold the new default * collection, then a new {@link MemoryConfiguration} will be created to
* value. * hold the new default value.
* <p> * <p>
* This method will not hold a reference to the specified Configuration, nor will it * This method will not hold a reference to the specified Configuration,
* automatically update if that Configuration ever changes. If you require this, * nor will it automatically update if that Configuration ever changes. If
* you should set the default source with {@link #setDefaults(org.bukkit.configuration.Configuration)}. * you require this, you should set the default source with {@link
* #setDefaults(org.bukkit.configuration.Configuration)}.
* *
* @param defaults A configuration holding a list of defaults to copy. * @param defaults A configuration holding a list of defaults to copy.
* @throws IllegalArgumentException Thrown if defaults is null or this. * @throws IllegalArgumentException Thrown if defaults is null or this.
@ -52,8 +54,8 @@ public interface Configuration extends ConfigurationSection {
/** /**
* Sets the source of all default values for this {@link Configuration}. * Sets the source of all default values for this {@link Configuration}.
* <p> * <p>
* If a previous source was set, or previous default values were defined, then they will * If a previous source was set, or previous default values were defined,
* not be copied to the new source. * then they will not be copied to the new source.
* *
* @param defaults New source of default values for this configuration. * @param defaults New source of default values for this configuration.
* @throws IllegalArgumentException Thrown if defaults is null or this. * @throws IllegalArgumentException Thrown if defaults is null or this.
@ -63,9 +65,9 @@ public interface Configuration extends ConfigurationSection {
/** /**
* Gets the source {@link Configuration} for this configuration. * Gets the source {@link Configuration} for this configuration.
* <p> * <p>
* If no configuration source was set, but default values were added, then a * If no configuration source was set, but default values were added, then
* {@link MemoryConfiguration} will be returned. If no source was set and no * a {@link MemoryConfiguration} will be returned. If no source was set
* defaults were set, then this method will return null. * and no defaults were set, then this method will return null.
* *
* @return Configuration source for default values, or null if none exist. * @return Configuration source for default values, or null if none exist.
*/ */

47
paper-api/src/main/java/org/bukkit/configuration/ConfigurationOptions.java
View File

@ -1,7 +1,8 @@
package org.bukkit.configuration; package org.bukkit.configuration;
/** /**
* Various settings for controlling the input and output of a {@link Configuration} * Various settings for controlling the input and output of a {@link
* Configuration}
*/ */
public class ConfigurationOptions { public class ConfigurationOptions {
private char pathSeparator = '.'; private char pathSeparator = '.';
@ -22,10 +23,11 @@ public class ConfigurationOptions {
} }
/** /**
* Gets the char that will be used to separate {@link ConfigurationSection}s * Gets the char that will be used to separate {@link
* ConfigurationSection}s
* <p> * <p>
* This value does not affect how the {@link Configuration} is stored, only in * This value does not affect how the {@link Configuration} is stored,
* how you access the data. The default value is '.'. * only in how you access the data. The default value is '.'.
* *
* @return Path separator * @return Path separator
*/ */
@ -34,10 +36,11 @@ public class ConfigurationOptions {
} }
/** /**
* Sets the char that will be used to separate {@link ConfigurationSection}s * Sets the char that will be used to separate {@link
* ConfigurationSection}s
* <p> * <p>
* This value does not affect how the {@link Configuration} is stored, only in * This value does not affect how the {@link Configuration} is stored,
* how you access the data. The default value is '.'. * only in how you access the data. The default value is '.'.
* *
* @param value Path separator * @param value Path separator
* @return This object, for chaining * @return This object, for chaining
@ -48,13 +51,16 @@ public class ConfigurationOptions {
} }
/** /**
* Checks if the {@link Configuration} should copy values from its default {@link Configuration} directly. * Checks if the {@link Configuration} should copy values from its default
* {@link Configuration} directly.
* <p> * <p>
* If this is true, all values in the default Configuration will be directly copied, * If this is true, all values in the default Configuration will be
* making it impossible to distinguish between values that were set and values that * directly copied, making it impossible to distinguish between values
* are provided by default. As a result, {@link ConfigurationSection#contains(java.lang.String)} will always * that were set and values that are provided by default. As a result,
* return the same value as {@link ConfigurationSection#isSet(java.lang.String)}. * {@link ConfigurationSection#contains(java.lang.String)} will always
* The default value is false. * return the same value as {@link
* ConfigurationSection#isSet(java.lang.String)}. The default value is
* false.
* *
* @return Whether or not defaults are directly copied * @return Whether or not defaults are directly copied
*/ */
@ -63,13 +69,16 @@ public class ConfigurationOptions {
} }
/** /**
* Sets if the {@link Configuration} should copy values from its default {@link Configuration} directly. * Sets if the {@link Configuration} should copy values from its default
* {@link Configuration} directly.
* <p> * <p>
* If this is true, all values in the default Configuration will be directly copied, * If this is true, all values in the default Configuration will be
* making it impossible to distinguish between values that were set and values that * directly copied, making it impossible to distinguish between values
* are provided by default. As a result, {@link ConfigurationSection#contains(java.lang.String)} will always * that were set and values that are provided by default. As a result,
* return the same value as {@link ConfigurationSection#isSet(java.lang.String)}. * {@link ConfigurationSection#contains(java.lang.String)} will always
* The default value is false. * return the same value as {@link
* ConfigurationSection#isSet(java.lang.String)}. The default value is
* false.
* *
* @param value Whether or not defaults are directly copied * @param value Whether or not defaults are directly copied
* @return This object, for chaining * @return This object, for chaining

475
paper-api/src/main/java/org/bukkit/configuration/ConfigurationSection.java
View File

@ -16,14 +16,15 @@ public interface ConfigurationSection {
/** /**
* Gets a set containing all keys in this section. * Gets a set containing all keys in this section.
* <p> * <p>
* If deep is set to true, then this will contain all the keys within any child * If deep is set to true, then this will contain all the keys within any
* {@link ConfigurationSection}s (and their children, etc). These will be in a * child {@link ConfigurationSection}s (and their children, etc). These
* valid path notation for you to use. * will be in a valid path notation for you to use.
* <p> * <p>
* If deep is set to false, then this will contain only the keys of any direct children, * If deep is set to false, then this will contain only the keys of any
* and not their own children. * direct children, and not their own children.
* *
* @param deep Whether or not to get a deep list, as opposed to a shallow list. * @param deep Whether or not to get a deep list, as opposed to a shallow
* list.
* @return Set of keys contained within this ConfigurationSection. * @return Set of keys contained within this ConfigurationSection.
*/ */
public Set<String> getKeys(boolean deep); public Set<String> getKeys(boolean deep);
@ -31,14 +32,15 @@ public interface ConfigurationSection {
/** /**
* Gets a Map containing all keys and their values for this section. * Gets a Map containing all keys and their values for this section.
* <p> * <p>
* If deep is set to true, then this will contain all the keys and values within * If deep is set to true, then this will contain all the keys and values
* any child {@link ConfigurationSection}s (and their children, etc). These * within any child {@link ConfigurationSection}s (and their children,
* keys will be in a valid path notation for you to use. * etc). These keys will be in a valid path notation for you to use.
* <p> * <p>
* If deep is set to false, then this will contain only the keys and values of any * If deep is set to false, then this will contain only the keys and
* direct children, and not their own children. * values of any direct children, and not their own children.
* *
* @param deep Whether or not to get a deep list, as opposed to a shallow list. * @param deep Whether or not to get a deep list, as opposed to a shallow
* list.
* @return Map of keys and values of this section. * @return Map of keys and values of this section.
*/ */
public Map<String, Object> getValues(boolean deep); public Map<String, Object> getValues(boolean deep);
@ -46,72 +48,80 @@ public interface ConfigurationSection {
/** /**
* Checks if this {@link ConfigurationSection} contains the given path. * Checks if this {@link ConfigurationSection} contains the given path.
* <p> * <p>
* If the value for the requested path does not exist but a default value has * If the value for the requested path does not exist but a default value
* been specified, this will return true. * has been specified, this will return true.
* *
* @param path Path to check for existence. * @param path Path to check for existence.
* @return True if this section contains the requested path, either via default or being set. * @return True if this section contains the requested path, either via
* default or being set.
* @throws IllegalArgumentException Thrown when path is null. * @throws IllegalArgumentException Thrown when path is null.
*/ */
public boolean contains(String path); public boolean contains(String path);
/** /**
* Checks if this {@link ConfigurationSection} has a value set for the given path. * Checks if this {@link ConfigurationSection} has a value set for the
* given path.
* <p> * <p>
* If the value for the requested path does not exist but a default value has * If the value for the requested path does not exist but a default value
* been specified, this will still return false. * has been specified, this will still return false.
* *
* @param path Path to check for existence. * @param path Path to check for existence.
* @return True if this section contains the requested path, regardless of having a default. * @return True if this section contains the requested path, regardless of
* having a default.
* @throws IllegalArgumentException Thrown when path is null. * @throws IllegalArgumentException Thrown when path is null.
*/ */
public boolean isSet(String path); public boolean isSet(String path);
/** /**
* Gets the path of this {@link ConfigurationSection} from its root {@link Configuration} * Gets the path of this {@link ConfigurationSection} from its root {@link
* Configuration}
* <p> * <p>
* For any {@link Configuration} themselves, this will return an empty string. * For any {@link Configuration} themselves, this will return an empty
* string.
* <p> * <p>
* If the section is no longer contained within its root for any reason, such as * If the section is no longer contained within its root for any reason,
* being replaced with a different value, this may return null. * such as being replaced with a different value, this may return null.
* <p> * <p>
* To retrieve the single name of this section, that is, the final part of the path * To retrieve the single name of this section, that is, the final part of
* returned by this method, you may use {@link #getName()}. * the path returned by this method, you may use {@link #getName()}.
* *
* @return Path of this section relative to its root * @return Path of this section relative to its root
*/ */
public String getCurrentPath(); public String getCurrentPath();
/** /**
* Gets the name of this individual {@link ConfigurationSection}, in the path. * Gets the name of this individual {@link ConfigurationSection}, in the
* path.
* <p> * <p>
* This will always be the final part of {@link #getCurrentPath()}, unless the * This will always be the final part of {@link #getCurrentPath()}, unless
* section is orphaned. * the section is orphaned.
* *
* @return Name of this section * @return Name of this section
*/ */
public String getName(); public String getName();
/** /**
* Gets the root {@link Configuration} that contains this {@link ConfigurationSection} * Gets the root {@link Configuration} that contains this {@link
* ConfigurationSection}
* <p> * <p>
* For any {@link Configuration} themselves, this will return its own object. * For any {@link Configuration} themselves, this will return its own
* object.
* <p> * <p>
* If the section is no longer contained within its root for any reason, such as * If the section is no longer contained within its root for any reason,
* being replaced with a different value, this may return null. * such as being replaced with a different value, this may return null.
* *
* @return Root configuration containing this section. * @return Root configuration containing this section.
*/ */
public Configuration getRoot(); public Configuration getRoot();
/** /**
* Gets the parent {@link ConfigurationSection} that directly contains this * Gets the parent {@link ConfigurationSection} that directly contains
* {@link ConfigurationSection}. * this {@link ConfigurationSection}.
* <p> * <p>
* For any {@link Configuration} themselves, this will return null. * For any {@link Configuration} themselves, this will return null.
* <p> * <p>
* If the section is no longer contained within its parent for any reason, such as * If the section is no longer contained within its parent for any reason,
* being replaced with a different value, this may return null. * such as being replaced with a different value, this may return null.
* *
* @return Parent section containing this section. * @return Parent section containing this section.
*/ */
@ -120,9 +130,9 @@ public interface ConfigurationSection {
/** /**
* Gets the requested Object by path. * Gets the requested Object by path.
* <p> * <p>
* If the Object does not exist but a default value has been specified, this * If the Object does not exist but a default value has been specified,
* will return the default value. If the Object does not exist and no default * this will return the default value. If the Object does not exist and no
* value was specified, this will return null. * default value was specified, this will return null.
* *
* @param path Path of the Object to get. * @param path Path of the Object to get.
* @return Requested Object. * @return Requested Object.
@ -130,10 +140,12 @@ public interface ConfigurationSection {
public Object get(String path); public Object get(String path);
/** /**
* Gets the requested Object by path, returning a default value if not found. * Gets the requested Object by path, returning a default value if not
* found.
* <p> * <p>
* If the Object does not exist then the specified default value will returned * If the Object does not exist then the specified default value will
* regardless of if a default has been identified in the root {@link Configuration}. * returned regardless of if a default has been identified in the root
* {@link Configuration}.
* *
* @param path Path of the Object to get. * @param path Path of the Object to get.
* @param def The default value to return if the path is not found. * @param def The default value to return if the path is not found.
@ -147,10 +159,10 @@ public interface ConfigurationSection {
* If value is null, the entry will be removed. Any existing entry will be * If value is null, the entry will be removed. Any existing entry will be
* replaced, regardless of what the new value is. * replaced, regardless of what the new value is.
* <p> * <p>
* Some implementations may have limitations on what you may store. See their * Some implementations may have limitations on what you may store. See
* individual javadocs for details. No implementations should allow you to store * their individual javadocs for details. No implementations should allow
* {@link Configuration}s or {@link ConfigurationSection}s, please use * you to store {@link Configuration}s or {@link ConfigurationSection}s,
* {@link #createSection(java.lang.String)} for that. * please use {@link #createSection(java.lang.String)} for that.
* *
* @param path Path of the object to set. * @param path Path of the object to set.
* @param value New value to set the path to. * @param value New value to set the path to.
@ -160,8 +172,9 @@ public interface ConfigurationSection {
/** /**
* Creates an empty {@link ConfigurationSection} at the specified path. * Creates an empty {@link ConfigurationSection} at the specified path.
* <p> * <p>
* Any value that was previously set at this path will be overwritten. If the * Any value that was previously set at this path will be overwritten. If
* previous value was itself a {@link ConfigurationSection}, it will be orphaned. * the previous value was itself a {@link ConfigurationSection}, it will
* be orphaned.
* *
* @param path Path to create the section at. * @param path Path to create the section at.
* @return Newly created section * @return Newly created section
@ -169,10 +182,12 @@ public interface ConfigurationSection {
public ConfigurationSection createSection(String path); public ConfigurationSection createSection(String path);
/** /**
* Creates a {@link ConfigurationSection} at the specified path, with specified values. * Creates a {@link ConfigurationSection} at the specified path, with
* specified values.
* <p> * <p>
* Any value that was previously set at this path will be overwritten. If the * Any value that was previously set at this path will be overwritten. If
* previous value was itself a {@link ConfigurationSection}, it will be orphaned. * the previous value was itself a {@link ConfigurationSection}, it will
* be orphaned.
* *
* @param path Path to create the section at. * @param path Path to create the section at.
* @param map The values to used. * @param map The values to used.
@ -184,9 +199,9 @@ public interface ConfigurationSection {
/** /**
* Gets the requested String by path. * Gets the requested String by path.
* <p> * <p>
* If the String does not exist but a default value has been specified, this * If the String does not exist but a default value has been specified,
* will return the default value. If the String does not exist and no default * this will return the default value. If the String does not exist and no
* value was specified, this will return null. * default value was specified, this will return null.
* *
* @param path Path of the String to get. * @param path Path of the String to get.
* @return Requested String. * @return Requested String.
@ -194,13 +209,16 @@ public interface ConfigurationSection {
public String getString(String path); public String getString(String path);
/** /**
* Gets the requested String by path, returning a default value if not found. * Gets the requested String by path, returning a default value if not
* found.
* <p> * <p>
* If the String does not exist then the specified default value will returned * If the String does not exist then the specified default value will
* regardless of if a default has been identified in the root {@link Configuration}. * returned regardless of if a default has been identified in the root
* {@link Configuration}.
* *
* @param path Path of the String to get. * @param path Path of the String to get.
* @param def The default value to return if the path is not found or is not a String. * @param def The default value to return if the path is not found or is
* not a String.
* @return Requested String. * @return Requested String.
*/ */
public String getString(String path, String def); public String getString(String path, String def);
@ -208,10 +226,10 @@ public interface ConfigurationSection {
/** /**
* Checks if the specified path is a String. * Checks if the specified path is a String.
* <p> * <p>
* If the path exists but is not a String, this will return false. If the path does not * If the path exists but is not a String, this will return false. If the
* exist, this will return false. If the path does not exist but a default value * path does not exist, this will return false. If the path does not exist
* has been specified, this will check if that default value is a String and return * but a default value has been specified, this will check if that default
* appropriately. * value is a String and return appropriately.
* *
* @param path Path of the String to check. * @param path Path of the String to check.
* @return Whether or not the specified path is a String. * @return Whether or not the specified path is a String.
@ -233,11 +251,13 @@ public interface ConfigurationSection {
/** /**
* Gets the requested int by path, returning a default value if not found. * Gets the requested int by path, returning a default value if not found.
* <p> * <p>
* If the int does not exist then the specified default value will returned * If the int does not exist then the specified default value will
* regardless of if a default has been identified in the root {@link Configuration}. * returned regardless of if a default has been identified in the root
* {@link Configuration}.
* *
* @param path Path of the int to get. * @param path Path of the int to get.
* @param def The default value to return if the path is not found or is not an int. * @param def The default value to return if the path is not found or is
* not an int.
* @return Requested int. * @return Requested int.
*/ */
public int getInt(String path, int def); public int getInt(String path, int def);
@ -245,10 +265,10 @@ public interface ConfigurationSection {
/** /**
* Checks if the specified path is an int. * Checks if the specified path is an int.
* <p> * <p>
* If the path exists but is not a int, this will return false. If the path does not * If the path exists but is not a int, this will return false. If the
* exist, this will return false. If the path does not exist but a default value * path does not exist, this will return false. If the path does not exist
* has been specified, this will check if that default value is a int and return * but a default value has been specified, this will check if that default
* appropriately. * value is a int and return appropriately.
* *
* @param path Path of the int to check. * @param path Path of the int to check.
* @return Whether or not the specified path is an int. * @return Whether or not the specified path is an int.
@ -258,9 +278,9 @@ public interface ConfigurationSection {
/** /**
* Gets the requested boolean by path. * Gets the requested boolean by path.
* <p> * <p>
* If the boolean does not exist but a default value has been specified, this * If the boolean does not exist but a default value has been specified,
* will return the default value. If the boolean does not exist and no default * this will return the default value. If the boolean does not exist and
* value was specified, this will return false. * no default value was specified, this will return false.
* *
* @param path Path of the boolean to get. * @param path Path of the boolean to get.
* @return Requested boolean. * @return Requested boolean.
@ -268,13 +288,16 @@ public interface ConfigurationSection {
public boolean getBoolean(String path); public boolean getBoolean(String path);
/** /**
* Gets the requested boolean by path, returning a default value if not found. * Gets the requested boolean by path, returning a default value if not
* found.
* <p> * <p>
* If the boolean does not exist then the specified default value will returned * If the boolean does not exist then the specified default value will
* regardless of if a default has been identified in the root {@link Configuration}. * returned regardless of if a default has been identified in the root
* {@link Configuration}.
* *
* @param path Path of the boolean to get. * @param path Path of the boolean to get.
* @param def The default value to return if the path is not found or is not a boolean. * @param def The default value to return if the path is not found or is
* not a boolean.
* @return Requested boolean. * @return Requested boolean.
*/ */
public boolean getBoolean(String path, boolean def); public boolean getBoolean(String path, boolean def);
@ -282,10 +305,10 @@ public interface ConfigurationSection {
/** /**
* Checks if the specified path is a boolean. * Checks if the specified path is a boolean.
* <p> * <p>
* If the path exists but is not a boolean, this will return false. If the path does not * If the path exists but is not a boolean, this will return false. If the
* exist, this will return false. If the path does not exist but a default value * path does not exist, this will return false. If the path does not exist
* has been specified, this will check if that default value is a boolean and return * but a default value has been specified, this will check if that default
* appropriately. * value is a boolean and return appropriately.
* *
* @param path Path of the boolean to check. * @param path Path of the boolean to check.
* @return Whether or not the specified path is a boolean. * @return Whether or not the specified path is a boolean.
@ -295,9 +318,9 @@ public interface ConfigurationSection {
/** /**
* Gets the requested double by path. * Gets the requested double by path.
* <p> * <p>
* If the double does not exist but a default value has been specified, this * If the double does not exist but a default value has been specified,
* will return the default value. If the double does not exist and no default * this will return the default value. If the double does not exist and no
* value was specified, this will return 0. * default value was specified, this will return 0.
* *
* @param path Path of the double to get. * @param path Path of the double to get.
* @return Requested double. * @return Requested double.
@ -305,13 +328,16 @@ public interface ConfigurationSection {
public double getDouble(String path); public double getDouble(String path);
/** /**
* Gets the requested double by path, returning a default value if not found. * Gets the requested double by path, returning a default value if not
* found.
* <p> * <p>
* If the double does not exist then the specified default value will returned * If the double does not exist then the specified default value will
* regardless of if a default has been identified in the root {@link Configuration}. * returned regardless of if a default has been identified in the root
* {@link Configuration}.
* *
* @param path Path of the double to get. * @param path Path of the double to get.
* @param def The default value to return if the path is not found or is not a double. * @param def The default value to return if the path is not found or is
* not a double.
* @return Requested double. * @return Requested double.
*/ */
public double getDouble(String path, double def); public double getDouble(String path, double def);
@ -319,10 +345,10 @@ public interface ConfigurationSection {
/** /**
* Checks if the specified path is a double. * Checks if the specified path is a double.
* <p> * <p>
* If the path exists but is not a double, this will return false. If the path does not * If the path exists but is not a double, this will return false. If the
* exist, this will return false. If the path does not exist but a default value * path does not exist, this will return false. If the path does not exist
* has been specified, this will check if that default value is a double and return * but a default value has been specified, this will check if that default
* appropriately. * value is a double and return appropriately.
* *
* @param path Path of the double to check. * @param path Path of the double to check.
* @return Whether or not the specified path is a double. * @return Whether or not the specified path is a double.
@ -333,8 +359,8 @@ public interface ConfigurationSection {
* Gets the requested long by path. * Gets the requested long by path.
* <p> * <p>
* If the long does not exist but a default value has been specified, this * If the long does not exist but a default value has been specified, this
* will return the default value. If the long does not exist and no default * will return the default value. If the long does not exist and no
* value was specified, this will return 0. * default value was specified, this will return 0.
* *
* @param path Path of the long to get. * @param path Path of the long to get.
* @return Requested long. * @return Requested long.
@ -342,13 +368,16 @@ public interface ConfigurationSection {
public long getLong(String path); public long getLong(String path);
/** /**
* Gets the requested long by path, returning a default value if not found. * Gets the requested long by path, returning a default value if not
* found.
* <p> * <p>
* If the long does not exist then the specified default value will returned * If the long does not exist then the specified default value will
* regardless of if a default has been identified in the root {@link Configuration}. * returned regardless of if a default has been identified in the root
* {@link Configuration}.
* *
* @param path Path of the long to get. * @param path Path of the long to get.
* @param def The default value to return if the path is not found or is not a long. * @param def The default value to return if the path is not found or is
* not a long.
* @return Requested long. * @return Requested long.
*/ */
public long getLong(String path, long def); public long getLong(String path, long def);
@ -356,10 +385,10 @@ public interface ConfigurationSection {
/** /**
* Checks if the specified path is a long. * Checks if the specified path is a long.
* <p> * <p>
* If the path exists but is not a long, this will return false. If the path does not * If the path exists but is not a long, this will return false. If the
* exist, this will return false. If the path does not exist but a default value * path does not exist, this will return false. If the path does not exist
* has been specified, this will check if that default value is a long and return * but a default value has been specified, this will check if that default
* appropriately. * value is a long and return appropriately.
* *
* @param path Path of the long to check. * @param path Path of the long to check.
* @return Whether or not the specified path is a long. * @return Whether or not the specified path is a long.
@ -371,8 +400,8 @@ public interface ConfigurationSection {
* Gets the requested List by path. * Gets the requested List by path.
* <p> * <p>
* If the List does not exist but a default value has been specified, this * If the List does not exist but a default value has been specified, this
* will return the default value. If the List does not exist and no default * will return the default value. If the List does not exist and no
* value was specified, this will return null. * default value was specified, this will return null.
* *
* @param path Path of the List to get. * @param path Path of the List to get.
* @return Requested List. * @return Requested List.
@ -380,13 +409,16 @@ public interface ConfigurationSection {
public List<?> getList(String path); public List<?> getList(String path);
/** /**
* Gets the requested List by path, returning a default value if not found. * Gets the requested List by path, returning a default value if not
* found.
* <p> * <p>
* If the List does not exist then the specified default value will returned * If the List does not exist then the specified default value will
* regardless of if a default has been identified in the root {@link Configuration}. * returned regardless of if a default has been identified in the root
* {@link Configuration}.
* *
* @param path Path of the List to get. * @param path Path of the List to get.
* @param def The default value to return if the path is not found or is not a List. * @param def The default value to return if the path is not found or is
* not a List.
* @return Requested List. * @return Requested List.
*/ */
public List<?> getList(String path, List<?> def); public List<?> getList(String path, List<?> def);
@ -394,10 +426,10 @@ public interface ConfigurationSection {
/** /**
* Checks if the specified path is a List. * Checks if the specified path is a List.
* <p> * <p>
* If the path exists but is not a List, this will return false. If the path does not * If the path exists but is not a List, this will return false. If the
* exist, this will return false. If the path does not exist but a default value * path does not exist, this will return false. If the path does not exist
* has been specified, this will check if that default value is a List and return * but a default value has been specified, this will check if that default
* appropriately. * value is a List and return appropriately.
* *
* @param path Path of the List to check. * @param path Path of the List to check.
* @return Whether or not the specified path is a List. * @return Whether or not the specified path is a List.
@ -408,11 +440,11 @@ public interface ConfigurationSection {
* Gets the requested List of String by path. * Gets the requested List of String by path.
* <p> * <p>
* If the List does not exist but a default value has been specified, this * If the List does not exist but a default value has been specified, this
* will return the default value. If the List does not exist and no default * will return the default value. If the List does not exist and no
* value was specified, this will return an empty List. * default value was specified, this will return an empty List.
* <p> * <p>
* This method will attempt to cast any values into a String if possible, but may * This method will attempt to cast any values into a String if possible,
* miss any values out if they are not compatible. * but may miss any values out if they are not compatible.
* *
* @param path Path of the List to get. * @param path Path of the List to get.
* @return Requested List of String. * @return Requested List of String.
@ -423,11 +455,11 @@ public interface ConfigurationSection {
* Gets the requested List of Integer by path. * Gets the requested List of Integer by path.
* <p> * <p>
* If the List does not exist but a default value has been specified, this * If the List does not exist but a default value has been specified, this
* will return the default value. If the List does not exist and no default * will return the default value. If the List does not exist and no
* value was specified, this will return an empty List. * default value was specified, this will return an empty List.
* <p> * <p>
* This method will attempt to cast any values into a Integer if possible, but may * This method will attempt to cast any values into a Integer if possible,
* miss any values out if they are not compatible. * but may miss any values out if they are not compatible.
* *
* @param path Path of the List to get. * @param path Path of the List to get.
* @return Requested List of Integer. * @return Requested List of Integer.
@ -438,11 +470,11 @@ public interface ConfigurationSection {
* Gets the requested List of Boolean by path. * Gets the requested List of Boolean by path.
* <p> * <p>
* If the List does not exist but a default value has been specified, this * If the List does not exist but a default value has been specified, this
* will return the default value. If the List does not exist and no default * will return the default value. If the List does not exist and no
* value was specified, this will return an empty List. * default value was specified, this will return an empty List.
* <p> * <p>
* This method will attempt to cast any values into a Boolean if possible, but may * This method will attempt to cast any values into a Boolean if possible,
* miss any values out if they are not compatible. * but may miss any values out if they are not compatible.
* *
* @param path Path of the List to get. * @param path Path of the List to get.
* @return Requested List of Boolean. * @return Requested List of Boolean.
@ -453,11 +485,11 @@ public interface ConfigurationSection {
* Gets the requested List of Double by path. * Gets the requested List of Double by path.
* <p> * <p>
* If the List does not exist but a default value has been specified, this * If the List does not exist but a default value has been specified, this
* will return the default value. If the List does not exist and no default * will return the default value. If the List does not exist and no
* value was specified, this will return an empty List. * default value was specified, this will return an empty List.
* <p> * <p>
* This method will attempt to cast any values into a Double if possible, but may * This method will attempt to cast any values into a Double if possible,
* miss any values out if they are not compatible. * but may miss any values out if they are not compatible.
* *
* @param path Path of the List to get. * @param path Path of the List to get.
* @return Requested List of Double. * @return Requested List of Double.
@ -468,11 +500,11 @@ public interface ConfigurationSection {
* Gets the requested List of Float by path. * Gets the requested List of Float by path.
* <p> * <p>
* If the List does not exist but a default value has been specified, this * If the List does not exist but a default value has been specified, this
* will return the default value. If the List does not exist and no default * will return the default value. If the List does not exist and no
* value was specified, this will return an empty List. * default value was specified, this will return an empty List.
* <p> * <p>
* This method will attempt to cast any values into a Float if possible, but may * This method will attempt to cast any values into a Float if possible,
* miss any values out if they are not compatible. * but may miss any values out if they are not compatible.
* *
* @param path Path of the List to get. * @param path Path of the List to get.
* @return Requested List of Float. * @return Requested List of Float.
@ -483,11 +515,11 @@ public interface ConfigurationSection {
* Gets the requested List of Long by path. * Gets the requested List of Long by path.
* <p> * <p>
* If the List does not exist but a default value has been specified, this * If the List does not exist but a default value has been specified, this
* will return the default value. If the List does not exist and no default * will return the default value. If the List does not exist and no
* value was specified, this will return an empty List. * default value was specified, this will return an empty List.
* <p> * <p>
* This method will attempt to cast any values into a Long if possible, but may * This method will attempt to cast any values into a Long if possible,
* miss any values out if they are not compatible. * but may miss any values out if they are not compatible.
* *
* @param path Path of the List to get. * @param path Path of the List to get.
* @return Requested List of Long. * @return Requested List of Long.
@ -498,11 +530,11 @@ public interface ConfigurationSection {
* Gets the requested List of Byte by path. * Gets the requested List of Byte by path.
* <p> * <p>
* If the List does not exist but a default value has been specified, this * If the List does not exist but a default value has been specified, this
* will return the default value. If the List does not exist and no default * will return the default value. If the List does not exist and no
* value was specified, this will return an empty List. * default value was specified, this will return an empty List.
* <p> * <p>
* This method will attempt to cast any values into a Byte if possible, but may * This method will attempt to cast any values into a Byte if possible,
* miss any values out if they are not compatible. * but may miss any values out if they are not compatible.
* *
* @param path Path of the List to get. * @param path Path of the List to get.
* @return Requested List of Byte. * @return Requested List of Byte.
@ -513,11 +545,11 @@ public interface ConfigurationSection {
* Gets the requested List of Character by path. * Gets the requested List of Character by path.
* <p> * <p>
* If the List does not exist but a default value has been specified, this * If the List does not exist but a default value has been specified, this
* will return the default value. If the List does not exist and no default * will return the default value. If the List does not exist and no
* value was specified, this will return an empty List. * default value was specified, this will return an empty List.
* <p> * <p>
* This method will attempt to cast any values into a Character if possible, but may * This method will attempt to cast any values into a Character if
* miss any values out if they are not compatible. * possible, but may miss any values out if they are not compatible.
* *
* @param path Path of the List to get. * @param path Path of the List to get.
* @return Requested List of Character. * @return Requested List of Character.
@ -528,11 +560,11 @@ public interface ConfigurationSection {
* Gets the requested List of Short by path. * Gets the requested List of Short by path.
* <p> * <p>
* If the List does not exist but a default value has been specified, this * If the List does not exist but a default value has been specified, this
* will return the default value. If the List does not exist and no default * will return the default value. If the List does not exist and no
* value was specified, this will return an empty List. * default value was specified, this will return an empty List.
* <p> * <p>
* This method will attempt to cast any values into a Short if possible, but may * This method will attempt to cast any values into a Short if possible,
* miss any values out if they are not compatible. * but may miss any values out if they are not compatible.
* *
* @param path Path of the List to get. * @param path Path of the List to get.
* @return Requested List of Short. * @return Requested List of Short.
@ -543,11 +575,11 @@ public interface ConfigurationSection {
* Gets the requested List of Maps by path. * Gets the requested List of Maps by path.
* <p> * <p>
* If the List does not exist but a default value has been specified, this * If the List does not exist but a default value has been specified, this
* will return the default value. If the List does not exist and no default * will return the default value. If the List does not exist and no
* value was specified, this will return an empty List. * default value was specified, this will return an empty List.
* <p> * <p>
* This method will attempt to cast any values into a Map if possible, but may * This method will attempt to cast any values into a Map if possible, but
* miss any values out if they are not compatible. * may miss any values out if they are not compatible.
* *
* @param path Path of the List to get. * @param path Path of the List to get.
* @return Requested List of Maps. * @return Requested List of Maps.
@ -558,9 +590,9 @@ public interface ConfigurationSection {
/** /**
* Gets the requested Vector by path. * Gets the requested Vector by path.
* <p> * <p>
* If the Vector does not exist but a default value has been specified, this * If the Vector does not exist but a default value has been specified,
* will return the default value. If the Vector does not exist and no default * this will return the default value. If the Vector does not exist and no
* value was specified, this will return null. * default value was specified, this will return null.
* *
* @param path Path of the Vector to get. * @param path Path of the Vector to get.
* @return Requested Vector. * @return Requested Vector.
@ -568,13 +600,16 @@ public interface ConfigurationSection {
public Vector getVector(String path); public Vector getVector(String path);
/** /**
* Gets the requested {@link Vector} by path, returning a default value if not found. * Gets the requested {@link Vector} by path, returning a default value if
* not found.
* <p> * <p>
* If the Vector does not exist then the specified default value will returned * If the Vector does not exist then the specified default value will
* regardless of if a default has been identified in the root {@link Configuration}. * returned regardless of if a default has been identified in the root
* {@link Configuration}.
* *
* @param path Path of the Vector to get. * @param path Path of the Vector to get.
* @param def The default value to return if the path is not found or is not a Vector. * @param def The default value to return if the path is not found or is
* not a Vector.
* @return Requested Vector. * @return Requested Vector.
*/ */
public Vector getVector(String path, Vector def); public Vector getVector(String path, Vector def);
@ -582,10 +617,10 @@ public interface ConfigurationSection {
/** /**
* Checks if the specified path is a Vector. * Checks if the specified path is a Vector.
* <p> * <p>
* If the path exists but is not a Vector, this will return false. If the path does not * If the path exists but is not a Vector, this will return false. If the
* exist, this will return false. If the path does not exist but a default value * path does not exist, this will return false. If the path does not exist
* has been specified, this will check if that default value is a Vector and return * but a default value has been specified, this will check if that default
* appropriately. * value is a Vector and return appropriately.
* *
* @param path Path of the Vector to check. * @param path Path of the Vector to check.
* @return Whether or not the specified path is a Vector. * @return Whether or not the specified path is a Vector.
@ -595,9 +630,10 @@ public interface ConfigurationSection {
/** /**
* Gets the requested OfflinePlayer by path. * Gets the requested OfflinePlayer by path.
* <p> * <p>
* If the OfflinePlayer does not exist but a default value has been specified, this * If the OfflinePlayer does not exist but a default value has been
* will return the default value. If the OfflinePlayer does not exist and no default * specified, this will return the default value. If the OfflinePlayer
* value was specified, this will return null. * does not exist and no default value was specified, this will return
* null.
* *
* @param path Path of the OfflinePlayer to get. * @param path Path of the OfflinePlayer to get.
* @return Requested OfflinePlayer. * @return Requested OfflinePlayer.
@ -605,13 +641,16 @@ public interface ConfigurationSection {
public OfflinePlayer getOfflinePlayer(String path); public OfflinePlayer getOfflinePlayer(String path);
/** /**
* Gets the requested {@link OfflinePlayer} by path, returning a default value if not found. * Gets the requested {@link OfflinePlayer} by path, returning a default
* value if not found.
* <p> * <p>
* If the OfflinePlayer does not exist then the specified default value will returned * If the OfflinePlayer does not exist then the specified default value
* regardless of if a default has been identified in the root {@link Configuration}. * will returned regardless of if a default has been identified in the
* root {@link Configuration}.
* *
* @param path Path of the OfflinePlayer to get. * @param path Path of the OfflinePlayer to get.
* @param def The default value to return if the path is not found or is not an OfflinePlayer. * @param def The default value to return if the path is not found or is
* not an OfflinePlayer.
* @return Requested OfflinePlayer. * @return Requested OfflinePlayer.
*/ */
public OfflinePlayer getOfflinePlayer(String path, OfflinePlayer def); public OfflinePlayer getOfflinePlayer(String path, OfflinePlayer def);
@ -619,10 +658,10 @@ public interface ConfigurationSection {
/** /**
* Checks if the specified path is an OfflinePlayer. * Checks if the specified path is an OfflinePlayer.
* <p> * <p>
* If the path exists but is not a OfflinePlayer, this will return false. If the path does not * If the path exists but is not a OfflinePlayer, this will return false.
* exist, this will return false. If the path does not exist but a default value * If the path does not exist, this will return false. If the path does
* has been specified, this will check if that default value is a OfflinePlayer and return * not exist but a default value has been specified, this will check if
* appropriately. * that default value is a OfflinePlayer and return appropriately.
* *
* @param path Path of the OfflinePlayer to check. * @param path Path of the OfflinePlayer to check.
* @return Whether or not the specified path is an OfflinePlayer. * @return Whether or not the specified path is an OfflinePlayer.
@ -632,9 +671,9 @@ public interface ConfigurationSection {
/** /**
* Gets the requested ItemStack by path. * Gets the requested ItemStack by path.
* <p> * <p>
* If the ItemStack does not exist but a default value has been specified, this * If the ItemStack does not exist but a default value has been specified,
* will return the default value. If the ItemStack does not exist and no default * this will return the default value. If the ItemStack does not exist and
* value was specified, this will return null. * no default value was specified, this will return null.
* *
* @param path Path of the ItemStack to get. * @param path Path of the ItemStack to get.
* @return Requested ItemStack. * @return Requested ItemStack.
@ -642,13 +681,16 @@ public interface ConfigurationSection {
public ItemStack getItemStack(String path); public ItemStack getItemStack(String path);
/** /**
* Gets the requested {@link ItemStack} by path, returning a default value if not found. * Gets the requested {@link ItemStack} by path, returning a default value
* if not found.
* <p> * <p>
* If the ItemStack does not exist then the specified default value will returned * If the ItemStack does not exist then the specified default value will
* regardless of if a default has been identified in the root {@link Configuration}. * returned regardless of if a default has been identified in the root
* {@link Configuration}.
* *
* @param path Path of the ItemStack to get. * @param path Path of the ItemStack to get.
* @param def The default value to return if the path is not found or is not an ItemStack. * @param def The default value to return if the path is not found or is
* not an ItemStack.
* @return Requested ItemStack. * @return Requested ItemStack.
*/ */
public ItemStack getItemStack(String path, ItemStack def); public ItemStack getItemStack(String path, ItemStack def);
@ -656,10 +698,10 @@ public interface ConfigurationSection {
/** /**
* Checks if the specified path is an ItemStack. * Checks if the specified path is an ItemStack.
* <p> * <p>
* If the path exists but is not a ItemStack, this will return false. If the path does not * If the path exists but is not a ItemStack, this will return false. If
* exist, this will return false. If the path does not exist but a default value * the path does not exist, this will return false. If the path does not
* has been specified, this will check if that default value is a ItemStack and return * exist but a default value has been specified, this will check if that
* appropriately. * default value is a ItemStack and return appropriately.
* *
* @param path Path of the ItemStack to check. * @param path Path of the ItemStack to check.
* @return Whether or not the specified path is an ItemStack. * @return Whether or not the specified path is an ItemStack.
@ -669,9 +711,9 @@ public interface ConfigurationSection {
/** /**
* Gets the requested Color by path. * Gets the requested Color by path.
* <p> * <p>
* If the Color does not exist but a default value has been specified, this * If the Color does not exist but a default value has been specified,
* will return the default value. If the Color does not exist and no default * this will return the default value. If the Color does not exist and no
* value was specified, this will return null. * default value was specified, this will return null.
* *
* @param path Path of the Color to get. * @param path Path of the Color to get.
* @return Requested Color. * @return Requested Color.
@ -679,13 +721,16 @@ public interface ConfigurationSection {
public Color getColor(String path); public Color getColor(String path);
/** /**
* Gets the requested {@link Color} by path, returning a default value if not found. * Gets the requested {@link Color} by path, returning a default value if
* not found.
* <p> * <p>
* If the Color does not exist then the specified default value will returned * If the Color does not exist then the specified default value will
* regardless of if a default has been identified in the root {@link Configuration}. * returned regardless of if a default has been identified in the root
* {@link Configuration}.
* *
* @param path Path of the Color to get. * @param path Path of the Color to get.
* @param def The default value to return if the path is not found or is not an Color. * @param def The default value to return if the path is not found or is
* not a Color.
* @return Requested Color. * @return Requested Color.
*/ */
public Color getColor(String path, Color def); public Color getColor(String path, Color def);
@ -693,22 +738,23 @@ public interface ConfigurationSection {
/** /**
* Checks if the specified path is a Color. * Checks if the specified path is a Color.
* <p> * <p>
* If the path exists but is not a Color, this will return false. If the path does not * If the path exists but is not a Color, this will return false. If the
* exist, this will return false. If the path does not exist but a default value * path does not exist, this will return false. If the path does not exist
* has been specified, this will check if that default value is a Color and return * but a default value has been specified, this will check if that default
* appropriately. * value is a Color and return appropriately.
* *
* @param path Path of the Color to check. * @param path Path of the Color to check.
* @return Whether or not the specified path is an Color. * @return Whether or not the specified path is a Color.
*/ */
public boolean isColor(String path); public boolean isColor(String path);
/** /**
* Gets the requested ConfigurationSection by path. * Gets the requested ConfigurationSection by path.
* <p> * <p>
* If the ConfigurationSection does not exist but a default value has been specified, this * If the ConfigurationSection does not exist but a default value has been
* will return the default value. If the ConfigurationSection does not exist and no default * specified, this will return the default value. If the
* value was specified, this will return null. * ConfigurationSection does not exist and no default value was specified,
* this will return null.
* *
* @param path Path of the ConfigurationSection to get. * @param path Path of the ConfigurationSection to get.
* @return Requested ConfigurationSection. * @return Requested ConfigurationSection.
@ -718,9 +764,10 @@ public interface ConfigurationSection {
/** /**
* Checks if the specified path is a ConfigurationSection. * Checks if the specified path is a ConfigurationSection.
* <p> * <p>
* If the path exists but is not a ConfigurationSection, this will return false. If the path does not * If the path exists but is not a ConfigurationSection, this will return
* exist, this will return false. If the path does not exist but a default value * false. If the path does not exist, this will return false. If the path
* has been specified, this will check if that default value is a ConfigurationSection and return * does not exist but a default value has been specified, this will check
* if that default value is a ConfigurationSection and return
* appropriately. * appropriately.
* *
* @param path Path of the ConfigurationSection to check. * @param path Path of the ConfigurationSection to check.
@ -729,11 +776,12 @@ public interface ConfigurationSection {
public boolean isConfigurationSection(String path); public boolean isConfigurationSection(String path);
/** /**
* Gets the equivalent {@link ConfigurationSection} from the default {@link Configuration} defined in {@link #getRoot()}. * Gets the equivalent {@link ConfigurationSection} from the default
* {@link Configuration} defined in {@link #getRoot()}.
* <p> * <p>
* If the root contains no defaults, or the defaults doesn't contain a value * If the root contains no defaults, or the defaults doesn't contain a
* for this path, or the value at this path is not a {@link ConfigurationSection} then * value for this path, or the value at this path is not a {@link
* this will return null. * ConfigurationSection} then this will return null.
* *
* @return Equivalent section in root configuration * @return Equivalent section in root configuration
*/ */
@ -742,15 +790,16 @@ public interface ConfigurationSection {
/** /**
* Sets the default value in the root at the given path as provided. * Sets the default value in the root at the given path as provided.
* <p> * <p>
* If no source {@link Configuration} was provided as a default collection, * If no source {@link Configuration} was provided as a default
* then a new {@link MemoryConfiguration} will be created to hold the new default * collection, then a new {@link MemoryConfiguration} will be created to
* value. * hold the new default value.
* <p> * <p>
* If value is null, the value will be removed from the default Configuration source. * If value is null, the value will be removed from the default
* Configuration source.
* <p> * <p>
* If the value as returned by {@link #getDefaultSection()} is null, * If the value as returned by {@link #getDefaultSection()} is null, then
* then this will create a new section at the path, replacing anything that * this will create a new section at the path, replacing anything that may
* may have existed there previously. * have existed there previously.
* *
* @param path Path of the value to set. * @param path Path of the value to set.
* @param value Value to set the default to. * @param value Value to set the default to.

12
paper-api/src/main/java/org/bukkit/configuration/InvalidConfigurationException.java
View File

@ -7,12 +7,14 @@ package org.bukkit.configuration;
public class InvalidConfigurationException extends Exception { public class InvalidConfigurationException extends Exception {
/** /**
* Creates a new instance of InvalidConfigurationException without a message or cause. * Creates a new instance of InvalidConfigurationException without a
* message or cause.
*/ */
public InvalidConfigurationException() {} public InvalidConfigurationException() {}
/** /**
* Constructs an instance of InvalidConfigurationException with the specified message. * Constructs an instance of InvalidConfigurationException with the
* specified message.
* *
* @param msg The details of the exception. * @param msg The details of the exception.
*/ */
@ -21,7 +23,8 @@ public class InvalidConfigurationException extends Exception {
} }
/** /**
* Constructs an instance of InvalidConfigurationException with the specified cause. * Constructs an instance of InvalidConfigurationException with the
* specified cause.
* *
* @param cause The cause of the exception. * @param cause The cause of the exception.
*/ */
@ -30,7 +33,8 @@ public class InvalidConfigurationException extends Exception {
} }
/** /**
* Constructs an instance of InvalidConfigurationException with the specified message and cause. * Constructs an instance of InvalidConfigurationException with the
* specified message and cause.
* *
* @param cause The cause of the exception. * @param cause The cause of the exception.
* @param msg The details of the exception. * @param msg The details of the exception.

4
paper-api/src/main/java/org/bukkit/configuration/MemoryConfiguration.java
View File

@ -19,8 +19,8 @@ public class MemoryConfiguration extends MemorySection implements Configuration
public MemoryConfiguration() {} public MemoryConfiguration() {}
/** /**
* Creates an empty {@link MemoryConfiguration} using the specified {@link Configuration} * Creates an empty {@link MemoryConfiguration} using the specified {@link
* as a source for all default values. * Configuration} as a source for all default values.
* *
* @param defaults Default value provider * @param defaults Default value provider
* @throws IllegalArgumentException Thrown if defaults is null * @throws IllegalArgumentException Thrown if defaults is null

3
paper-api/src/main/java/org/bukkit/configuration/MemoryConfigurationOptions.java
View File

@ -1,7 +1,8 @@
package org.bukkit.configuration; package org.bukkit.configuration;
/** /**
* Various settings for controlling the input and output of a {@link MemoryConfiguration} * Various settings for controlling the input and output of a {@link
* MemoryConfiguration}
*/ */
public class MemoryConfigurationOptions extends ConfigurationOptions { public class MemoryConfigurationOptions extends ConfigurationOptions {
protected MemoryConfigurationOptions(MemoryConfiguration configuration) { protected MemoryConfigurationOptions(MemoryConfiguration configuration) {

28
paper-api/src/main/java/org/bukkit/configuration/MemorySection.java
View File

@ -26,12 +26,14 @@ public class MemorySection implements ConfigurationSection {
private final String fullPath; private final String fullPath;
/** /**
* Creates an empty MemorySection for use as a root {@link Configuration} section. * Creates an empty MemorySection for use as a root {@link Configuration}
* section.
* <p> * <p>
* Note that calling this without being yourself a {@link Configuration} will throw an * Note that calling this without being yourself a {@link Configuration}
* exception! * will throw an exception!
* *
* @throws IllegalStateException Thrown if this is not a {@link Configuration} root. * @throws IllegalStateException Thrown if this is not a {@link
* Configuration} root.
*/ */
protected MemorySection() { protected MemorySection() {
if (!(this instanceof Configuration)) { if (!(this instanceof Configuration)) {
@ -48,8 +50,10 @@ public class MemorySection implements ConfigurationSection {
* Creates an empty MemorySection with the specified parent and path. * Creates an empty MemorySection with the specified parent and path.
* *
* @param parent Parent section that contains this own section. * @param parent Parent section that contains this own section.
* @param path Path that you may access this section from via the root {@link Configuration}. * @param path Path that you may access this section from via the root
* @throws IllegalArgumentException Thrown is parent or path is null, or if parent contains no root Configuration. * {@link Configuration}.
* @throws IllegalArgumentException Thrown is parent or path is null, or
* if parent contains no root Configuration.
*/ */
protected MemorySection(ConfigurationSection parent, String path) { protected MemorySection(ConfigurationSection parent, String path) {
Validate.notNull(parent, "Parent cannot be null"); Validate.notNull(parent, "Parent cannot be null");
@ -745,9 +749,11 @@ public class MemorySection implements ConfigurationSection {
} }
/** /**
* Creates a full path to the given {@link ConfigurationSection} from its root {@link Configuration}. * Creates a full path to the given {@link ConfigurationSection} from its
* root {@link Configuration}.
* <p> * <p>
* You may use this method for any given {@link ConfigurationSection}, not only {@link MemorySection}. * You may use this method for any given {@link ConfigurationSection}, not
* only {@link MemorySection}.
* *
* @param section Section to create a path for. * @param section Section to create a path for.
* @param key Name of the specified section. * @param key Name of the specified section.
@ -758,9 +764,11 @@ public class MemorySection implements ConfigurationSection {
} }
/** /**
* Creates a relative path to the given {@link ConfigurationSection} from the given relative section. * Creates a relative path to the given {@link ConfigurationSection} from
* the given relative section.
* <p> * <p>
* You may use this method for any given {@link ConfigurationSection}, not only {@link MemorySection}. * You may use this method for any given {@link ConfigurationSection}, not
* only {@link MemorySection}.
* *
* @param section Section to create a path for. * @param section Section to create a path for.
* @param key Name of the specified section. * @param key Name of the specified section.

78
paper-api/src/main/java/org/bukkit/configuration/file/FileConfiguration.java
View File

@ -16,7 +16,8 @@ import org.bukkit.configuration.Configuration;
import org.bukkit.configuration.MemoryConfiguration; import org.bukkit.configuration.MemoryConfiguration;
/** /**
* This is a base class for all File based implementations of {@link Configuration} * This is a base class for all File based implementations of {@link
* Configuration}
*/ */
public abstract class FileConfiguration extends MemoryConfiguration { public abstract class FileConfiguration extends MemoryConfiguration {
/** /**
@ -27,8 +28,8 @@ public abstract class FileConfiguration extends MemoryConfiguration {
} }
/** /**
* Creates an empty {@link FileConfiguration} using the specified {@link Configuration} * Creates an empty {@link FileConfiguration} using the specified {@link
* as a source for all default values. * Configuration} as a source for all default values.
* *
* @param defaults Default value provider * @param defaults Default value provider
*/ */
@ -39,11 +40,13 @@ public abstract class FileConfiguration extends MemoryConfiguration {
/** /**
* Saves this {@link FileConfiguration} to the specified location. * Saves this {@link FileConfiguration} to the specified location.
* <p> * <p>
* If the file does not exist, it will be created. If already exists, it will * If the file does not exist, it will be created. If already exists, it
* be overwritten. If it cannot be overwritten or created, an exception will be thrown. * will be overwritten. If it cannot be overwritten or created, an
* exception will be thrown.
* *
* @param file File to save to. * @param file File to save to.
* @throws IOException Thrown when the given file cannot be written to for any reason. * @throws IOException Thrown when the given file cannot be written to for
* any reason.
* @throws IllegalArgumentException Thrown when file is null. * @throws IllegalArgumentException Thrown when file is null.
*/ */
public void save(File file) throws IOException { public void save(File file) throws IOException {
@ -65,11 +68,13 @@ public abstract class FileConfiguration extends MemoryConfiguration {
/** /**
* Saves this {@link FileConfiguration} to the specified location. * Saves this {@link FileConfiguration} to the specified location.
* <p> * <p>
* If the file does not exist, it will be created. If already exists, it will * If the file does not exist, it will be created. If already exists, it
* be overwritten. If it cannot be overwritten or created, an exception will be thrown. * will be overwritten. If it cannot be overwritten or created, an
* exception will be thrown.
* *
* @param file File to save to. * @param file File to save to.
* @throws IOException Thrown when the given file cannot be written to for any reason. * @throws IOException Thrown when the given file cannot be written to for
* any reason.
* @throws IllegalArgumentException Thrown when file is null. * @throws IllegalArgumentException Thrown when file is null.
*/ */
public void save(String file) throws IOException { public void save(String file) throws IOException {
@ -88,15 +93,19 @@ public abstract class FileConfiguration extends MemoryConfiguration {
/** /**
* Loads this {@link FileConfiguration} from the specified location. * Loads this {@link FileConfiguration} from the specified location.
* <p> * <p>
* All the values contained within this configuration will be removed, leaving * All the values contained within this configuration will be removed,
* only settings and defaults, and the new values will be loaded from the given file. * leaving only settings and defaults, and the new values will be loaded
* from the given file.
* <p> * <p>
* If the file cannot be loaded for any reason, an exception will be thrown. * If the file cannot be loaded for any reason, an exception will be
* thrown.
* *
* @param file File to load from. * @param file File to load from.
* @throws FileNotFoundException Thrown when the given file cannot be opened. * @throws FileNotFoundException Thrown when the given file cannot be
* opened.
* @throws IOException Thrown when the given file cannot be read. * @throws IOException Thrown when the given file cannot be read.
* @throws InvalidConfigurationException Thrown when the given file is not a valid Configuration. * @throws InvalidConfigurationException Thrown when the given file is not
* a valid Configuration.
* @throws IllegalArgumentException Thrown when file is null. * @throws IllegalArgumentException Thrown when file is null.
*/ */
public void load(File file) throws FileNotFoundException, IOException, InvalidConfigurationException { public void load(File file) throws FileNotFoundException, IOException, InvalidConfigurationException {
@ -108,12 +117,14 @@ public abstract class FileConfiguration extends MemoryConfiguration {
/** /**
* Loads this {@link FileConfiguration} from the specified stream. * Loads this {@link FileConfiguration} from the specified stream.
* <p> * <p>
* All the values contained within this configuration will be removed, leaving * All the values contained within this configuration will be removed,
* only settings and defaults, and the new values will be loaded from the given stream. * leaving only settings and defaults, and the new values will be loaded
* from the given stream.
* *
* @param stream Stream to load from * @param stream Stream to load from
* @throws IOException Thrown when the given file cannot be read. * @throws IOException Thrown when the given file cannot be read.
* @throws InvalidConfigurationException Thrown when the given file is not a valid Configuration. * @throws InvalidConfigurationException Thrown when the given file is not
* a valid Configuration.
* @throws IllegalArgumentException Thrown when stream is null. * @throws IllegalArgumentException Thrown when stream is null.
*/ */
public void load(InputStream stream) throws IOException, InvalidConfigurationException { public void load(InputStream stream) throws IOException, InvalidConfigurationException {
@ -141,15 +152,19 @@ public abstract class FileConfiguration extends MemoryConfiguration {
/** /**
* Loads this {@link FileConfiguration} from the specified location. * Loads this {@link FileConfiguration} from the specified location.
* <p> * <p>
* All the values contained within this configuration will be removed, leaving * All the values contained within this configuration will be removed,
* only settings and defaults, and the new values will be loaded from the given file. * leaving only settings and defaults, and the new values will be loaded
* from the given file.
* <p> * <p>
* If the file cannot be loaded for any reason, an exception will be thrown. * If the file cannot be loaded for any reason, an exception will be
* thrown.
* *
* @param file File to load from. * @param file File to load from.
* @throws FileNotFoundException Thrown when the given file cannot be opened. * @throws FileNotFoundException Thrown when the given file cannot be
* opened.
* @throws IOException Thrown when the given file cannot be read. * @throws IOException Thrown when the given file cannot be read.
* @throws InvalidConfigurationException Thrown when the given file is not a valid Configuration. * @throws InvalidConfigurationException Thrown when the given file is not
* a valid Configuration.
* @throws IllegalArgumentException Thrown when file is null. * @throws IllegalArgumentException Thrown when file is null.
*/ */
public void load(String file) throws FileNotFoundException, IOException, InvalidConfigurationException { public void load(String file) throws FileNotFoundException, IOException, InvalidConfigurationException {
@ -159,24 +174,29 @@ public abstract class FileConfiguration extends MemoryConfiguration {
} }
/** /**
* Loads this {@link FileConfiguration} from the specified string, as opposed to from file. * Loads this {@link FileConfiguration} from the specified string, as
* opposed to from file.
* <p> * <p>
* All the values contained within this configuration will be removed, leaving * All the values contained within this configuration will be removed,
* only settings and defaults, and the new values will be loaded from the given string. * leaving only settings and defaults, and the new values will be loaded
* from the given string.
* <p> * <p>
* If the string is invalid in any way, an exception will be thrown. * If the string is invalid in any way, an exception will be thrown.
* *
* @param contents Contents of a Configuration to load. * @param contents Contents of a Configuration to load.
* @throws InvalidConfigurationException Thrown if the specified string is invalid. * @throws InvalidConfigurationException Thrown if the specified string is
* invalid.
* @throws IllegalArgumentException Thrown if contents is null. * @throws IllegalArgumentException Thrown if contents is null.
*/ */
public abstract void loadFromString(String contents) throws InvalidConfigurationException; public abstract void loadFromString(String contents) throws InvalidConfigurationException;
/** /**
* Compiles the header for this {@link FileConfiguration} and returns the result. * Compiles the header for this {@link FileConfiguration} and returns the
* result.
* <p> * <p>
* This will use the header from {@link #options()} -> {@link FileConfigurationOptions#header()}, * This will use the header from {@link #options()} -> {@link
* respecting the rules of {@link FileConfigurationOptions#copyHeader()} if set. * FileConfigurationOptions#header()}, respecting the rules of {@link
* FileConfigurationOptions#copyHeader()} if set.
* *
* @return Compiled header * @return Compiled header
*/ */

54
paper-api/src/main/java/org/bukkit/configuration/file/FileConfigurationOptions.java
View File

@ -3,7 +3,8 @@ package org.bukkit.configuration.file;
import org.bukkit.configuration.*; import org.bukkit.configuration.*;
/** /**
* Various settings for controlling the input and output of a {@link FileConfiguration} * Various settings for controlling the input and output of a {@link
* FileConfiguration}
*/ */
public class FileConfigurationOptions extends MemoryConfigurationOptions { public class FileConfigurationOptions extends MemoryConfigurationOptions {
private String header = null; private String header = null;
@ -33,13 +34,14 @@ public class FileConfigurationOptions extends MemoryConfigurationOptions {
/** /**
* Gets the header that will be applied to the top of the saved output. * Gets the header that will be applied to the top of the saved output.
* <p> * <p>
* This header will be commented out and applied directly at the top of the * This header will be commented out and applied directly at the top of
* generated output of the {@link FileConfiguration}. It is not required to * the generated output of the {@link FileConfiguration}. It is not
* include a newline at the end of the header as it will automatically be applied, * required to include a newline at the end of the header as it will
* but you may include one if you wish for extra spacing. * automatically be applied, but you may include one if you wish for extra
* spacing.
* <p> * <p>
* Null is a valid value which will indicate that no header is to be applied. * Null is a valid value which will indicate that no header is to be
* The default value is null. * applied. The default value is null.
* *
* @return Header * @return Header
*/ */
@ -50,12 +52,14 @@ public class FileConfigurationOptions extends MemoryConfigurationOptions {
/** /**
* Sets the header that will be applied to the top of the saved output. * Sets the header that will be applied to the top of the saved output.
* <p> * <p>
* This header will be commented out and applied directly at the top of the * This header will be commented out and applied directly at the top of
* generated output of the {@link FileConfiguration}. It is not required to * the generated output of the {@link FileConfiguration}. It is not
* include a newline at the end of the header as it will automatically be applied, * required to include a newline at the end of the header as it will
* but you may include one if you wish for extra spacing. * automatically be applied, but you may include one if you wish for extra
* spacing.
* <p> * <p>
* Null is a valid value which will indicate that no header is to be applied. * Null is a valid value which will indicate that no header is to be
* applied.
* *
* @param value New header * @param value New header
* @return This object, for chaining * @return This object, for chaining
@ -69,12 +73,15 @@ public class FileConfigurationOptions extends MemoryConfigurationOptions {
* Gets whether or not the header should be copied from a default source. * Gets whether or not the header should be copied from a default source.
* <p> * <p>
* If this is true, if a default {@link FileConfiguration} is passed to * If this is true, if a default {@link FileConfiguration} is passed to
* {@link FileConfiguration#setDefaults(org.bukkit.configuration.Configuration)} * {@link
* then upon saving it will use the header from that config, instead of the one provided here. * FileConfiguration#setDefaults(org.bukkit.configuration.Configuration)}
* then upon saving it will use the header from that config, instead of
* the one provided here.
* <p> * <p>
* If no default is set on the configuration, or the default is not of type FileConfiguration, * If no default is set on the configuration, or the default is not of
* or that config has no header ({@link #header()} returns null) then the header * type FileConfiguration, or that config has no header ({@link #header()}
* specified in this configuration will be used. * returns null) then the header specified in this configuration will be
* used.
* <p> * <p>
* Defaults to true. * Defaults to true.
* *
@ -88,12 +95,15 @@ public class FileConfigurationOptions extends MemoryConfigurationOptions {
* Sets whether or not the header should be copied from a default source. * Sets whether or not the header should be copied from a default source.
* <p> * <p>
* If this is true, if a default {@link FileConfiguration} is passed to * If this is true, if a default {@link FileConfiguration} is passed to
* {@link FileConfiguration#setDefaults(org.bukkit.configuration.Configuration)} * {@link
* then upon saving it will use the header from that config, instead of the one provided here. * FileConfiguration#setDefaults(org.bukkit.configuration.Configuration)}
* then upon saving it will use the header from that config, instead of
* the one provided here.
* <p> * <p>
* If no default is set on the configuration, or the default is not of type FileConfiguration, * If no default is set on the configuration, or the default is not of
* or that config has no header ({@link #header()} returns null) then the header * type FileConfiguration, or that config has no header ({@link #header()}
* specified in this configuration will be used. * returns null) then the header specified in this configuration will be
* used.
* <p> * <p>
* Defaults to true. * Defaults to true.
* *

6
paper-api/src/main/java/org/bukkit/configuration/file/YamlConfiguration.java
View File

@ -160,7 +160,8 @@ public class YamlConfiguration extends FileConfiguration {
* Creates a new {@link YamlConfiguration}, loading from the given file. * Creates a new {@link YamlConfiguration}, loading from the given file.
* <p> * <p>
* Any errors loading the Configuration will be logged and then ignored. * Any errors loading the Configuration will be logged and then ignored.
* If the specified input is not a valid config, a blank config will be returned. * If the specified input is not a valid config, a blank config will be
* returned.
* *
* @param file Input file * @param file Input file
* @return Resulting configuration * @return Resulting configuration
@ -187,7 +188,8 @@ public class YamlConfiguration extends FileConfiguration {
* Creates a new {@link YamlConfiguration}, loading from the given stream. * Creates a new {@link YamlConfiguration}, loading from the given stream.
* <p> * <p>
* Any errors loading the Configuration will be logged and then ignored. * Any errors loading the Configuration will be logged and then ignored.
* If the specified input is not a valid config, a blank config will be returned. * If the specified input is not a valid config, a blank config will be
* returned.
* *
* @param stream Input stream * @param stream Input stream
* @return Resulting configuration * @return Resulting configuration

3
paper-api/src/main/java/org/bukkit/configuration/file/YamlConfigurationOptions.java
View File

@ -3,7 +3,8 @@ package org.bukkit.configuration.file;
import org.apache.commons.lang.Validate; import org.apache.commons.lang.Validate;
/** /**
* Various settings for controlling the input and output of a {@link YamlConfiguration} * Various settings for controlling the input and output of a {@link
* YamlConfiguration}
*/ */
public class YamlConfigurationOptions extends FileConfigurationOptions { public class YamlConfigurationOptions extends FileConfigurationOptions {
private int indent = 2; private int indent = 2;

23
paper-api/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerializable.java
View File

@ -5,17 +5,18 @@ import java.util.Map;
/** /**
* Represents an object that may be serialized. * Represents an object that may be serialized.
* <p> * <p>
* These objects MUST implement one of the following, in addition to the methods * These objects MUST implement one of the following, in addition to the
* as defined by this interface: * methods as defined by this interface:
* <ul> * <ul>
* <li>A static method "deserialize" that accepts a single {@link Map}&lt;{@link String}, {@link Object}> * <li>A static method "deserialize" that accepts a single {@link Map}&lt;
* and returns the class.</li> * {@link String}, {@link Object}> and returns the class.</li>
* <li>A static method "valueOf" that accepts a single {@link Map}&lt;{@link String}, {@link Object}> * <li>A static method "valueOf" that accepts a single {@link Map}&lt;{@link
* and returns the class.</li> * String}, {@link Object}> and returns the class.</li>
* <li>A constructor that accepts a single {@link Map}&lt;{@link String}, {@link Object}>.</li> * <li>A constructor that accepts a single {@link Map}&lt;{@link String},
* {@link Object}>.</li>
* </ul> * </ul>
* In addition to implementing this interface, you must register the class with * In addition to implementing this interface, you must register the class
* {@link ConfigurationSerialization#registerClass(Class)}. * with {@link ConfigurationSerialization#registerClass(Class)}.
* *
* @see DelegateDeserialization * @see DelegateDeserialization
* @see SerializableAs * @see SerializableAs
@ -25,8 +26,8 @@ public interface ConfigurationSerializable {
/** /**
* Creates a Map representation of this class. * Creates a Map representation of this class.
* <p> * <p>
* This class must provide a method to restore this class, as defined in the * This class must provide a method to restore this class, as defined in
* {@link ConfigurationSerializable} interface javadocs. * the {@link ConfigurationSerializable} interface javadocs.
* *
* @return Map containing the current state of this class * @return Map containing the current state of this class
*/ */

39
paper-api/src/main/java/org/bukkit/configuration/serialization/ConfigurationSerialization.java
View File

@ -134,13 +134,15 @@ public class ConfigurationSerialization {
} }
/** /**
* Attempts to deserialize the given arguments into a new instance of the given class. * Attempts to deserialize the given arguments into a new instance of the
* given class.
* <p> * <p>
* The class must implement {@link ConfigurationSerializable}, including the extra methods * The class must implement {@link ConfigurationSerializable}, including
* as specified in the javadoc of ConfigurationSerializable. * the extra methods as specified in the javadoc of
* ConfigurationSerializable.
* <p> * <p>
* If a new instance could not be made, an example being the class not fully implementing * If a new instance could not be made, an example being the class not
* the interface, null will be returned. * fully implementing the interface, null will be returned.
* *
* @param args Arguments for deserialization * @param args Arguments for deserialization
* @param clazz Class to deserialize into * @param clazz Class to deserialize into
@ -151,13 +153,15 @@ public class ConfigurationSerialization {
} }
/** /**
* Attempts to deserialize the given arguments into a new instance of the given class. * Attempts to deserialize the given arguments into a new instance of the
* given class.
* <p> * <p>
* The class must implement {@link ConfigurationSerializable}, including the extra methods * The class must implement {@link ConfigurationSerializable}, including
* as specified in the javadoc of ConfigurationSerializable. * the extra methods as specified in the javadoc of
* ConfigurationSerializable.
* <p> * <p>
* If a new instance could not be made, an example being the class not fully implementing * If a new instance could not be made, an example being the class not
* the interface, null will be returned. * fully implementing the interface, null will be returned.
* *
* @param args Arguments for deserialization * @param args Arguments for deserialization
* @return New instance of the specified class * @return New instance of the specified class
@ -188,7 +192,8 @@ public class ConfigurationSerialization {
} }
/** /**
* Registers the given {@link ConfigurationSerializable} class by its alias * Registers the given {@link ConfigurationSerializable} class by its
* alias
* *
* @param clazz Class to register * @param clazz Class to register
*/ */
@ -202,7 +207,8 @@ public class ConfigurationSerialization {
} }
/** /**
* Registers the given alias to the specified {@link ConfigurationSerializable} class * Registers the given alias to the specified {@link
* ConfigurationSerializable} class
* *
* @param clazz Class to register * @param clazz Class to register
* @param alias Alias to register as * @param alias Alias to register as
@ -222,7 +228,8 @@ public class ConfigurationSerialization {
} }
/** /**
* Unregisters any aliases for the specified {@link ConfigurationSerializable} class * Unregisters any aliases for the specified {@link
* ConfigurationSerializable} class
* *
* @param clazz Class to unregister * @param clazz Class to unregister
*/ */
@ -233,7 +240,8 @@ public class ConfigurationSerialization {
} }
/** /**
* Attempts to get a registered {@link ConfigurationSerializable} class by its alias * Attempts to get a registered {@link ConfigurationSerializable} class by
* its alias
* *
* @param alias Alias of the serializable * @param alias Alias of the serializable
* @return Registered class, or null if not found * @return Registered class, or null if not found
@ -243,7 +251,8 @@ public class ConfigurationSerialization {
} }
/** /**
* Gets the correct alias for the given {@link ConfigurationSerializable} class * Gets the correct alias for the given {@link ConfigurationSerializable}
* class
* *
* @param clazz Class to get alias for * @param clazz Class to get alias for
* @return Alias to use for the class * @return Alias to use for the class

7
paper-api/src/main/java/org/bukkit/configuration/serialization/DelegateDeserialization.java
View File

@ -6,14 +6,15 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target; import java.lang.annotation.Target;
/** /**
* Applies to a {@link ConfigurationSerializable} that will delegate all deserialization to another * Applies to a {@link ConfigurationSerializable} that will delegate all
* {@link ConfigurationSerializable}. * deserialization to another {@link ConfigurationSerializable}.
*/ */
@Retention(RetentionPolicy.RUNTIME) @Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE) @Target(ElementType.TYPE)
public @interface DelegateDeserialization { public @interface DelegateDeserialization {
/** /**
* Which class should be used as a delegate for this classes deserialization * Which class should be used as a delegate for this classes
* deserialization
* *
* @return Delegate class * @return Delegate class
*/ */

19
paper-api/src/main/java/org/bukkit/configuration/serialization/SerializableAs.java
View File

@ -6,15 +6,16 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target; import java.lang.annotation.Target;
/** /**
* Represents an "alias" that a {@link ConfigurationSerializable} may be stored as. * Represents an "alias" that a {@link ConfigurationSerializable} may be
* If this is not present on a {@link ConfigurationSerializable} class, it will use the * stored as.
* fully qualified name of the class. * If this is not present on a {@link ConfigurationSerializable} class, it
* will use the fully qualified name of the class.
* <p> * <p>
* This value will be stored in the configuration so that the configuration deserialization * This value will be stored in the configuration so that the configuration
* can determine what type it is. * deserialization can determine what type it is.
* <p> * <p>
* Using this annotation on any other class than a {@link ConfigurationSerializable} will * Using this annotation on any other class than a {@link
* have no effect. * ConfigurationSerializable} will have no effect.
* *
* @see ConfigurationSerialization#registerClass(Class, String) * @see ConfigurationSerialization#registerClass(Class, String)
*/ */
@ -24,8 +25,8 @@ public @interface SerializableAs {
/** /**
* This is the name your class will be stored and retrieved as. * This is the name your class will be stored and retrieved as.
* <p> * <p>
* This name MUST be unique. We recommend using names such as "MyPluginThing" instead of * This name MUST be unique. We recommend using names such as
* "Thing". * "MyPluginThing" instead of "Thing".
* *
* @return Name to serialize the class as. * @return Name to serialize the class as.
*/ */

6
paper-api/src/main/java/org/bukkit/conversations/BooleanPrompt.java
View File

@ -4,7 +4,8 @@ import org.apache.commons.lang.ArrayUtils;
import org.apache.commons.lang.BooleanUtils; import org.apache.commons.lang.BooleanUtils;
/** /**
* BooleanPrompt is the base class for any prompt that requires a boolean response from the user. * BooleanPrompt is the base class for any prompt that requires a boolean
* response from the user.
*/ */
public abstract class BooleanPrompt extends ValidatingPrompt{ public abstract class BooleanPrompt extends ValidatingPrompt{
@ -24,7 +25,8 @@ public abstract class BooleanPrompt extends ValidatingPrompt{
} }
/** /**
* Override this method to perform some action with the user's boolean response. * Override this method to perform some action with the user's boolean
* response.
* *
* @param context Context information about the conversation. * @param context Context information about the conversation.
* @param input The user's boolean response. * @param input The user's boolean response.

13
paper-api/src/main/java/org/bukkit/conversations/Conversable.java
View File

@ -3,20 +3,22 @@ package org.bukkit.conversations;
import org.bukkit.command.CommandSender; import org.bukkit.command.CommandSender;
/** /**
* The Conversable interface is used to indicate objects that can have conversations. * The Conversable interface is used to indicate objects that can have
* conversations.
*/ */
public interface Conversable { public interface Conversable {
/** /**
* Tests to see of a Conversable object is actively engaged in a conversation. * Tests to see of a Conversable object is actively engaged in a
* conversation.
* *
* @return True if a conversation is in progress * @return True if a conversation is in progress
*/ */
public boolean isConversing(); public boolean isConversing();
/** /**
* Accepts input into the active conversation. If no conversation is in progress, * Accepts input into the active conversation. If no conversation is in
* this method does nothing. * progress, this method does nothing.
* *
* @param input The input message into the conversation * @param input The input message into the conversation
*/ */
@ -26,7 +28,8 @@ public interface Conversable {
* Enters into a dialog with a Conversation object. * Enters into a dialog with a Conversation object.
* *
* @param conversation The conversation to begin * @param conversation The conversation to begin
* @return True if the conversation should proceed, false if it has been enqueued * @return True if the conversation should proceed, false if it has been
* enqueued
*/ */
public boolean beginConversation(Conversation conversation); public boolean beginConversation(Conversation conversation);

82
paper-api/src/main/java/org/bukkit/conversations/Conversation.java
View File

@ -8,23 +8,29 @@ import java.util.List;
import java.util.Map; import java.util.Map;
/** /**
* The Conversation class is responsible for tracking the current state of a conversation, displaying prompts to * The Conversation class is responsible for tracking the current state of a
* the user, and dispatching the user's response to the appropriate place. Conversation objects are not typically * conversation, displaying prompts to the user, and dispatching the user's
* instantiated directly. Instead a {@link ConversationFactory} is used to construct identical conversations on demand. * response to the appropriate place. Conversation objects are not typically
* instantiated directly. Instead a {@link ConversationFactory} is used to
* construct identical conversations on demand.
* <p> * <p>
* Conversation flow consists of a directed graph of {@link Prompt} objects. Each time a prompt gets input from the * Conversation flow consists of a directed graph of {@link Prompt} objects.
* user, it must return the next prompt in the graph. Since each Prompt chooses the next Prompt, complex conversation * Each time a prompt gets input from the user, it must return the next prompt
* trees can be implemented where the nature of the player's response directs the flow of the conversation. * in the graph. Since each Prompt chooses the next Prompt, complex
* conversation trees can be implemented where the nature of the player's
* response directs the flow of the conversation.
* <p> * <p>
* Each conversation has a {@link ConversationPrefix} that prepends all output from the conversation to the player. * Each conversation has a {@link ConversationPrefix} that prepends all output
* The ConversationPrefix can be used to display the plugin name or conversation status as the conversation evolves. * from the conversation to the player. The ConversationPrefix can be used to
* display the plugin name or conversation status as the conversation evolves.
* <p> * <p>
* Each conversation has a timeout measured in the number of inactive seconds to wait before abandoning the conversation. * Each conversation has a timeout measured in the number of inactive seconds
* If the inactivity timeout is reached, the conversation is abandoned and the user's incoming and outgoing chat is * to wait before abandoning the conversation. If the inactivity timeout is
* returned to normal. * reached, the conversation is abandoned and the user's incoming and outgoing
* chat is returned to normal.
* <p> * <p>
* You should not construct a conversation manually. Instead, use the {@link ConversationFactory} for access to all * You should not construct a conversation manually. Instead, use the {@link
* available options. * ConversationFactory} for access to all available options.
*/ */
public class Conversation { public class Conversation {
@ -55,7 +61,8 @@ public class Conversation {
* @param plugin The plugin that owns this conversation. * @param plugin The plugin that owns this conversation.
* @param forWhom The entity for whom this conversation is mediating. * @param forWhom The entity for whom this conversation is mediating.
* @param firstPrompt The first prompt in the conversation graph. * @param firstPrompt The first prompt in the conversation graph.
* @param initialSessionData Any initial values to put in the conversation context sessionData map. * @param initialSessionData Any initial values to put in the conversation
* context sessionData map.
*/ */
public Conversation(Plugin plugin, Conversable forWhom, Prompt firstPrompt, Map<Object, Object> initialSessionData) { public Conversation(Plugin plugin, Conversable forWhom, Prompt firstPrompt, Map<Object, Object> initialSessionData) {
this.firstPrompt = firstPrompt; this.firstPrompt = firstPrompt;
@ -77,8 +84,9 @@ public class Conversation {
} }
/** /**
* Gets the modality of this conversation. If a conversation is modal, all messages directed to the player * Gets the modality of this conversation. If a conversation is modal, all
* are suppressed for the duration of the conversation. * messages directed to the player are suppressed for the duration of the
* conversation.
* *
* @return The conversation modality. * @return The conversation modality.
*/ */
@ -87,8 +95,9 @@ public class Conversation {
} }
/** /**
* Sets the modality of this conversation. If a conversation is modal, all messages directed to the player * Sets the modality of this conversation. If a conversation is modal,
* are suppressed for the duration of the conversation. * all messages directed to the player are suppressed for the duration of
* the conversation.
* *
* @param modal The new conversation modality. * @param modal The new conversation modality.
*/ */
@ -97,8 +106,9 @@ public class Conversation {
} }
/** /**
* Gets the status of local echo for this conversation. If local echo is enabled, any text submitted to a conversation * Gets the status of local echo for this conversation. If local echo is
* gets echoed back into the submitter's chat window. * enabled, any text submitted to a conversation gets echoed back into the
* submitter's chat window.
* *
* @return The status of local echo. * @return The status of local echo.
*/ */
@ -107,8 +117,9 @@ public class Conversation {
} }
/** /**
* Sets the status of local echo for this conversation. If local echo is enabled, any text submitted to a conversation * Sets the status of local echo for this conversation. If local echo is
* gets echoed back into the submitter's chat window. * enabled, any text submitted to a conversation gets echoed back into the
* submitter's chat window.
* *
* @param localEchoEnabled The status of local echo. * @param localEchoEnabled The status of local echo.
*/ */
@ -117,7 +128,8 @@ public class Conversation {
} }
/** /**
* Gets the {@link ConversationPrefix} that prepends all output from this conversation. * Gets the {@link ConversationPrefix} that prepends all output from this
* conversation.
* *
* @return The ConversationPrefix in use. * @return The ConversationPrefix in use.
*/ */
@ -126,7 +138,8 @@ public class Conversation {
} }
/** /**
* Sets the {@link ConversationPrefix} that prepends all output from this conversation. * Sets the {@link ConversationPrefix} that prepends all output from this
* conversation.
* *
* @param prefix The ConversationPrefix to use. * @param prefix The ConversationPrefix to use.
*/ */
@ -163,7 +176,8 @@ public class Conversation {
} }
/** /**
* Displays the first prompt of this conversation and begins redirecting the user's chat responses. * Displays the first prompt of this conversation and begins redirecting
* the user's chat responses.
*/ */
public void begin() { public void begin() {
if (currentPrompt == null) { if (currentPrompt == null) {
@ -175,6 +189,7 @@ public class Conversation {
/** /**
* Returns Returns the current state of the conversation. * Returns Returns the current state of the conversation.
*
* @return The current state of the conversation. * @return The current state of the conversation.
*/ */
public ConversationState getState() { public ConversationState getState() {
@ -188,8 +203,9 @@ public class Conversation {
} }
/** /**
* Passes player input into the current prompt. The next prompt (as determined by the current prompt) is then * Passes player input into the current prompt. The next prompt (as
* displayed to the user. * determined by the current prompt) is then displayed to the user.
*
* @param input The user's chat text. * @param input The user's chat text.
*/ */
public void acceptInput(String input) { public void acceptInput(String input) {
@ -216,6 +232,7 @@ public class Conversation {
/** /**
* Adds a {@link ConversationAbandonedListener}. * Adds a {@link ConversationAbandonedListener}.
*
* @param listener The listener to add. * @param listener The listener to add.
*/ */
public synchronized void addConversationAbandonedListener(ConversationAbandonedListener listener) { public synchronized void addConversationAbandonedListener(ConversationAbandonedListener listener) {
@ -224,6 +241,7 @@ public class Conversation {
/** /**
* Removes a {@link ConversationAbandonedListener}. * Removes a {@link ConversationAbandonedListener}.
*
* @param listener The listener to remove. * @param listener The listener to remove.
*/ */
public synchronized void removeConversationAbandonedListener(ConversationAbandonedListener listener) { public synchronized void removeConversationAbandonedListener(ConversationAbandonedListener listener) {
@ -231,14 +249,17 @@ public class Conversation {
} }
/** /**
* Abandons and resets the current conversation. Restores the user's normal chat behavior. * Abandons and resets the current conversation. Restores the user's
* normal chat behavior.
*/ */
public void abandon() { public void abandon() {
abandon(new ConversationAbandonedEvent(this, new ManuallyAbandonedConversationCanceller())); abandon(new ConversationAbandonedEvent(this, new ManuallyAbandonedConversationCanceller()));
} }
/** /**
* Abandons and resets the current conversation. Restores the user's normal chat behavior. * Abandons and resets the current conversation. Restores the user's
* normal chat behavior.
*
* @param details Details about why the conversation was abandoned * @param details Details about why the conversation was abandoned
*/ */
public synchronized void abandon(ConversationAbandonedEvent details) { public synchronized void abandon(ConversationAbandonedEvent details) {
@ -253,7 +274,8 @@ public class Conversation {
} }
/** /**
* Displays the next user prompt and abandons the conversation if the next prompt is null. * Displays the next user prompt and abandons the conversation if the next
* prompt is null.
*/ */
public void outputNextPrompt() { public void outputNextPrompt() {
if (currentPrompt == null) { if (currentPrompt == null) {

12
paper-api/src/main/java/org/bukkit/conversations/ConversationAbandonedEvent.java
View File

@ -3,7 +3,8 @@ package org.bukkit.conversations;
import java.util.EventObject; import java.util.EventObject;
/** /**
* ConversationAbandonedEvent contains information about an abandoned conversation. * ConversationAbandonedEvent contains information about an abandoned
* conversation.
*/ */
public class ConversationAbandonedEvent extends EventObject { public class ConversationAbandonedEvent extends EventObject {
@ -39,11 +40,12 @@ public class ConversationAbandonedEvent extends EventObject {
} }
/** /**
* Indicates how the conversation was abandoned - naturally as part of the prompt chain or prematurely via a * Indicates how the conversation was abandoned - naturally as part of the
* {@link ConversationCanceller}. * prompt chain or prematurely via a {@link ConversationCanceller}.
* *
* @return True if the conversation is abandoned gracefully by a {@link Prompt} returning null * @return True if the conversation is abandoned gracefully by a {@link
* or the next prompt. False of the conversations is abandoned prematurely by a ConversationCanceller. * Prompt} returning null or the next prompt. False of the
* conversations is abandoned prematurely by a ConversationCanceller.
*/ */
public boolean gracefulExit() { public boolean gracefulExit() {
return canceller == null; return canceller == null;

3
paper-api/src/main/java/org/bukkit/conversations/ConversationAbandonedListener.java
View File

@ -8,7 +8,8 @@ public interface ConversationAbandonedListener extends EventListener {
/** /**
* Called whenever a {@link Conversation} is abandoned. * Called whenever a {@link Conversation} is abandoned.
* *
* @param abandonedEvent Contains details about the abandoned conversation. * @param abandonedEvent Contains details about the abandoned
* conversation.
*/ */
public void conversationAbandoned(ConversationAbandonedEvent abandonedEvent); public void conversationAbandoned(ConversationAbandonedEvent abandonedEvent);
} }

7
paper-api/src/main/java/org/bukkit/conversations/ConversationCanceller.java
View File

@ -1,8 +1,8 @@
package org.bukkit.conversations; package org.bukkit.conversations;
/** /**
* A ConversationCanceller is a class that cancels an active {@link Conversation}. A Conversation can have more * A ConversationCanceller is a class that cancels an active {@link
* than one ConversationCanceller. * Conversation}. A Conversation can have more than one ConversationCanceller.
*/ */
public interface ConversationCanceller extends Cloneable { public interface ConversationCanceller extends Cloneable {
@ -23,7 +23,8 @@ public interface ConversationCanceller extends Cloneable {
public boolean cancelBasedOnInput(ConversationContext context, String input); public boolean cancelBasedOnInput(ConversationContext context, String input);
/** /**
* Allows the {@link ConversationFactory} to duplicate this ConversationCanceller when creating a new {@link Conversation}. * Allows the {@link ConversationFactory} to duplicate this
* ConversationCanceller when creating a new {@link Conversation}.
* <p> * <p>
* Implementing this method should reset any internal object state. * Implementing this method should reset any internal object state.
* *

18
paper-api/src/main/java/org/bukkit/conversations/ConversationContext.java
View File

@ -5,8 +5,9 @@ import org.bukkit.plugin.Plugin;
import java.util.Map; import java.util.Map;
/** /**
* A ConversationContext provides continuity between nodes in the prompt graph by giving the developer access to the * A ConversationContext provides continuity between nodes in the prompt graph
* subject of the conversation and a generic map for storing values that are shared between all {@link Prompt} * by giving the developer access to the subject of the conversation and a
* generic map for storing values that are shared between all {@link Prompt}
* invocations. * invocations.
*/ */
public class ConversationContext { public class ConversationContext {
@ -17,7 +18,8 @@ public class ConversationContext {
/** /**
* @param plugin The owning plugin. * @param plugin The owning plugin.
* @param forWhom The subject of the conversation. * @param forWhom The subject of the conversation.
* @param initialSessionData Any initial values to put in the sessionData map. * @param initialSessionData Any initial values to put in the sessionData
* map.
*/ */
public ConversationContext(Plugin plugin, Conversable forWhom, Map<Object, Object> initialSessionData) { public ConversationContext(Plugin plugin, Conversable forWhom, Map<Object, Object> initialSessionData) {
this.plugin = plugin; this.plugin = plugin;
@ -44,8 +46,9 @@ public class ConversationContext {
} }
/** /**
* Gets session data shared between all {@link Prompt} invocations. Use this as a way * Gets session data shared between all {@link Prompt} invocations. Use
* to pass data through each Prompt as the conversation develops. * this as a way to pass data through each Prompt as the conversation
* develops.
* *
* @param key The session data key. * @param key The session data key.
* @return The requested session data. * @return The requested session data.
@ -55,8 +58,9 @@ public class ConversationContext {
} }
/** /**
* Sets session data shared between all {@link Prompt} invocations. Use this as a way to pass * Sets session data shared between all {@link Prompt} invocations. Use
* data through each prompt as the conversation develops. * this as a way to pass data through each prompt as the conversation
* develops.
* *
* @param key The session data key. * @param key The session data key.
* @param value The session data value. * @param value The session data value.

48
paper-api/src/main/java/org/bukkit/conversations/ConversationFactory.java
View File

@ -9,11 +9,14 @@ import java.util.List;
import java.util.Map; import java.util.Map;
/** /**
* A ConversationFactory is responsible for creating a {@link Conversation} from a predefined template. A ConversationFactory * A ConversationFactory is responsible for creating a {@link Conversation}
* is typically created when a plugin is instantiated and builds a Conversation each time a user initiates a conversation * from a predefined template. A ConversationFactory is typically created when
* with the plugin. Each Conversation maintains its own state and calls back as needed into the plugin. * a plugin is instantiated and builds a Conversation each time a user
* initiates a conversation with the plugin. Each Conversation maintains its
* own state and calls back as needed into the plugin.
* <p> * <p>
* The ConversationFactory implements a fluid API, allowing parameters to be set as an extension to the constructor. * The ConversationFactory implements a fluid API, allowing parameters to be
* set as an extension to the constructor.
*/ */
public class ConversationFactory { public class ConversationFactory {
@ -46,8 +49,9 @@ public class ConversationFactory {
} }
/** /**
* Sets the modality of all {@link Conversation}s created by this factory. If a conversation is modal, all messages * Sets the modality of all {@link Conversation}s created by this factory.
* directed to the player are suppressed for the duration of the conversation. * If a conversation is modal, all messages directed to the player are
* suppressed for the duration of the conversation.
* <p> * <p>
* The default is True. * The default is True.
* *
@ -61,8 +65,9 @@ public class ConversationFactory {
} }
/** /**
* Sets the local echo status for all {@link Conversation}s created by this factory. If local echo is enabled, * Sets the local echo status for all {@link Conversation}s created by
* any text submitted to a conversation gets echoed back into the submitter's chat window. * this factory. If local echo is enabled, any text submitted to a
* conversation gets echoed back into the submitter's chat window.
* *
* @param localEchoEnabled The status of local echo. * @param localEchoEnabled The status of local echo.
* @return This object. * @return This object.
@ -73,7 +78,8 @@ public class ConversationFactory {
} }
/** /**
* Sets the {@link ConversationPrefix} that prepends all output from all generated conversations. * Sets the {@link ConversationPrefix} that prepends all output from all
* generated conversations.
* <p> * <p>
* The default is a {@link NullConversationPrefix}; * The default is a {@link NullConversationPrefix};
* *
@ -86,7 +92,8 @@ public class ConversationFactory {
} }
/** /**
* Sets the number of inactive seconds to wait before automatically abandoning all generated conversations. * Sets the number of inactive seconds to wait before automatically
* abandoning all generated conversations.
* <p> * <p>
* The default is 600 seconds (5 minutes). * The default is 600 seconds (5 minutes).
* *
@ -111,9 +118,11 @@ public class ConversationFactory {
} }
/** /**
* Sets any initial data with which to populate the conversation context sessionData map. * Sets any initial data with which to populate the conversation context
* sessionData map.
* *
* @param initialSessionData The conversation context's initial sessionData. * @param initialSessionData The conversation context's initial
* sessionData.
* @return This object. * @return This object.
*/ */
public ConversationFactory withInitialSessionData(Map<Object, Object> initialSessionData) { public ConversationFactory withInitialSessionData(Map<Object, Object> initialSessionData) {
@ -122,7 +131,8 @@ public class ConversationFactory {
} }
/** /**
* Sets the player input that, when received, will immediately terminate the conversation. * Sets the player input that, when received, will immediately terminate
* the conversation.
* *
* @param escapeSequence Input to terminate the conversation. * @param escapeSequence Input to terminate the conversation.
* @return This object. * @return This object.
@ -144,9 +154,11 @@ public class ConversationFactory {
} }
/** /**
* Prevents this factory from creating a conversation for non-player {@link Conversable} objects. * Prevents this factory from creating a conversation for non-player
* {@link Conversable} objects.
* *
* @param playerOnlyMessage The message to return to a non-play in lieu of starting a conversation. * @param playerOnlyMessage The message to return to a non-play in lieu of
* starting a conversation.
* @return This object. * @return This object.
*/ */
public ConversationFactory thatExcludesNonPlayersWithMessage(String playerOnlyMessage) { public ConversationFactory thatExcludesNonPlayersWithMessage(String playerOnlyMessage) {
@ -155,7 +167,8 @@ public class ConversationFactory {
} }
/** /**
* Adds a {@link ConversationAbandonedListener} to all conversations constructed by this factory. * Adds a {@link ConversationAbandonedListener} to all conversations
* constructed by this factory.
* *
* @param listener The listener to add. * @param listener The listener to add.
* @return This object. * @return This object.
@ -166,7 +179,8 @@ public class ConversationFactory {
} }
/** /**
* Constructs a {@link Conversation} in accordance with the defaults set for this factory. * Constructs a {@link Conversation} in accordance with the defaults set
* for this factory.
* *
* @param forWhom The entity for whom the new conversation is mediating. * @param forWhom The entity for whom the new conversation is mediating.
* @return A new conversation. * @return A new conversation.

5
paper-api/src/main/java/org/bukkit/conversations/ConversationPrefix.java
View File

@ -3,8 +3,9 @@ package org.bukkit.conversations;
import org.bukkit.command.CommandSender; import org.bukkit.command.CommandSender;
/** /**
* A ConversationPrefix implementation prepends all output from the conversation to the player. * A ConversationPrefix implementation prepends all output from the
* The ConversationPrefix can be used to display the plugin name or conversation status as the conversation evolves. * conversation to the player. The ConversationPrefix can be used to display
* the plugin name or conversation status as the conversation evolves.
*/ */
public interface ConversationPrefix { public interface ConversationPrefix {

6
paper-api/src/main/java/org/bukkit/conversations/ExactMatchConversationCanceller.java
View File

@ -1,7 +1,8 @@
package org.bukkit.conversations; package org.bukkit.conversations;
/** /**
* An ExactMatchConversationCanceller cancels a conversation if the user enters an exact input string * An ExactMatchConversationCanceller cancels a conversation if the user
* enters an exact input string
*/ */
public class ExactMatchConversationCanceller implements ConversationCanceller { public class ExactMatchConversationCanceller implements ConversationCanceller {
private String escapeSequence; private String escapeSequence;
@ -9,7 +10,8 @@ public class ExactMatchConversationCanceller implements ConversationCanceller {
/** /**
* Builds an ExactMatchConversationCanceller. * Builds an ExactMatchConversationCanceller.
* *
* @param escapeSequence The string that, if entered by the user, will cancel the conversation. * @param escapeSequence The string that, if entered by the user, will
* cancel the conversation.
*/ */
public ExactMatchConversationCanceller(String escapeSequence) { public ExactMatchConversationCanceller(String escapeSequence) {
this.escapeSequence = escapeSequence; this.escapeSequence = escapeSequence;

13
paper-api/src/main/java/org/bukkit/conversations/FixedSetPrompt.java
View File

@ -6,7 +6,8 @@ import java.util.Arrays;
import java.util.List; import java.util.List;
/** /**
* FixedSetPrompt is the base class for any prompt that requires a fixed set response from the user. * FixedSetPrompt is the base class for any prompt that requires a fixed set
* response from the user.
*/ */
public abstract class FixedSetPrompt extends ValidatingPrompt { public abstract class FixedSetPrompt extends ValidatingPrompt {
@ -14,9 +15,11 @@ public abstract class FixedSetPrompt extends ValidatingPrompt {
/** /**
* Creates a FixedSetPrompt from a set of strings. * Creates a FixedSetPrompt from a set of strings.
* <p>
* foo = new FixedSetPrompt("bar", "cheese", "panda"); * foo = new FixedSetPrompt("bar", "cheese", "panda");
* *
* @param fixedSet A fixed set of strings, one of which the user must type. * @param fixedSet A fixed set of strings, one of which the user must
* type.
*/ */
public FixedSetPrompt(String... fixedSet) { public FixedSetPrompt(String... fixedSet) {
super(); super();
@ -31,9 +34,11 @@ public abstract class FixedSetPrompt extends ValidatingPrompt {
} }
/** /**
* Utility function to create a formatted string containing all the options declared in the constructor. * Utility function to create a formatted string containing all the
* options declared in the constructor.
* *
* @return the options formatted like "[bar, cheese, panda]" if bar, cheese, and panda were the options used * @return the options formatted like "[bar, cheese, panda]" if bar,
* cheese, and panda were the options used
*/ */
protected String formatFixedSet() { protected String formatFixedSet() {
return "[" + StringUtils.join(fixedSet, ", ") + "]"; return "[" + StringUtils.join(fixedSet, ", ") + "]";

8
paper-api/src/main/java/org/bukkit/conversations/InactivityConversationCanceller.java
View File

@ -4,7 +4,8 @@ import org.bukkit.Server;
import org.bukkit.plugin.Plugin; import org.bukkit.plugin.Plugin;
/** /**
* An InactivityConversationCanceller will cancel a {@link Conversation} after a period of inactivity by the user. * An InactivityConversationCanceller will cancel a {@link Conversation} after
* a period of inactivity by the user.
*/ */
public class InactivityConversationCanceller implements ConversationCanceller { public class InactivityConversationCanceller implements ConversationCanceller {
protected Plugin plugin; protected Plugin plugin;
@ -66,8 +67,9 @@ public class InactivityConversationCanceller implements ConversationCanceller {
} }
/** /**
* Subclasses of InactivityConversationCanceller can override this method to take additional actions when the * Subclasses of InactivityConversationCanceller can override this method
* inactivity timer abandons the conversation. * to take additional actions when the inactivity timer abandons the
* conversation.
* *
* @param conversation The conversation being abandoned. * @param conversation The conversation being abandoned.
*/ */

5
paper-api/src/main/java/org/bukkit/conversations/ManuallyAbandonedConversationCanceller.java
View File

@ -1,8 +1,9 @@
package org.bukkit.conversations; package org.bukkit.conversations;
/** /**
* The ManuallyAbandonedConversationCanceller is only used as part of a {@link ConversationAbandonedEvent} to indicate * The ManuallyAbandonedConversationCanceller is only used as part of a {@link
* that the conversation was manually abandoned by programatically calling the abandon() method on it. * ConversationAbandonedEvent} to indicate that the conversation was manually
* abandoned by programmatically calling the abandon() method on it.
*/ */
public class ManuallyAbandonedConversationCanceller implements ConversationCanceller{ public class ManuallyAbandonedConversationCanceller implements ConversationCanceller{
public void setConversation(Conversation conversation) { public void setConversation(Conversation conversation) {

6
paper-api/src/main/java/org/bukkit/conversations/MessagePrompt.java
View File

@ -1,7 +1,8 @@
package org.bukkit.conversations; package org.bukkit.conversations;
/** /**
* MessagePrompt is the base class for any prompt that only displays a message to the user and requires no input. * MessagePrompt is the base class for any prompt that only displays a message
* to the user and requires no input.
*/ */
public abstract class MessagePrompt implements Prompt{ public abstract class MessagePrompt implements Prompt{
@ -20,7 +21,8 @@ public abstract class MessagePrompt implements Prompt{
} }
/** /**
* Accepts and ignores any user input, returning the next prompt in the prompt graph instead. * Accepts and ignores any user input, returning the next prompt in the
* prompt graph instead.
* *
* @param context Context information about the conversation. * @param context Context information about the conversation.
* @param input Ignored. * @param input Ignored.

4
paper-api/src/main/java/org/bukkit/conversations/NullConversationPrefix.java
View File

@ -3,8 +3,8 @@ package org.bukkit.conversations;
import org.bukkit.command.CommandSender; import org.bukkit.command.CommandSender;
/** /**
* NullConversationPrefix is a {@link ConversationPrefix} implementation that displays nothing in front of * NullConversationPrefix is a {@link ConversationPrefix} implementation that
* conversation output. * displays nothing in front of conversation output.
*/ */
public class NullConversationPrefix implements ConversationPrefix{ public class NullConversationPrefix implements ConversationPrefix{

16
paper-api/src/main/java/org/bukkit/conversations/NumericPrompt.java
View File

@ -3,7 +3,8 @@ package org.bukkit.conversations;
import org.apache.commons.lang.math.NumberUtils; import org.apache.commons.lang.math.NumberUtils;
/** /**
* NumericPrompt is the base class for any prompt that requires a {@link Number} response from the user. * NumericPrompt is the base class for any prompt that requires a {@link
* Number} response from the user.
*/ */
public abstract class NumericPrompt extends ValidatingPrompt{ public abstract class NumericPrompt extends ValidatingPrompt{
public NumericPrompt() { public NumericPrompt() {
@ -16,8 +17,8 @@ public abstract class NumericPrompt extends ValidatingPrompt{
} }
/** /**
* Override this method to do further validation on the numeric player input after the input has been determined * Override this method to do further validation on the numeric player
* to actually be a number. * input after the input has been determined to actually be a number.
* *
* @param context Context information about the conversation. * @param context Context information about the conversation.
* @param input The number the player provided. * @param input The number the player provided.
@ -38,7 +39,8 @@ public abstract class NumericPrompt extends ValidatingPrompt{
} }
/** /**
* Override this method to perform some action with the user's integer response. * Override this method to perform some action with the user's integer
* response.
* *
* @param context Context information about the conversation. * @param context Context information about the conversation.
* @param input The user's response as a {@link Number}. * @param input The user's response as a {@link Number}.
@ -56,7 +58,8 @@ public abstract class NumericPrompt extends ValidatingPrompt{
} }
/** /**
* Optionally override this method to display an additional message if the user enters an invalid number. * Optionally override this method to display an additional message if the
* user enters an invalid number.
* *
* @param context Context information about the conversation. * @param context Context information about the conversation.
* @param invalidInput The invalid input provided by the user. * @param invalidInput The invalid input provided by the user.
@ -67,7 +70,8 @@ public abstract class NumericPrompt extends ValidatingPrompt{
} }
/** /**
* Optionally override this method to display an additional message if the user enters an invalid numeric input. * Optionally override this method to display an additional message if the
* user enters an invalid numeric input.
* *
* @param context Context information about the conversation. * @param context Context information about the conversation.
* @param invalidInput The invalid input provided by the user. * @param invalidInput The invalid input provided by the user.

6
paper-api/src/main/java/org/bukkit/conversations/PlayerNamePrompt.java
View File

@ -4,7 +4,8 @@ import org.bukkit.entity.Player;
import org.bukkit.plugin.Plugin; import org.bukkit.plugin.Plugin;
/** /**
* PlayerNamePrompt is the base class for any prompt that requires the player to enter another player's name. * PlayerNamePrompt is the base class for any prompt that requires the player
* to enter another player's name.
*/ */
public abstract class PlayerNamePrompt extends ValidatingPrompt{ public abstract class PlayerNamePrompt extends ValidatingPrompt{
private Plugin plugin; private Plugin plugin;
@ -26,7 +27,8 @@ public abstract class PlayerNamePrompt extends ValidatingPrompt{
} }
/** /**
* Override this method to perform some action with the user's player name response. * Override this method to perform some action with the user's player name
* response.
* *
* @param context Context information about the conversation. * @param context Context information about the conversation.
* @param input The user's player name response. * @param input The user's player name response.

4
paper-api/src/main/java/org/bukkit/conversations/PluginNameConversationPrefix.java
View File

@ -5,8 +5,8 @@ import org.bukkit.command.CommandSender;
import org.bukkit.plugin.Plugin; import org.bukkit.plugin.Plugin;
/** /**
* PluginNameConversationPrefix is a {@link ConversationPrefix} implementation that displays the plugin name in front of * PluginNameConversationPrefix is a {@link ConversationPrefix} implementation
* conversation output. * that displays the plugin name in front of conversation output.
*/ */
public class PluginNameConversationPrefix implements ConversationPrefix { public class PluginNameConversationPrefix implements ConversationPrefix {

20
paper-api/src/main/java/org/bukkit/conversations/Prompt.java
View File

@ -1,9 +1,11 @@
package org.bukkit.conversations; package org.bukkit.conversations;
/** /**
* A Prompt is the main constituent of a {@link Conversation}. Each prompt displays text to the user and optionally * A Prompt is the main constituent of a {@link Conversation}. Each prompt
* waits for a user's response. Prompts are chained together into a directed graph that represents the conversation * displays text to the user and optionally waits for a user's response.
* flow. To halt a conversation, END_OF_CONVERSATION is returned in liu of another Prompt object. * Prompts are chained together into a directed graph that represents the
* conversation flow. To halt a conversation, END_OF_CONVERSATION is returned
* in liu of another Prompt object.
*/ */
public interface Prompt extends Cloneable { public interface Prompt extends Cloneable {
@ -13,7 +15,8 @@ public interface Prompt extends Cloneable {
static final Prompt END_OF_CONVERSATION = null; static final Prompt END_OF_CONVERSATION = null;
/** /**
* Gets the text to display to the user when this prompt is first presented. * Gets the text to display to the user when this prompt is first
* presented.
* *
* @param context Context information about the conversation. * @param context Context information about the conversation.
* @return The text to display. * @return The text to display.
@ -21,15 +24,18 @@ public interface Prompt extends Cloneable {
String getPromptText(ConversationContext context); String getPromptText(ConversationContext context);
/** /**
* Checks to see if this prompt implementation should wait for user input or immediately display the next prompt. * Checks to see if this prompt implementation should wait for user input
* or immediately display the next prompt.
* *
* @param context Context information about the conversation. * @param context Context information about the conversation.
* @return If true, the {@link Conversation} will wait for input before continuing. * @return If true, the {@link Conversation} will wait for input before
* continuing.
*/ */
boolean blocksForInput(ConversationContext context); boolean blocksForInput(ConversationContext context);
/** /**
* Accepts and processes input from the user. Using the input, the next Prompt in the prompt graph is returned. * Accepts and processes input from the user. Using the input, the next
* Prompt in the prompt graph is returned.
* *
* @param context Context information about the conversation. * @param context Context information about the conversation.
* @param input The input text from the user. * @param input The input text from the user.

3
paper-api/src/main/java/org/bukkit/conversations/RegexPrompt.java
View File

@ -3,7 +3,8 @@ package org.bukkit.conversations;
import java.util.regex.Pattern; import java.util.regex.Pattern;
/** /**
* RegexPrompt is the base class for any prompt that requires an input validated by a regular expression. * RegexPrompt is the base class for any prompt that requires an input
* validated by a regular expression.
*/ */
public abstract class RegexPrompt extends ValidatingPrompt { public abstract class RegexPrompt extends ValidatingPrompt {

3
paper-api/src/main/java/org/bukkit/conversations/StringPrompt.java
View File

@ -1,7 +1,8 @@
package org.bukkit.conversations; package org.bukkit.conversations;
/** /**
* StringPrompt is the base class for any prompt that accepts an arbitrary string from the user. * StringPrompt is the base class for any prompt that accepts an arbitrary
* string from the user.
*/ */
public abstract class StringPrompt implements Prompt{ public abstract class StringPrompt implements Prompt{

18
paper-api/src/main/java/org/bukkit/conversations/ValidatingPrompt.java
View File

@ -3,8 +3,9 @@ package org.bukkit.conversations;
import org.bukkit.ChatColor; import org.bukkit.ChatColor;
/** /**
* ValidatingPrompt is the base class for any prompt that requires validation. ValidatingPrompt will keep replaying * ValidatingPrompt is the base class for any prompt that requires validation.
* the prompt text until the user enters a valid response. * ValidatingPrompt will keep replaying the prompt text until the user enters
* a valid response.
*/ */
public abstract class ValidatingPrompt implements Prompt { public abstract class ValidatingPrompt implements Prompt {
public ValidatingPrompt() { public ValidatingPrompt() {
@ -12,8 +13,9 @@ public abstract class ValidatingPrompt implements Prompt {
} }
/** /**
* Accepts and processes input from the user and validates it. If validation fails, this prompt is returned for * Accepts and processes input from the user and validates it. If
* re-execution, otherwise the next Prompt in the prompt graph is returned. * validation fails, this prompt is returned for re-execution, otherwise
* the next Prompt in the prompt graph is returned.
* *
* @param context Context information about the conversation. * @param context Context information about the conversation.
* @param input The input text from the user. * @param input The input text from the user.
@ -52,8 +54,9 @@ public abstract class ValidatingPrompt implements Prompt {
protected abstract boolean isInputValid(ConversationContext context, String input); protected abstract boolean isInputValid(ConversationContext context, String input);
/** /**
* Override this method to accept and processes the validated input from the user. Using the input, the next Prompt * Override this method to accept and processes the validated input from
* in the prompt graph should be returned. * the user. Using the input, the next Prompt in the prompt graph should
* be returned.
* *
* @param context Context information about the conversation. * @param context Context information about the conversation.
* @param input The validated input text from the user. * @param input The validated input text from the user.
@ -62,7 +65,8 @@ public abstract class ValidatingPrompt implements Prompt {
protected abstract Prompt acceptValidatedInput(ConversationContext context, String input); protected abstract Prompt acceptValidatedInput(ConversationContext context, String input);
/** /**
* Optionally override this method to display an additional message if the user enters an invalid input. * Optionally override this method to display an additional message if the
* user enters an invalid input.
* *
* @param context Context information about the conversation. * @param context Context information about the conversation.
* @param invalidInput The invalid input provided by the user. * @param invalidInput The invalid input provided by the user.

10
paper-api/src/main/java/org/bukkit/enchantments/Enchantment.java
View File

@ -86,7 +86,8 @@ public abstract class Enchantment {
public static final Enchantment DIG_SPEED = new EnchantmentWrapper(32); public static final Enchantment DIG_SPEED = new EnchantmentWrapper(32);
/** /**
* Allows blocks to drop themselves instead of fragments (for example, stone instead of cobblestone) * Allows blocks to drop themselves instead of fragments (for example,
* stone instead of cobblestone)
*/ */
public static final Enchantment SILK_TOUCH = new EnchantmentWrapper(33); public static final Enchantment SILK_TOUCH = new EnchantmentWrapper(33);
@ -187,8 +188,11 @@ public abstract class Enchantment {
public abstract boolean conflictsWith(Enchantment other); public abstract boolean conflictsWith(Enchantment other);
/** /**
* Checks if this Enchantment may be applied to the given {@link ItemStack}. * Checks if this Enchantment may be applied to the given {@link
* This does not check if it conflicts with any enchantments already applied to the item. * ItemStack}.
* <p>
* This does not check if it conflicts with any enchantments already
* applied to the item.
* *
* @param item Item to test * @param item Item to test
* @return True if the enchantment may be applied, otherwise False * @return True if the enchantment may be applied, otherwise False

3
paper-api/src/main/java/org/bukkit/enchantments/EnchantmentTarget.java
View File

@ -101,7 +101,8 @@ public enum EnchantmentTarget {
}, },
/** /**
* Allows the Enchantment to be placed on tools (spades, pickaxe, hoes, axes) * Allows the Enchantment to be placed on tools (spades, pickaxe, hoes,
* axes)
*/ */
TOOL { TOOL {
@Override @Override

6
paper-api/src/main/java/org/bukkit/entity/Ageable.java
View File

@ -19,7 +19,8 @@ public interface Ageable extends Creature {
public void setAge(int age); public void setAge(int age);
/** /**
* Lock the age of the animal, setting this will prevent the animal from maturing or getting ready for mating. * Lock the age of the animal, setting this will prevent the animal from
* maturing or getting ready for mating.
* *
* @param lock new lock * @param lock new lock
*/ */
@ -57,7 +58,8 @@ public interface Ageable extends Creature {
public boolean canBreed(); public boolean canBreed();
/** /**
* Set breedability of the animal, if the animal is a baby and set to breed it will instantly grow up. * Set breedability of the animal, if the animal is a baby and set to
* breed it will instantly grow up.
* *
* @param breed breedability of the animal * @param breed breedability of the animal
*/ */

3
paper-api/src/main/java/org/bukkit/entity/Boat.java
View File

@ -6,7 +6,8 @@ package org.bukkit.entity;
public interface Boat extends Vehicle { public interface Boat extends Vehicle {
/** /**
* Gets the maximum speed of a boat. The speed is unrelated to the velocity. * Gets the maximum speed of a boat. The speed is unrelated to the
* velocity.
* *
* @return The max speed. * @return The max speed.
*/ */

3
paper-api/src/main/java/org/bukkit/entity/ComplexLivingEntity.java
View File

@ -3,7 +3,8 @@ package org.bukkit.entity;
import java.util.Set; import java.util.Set;
/** /**
* Represents a complex living entity - one that is made up of various smaller parts * Represents a complex living entity - one that is made up of various smaller
* parts
*/ */
public interface ComplexLivingEntity extends LivingEntity { public interface ComplexLivingEntity extends LivingEntity {
/** /**

8
paper-api/src/main/java/org/bukkit/entity/Creature.java
View File

@ -1,13 +1,15 @@
package org.bukkit.entity; package org.bukkit.entity;
/** /**
* Represents a Creature. Creatures are non-intelligent monsters or animals which * Represents a Creature. Creatures are non-intelligent monsters or animals
* have very simple abilities. * which have very simple abilities.
*/ */
public interface Creature extends LivingEntity { public interface Creature extends LivingEntity {
/** /**
* Instructs this Creature to set the specified LivingEntity as its target. * Instructs this Creature to set the specified LivingEntity as its
* target.
* <p>
* Hostile creatures may attack their target, and friendly creatures may * Hostile creatures may attack their target, and friendly creatures may
* follow their target. * follow their target.
* *

15
paper-api/src/main/java/org/bukkit/entity/Damageable.java
View File

@ -20,7 +20,8 @@ public interface Damageable extends Entity {
void _INVALID_damage(int amount); void _INVALID_damage(int amount);
/** /**
* Deals the given amount of damage to this entity, from a specified entity. * Deals the given amount of damage to this entity, from a specified
* entity.
* *
* @param amount Amount of damage to deal * @param amount Amount of damage to deal
* @param source Entity which to attribute this damage from * @param source Entity which to attribute this damage from
@ -51,10 +52,12 @@ public interface Damageable extends Entity {
int _INVALID_getHealth(); int _INVALID_getHealth();
/** /**
* Sets the entity's health from 0 to {@link #getMaxHealth()}, where 0 is dead. * Sets the entity's health from 0 to {@link #getMaxHealth()}, where 0 is
* dead.
* *
* @param health New health represented from 0 to max * @param health New health represented from 0 to max
* @throws IllegalArgumentException Thrown if the health is < 0 or > {@link #getMaxHealth()} * @throws IllegalArgumentException Thrown if the health is < 0 or >
* {@link #getMaxHealth()}
*/ */
void setHealth(double health); void setHealth(double health);
@ -84,9 +87,11 @@ public interface Damageable extends Entity {
/** /**
* Sets the maximum health this entity can have. * Sets the maximum health this entity can have.
* <p> * <p>
* If the health of the entity is above the value provided it will be set to that value. * If the health of the entity is above the value provided it will be set
* to that value.
* <p> * <p>
* Note: An entity with a health bar ({@link Player}, {@link EnderDragon}, {@link Wither}, etc...} will have their bar scaled accordingly. * Note: An entity with a health bar ({@link Player}, {@link EnderDragon},
* {@link Wither}, etc...} will have their bar scaled accordingly.
* *
* @param health amount of health to set the maximum to * @param health amount of health to set the maximum to
*/ */

3
paper-api/src/main/java/org/bukkit/entity/EnderSignal.java
View File

@ -1,7 +1,8 @@
package org.bukkit.entity; package org.bukkit.entity;
/** /**
* Represents an Ender Signal, which is often created upon throwing an ender eye * Represents an Ender Signal, which is often created upon throwing an ender
* eye
*/ */
public interface EnderSignal extends Entity { public interface EnderSignal extends Entity {

37
paper-api/src/main/java/org/bukkit/entity/Entity.java
View File

@ -25,8 +25,10 @@ public interface Entity extends Metadatable {
public Location getLocation(); public Location getLocation();
/** /**
* Stores the entity's current position in the provided Location object.<br /> * Stores the entity's current position in the provided Location object.
* If the provided Location is null this method does nothing and returns null. * <p>
* If the provided Location is null this method does nothing and returns
* null.
* *
* @return The Location object provided or null * @return The Location object provided or null
*/ */
@ -47,8 +49,9 @@ public interface Entity extends Metadatable {
public Vector getVelocity(); public Vector getVelocity();
/** /**
* Returns true if the entity is supported by a block. This value is a state * Returns true if the entity is supported by a block. This value is a
* updated by the server and is not recalculated unless the entity moves. * state updated by the server and is not recalculated unless the entity
* moves.
* *
* @return True if entity is on ground. * @return True if entity is on ground.
*/ */
@ -96,7 +99,8 @@ public interface Entity extends Metadatable {
public boolean teleport(Entity destination, TeleportCause cause); public boolean teleport(Entity destination, TeleportCause cause);
/** /**
* Returns a list of entities within a bounding box centered around this entity * Returns a list of entities within a bounding box centered around this
* entity
* *
* @param x 1/2 the size of the box along x axis * @param x 1/2 the size of the box along x axis
* @param y 1/2 the size of the box along y axis * @param y 1/2 the size of the box along y axis
@ -113,7 +117,8 @@ public interface Entity extends Metadatable {
public int getEntityId(); public int getEntityId();
/** /**
* Returns the entity's current fire ticks (ticks before the entity stops being on fire). * Returns the entity's current fire ticks (ticks before the entity stops
* being on fire).
* *
* @return int fireTicks * @return int fireTicks
*/ */
@ -127,7 +132,8 @@ public interface Entity extends Metadatable {
public int getMaxFireTicks(); public int getMaxFireTicks();
/** /**
* Sets the entity's current fire ticks (ticks before the entity stops being on fire). * Sets the entity's current fire ticks (ticks before the entity stops
* being on fire).
* *
* @param ticks Current ticks remaining * @param ticks Current ticks remaining
*/ */
@ -148,6 +154,7 @@ public interface Entity extends Metadatable {
/** /**
* Returns false if the entity has died or been despawned for some other * Returns false if the entity has died or been despawned for some other
* reason. * reason.
*
* @return True if valid. * @return True if valid.
*/ */
public boolean isValid(); public boolean isValid();
@ -211,9 +218,11 @@ public interface Entity extends Metadatable {
public void setLastDamageCause(EntityDamageEvent event); public void setLastDamageCause(EntityDamageEvent event);
/** /**
* Retrieve the last {@link EntityDamageEvent} inflicted on this entity. This event may have been cancelled. * Retrieve the last {@link EntityDamageEvent} inflicted on this entity.
* This event may have been cancelled.
* *
* @return the last known {@link EntityDamageEvent} or null if hitherto unharmed * @return the last known {@link EntityDamageEvent} or null if hitherto
* unharmed
*/ */
public EntityDamageEvent getLastDamageCause(); public EntityDamageEvent getLastDamageCause();
@ -236,7 +245,8 @@ public interface Entity extends Metadatable {
/** /**
* Sets the amount of ticks this entity has lived for. * Sets the amount of ticks this entity has lived for.
* <p> * <p>
* This is the equivalent to "age" in entities. May not be less than one tick. * This is the equivalent to "age" in entities. May not be less than one
* tick.
* *
* @param value Age of entity * @param value Age of entity
*/ */
@ -253,6 +263,7 @@ public interface Entity extends Metadatable {
/** /**
* Get the type of the entity. * Get the type of the entity.
*
* @return The entity type. * @return The entity type.
*/ */
public EntityType getType(); public EntityType getType();
@ -265,9 +276,9 @@ public interface Entity extends Metadatable {
public boolean isInsideVehicle(); public boolean isInsideVehicle();
/** /**
* Leave the current vehicle. If the entity is currently in a vehicle * Leave the current vehicle. If the entity is currently in a vehicle (and
* (and is removed from it), true will be returned, otherwise false will * is removed from it), true will be returned, otherwise false will be
* be returned. * returned.
* *
* @return True if the entity was in a vehicle. * @return True if the entity was in a vehicle.
*/ */

13
paper-api/src/main/java/org/bukkit/entity/EntityType.java
View File

@ -20,8 +20,8 @@ public enum EntityType {
/** /**
* An item resting on the ground. * An item resting on the ground.
* <p> * <p>
* Spawn with {@link World#dropItem(Location, ItemStack)} * Spawn with {@link World#dropItem(Location, ItemStack)} or {@link
* or {@link World#dropItemNaturally(Location, ItemStack)} * World#dropItemNaturally(Location, ItemStack)}
*/ */
DROPPED_ITEM("Item", Item.class, 1, false), DROPPED_ITEM("Item", Item.class, 1, false),
/** /**
@ -158,7 +158,7 @@ public enum EntityType {
FISHING_HOOK(null, Fish.class, -1, false), FISHING_HOOK(null, Fish.class, -1, false),
/** /**
* A bolt of lightning. * A bolt of lightning.
* * <p>
* Spawn with {@link World#strikeLightning(Location)}. * Spawn with {@link World#strikeLightning(Location)}.
*/ */
LIGHTNING(null, LightningStrike.class, -1, false), LIGHTNING(null, LightningStrike.class, -1, false),
@ -250,9 +250,10 @@ public enum EntityType {
} }
/** /**
* Some entities cannot be spawned using {@link World#spawnEntity(Location, EntityType)} * Some entities cannot be spawned using {@link
* or {@link World#spawn(Location, Class)}, usually * World#spawnEntity(Location, EntityType)} or {@link
* because they require additional information in order to spawn. * World#spawn(Location, Class)}, usually because they require additional
* information in order to spawn.
* *
* @return False if the entity type cannot be spawned * @return False if the entity type cannot be spawned
*/ */

3
paper-api/src/main/java/org/bukkit/entity/Fireball.java
View File

@ -10,8 +10,7 @@ public interface Fireball extends Projectile, Explosive {
/** /**
* Fireballs fly straight and do not take setVelocity(...) well. * Fireballs fly straight and do not take setVelocity(...) well.
* *
* @param direction * @param direction the direction this fireball is flying toward
* the direction this fireball is flying toward
*/ */
public void setDirection(Vector direction); public void setDirection(Vector direction);

3
paper-api/src/main/java/org/bukkit/entity/Fish.java
View File

@ -22,7 +22,8 @@ public interface Fish extends Projectile {
* 1.0 = Instant catch. * 1.0 = Instant catch.
* *
* @param chance the bite chance * @param chance the bite chance
* @throws IllegalArgumentException if the bite chance is not between 0 and 1 * @throws IllegalArgumentException if the bite chance is not between 0
* and 1
*/ */
public void setBiteChance(double chance) throws IllegalArgumentException; public void setBiteChance(double chance) throws IllegalArgumentException;
} }

8
paper-api/src/main/java/org/bukkit/entity/Hanging.java
View File

@ -9,12 +9,14 @@ import org.bukkit.material.Attachable;
public interface Hanging extends Entity, Attachable { public interface Hanging extends Entity, Attachable {
/** /**
* Sets the direction of the hanging entity, potentially overriding rules of placement. Note that if the result * Sets the direction of the hanging entity, potentially overriding rules
* is not valid the object would normally drop as an item. * of placement. Note that if the result is not valid the object would
* normally drop as an item.
* *
* @param face The new direction. * @param face The new direction.
* @param force Whether to force it. * @param force Whether to force it.
* @return False if force was false and there was no block for it to attach to in order to face the given direction. * @return False if force was false and there was no block for it to
* attach to in order to face the given direction.
*/ */
public boolean setFacingDirection(BlockFace face, boolean force); public boolean setFacingDirection(BlockFace face, boolean force);
} }

48
paper-api/src/main/java/org/bukkit/entity/HumanEntity.java
View File

@ -24,7 +24,8 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
/** /**
* Get the player's inventory. * Get the player's inventory.
* *
* @return The inventory of the player, this also contains the armor slots. * @return The inventory of the player, this also contains the armor
* slots.
*/ */
public PlayerInventory getInventory(); public PlayerInventory getInventory();
@ -36,8 +37,8 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
public Inventory getEnderChest(); public Inventory getEnderChest();
/** /**
* If the player currently has an inventory window open, this method will set a * If the player currently has an inventory window open, this method will
* property of that window, such as the state of a progress bar. * set a property of that window, such as the state of a progress bar.
* *
* @param prop The property. * @param prop The property.
* @param value The value to set the property to. * @param value The value to set the property to.
@ -46,16 +47,16 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
public boolean setWindowProperty(InventoryView.Property prop, int value); public boolean setWindowProperty(InventoryView.Property prop, int value);
/** /**
* Gets the inventory view the player is currently viewing. If they do not have * Gets the inventory view the player is currently viewing. If they do not
* an inventory window open, it returns their internal crafting view. * have an inventory window open, it returns their internal crafting view.
* *
* @return The inventory view. * @return The inventory view.
*/ */
public InventoryView getOpenInventory(); public InventoryView getOpenInventory();
/** /**
* Opens an inventory window with the specified inventory on the top and the player's inventory * Opens an inventory window with the specified inventory on the top and
* on the bottom. * the player's inventory on the bottom.
* *
* @param inventory The inventory to open * @param inventory The inventory to open
* @return The newly opened inventory view * @return The newly opened inventory view
@ -63,22 +64,28 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
public InventoryView openInventory(Inventory inventory); public InventoryView openInventory(Inventory inventory);
/** /**
* Opens an empty workbench inventory window with the player's inventory on the bottom. * Opens an empty workbench inventory window with the player's inventory
* on the bottom.
* *
* @param location The location to attach it to. If null, the player's location is used. * @param location The location to attach it to. If null, the player's
* @param force If false, and there is no workbench block at the location, no inventory will be * location is used.
* opened and null will be returned. * @param force If false, and there is no workbench block at the location,
* @return The newly opened inventory view, or null if it could not be opened. * no inventory will be opened and null will be returned.
* @return The newly opened inventory view, or null if it could not be
* opened.
*/ */
public InventoryView openWorkbench(Location location, boolean force); public InventoryView openWorkbench(Location location, boolean force);
/** /**
* Opens an empty enchanting inventory window with the player's inventory on the bottom. * Opens an empty enchanting inventory window with the player's inventory
* on the bottom.
* *
* @param location The location to attach it to. If null, the player's location is used. * @param location The location to attach it to. If null, the player's
* @param force If false, and there is no enchanting table at the location, no inventory will be * location is used.
* opened and null will be returned. * @param force If false, and there is no enchanting table at the
* @return The newly opened inventory view, or null if it could not be opened. * location, no inventory will be opened and null will be returned.
* @return The newly opened inventory view, or null if it could not be
* opened.
*/ */
public InventoryView openEnchanting(Location location, boolean force); public InventoryView openEnchanting(Location location, boolean force);
@ -110,8 +117,8 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
public void setItemInHand(ItemStack item); public void setItemInHand(ItemStack item);
/** /**
* Returns the ItemStack currently on your cursor, can be empty. * Returns the ItemStack currently on your cursor, can be empty. Will
* Will always be empty if the player currently has no open window. * always be empty if the player currently has no open window.
* *
* @return The ItemStack of the item you are currently moving around. * @return The ItemStack of the item you are currently moving around.
*/ */
@ -119,7 +126,8 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, Permissible, Inv
/** /**
* Sets the item to the given ItemStack, this will replace whatever the * Sets the item to the given ItemStack, this will replace whatever the
* user was moving. Will always be empty if the player currently has no open window. * user was moving. Will always be empty if the player currently has no
* open window.
* *
* @param item The ItemStack which will end up in the hand * @param item The ItemStack which will end up in the hand
*/ */

Some files were not shown because too many files have changed in this diff Show More