twin/paper-mc
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2025-08-15 04:05:50 -07:00
Code Issues Packages 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
Download Patch File Download Diff File Expand all files Collapse all files

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.
* <p>
* If no source {@link Configuration} was provided as a default collection,
* then a new {@link MemoryConfiguration} will be created to hold the new default
* value.
* If no source {@link Configuration} was provided as a default
* collection, then a new {@link MemoryConfiguration} will be created to
* hold the new default value.
* <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 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.
* <p>
* If no source {@link Configuration} was provided as a default collection,
* then a new {@link MemoryConfiguration} will be created to hold the new default
* values.
* If no source {@link Configuration} was provided as a default
* collection, then a new {@link MemoryConfiguration} will be created to
* hold the new default values.
*
* @param defaults A map of Path->Values to add to defaults.
* @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.
* <p>
* If no source {@link Configuration} was provided as a default collection,
* then a new {@link MemoryConfiguration} will be created to hold the new default
* value.
* If no source {@link Configuration} was provided as a default
* collection, then a new {@link MemoryConfiguration} will be created to
* hold the new default value.
* <p>
* This method will not hold a reference to the specified Configuration, nor will it
* automatically update if that Configuration ever changes. If you require this,
* you should set the default source with {@link #setDefaults(org.bukkit.configuration.Configuration)}.
* This method will not hold a reference to the specified Configuration,
* nor will it automatically update if that Configuration ever changes. If
* 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.
* @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}.
* <p>
* If a previous source was set, or previous default values were defined, then they will
* not be copied to the new source.
* If a previous source was set, or previous default values were defined,
* then they will not be copied to the new source.
*
* @param defaults New source of default values for this configuration.
* @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.
* <p>
* If no configuration source was set, but default values were added, then a
* {@link MemoryConfiguration} will be returned. If no source was set and no
* defaults were set, then this method will return null.
* If no configuration source was set, but default values were added, then
* a {@link MemoryConfiguration} will be returned. If no source was set
* and no defaults were set, then this method will return null.
*
* @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;
/**
* 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 {
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>
* This value does not affect how the {@link Configuration} is stored, only in
* how you access the data. The default value is '.'.
* This value does not affect how the {@link Configuration} is stored,
* only in how you access the data. The default value is '.'.
*
* @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>
* This value does not affect how the {@link Configuration} is stored, only in
* how you access the data. The default value is '.'.
* This value does not affect how the {@link Configuration} is stored,
* only in how you access the data. The default value is '.'.
*
* @param value Path separator
* @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>
* If this is true, all values in the default Configuration will be directly copied,
* making it impossible to distinguish between values that were set and values that
* are provided by default. As a result, {@link ConfigurationSection#contains(java.lang.String)} will always
* return the same value as {@link ConfigurationSection#isSet(java.lang.String)}.
* The default value is false.
* If this is true, all values in the default Configuration will be
* directly copied, making it impossible to distinguish between values
* that were set and values that are provided by default. As a result,
* {@link ConfigurationSection#contains(java.lang.String)} will always
* return the same value as {@link
* ConfigurationSection#isSet(java.lang.String)}. The default value is
* false.
*
* @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>
* If this is true, all values in the default Configuration will be directly copied,
* making it impossible to distinguish between values that were set and values that
* are provided by default. As a result, {@link ConfigurationSection#contains(java.lang.String)} will always
* return the same value as {@link ConfigurationSection#isSet(java.lang.String)}.
* The default value is false.
* If this is true, all values in the default Configuration will be
* directly copied, making it impossible to distinguish between values
* that were set and values that are provided by default. As a result,
* {@link ConfigurationSection#contains(java.lang.String)} will always
* 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
* @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.
* <p>
* If deep is set to true, then this will contain all the keys within any child
* {@link ConfigurationSection}s (and their children, etc). These will be in a
* valid path notation for you to use.
* If deep is set to true, then this will contain all the keys within any
* child {@link ConfigurationSection}s (and their children, etc). These
* will be in a valid path notation for you to use.
* <p>
* If deep is set to false, then this will contain only the keys of any direct children,
* and not their own children.
* If deep is set to false, then this will contain only the keys 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 Set of keys contained within this ConfigurationSection.
*/
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.
* <p>
* If deep is set to true, then this will contain all the keys and values within
* any child {@link ConfigurationSection}s (and their children, etc). These
* keys will be in a valid path notation for you to use.
* If deep is set to true, then this will contain all the keys and values
* within any child {@link ConfigurationSection}s (and their children,
* etc). These keys will be in a valid path notation for you to use.
* <p>
* If deep is set to false, then this will contain only the keys and values of any
* direct children, and not their own children.
* If deep is set to false, then this will contain only the keys and
* 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.
*/
public Map<String, Object> getValues(boolean deep);
@@ -46,72 +48,80 @@ public interface ConfigurationSection {
/**
* Checks if this {@link ConfigurationSection} contains the given path.
* <p>
* If the value for the requested path does not exist but a default value has
* been specified, this will return true.
* If the value for the requested path does not exist but a default value
* has been specified, this will return true.
*
* @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.
*/
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>
* If the value for the requested path does not exist but a default value has
* been specified, this will still return false.
* If the value for the requested path does not exist but a default value
* has been specified, this will still return false.
*
* @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.
*/
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>
* For any {@link Configuration} themselves, this will return an empty string.
* For any {@link Configuration} themselves, this will return an empty
* string.
* <p>
* If the section is no longer contained within its root for any reason, such as
* being replaced with a different value, this may return null.
* If the section is no longer contained within its root for any reason,
* such as being replaced with a different value, this may return null.
* <p>
* To retrieve the single name of this section, that is, the final part of the path
* returned by this method, you may use {@link #getName()}.
* To retrieve the single name of this section, that is, the final part of
* the path returned by this method, you may use {@link #getName()}.
*
* @return Path of this section relative to its root
*/
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>
* This will always be the final part of {@link #getCurrentPath()}, unless the
* section is orphaned.
* This will always be the final part of {@link #getCurrentPath()}, unless
* the section is orphaned.
*
* @return Name of this section
*/
public String getName();
/**
* Gets the root {@link Configuration} that contains this {@link ConfigurationSection}
* Gets the root {@link Configuration} that contains this {@link
* ConfigurationSection}
* <p>
* For any {@link Configuration} themselves, this will return its own object.
* For any {@link Configuration} themselves, this will return its own
* object.
* <p>
* If the section is no longer contained within its root for any reason, such as
* being replaced with a different value, this may return null.
* If the section is no longer contained within its root for any reason,
* such as being replaced with a different value, this may return null.
*
* @return Root configuration containing this section.
*/
public Configuration getRoot();
/**
* Gets the parent {@link ConfigurationSection} that directly contains this
* {@link ConfigurationSection}.
* Gets the parent {@link ConfigurationSection} that directly contains
* this {@link ConfigurationSection}.
* <p>
* For any {@link Configuration} themselves, this will return null.
* <p>
* If the section is no longer contained within its parent for any reason, such as
* being replaced with a different value, this may return null.
* If the section is no longer contained within its parent for any reason,
* such as being replaced with a different value, this may return null.
*
* @return Parent section containing this section.
*/
@@ -120,9 +130,9 @@ public interface ConfigurationSection {
/**
* Gets the requested Object by path.
* <p>
* If the Object does not exist but a default value has been specified, this
* will return the default value. If the Object does not exist and no default
* value was specified, this will return null.
* If the Object does not exist but a default value has been specified,
* this will return the default value. If the Object does not exist and no
* default value was specified, this will return null.
*
* @param path Path of the Object to get.
* @return Requested Object.
@@ -130,10 +140,12 @@ public interface ConfigurationSection {
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>
* If the Object does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
* If the Object does not exist then the specified default value will
* returned regardless of if a default has been identified in the root
* {@link Configuration}.
*
* @param path Path of the Object to get.
* @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
* replaced, regardless of what the new value is.
* <p>
* Some implementations may have limitations on what you may store. See their
* individual javadocs for details. No implementations should allow you to store
* {@link Configuration}s or {@link ConfigurationSection}s, please use
* {@link #createSection(java.lang.String)} for that.
* Some implementations may have limitations on what you may store. See
* their individual javadocs for details. No implementations should allow
* you to store {@link Configuration}s or {@link ConfigurationSection}s,
* please use {@link #createSection(java.lang.String)} for that.
*
* @param path Path of the object to set.
* @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.
* <p>
* Any value that was previously set at this path will be overwritten. If the
* previous value was itself a {@link ConfigurationSection}, it will be orphaned.
* Any value that was previously set at this path will be overwritten. If
* the previous value was itself a {@link ConfigurationSection}, it will
* be orphaned.
*
* @param path Path to create the section at.
* @return Newly created section
@@ -169,10 +182,12 @@ public interface ConfigurationSection {
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>
* Any value that was previously set at this path will be overwritten. If the
* previous value was itself a {@link ConfigurationSection}, it will be orphaned.
* Any value that was previously set at this path will be overwritten. If
* the previous value was itself a {@link ConfigurationSection}, it will
* be orphaned.
*
* @param path Path to create the section at.
* @param map The values to used.
@@ -184,9 +199,9 @@ public interface ConfigurationSection {
/**
* Gets the requested String by path.
* <p>
* If the String does not exist but a default value has been specified, this
* will return the default value. If the String does not exist and no default
* value was specified, this will return null.
* If the String does not exist but a default value has been specified,
* this will return the default value. If the String does not exist and no
* default value was specified, this will return null.
*
* @param path Path of the String to get.
* @return Requested String.
@@ -194,13 +209,16 @@ public interface ConfigurationSection {
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>
* If the String does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
* If the String does not exist then the specified default value will
* returned regardless of if a default has been identified in the root
* {@link Configuration}.
*
* @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.
*/
public String getString(String path, String def);
@@ -208,10 +226,10 @@ public interface ConfigurationSection {
/**
* Checks if the specified path is a String.
* <p>
* If the path exists but is not a String, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a String and return
* appropriately.
* If the path exists but is not a String, this will return false. If the
* path does not exist, this will return false. If the path does not exist
* but a default value has been specified, this will check if that default
* value is a String and return appropriately.
*
* @param path Path of the String to check.
* @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.
* <p>
* If the int does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
* If the int does not exist then the specified default value will
* returned regardless of if a default has been identified in the root
* {@link Configuration}.
*
* @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.
*/
public int getInt(String path, int def);
@@ -245,10 +265,10 @@ public interface ConfigurationSection {
/**
* Checks if the specified path is an int.
* <p>
* If the path exists but is not a int, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a int and return
* appropriately.
* If the path exists but is not a int, this will return false. If the
* path does not exist, this will return false. If the path does not exist
* but a default value has been specified, this will check if that default
* value is a int and return appropriately.
*
* @param path Path of the int to check.
* @return Whether or not the specified path is an int.
@@ -258,9 +278,9 @@ public interface ConfigurationSection {
/**
* Gets the requested boolean by path.
* <p>
* If the boolean does not exist but a default value has been specified, this
* will return the default value. If the boolean does not exist and no default
* value was specified, this will return false.
* If the boolean does not exist but a default value has been specified,
* this will return the default value. If the boolean does not exist and
* no default value was specified, this will return false.
*
* @param path Path of the boolean to get.
* @return Requested boolean.
@@ -268,13 +288,16 @@ public interface ConfigurationSection {
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>
* If the boolean does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
* If the boolean does not exist then the specified default value will
* returned regardless of if a default has been identified in the root
* {@link Configuration}.
*
* @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.
*/
public boolean getBoolean(String path, boolean def);
@@ -282,10 +305,10 @@ public interface ConfigurationSection {
/**
* Checks if the specified path is a boolean.
* <p>
* If the path exists but is not a boolean, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a boolean and return
* appropriately.
* If the path exists but is not a boolean, this will return false. If the
* path does not exist, this will return false. If the path does not exist
* but a default value has been specified, this will check if that default
* value is a boolean and return appropriately.
*
* @param path Path of the boolean to check.
* @return Whether or not the specified path is a boolean.
@@ -295,9 +318,9 @@ public interface ConfigurationSection {
/**
* Gets the requested double by path.
* <p>
* If the double does not exist but a default value has been specified, this
* will return the default value. If the double does not exist and no default
* value was specified, this will return 0.
* If the double does not exist but a default value has been specified,
* this will return the default value. If the double does not exist and no
* default value was specified, this will return 0.
*
* @param path Path of the double to get.
* @return Requested double.
@@ -305,13 +328,16 @@ public interface ConfigurationSection {
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>
* If the double does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
* If the double does not exist then the specified default value will
* returned regardless of if a default has been identified in the root
* {@link Configuration}.
*
* @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.
*/
public double getDouble(String path, double def);
@@ -319,10 +345,10 @@ public interface ConfigurationSection {
/**
* Checks if the specified path is a double.
* <p>
* If the path exists but is not a double, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a double and return
* appropriately.
* If the path exists but is not a double, this will return false. If the
* path does not exist, this will return false. If the path does not exist
* but a default value has been specified, this will check if that default
* value is a double and return appropriately.
*
* @param path Path of the double to check.
* @return Whether or not the specified path is a double.
@@ -333,8 +359,8 @@ public interface ConfigurationSection {
* Gets the requested long by path.
* <p>
* 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
* value was specified, this will return 0.
* will return the default value. If the long does not exist and no
* default value was specified, this will return 0.
*
* @param path Path of the long to get.
* @return Requested long.
@@ -342,13 +368,16 @@ public interface ConfigurationSection {
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>
* If the long does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
* If the long does not exist then the specified default value will
* returned regardless of if a default has been identified in the root
* {@link Configuration}.
*
* @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.
*/
public long getLong(String path, long def);
@@ -356,10 +385,10 @@ public interface ConfigurationSection {
/**
* Checks if the specified path is a long.
* <p>
* If the path exists but is not a long, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a long and return
* appropriately.
* If the path exists but is not a long, this will return false. If the
* path does not exist, this will return false. If the path does not exist
* but a default value has been specified, this will check if that default
* value is a long and return appropriately.
*
* @param path Path of the long to check.
* @return Whether or not the specified path is a long.
@@ -371,8 +400,8 @@ public interface ConfigurationSection {
* Gets the requested List by path.
* <p>
* 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
* value was specified, this will return null.
* will return the default value. If the List does not exist and no
* default value was specified, this will return null.
*
* @param path Path of the List to get.
* @return Requested List.
@@ -380,13 +409,16 @@ public interface ConfigurationSection {
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>
* If the List does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
* If the List does not exist then the specified default value will
* returned regardless of if a default has been identified in the root
* {@link Configuration}.
*
* @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.
*/
public List<?> getList(String path, List<?> def);
@@ -394,10 +426,10 @@ public interface ConfigurationSection {
/**
* Checks if the specified path is a List.
* <p>
* If the path exists but is not a List, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a List and return
* appropriately.
* If the path exists but is not a List, this will return false. If the
* path does not exist, this will return false. If the path does not exist
* but a default value has been specified, this will check if that default
* value is a List and return appropriately.
*
* @param path Path of the List to check.
* @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.
* <p>
* 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
* value was specified, this will return an empty List.
* will return the default value. If the List does not exist and no
* default value was specified, this will return an empty List.
* <p>
* This method will attempt to cast any values into a String if possible, but may
* miss any values out if they are not compatible.
* This method will attempt to cast any values into a String if possible,
* but may miss any values out if they are not compatible.
*
* @param path Path of the List to get.
* @return Requested List of String.
@@ -423,11 +455,11 @@ public interface ConfigurationSection {
* Gets the requested List of Integer by path.
* <p>
* 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
* value was specified, this will return an empty List.
* will return the default value. If the List does not exist and no
* default value was specified, this will return an empty List.
* <p>
* This method will attempt to cast any values into a Integer if possible, but may
* miss any values out if they are not compatible.
* This method will attempt to cast any values into a Integer if possible,
* but may miss any values out if they are not compatible.
*
* @param path Path of the List to get.
* @return Requested List of Integer.
@@ -438,11 +470,11 @@ public interface ConfigurationSection {
* Gets the requested List of Boolean by path.
* <p>
* 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
* value was specified, this will return an empty List.
* will return the default value. If the List does not exist and no
* default value was specified, this will return an empty List.
* <p>
* This method will attempt to cast any values into a Boolean if possible, but may
* miss any values out if they are not compatible.
* This method will attempt to cast any values into a Boolean if possible,
* but may miss any values out if they are not compatible.
*
* @param path Path of the List to get.
* @return Requested List of Boolean.
@@ -453,11 +485,11 @@ public interface ConfigurationSection {
* Gets the requested List of Double by path.
* <p>
* 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
* value was specified, this will return an empty List.
* will return the default value. If the List does not exist and no
* default value was specified, this will return an empty List.
* <p>
* This method will attempt to cast any values into a Double if possible, but may
* miss any values out if they are not compatible.
* This method will attempt to cast any values into a Double if possible,
* but may miss any values out if they are not compatible.
*
* @param path Path of the List to get.
* @return Requested List of Double.
@@ -468,11 +500,11 @@ public interface ConfigurationSection {
* Gets the requested List of Float by path.
* <p>
* 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
* value was specified, this will return an empty List.
* will return the default value. If the List does not exist and no
* default value was specified, this will return an empty List.
* <p>
* This method will attempt to cast any values into a Float if possible, but may
* miss any values out if they are not compatible.
* This method will attempt to cast any values into a Float if possible,
* but may miss any values out if they are not compatible.
*
* @param path Path of the List to get.
* @return Requested List of Float.
@@ -483,11 +515,11 @@ public interface ConfigurationSection {
* Gets the requested List of Long by path.
* <p>
* 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
* value was specified, this will return an empty List.
* will return the default value. If the List does not exist and no
* default value was specified, this will return an empty List.
* <p>
* This method will attempt to cast any values into a Long if possible, but may
* miss any values out if they are not compatible.
* This method will attempt to cast any values into a Long if possible,
* but may miss any values out if they are not compatible.
*
* @param path Path of the List to get.
* @return Requested List of Long.
@@ -498,11 +530,11 @@ public interface ConfigurationSection {
* Gets the requested List of Byte by path.
* <p>
* 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
* value was specified, this will return an empty List.
* will return the default value. If the List does not exist and no
* default value was specified, this will return an empty List.
* <p>
* This method will attempt to cast any values into a Byte if possible, but may
* miss any values out if they are not compatible.
* This method will attempt to cast any values into a Byte if possible,
* but may miss any values out if they are not compatible.
*
* @param path Path of the List to get.
* @return Requested List of Byte.
@@ -513,11 +545,11 @@ public interface ConfigurationSection {
* Gets the requested List of Character by path.
* <p>
* 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
* value was specified, this will return an empty List.
* will return the default value. If the List does not exist and no
* default value was specified, this will return an empty List.
* <p>
* This method will attempt to cast any values into a Character if possible, but may
* miss any values out if they are not compatible.
* This method will attempt to cast any values into a Character if
* possible, but may miss any values out if they are not compatible.
*
* @param path Path of the List to get.
* @return Requested List of Character.
@@ -528,11 +560,11 @@ public interface ConfigurationSection {
* Gets the requested List of Short by path.
* <p>
* 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
* value was specified, this will return an empty List.
* will return the default value. If the List does not exist and no
* default value was specified, this will return an empty List.
* <p>
* This method will attempt to cast any values into a Short if possible, but may
* miss any values out if they are not compatible.
* This method will attempt to cast any values into a Short if possible,
* but may miss any values out if they are not compatible.
*
* @param path Path of the List to get.
* @return Requested List of Short.
@@ -543,11 +575,11 @@ public interface ConfigurationSection {
* Gets the requested List of Maps by path.
* <p>
* 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
* value was specified, this will return an empty List.
* will return the default value. If the List does not exist and no
* default value was specified, this will return an empty List.
* <p>
* This method will attempt to cast any values into a Map if possible, but may
* miss any values out if they are not compatible.
* This method will attempt to cast any values into a Map if possible, but
* may miss any values out if they are not compatible.
*
* @param path Path of the List to get.
* @return Requested List of Maps.
@@ -558,9 +590,9 @@ public interface ConfigurationSection {
/**
* Gets the requested Vector by path.
* <p>
* If the Vector does not exist but a default value has been specified, this
* will return the default value. If the Vector does not exist and no default
* value was specified, this will return null.
* If the Vector does not exist but a default value has been specified,
* this will return the default value. If the Vector does not exist and no
* default value was specified, this will return null.
*
* @param path Path of the Vector to get.
* @return Requested Vector.
@@ -568,13 +600,16 @@ public interface ConfigurationSection {
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>
* If the Vector does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
* If the Vector does not exist then the specified default value will
* returned regardless of if a default has been identified in the root
* {@link Configuration}.
*
* @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.
*/
public Vector getVector(String path, Vector def);
@@ -582,10 +617,10 @@ public interface ConfigurationSection {
/**
* Checks if the specified path is a Vector.
* <p>
* If the path exists but is not a Vector, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a Vector and return
* appropriately.
* If the path exists but is not a Vector, this will return false. If the
* path does not exist, this will return false. If the path does not exist
* but a default value has been specified, this will check if that default
* value is a Vector and return appropriately.
*
* @param path Path of the Vector to check.
* @return Whether or not the specified path is a Vector.
@@ -595,9 +630,10 @@ public interface ConfigurationSection {
/**
* Gets the requested OfflinePlayer by path.
* <p>
* If the OfflinePlayer does not exist but a default value has been specified, this
* will return the default value. If the OfflinePlayer does not exist and no default
* value was specified, this will return null.
* If the OfflinePlayer does not exist but a default value has been
* specified, this will return the default value. If the OfflinePlayer
* does not exist and no default value was specified, this will return
* null.
*
* @param path Path of the OfflinePlayer to get.
* @return Requested OfflinePlayer.
@@ -605,13 +641,16 @@ public interface ConfigurationSection {
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>
* If the OfflinePlayer does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
* If the OfflinePlayer does not exist then the specified default value
* will returned regardless of if a default has been identified in the
* root {@link Configuration}.
*
* @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.
*/
public OfflinePlayer getOfflinePlayer(String path, OfflinePlayer def);
@@ -619,10 +658,10 @@ public interface ConfigurationSection {
/**
* Checks if the specified path is an OfflinePlayer.
* <p>
* If the path exists but is not a OfflinePlayer, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a OfflinePlayer and return
* appropriately.
* If the path exists but is not a OfflinePlayer, this will return false.
* If the path does not exist, this will return false. If the path does
* not exist but a default value has been specified, this will check if
* that default value is a OfflinePlayer and return appropriately.
*
* @param path Path of the OfflinePlayer to check.
* @return Whether or not the specified path is an OfflinePlayer.
@@ -632,9 +671,9 @@ public interface ConfigurationSection {
/**
* Gets the requested ItemStack by path.
* <p>
* If the ItemStack does not exist but a default value has been specified, this
* will return the default value. If the ItemStack does not exist and no default
* value was specified, this will return null.
* If the ItemStack does not exist but a default value has been specified,
* this will return the default value. If the ItemStack does not exist and
* no default value was specified, this will return null.
*
* @param path Path of the ItemStack to get.
* @return Requested ItemStack.
@@ -642,13 +681,16 @@ public interface ConfigurationSection {
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>
* If the ItemStack does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
* If the ItemStack does not exist then the specified default value will
* returned regardless of if a default has been identified in the root
* {@link Configuration}.
*
* @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.
*/
public ItemStack getItemStack(String path, ItemStack def);
@@ -656,10 +698,10 @@ public interface ConfigurationSection {
/**
* Checks if the specified path is an ItemStack.
* <p>
* If the path exists but is not a ItemStack, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a ItemStack and return
* appropriately.
* If the path exists but is not a ItemStack, this will return false. If
* the path does not exist, this will return false. If the path does not
* exist but a default value has been specified, this will check if that
* default value is a ItemStack and return appropriately.
*
* @param path Path of the ItemStack to check.
* @return Whether or not the specified path is an ItemStack.
@@ -669,9 +711,9 @@ public interface ConfigurationSection {
/**
* Gets the requested Color by path.
* <p>
* If the Color does not exist but a default value has been specified, this
* will return the default value. If the Color does not exist and no default
* value was specified, this will return null.
* If the Color does not exist but a default value has been specified,
* this will return the default value. If the Color does not exist and no
* default value was specified, this will return null.
*
* @param path Path of the Color to get.
* @return Requested Color.
@@ -679,13 +721,16 @@ public interface ConfigurationSection {
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>
* If the Color does not exist then the specified default value will returned
* regardless of if a default has been identified in the root {@link Configuration}.
* If the Color does not exist then the specified default value will
* returned regardless of if a default has been identified in the root
* {@link Configuration}.
*
* @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.
*/
public Color getColor(String path, Color def);
@@ -693,22 +738,23 @@ public interface ConfigurationSection {
/**
* Checks if the specified path is a Color.
* <p>
* If the path exists but is not a Color, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a Color and return
* appropriately.
* If the path exists but is not a Color, this will return false. If the
* path does not exist, this will return false. If the path does not exist
* but a default value has been specified, this will check if that default
* value is a Color and return appropriately.
*
* @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);
/**
* Gets the requested ConfigurationSection by path.
* <p>
* If the ConfigurationSection does not exist but a default value has been specified, this
* will return the default value. If the ConfigurationSection does not exist and no default
* value was specified, this will return null.
* If the ConfigurationSection does not exist but a default value has been
* specified, this will return the default value. If the
* ConfigurationSection does not exist and no default value was specified,
* this will return null.
*
* @param path Path of the ConfigurationSection to get.
* @return Requested ConfigurationSection.
@@ -718,9 +764,10 @@ public interface ConfigurationSection {
/**
* Checks if the specified path is a ConfigurationSection.
* <p>
* If the path exists but is not a ConfigurationSection, this will return false. If the path does not
* exist, this will return false. If the path does not exist but a default value
* has been specified, this will check if that default value is a ConfigurationSection and return
* If the path exists but is not a ConfigurationSection, this will return
* false. If the path does not exist, this will return false. If the path
* does not exist but a default value has been specified, this will check
* if that default value is a ConfigurationSection and return
* appropriately.
*
* @param path Path of the ConfigurationSection to check.
@@ -729,11 +776,12 @@ public interface ConfigurationSection {
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>
* If the root contains no defaults, or the defaults doesn't contain a value
* for this path, or the value at this path is not a {@link ConfigurationSection} then
* this will return null.
* If the root contains no defaults, or the defaults doesn't contain a
* value for this path, or the value at this path is not a {@link
* ConfigurationSection} then this will return null.
*
* @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.
* <p>
* If no source {@link Configuration} was provided as a default collection,
* then a new {@link MemoryConfiguration} will be created to hold the new default
* value.
* If no source {@link Configuration} was provided as a default
* collection, then a new {@link MemoryConfiguration} will be created to
* hold the new default value.
* <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>
* If the value as returned by {@link #getDefaultSection()} is null,
* then this will create a new section at the path, replacing anything that
* may have existed there previously.
* If the value as returned by {@link #getDefaultSection()} is null, then
* this will create a new section at the path, replacing anything that may
* have existed there previously.
*
* @param path Path of the value to set.
* @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 {
/**
* Creates a new instance of InvalidConfigurationException without a message or cause.
* Creates a new instance of InvalidConfigurationException without a
* message or cause.
*/
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.
*/
@@ -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.
*/
@@ -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 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() {}
/**
* Creates an empty {@link MemoryConfiguration} using the specified {@link Configuration}
* as a source for all default values.
* Creates an empty {@link MemoryConfiguration} using the specified {@link
* Configuration} as a source for all default values.
*
* @param defaults Default value provider
* @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;
/**
* 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 {
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;
/**
* 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>
* Note that calling this without being yourself a {@link Configuration} will throw an
* exception!
* Note that calling this without being yourself a {@link Configuration}
* 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() {
if (!(this instanceof Configuration)) {
@@ -48,8 +50,10 @@ public class MemorySection implements ConfigurationSection {
* Creates an empty MemorySection with the specified parent and path.
*
* @param parent Parent section that contains this own section.
* @param path Path that you may access this section from via the root {@link Configuration}.
* @throws IllegalArgumentException Thrown is parent or path is null, or if parent contains no root Configuration.
* @param path Path that you may access this section from via the root
* {@link Configuration}.
* @throws IllegalArgumentException Thrown is parent or path is null, or
* if parent contains no root Configuration.
*/
protected MemorySection(ConfigurationSection parent, String path) {
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>
* 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 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>
* 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 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;
/**
* 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 {
/**
@@ -27,8 +28,8 @@ public abstract class FileConfiguration extends MemoryConfiguration {
}
/**
* Creates an empty {@link FileConfiguration} using the specified {@link Configuration}
* as a source for all default values.
* Creates an empty {@link FileConfiguration} using the specified {@link
* Configuration} as a source for all default values.
*
* @param defaults Default value provider
*/
@@ -39,11 +40,13 @@ public abstract class FileConfiguration extends MemoryConfiguration {
/**
* Saves this {@link FileConfiguration} to the specified location.
* <p>
* If the file does not exist, it will be created. If already exists, it will
* be overwritten. If it cannot be overwritten or created, an exception will be thrown.
* If the file does not exist, it will be created. If already exists, it
* will be overwritten. If it cannot be overwritten or created, an
* exception will be thrown.
*
* @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.
*/
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.
* <p>
* If the file does not exist, it will be created. If already exists, it will
* be overwritten. If it cannot be overwritten or created, an exception will be thrown.
* If the file does not exist, it will be created. If already exists, it
* will be overwritten. If it cannot be overwritten or created, an
* exception will be thrown.
*
* @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.
*/
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.
* <p>
* All the values contained within this configuration will be removed, leaving
* only settings and defaults, and the new values will be loaded from the given file.
* All the values contained within this configuration will be removed,
* leaving only settings and defaults, and the new values will be loaded
* from the given file.
* <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.
* @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 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.
*/
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.
* <p>
* All the values contained within this configuration will be removed, leaving
* only settings and defaults, and the new values will be loaded from the given stream.
* All the values contained within this configuration will be removed,
* leaving only settings and defaults, and the new values will be loaded
* from the given stream.
*
* @param stream Stream to load from
* @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.
*/
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.
* <p>
* All the values contained within this configuration will be removed, leaving
* only settings and defaults, and the new values will be loaded from the given file.
* All the values contained within this configuration will be removed,
* leaving only settings and defaults, and the new values will be loaded
* from the given file.
* <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.
* @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 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.
*/
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>
* All the values contained within this configuration will be removed, leaving
* only settings and defaults, and the new values will be loaded from the given string.
* All the values contained within this configuration will be removed,
* leaving only settings and defaults, and the new values will be loaded
* from the given string.
* <p>
* If the string is invalid in any way, an exception will be thrown.
*
* @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.
*/
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>
* This will use the header from {@link #options()} -> {@link FileConfigurationOptions#header()},
* respecting the rules of {@link FileConfigurationOptions#copyHeader()} if set.
* This will use the header from {@link #options()} -> {@link
* FileConfigurationOptions#header()}, respecting the rules of {@link
* FileConfigurationOptions#copyHeader()} if set.
*
* @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.*;
/**
* 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 {
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.
* <p>
* This header will be commented out and applied directly at the top of the
* generated output of the {@link FileConfiguration}. It is not required to
* include a newline at the end of the header as it will automatically be applied,
* but you may include one if you wish for extra spacing.
* This header will be commented out and applied directly at the top of
* the generated output of the {@link FileConfiguration}. It is not
* required to include a newline at the end of the header as it will
* automatically be applied, but you may include one if you wish for extra
* spacing.
* <p>
* Null is a valid value which will indicate that no header is to be applied.
* The default value is null.
* Null is a valid value which will indicate that no header is to be
* applied. The default value is null.
*
* @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.
* <p>
* This header will be commented out and applied directly at the top of the
* generated output of the {@link FileConfiguration}. It is not required to
* include a newline at the end of the header as it will automatically be applied,
* but you may include one if you wish for extra spacing.
* This header will be commented out and applied directly at the top of
* the generated output of the {@link FileConfiguration}. It is not
* required to include a newline at the end of the header as it will
* automatically be applied, but you may include one if you wish for extra
* spacing.
* <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
* @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.
* <p>
* If this is true, if a default {@link FileConfiguration} is passed to
* {@link FileConfiguration#setDefaults(org.bukkit.configuration.Configuration)}
* then upon saving it will use the header from that config, instead of the one provided here.
* {@link
* FileConfiguration#setDefaults(org.bukkit.configuration.Configuration)}
* then upon saving it will use the header from that config, instead of
* the one provided here.
* <p>
* If no default is set on the configuration, or the default is not of type FileConfiguration,
* or that config has no header ({@link #header()} returns null) then the header
* specified in this configuration will be used.
* If no default is set on the configuration, or the default is not of
* type FileConfiguration, or that config has no header ({@link #header()}
* returns null) then the header specified in this configuration will be
* used.
* <p>
* 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.
* <p>
* If this is true, if a default {@link FileConfiguration} is passed to
* {@link FileConfiguration#setDefaults(org.bukkit.configuration.Configuration)}
* then upon saving it will use the header from that config, instead of the one provided here.
* {@link
* FileConfiguration#setDefaults(org.bukkit.configuration.Configuration)}
* then upon saving it will use the header from that config, instead of
* the one provided here.
* <p>
* If no default is set on the configuration, or the default is not of type FileConfiguration,
* or that config has no header ({@link #header()} returns null) then the header
* specified in this configuration will be used.
* If no default is set on the configuration, or the default is not of
* type FileConfiguration, or that config has no header ({@link #header()}
* returns null) then the header specified in this configuration will be
* used.
* <p>
* 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.
* <p>
* 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
* @return Resulting configuration
@@ -187,7 +188,8 @@ public class YamlConfiguration extends FileConfiguration {
* Creates a new {@link YamlConfiguration}, loading from the given stream.
* <p>
* 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
* @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;
/**
* 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 {
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.
* <p>
* These objects MUST implement one of the following, in addition to the methods
* as defined by this interface:
* These objects MUST implement one of the following, in addition to the
* methods as defined by this interface:
* <ul>
* <li>A static method "deserialize" that accepts a single {@link Map}&lt;{@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}>
* and returns the class.</li>
* <li>A constructor that accepts a single {@link Map}&lt;{@link String}, {@link Object}>.</li>
* <li>A static method "deserialize" that accepts a single {@link Map}&lt;
* {@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}> and returns the class.</li>
* <li>A constructor that accepts a single {@link Map}&lt;{@link String},
* {@link Object}>.</li>
* </ul>
* In addition to implementing this interface, you must register the class with
* {@link ConfigurationSerialization#registerClass(Class)}.
* In addition to implementing this interface, you must register the class
* with {@link ConfigurationSerialization#registerClass(Class)}.
*
* @see DelegateDeserialization
* @see SerializableAs
@@ -25,8 +26,8 @@ public interface ConfigurationSerializable {
/**
* Creates a Map representation of this class.
* <p>
* This class must provide a method to restore this class, as defined in the
* {@link ConfigurationSerializable} interface javadocs.
* This class must provide a method to restore this class, as defined in
* the {@link ConfigurationSerializable} interface javadocs.
*
* @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>
* The class must implement {@link ConfigurationSerializable}, including the extra methods
* as specified in the javadoc of ConfigurationSerializable.
* The class must implement {@link ConfigurationSerializable}, including
* the extra methods as specified in the javadoc of
* ConfigurationSerializable.
* <p>
* If a new instance could not be made, an example being the class not fully implementing
* the interface, null will be returned.
* If a new instance could not be made, an example being the class not
* fully implementing the interface, null will be returned.
*
* @param args Arguments for deserialization
* @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>
* The class must implement {@link ConfigurationSerializable}, including the extra methods
* as specified in the javadoc of ConfigurationSerializable.
* The class must implement {@link ConfigurationSerializable}, including
* the extra methods as specified in the javadoc of
* ConfigurationSerializable.
* <p>
* If a new instance could not be made, an example being the class not fully implementing
* the interface, null will be returned.
* If a new instance could not be made, an example being the class not
* fully implementing the interface, null will be returned.
*
* @param args Arguments for deserialization
* @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
*/
@@ -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 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
*/
@@ -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
* @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
* @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;
/**
* Applies to a {@link ConfigurationSerializable} that will delegate all deserialization to another
* {@link ConfigurationSerializable}.
* Applies to a {@link ConfigurationSerializable} that will delegate all
* deserialization to another {@link ConfigurationSerializable}.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
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
*/

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