diff --git a/src/main/java/com/drtshock/playervaults/PlayerVaults.java b/src/main/java/com/drtshock/playervaults/PlayerVaults.java index 1791304..df11681 100644 --- a/src/main/java/com/drtshock/playervaults/PlayerVaults.java +++ b/src/main/java/com/drtshock/playervaults/PlayerVaults.java @@ -25,18 +25,7 @@ import com.drtshock.playervaults.util.Metrics; import com.drtshock.playervaults.util.Updater; import com.drtshock.playervaults.vaultmanagement.VaultManager; import com.drtshock.playervaults.vaultmanagement.VaultViewInfo; - -import java.io.File; -import java.io.FileOutputStream; -import java.io.IOException; -import java.io.InputStream; -import java.io.OutputStream; -import java.util.HashMap; -import java.util.logging.Level; -import java.util.logging.Logger; - import net.milkbowl.vault.economy.Economy; - import org.bukkit.Bukkit; import org.bukkit.configuration.file.YamlConfiguration; import org.bukkit.entity.Player; @@ -45,6 +34,11 @@ import org.bukkit.plugin.RegisteredServiceProvider; import org.bukkit.plugin.java.JavaPlugin; import org.bukkit.scheduler.BukkitRunnable; +import java.io.*; +import java.util.HashMap; +import java.util.logging.Level; +import java.util.logging.Logger; + public class PlayerVaults extends JavaPlugin { public static PlayerVaults PLUGIN; @@ -94,7 +88,7 @@ public class PlayerVaults extends JavaPlugin { new File(DIRECTORY + File.separator + "backups").mkdirs(); VM = new VaultManager(this); - if(getConfig().getBoolean("cleanup.enable", false)) { + if (getConfig().getBoolean("cleanup.enable", false)) { getServer().getScheduler().runTaskAsynchronously(this, new Cleanup(getConfig().getInt("cleanup.lastEdit", 30))); } } diff --git a/src/main/java/com/drtshock/playervaults/commands/Commands.java b/src/main/java/com/drtshock/playervaults/commands/Commands.java index 9f8be9c..a6239b5 100644 --- a/src/main/java/com/drtshock/playervaults/commands/Commands.java +++ b/src/main/java/com/drtshock/playervaults/commands/Commands.java @@ -16,12 +16,10 @@ */ package com.drtshock.playervaults.commands; -import com.drtshock.playervaults.vaultmanagement.VaultOperations; -import com.drtshock.playervaults.vaultmanagement.VaultViewInfo; import com.drtshock.playervaults.PlayerVaults; import com.drtshock.playervaults.util.Lang; -import java.util.Set; - +import com.drtshock.playervaults.vaultmanagement.VaultOperations; +import com.drtshock.playervaults.vaultmanagement.VaultViewInfo; import org.bukkit.ChatColor; import org.bukkit.command.Command; import org.bukkit.command.CommandExecutor; diff --git a/src/main/java/com/drtshock/playervaults/commands/SignSetInfo.java b/src/main/java/com/drtshock/playervaults/commands/SignSetInfo.java index 1456f19..9a2ff53 100644 --- a/src/main/java/com/drtshock/playervaults/commands/SignSetInfo.java +++ b/src/main/java/com/drtshock/playervaults/commands/SignSetInfo.java @@ -17,8 +17,8 @@ package com.drtshock.playervaults.commands; /** - * A class for setting signs. Stores information about the sign owner, number, - * and whether or not is opens a self vault or another person's vault. + * A class for setting signs. Stores information about the sign owner, number, and whether or not is opens a self vault + * or another person's vault. */ public class SignSetInfo { @@ -48,8 +48,7 @@ public class SignSetInfo { } /** - * Get whether or not the sign will open their own vault or another - * person's. + * Get whether or not the sign will open their own vault or another person's. * * @return Whether or not it is a 'self' sign. */ diff --git a/src/main/java/com/drtshock/playervaults/listeners/Listeners.java b/src/main/java/com/drtshock/playervaults/listeners/Listeners.java index 14d6905..6c43081 100644 --- a/src/main/java/com/drtshock/playervaults/listeners/Listeners.java +++ b/src/main/java/com/drtshock/playervaults/listeners/Listeners.java @@ -17,13 +17,10 @@ package com.drtshock.playervaults.listeners; import com.drtshock.playervaults.PlayerVaults; -import com.drtshock.playervaults.vaultmanagement.VaultOperations; -import com.drtshock.playervaults.vaultmanagement.VaultViewInfo; import com.drtshock.playervaults.util.Lang; import com.drtshock.playervaults.vaultmanagement.VaultManager; - -import java.io.IOException; - +import com.drtshock.playervaults.vaultmanagement.VaultOperations; +import com.drtshock.playervaults.vaultmanagement.VaultViewInfo; import org.bukkit.ChatColor; import org.bukkit.Location; import org.bukkit.Material; @@ -40,13 +37,11 @@ import org.bukkit.event.block.BlockPhysicsEvent; import org.bukkit.event.entity.EntityChangeBlockEvent; import org.bukkit.event.entity.PlayerDeathEvent; import org.bukkit.event.inventory.InventoryCloseEvent; -import org.bukkit.event.player.PlayerInteractEntityEvent; -import org.bukkit.event.player.PlayerInteractEvent; -import org.bukkit.event.player.PlayerJoinEvent; -import org.bukkit.event.player.PlayerQuitEvent; -import org.bukkit.event.player.PlayerTeleportEvent; +import org.bukkit.event.player.*; import org.bukkit.inventory.Inventory; +import java.io.IOException; + public class Listeners implements Listener { public PlayerVaults plugin; @@ -54,6 +49,7 @@ public class Listeners implements Listener { public Listeners(PlayerVaults playerVaults) { this.plugin = playerVaults; } + VaultManager vm = new VaultManager(plugin); public void saveVault(Player player) { @@ -203,8 +199,7 @@ public class Listeners implements Listener { } /** - * Check if the location given is a sign, and if so, remove it from the - * signs.yml file + * Check if the location given is a sign, and if so, remove it from the signs.yml file * * @param location The location to check */ diff --git a/src/main/java/com/drtshock/playervaults/tasks/Cleanup.java b/src/main/java/com/drtshock/playervaults/tasks/Cleanup.java index a27a4c7..cd00423 100644 --- a/src/main/java/com/drtshock/playervaults/tasks/Cleanup.java +++ b/src/main/java/com/drtshock/playervaults/tasks/Cleanup.java @@ -17,11 +17,11 @@ public class Cleanup extends BukkitRunnable { @Override public void run() { File file = new File(PlayerVaults.DIRECTORY); - if(!file.exists()) return; + if (!file.exists()) return; long time = System.currentTimeMillis(); - for(File f : file.listFiles()) { - if(time - f.lastModified() > diff) { + for (File f : file.listFiles()) { + if (time - f.lastModified() > diff) { f.delete(); PlayerVaults.PLUGIN.getLogger().info("Deleting vault file: " + f.getName()); } diff --git a/src/main/java/com/drtshock/playervaults/util/Lang.java b/src/main/java/com/drtshock/playervaults/util/Lang.java index 142ec06..296d586 100644 --- a/src/main/java/com/drtshock/playervaults/util/Lang.java +++ b/src/main/java/com/drtshock/playervaults/util/Lang.java @@ -52,6 +52,7 @@ public enum Lang { /** * Lang enum constructor. + * * @param path The string path. * @param start The default string. */ @@ -62,6 +63,7 @@ public enum Lang { /** * Set the {@code YamlConfiguration} to use. + * * @param config The config to set. */ public static void setFile(YamlConfiguration config) { @@ -77,6 +79,7 @@ public enum Lang { /** * Get the default value of the path. + * * @return The default value of the path. */ public String getDefault() { @@ -85,6 +88,7 @@ public enum Lang { /** * Get the path to the string. + * * @return The path to the string. */ public String getPath() { diff --git a/src/main/java/com/drtshock/playervaults/util/Metrics.java b/src/main/java/com/drtshock/playervaults/util/Metrics.java index 046f0c1..9bd2f16 100644 --- a/src/main/java/com/drtshock/playervaults/util/Metrics.java +++ b/src/main/java/com/drtshock/playervaults/util/Metrics.java @@ -34,23 +34,12 @@ import org.bukkit.plugin.Plugin; import org.bukkit.plugin.PluginDescriptionFile; import org.bukkit.scheduler.BukkitTask; -import java.io.BufferedReader; -import java.io.ByteArrayOutputStream; -import java.io.File; -import java.io.IOException; -import java.io.InputStreamReader; -import java.io.OutputStream; -import java.io.UnsupportedEncodingException; +import java.io.*; import java.net.Proxy; import java.net.URL; import java.net.URLConnection; import java.net.URLEncoder; -import java.util.Collections; -import java.util.HashSet; -import java.util.Iterator; -import java.util.LinkedHashSet; -import java.util.Set; -import java.util.UUID; +import java.util.*; import java.util.logging.Level; import java.util.zip.GZIPOutputStream; @@ -148,6 +137,7 @@ public class Metrics { * website. Plotters can be added to the graph object returned. * * @param name The name of the graph + * * @return Graph object created. Will never return NULL under normal circumstances unless bad parameters are given */ public Graph createGraph(final String name) { @@ -488,6 +478,7 @@ public class Metrics { * GZip compress a string of bytes * * @param input + * * @return */ public static byte[] gzip(String input) { @@ -529,6 +520,7 @@ public class Metrics { * @param json * @param key * @param value + * * @throws UnsupportedEncodingException */ private static void appendJSONPair(StringBuilder json, String key, String value) throws UnsupportedEncodingException { @@ -561,6 +553,7 @@ public class Metrics { * Escape a string to create a valid JSON string * * @param text + * * @return */ private static String escapeJSON(String text) { @@ -607,6 +600,7 @@ public class Metrics { * Encode text as UTF-8 * * @param text the text to encode + * * @return the encoded text, as UTF-8 */ private static String urlEncode(final String text) throws UnsupportedEncodingException { diff --git a/src/main/java/com/drtshock/playervaults/util/Updater.java b/src/main/java/com/drtshock/playervaults/util/Updater.java index fa394fd..1c1cb1b 100644 --- a/src/main/java/com/drtshock/playervaults/util/Updater.java +++ b/src/main/java/com/drtshock/playervaults/util/Updater.java @@ -1,5 +1,11 @@ package com.drtshock.playervaults.util; +import org.bukkit.configuration.file.YamlConfiguration; +import org.bukkit.plugin.Plugin; +import org.json.simple.JSONArray; +import org.json.simple.JSONObject; +import org.json.simple.JSONValue; + import java.io.*; import java.net.MalformedURLException; import java.net.URL; @@ -9,24 +15,18 @@ import java.util.logging.Level; import java.util.zip.ZipEntry; import java.util.zip.ZipFile; -import org.bukkit.configuration.file.YamlConfiguration; -import org.bukkit.plugin.Plugin; -import org.json.simple.JSONArray; -import org.json.simple.JSONObject; -import org.json.simple.JSONValue; - /** * Check dev.bukkit.org to find updates for a given plugin, and download the updates if needed. *

- * VERY, VERY IMPORTANT: Because there are no standards for adding auto-update toggles in your plugin's config, this system provides NO CHECK WITH YOUR CONFIG to make sure the user has allowed auto-updating. - *
- * It is a BUKKIT POLICY that you include a boolean value in your config that prevents the auto-updater from running AT ALL. - *
- * If you fail to include this option in your config, your plugin will be REJECTED when you attempt to submit it to dev.bukkit.org. + * VERY, VERY IMPORTANT: Because there are no standards for adding auto-update toggles in your plugin's config, + * this system provides NO CHECK WITH YOUR CONFIG to make sure the user has allowed auto-updating.
It is a + * BUKKIT POLICY that you include a boolean value in your config that prevents the auto-updater from running + * AT ALL.
If you fail to include this option in your config, your plugin will be REJECTED when you + * attempt to submit it to dev.bukkit.org. *

- * An example of a good configuration option would be something similar to 'auto-update: true' - if this value is set to false you may NOT run the auto-updater. - *
- * If you are unsure about these rules, please read the plugin submission guidelines: http://goo.gl/8iU5l + * An example of a good configuration option would be something similar to 'auto-update: true' - if this value is set to + * false you may NOT run the auto-updater.
If you are unsure about these rules, please read the plugin submission + * guidelines: http://goo.gl/8iU5l * * @author Gravity */ @@ -92,7 +92,8 @@ public class Updater { */ FAIL_DBO, /** - * When running the version check, the file on DBO did not contain the a version in the format 'vVersion' such as 'v1.0'. + * When running the version check, the file on DBO did not contain the a version in the format 'vVersion' such + * as 'v1.0'. */ FAIL_NOVERSION, /** @@ -130,10 +131,11 @@ public class Updater { /** * Initialize the updater * - * @param plugin The plugin that is checking for an update. - * @param id The dev.bukkit.org id of the project - * @param file The file that the plugin is running from, get this by doing this.getFile() from within your main class. - * @param type Specify the type of update this will be. See {@link UpdateType} + * @param plugin The plugin that is checking for an update. + * @param id The dev.bukkit.org id of the project + * @param file The file that the plugin is running from, get this by doing this.getFile() from within your main + * class. + * @param type Specify the type of update this will be. See {@link UpdateType} * @param announce True if the program should announce the progress of new updates in console */ public Updater(Plugin plugin, int id, File file, Updater.UpdateType type, boolean announce) { @@ -230,8 +232,8 @@ public class Updater { } /** - * As the result of Updater output depends on the thread's completion, it is necessary to wait for the thread to finish - * before allowing anyone to check the result. + * As the result of Updater output depends on the thread's completion, it is necessary to wait for the thread to + * finish before allowing anyone to check the result. */ private void waitForThread() { if (thread != null && thread.isAlive()) { @@ -378,7 +380,8 @@ public class Updater { } /** - * Check if the name of a jar is one of the plugins currently installed, used for extracting the correct files out of a zip. + * Check if the name of a jar is one of the plugins currently installed, used for extracting the correct files out + * of a zip. */ private boolean pluginFile(String name) { for (File file : new File("plugins").listFiles()) { @@ -390,7 +393,8 @@ public class Updater { } /** - * Check to see if the program should continue by evaluation whether the plugin is already updated, or shouldn't be updated + * Check to see if the program should continue by evaluation whether the plugin is already updated, or shouldn't be + * updated */ private boolean versionCheck(String title) { if (type != Updater.UpdateType.NO_VERSION_CHECK) { diff --git a/src/main/java/com/drtshock/playervaults/vaultmanagement/EconomyOperations.java b/src/main/java/com/drtshock/playervaults/vaultmanagement/EconomyOperations.java index 3f96875..e34022f 100644 --- a/src/main/java/com/drtshock/playervaults/vaultmanagement/EconomyOperations.java +++ b/src/main/java/com/drtshock/playervaults/vaultmanagement/EconomyOperations.java @@ -18,17 +18,15 @@ package com.drtshock.playervaults.vaultmanagement; import com.drtshock.playervaults.PlayerVaults; import com.drtshock.playervaults.util.Lang; - -import java.io.File; -import java.io.IOException; - import net.milkbowl.vault.economy.EconomyResponse; - import org.bukkit.ChatColor; import org.bukkit.configuration.InvalidConfigurationException; import org.bukkit.configuration.file.YamlConfiguration; import org.bukkit.entity.Player; +import java.io.File; +import java.io.IOException; + /** * A class that handles all economy operations. */ @@ -48,6 +46,7 @@ public class EconomyOperations { * * @param player The player to pay. * @param number The vault number to open. + * * @return The transaction success. */ public static boolean payToOpen(Player player, int number) { @@ -71,6 +70,7 @@ public class EconomyOperations { * Have a player pay to create a vault. * * @param player The player to pay. + * * @return The transaction success */ public static boolean payToCreate(Player player) { @@ -92,6 +92,7 @@ public class EconomyOperations { * * @param player The player to receive the money. * @param number The vault number to delete. + * * @return The transaction success. */ public static boolean refundOnDelete(Player player, int number) { diff --git a/src/main/java/com/drtshock/playervaults/vaultmanagement/Serialization.java b/src/main/java/com/drtshock/playervaults/vaultmanagement/Serialization.java index 815b2b0..721c667 100644 --- a/src/main/java/com/drtshock/playervaults/vaultmanagement/Serialization.java +++ b/src/main/java/com/drtshock/playervaults/vaultmanagement/Serialization.java @@ -16,13 +16,6 @@ */ package com.drtshock.playervaults.vaultmanagement; -import java.util.ArrayList; -import java.util.HashMap; -import java.util.Iterator; -import java.util.List; -import java.util.Map; -import java.util.Map.Entry; - import org.bukkit.Bukkit; import org.bukkit.ChatColor; import org.bukkit.configuration.serialization.ConfigurationSerializable; @@ -33,11 +26,13 @@ import org.json.JSONArray; import org.json.JSONException; import org.json.JSONObject; +import java.util.*; +import java.util.Map.Entry; + /** * Fancy JSON serialization mostly by evilmidget38. * * @author evilmidget38, gomeow - * */ public class Serialization { diff --git a/src/main/java/com/drtshock/playervaults/vaultmanagement/VaultHolder.java b/src/main/java/com/drtshock/playervaults/vaultmanagement/VaultHolder.java index f6afd49..52f9856 100644 --- a/src/main/java/com/drtshock/playervaults/vaultmanagement/VaultHolder.java +++ b/src/main/java/com/drtshock/playervaults/vaultmanagement/VaultHolder.java @@ -20,8 +20,7 @@ import org.bukkit.inventory.Inventory; import org.bukkit.inventory.InventoryHolder; /** - * Represents a VaultHolder to assist in detection of Player Vaults from other - * plugins. + * Represents a VaultHolder to assist in detection of Player Vaults from other plugins. */ public class VaultHolder implements InventoryHolder { diff --git a/src/main/java/com/drtshock/playervaults/vaultmanagement/VaultManager.java b/src/main/java/com/drtshock/playervaults/vaultmanagement/VaultManager.java index 6989dbe..84530c0 100644 --- a/src/main/java/com/drtshock/playervaults/vaultmanagement/VaultManager.java +++ b/src/main/java/com/drtshock/playervaults/vaultmanagement/VaultManager.java @@ -18,23 +18,20 @@ package com.drtshock.playervaults.vaultmanagement; import com.drtshock.playervaults.PlayerVaults; import com.drtshock.playervaults.util.Lang; - -import java.io.File; -import java.io.IOException; -import java.util.ArrayList; -import java.util.List; - import org.bukkit.Bukkit; -import org.bukkit.ChatColor; import org.bukkit.command.CommandSender; import org.bukkit.configuration.file.FileConfiguration; import org.bukkit.configuration.file.YamlConfiguration; import org.bukkit.entity.Player; import org.bukkit.inventory.Inventory; +import java.io.File; +import java.io.IOException; +import java.util.ArrayList; +import java.util.List; + /** - * A class for managing actual IO to the files, loading inventories, and saving - * them. + * A class for managing actual IO to the files, loading inventories, and saving them. */ public class VaultManager { @@ -43,6 +40,7 @@ public class VaultManager { public VaultManager(PlayerVaults instance) { this.plugin = instance; } + private final String directory = "plugins" + File.separator + "PlayerVaults" + File.separator + "vaults"; /** @@ -51,6 +49,7 @@ public class VaultManager { * @param inventory The inventory to be saved. * @param player The player of whose file to save to. * @param number The vault number. + * * @throws IOException Uh oh! */ public void saveVault(Inventory inventory, String player, int number) throws IOException { @@ -92,7 +91,7 @@ public class VaultManager { if (playerFile.getConfigurationSection("vault" + number) == null) { VaultHolder vaultHolder = new VaultHolder(number); Player player = Bukkit.getPlayer(holder); - if(player == null) { + if (player == null) { return null; } if (EconomyOperations.payToCreate(player)) { @@ -145,12 +144,12 @@ public class VaultManager { } /** - * Get an inventory from file. Returns null if the inventory doesn't exist. - * SHOULD ONLY BE USED INTERNALLY + * Get an inventory from file. Returns null if the inventory doesn't exist. SHOULD ONLY BE USED INTERNALLY * * @param playerFile the YamlConfiguration file. * @param size the size of the vault. * @param number the vault number. + * * @return inventory if exists, otherwise null. */ private Inventory getInventory(YamlConfiguration playerFile, int size, int number) { @@ -167,11 +166,11 @@ public class VaultManager { } /** - * Gets an inventory without storing references to it. Used for dropping a - * players inventories on death. + * Gets an inventory without storing references to it. Used for dropping a players inventories on death. * * @param holder The holder of the vault. * @param number The vault number. + * * @return The inventory of the specified holder and vault number. */ public Inventory getVault(String holder, int number) { @@ -199,12 +198,13 @@ public class VaultManager { * @param sender The sender of whom to send messages to. * @param holder The vault holder. * @param number The vault number. + * * @throws IOException Uh oh! */ public void deleteVault(CommandSender sender, String holder, int number) throws IOException { String name = holder.toLowerCase(); File file = new File(directory + File.separator + name.toLowerCase() + ".yml"); - if(!file.exists()) { + if (!file.exists()) { return; } FileConfiguration playerFile = YamlConfiguration.loadConfiguration(file); @@ -223,6 +223,7 @@ public class VaultManager { * Get the holder's vault file. Create if doesn't exist. * * @param holder The vault holder. + * * @return The holder's vault config file. */ public YamlConfiguration getPlayerVaultFile(String holder) { @@ -247,6 +248,7 @@ public class VaultManager { * * @param holder The vault holder of whose file to save. * @param yaml The config to save. + * * @throws IOException Uh oh! */ public void saveFile(String holder, YamlConfiguration yaml) throws IOException { diff --git a/src/main/java/com/drtshock/playervaults/vaultmanagement/VaultOperations.java b/src/main/java/com/drtshock/playervaults/vaultmanagement/VaultOperations.java index 752d7eb..a4d8f80 100644 --- a/src/main/java/com/drtshock/playervaults/vaultmanagement/VaultOperations.java +++ b/src/main/java/com/drtshock/playervaults/vaultmanagement/VaultOperations.java @@ -18,23 +18,22 @@ package com.drtshock.playervaults.vaultmanagement; import com.drtshock.playervaults.PlayerVaults; import com.drtshock.playervaults.util.Lang; - -import java.io.IOException; - import org.bukkit.Bukkit; import org.bukkit.ChatColor; import org.bukkit.command.CommandSender; import org.bukkit.entity.Player; import org.bukkit.inventory.Inventory; +import java.io.IOException; + public class VaultOperations { /** - * Check whether or not the player has permission to open the requested - * vault. + * Check whether or not the player has permission to open the requested vault. * * @param sender The person to check. * @param number The vault number. + * * @return Whether or not they have permission. */ public static boolean checkPerms(CommandSender sender, int number) { @@ -53,8 +52,8 @@ public class VaultOperations { * Get the max size vault a player is allowed to have. * * @param player that is having his permissions checked. - * @return max size as integer. If no max size is set then it will default - * to 54. + * + * @return max size as integer. If no max size is set then it will default to 54. */ public static int getMaxVaultSize(Player player) { if (player == null) { @@ -73,6 +72,7 @@ public class VaultOperations { * * @param player The player to open to. * @param arg The vault number to open. + * * @return Whether or not the player was allowed to open it. */ public static boolean openOwnVault(Player player, String arg) { @@ -107,6 +107,7 @@ public class VaultOperations { * @param player The player to open to. * @param holder The user to whom the requested vault belongs. * @param arg The vault number to open. + * * @return Whether or not the player was allowed to open it. */ public static boolean openOtherVault(Player player, String holder, String arg) { diff --git a/src/main/java/com/drtshock/playervaults/vaultmanagement/VaultViewInfo.java b/src/main/java/com/drtshock/playervaults/vaultmanagement/VaultViewInfo.java index 03f0d13..c79030d 100644 --- a/src/main/java/com/drtshock/playervaults/vaultmanagement/VaultViewInfo.java +++ b/src/main/java/com/drtshock/playervaults/vaultmanagement/VaultViewInfo.java @@ -17,8 +17,7 @@ package com.drtshock.playervaults.vaultmanagement; /** - * A class that stores information about a vault viewing including the holder of - * the vault, and the vault number. + * A class that stores information about a vault viewing including the holder of the vault, and the vault number. */ public class VaultViewInfo { diff --git a/src/main/java/org/json/JSONArray.java b/src/main/java/org/json/JSONArray.java index e45fcc5..b93ddf8 100644 --- a/src/main/java/org/json/JSONArray.java +++ b/src/main/java/org/json/JSONArray.java @@ -34,47 +34,30 @@ import java.util.Iterator; import java.util.Map; /** - * A JSONArray is an ordered sequence of values. Its external text form is a - * string wrapped in square brackets with commas separating the values. The - * internal form is an object having get and opt - * methods for accessing the values by index, and put methods for - * adding or replacing values. The values can be any of these types: - * Boolean, JSONArray, JSONObject, - * Number, String, or the - * JSONObject.NULL object. - *

- * The constructor can convert a JSON text into a Java object. The - * toString method converts to JSON text. - *

- * A get method returns a value if one can be found, and throws an - * exception if one cannot be found. An opt method returns a - * default value instead of throwing an exception, and so is useful for - * obtaining optional values. - *

- * The generic get() and opt() methods return an - * object which you can cast or query for type. There are also typed - * get and opt methods that do type checking and type - * coercion for you. - *

- * The texts produced by the toString methods strictly conform to - * JSON syntax rules. The constructors are more forgiving in the texts they will - * accept: - *

+ * A JSONArray is an ordered sequence of values. Its external text form is a string wrapped in square brackets with + * commas separating the values. The internal form is an object having get and opt methods for + * accessing the values by index, and put methods for adding or replacing values. The values can be any of + * these types: Boolean, JSONArray, JSONObject, Number, + * String, or the JSONObject.NULL object. + *

+ * The constructor can convert a JSON text into a Java object. The toString method converts to JSON text. + *

+ * A get method returns a value if one can be found, and throws an exception if one cannot be found. An + * opt method returns a default value instead of throwing an exception, and so is useful for obtaining + * optional values. + *

+ * The generic get() and opt() methods return an object which you can cast or query for type. + * There are also typed get and opt methods that do type checking and type coercion for you. + *

+ * The texts produced by the toString methods strictly conform to JSON syntax rules. The constructors are + * more forgiving in the texts they will accept:

* * @author JSON.org * @version 2012-11-13 @@ -95,7 +78,9 @@ public class JSONArray { /** * Construct a JSONArray from a JSONTokener. + * * @param x A JSONTokener + * * @throws JSONException If there is a syntax error. */ public JSONArray(JSONTokener x) throws JSONException { @@ -132,10 +117,11 @@ public class JSONArray { /** * Construct a JSONArray from a source JSON text. - * @param source A string that begins with - * [ (left bracket) - * and ends with ] (right bracket). - * @throws JSONException If there is a syntax error. + * + * @param source A string that begins with [ (left bracket) and ends with + * ] (right bracket). + * + * @throws JSONException If there is a syntax error. */ public JSONArray(String source) throws JSONException { this(new JSONTokener(source)); @@ -143,7 +129,8 @@ public class JSONArray { /** * Construct a JSONArray from a Collection. - * @param collection A Collection. + * + * @param collection A Collection. */ public JSONArray(Collection collection) { this.myArrayList = new ArrayList(); @@ -157,6 +144,7 @@ public class JSONArray { /** * Construct a JSONArray from an array + * * @throws JSONException If not an array. */ public JSONArray(Object array) throws JSONException { @@ -174,9 +162,11 @@ public class JSONArray { /** * Get the object value associated with an index. - * @param index - * The index must be between 0 and length() - 1. + * + * @param index The index must be between 0 and length() - 1. + * * @return An object value. + * * @throws JSONException If there is no value for the index. */ public Object get(int index) throws JSONException { @@ -188,13 +178,13 @@ public class JSONArray { } /** - * Get the boolean value associated with an index. - * The string values "true" and "false" are converted to boolean. + * Get the boolean value associated with an index. The string values "true" and "false" are converted to boolean. * * @param index The index must be between 0 and length() - 1. + * * @return The truth. - * @throws JSONException If there is no value for the index or if the - * value is not convertible to boolean. + * + * @throws JSONException If there is no value for the index or if the value is not convertible to boolean. */ public boolean getBoolean(int index) throws JSONException { Object object = this.get(index); @@ -214,9 +204,10 @@ public class JSONArray { * Get the double value associated with an index. * * @param index The index must be between 0 and length() - 1. + * * @return The value. - * @throws JSONException If the key is not found or if the value cannot - * be converted to a number. + * + * @throws JSONException If the key is not found or if the value cannot be converted to a number. */ public double getDouble(int index) throws JSONException { Object object = this.get(index); @@ -234,7 +225,9 @@ public class JSONArray { * Get the int value associated with an index. * * @param index The index must be between 0 and length() - 1. + * * @return The value. + * * @throws JSONException If the key is not found or if the value is not a number. */ public int getInt(int index) throws JSONException { @@ -251,10 +244,12 @@ public class JSONArray { /** * Get the JSONArray associated with an index. + * * @param index The index must be between 0 and length() - 1. + * * @return A JSONArray value. - * @throws JSONException If there is no value for the index. or if the - * value is not a JSONArray + * + * @throws JSONException If there is no value for the index. or if the value is not a JSONArray */ public JSONArray getJSONArray(int index) throws JSONException { Object object = this.get(index); @@ -267,10 +262,12 @@ public class JSONArray { /** * Get the JSONObject associated with an index. + * * @param index subscript + * * @return A JSONObject value. - * @throws JSONException If there is no value for the index or if the - * value is not a JSONObject + * + * @throws JSONException If there is no value for the index or if the value is not a JSONObject */ public JSONObject getJSONObject(int index) throws JSONException { Object object = this.get(index); @@ -285,9 +282,10 @@ public class JSONArray { * Get the long value associated with an index. * * @param index The index must be between 0 and length() - 1. + * * @return The value. - * @throws JSONException If the key is not found or if the value cannot - * be converted to a number. + * + * @throws JSONException If the key is not found or if the value cannot be converted to a number. */ public long getLong(int index) throws JSONException { Object object = this.get(index); @@ -303,8 +301,11 @@ public class JSONArray { /** * Get the string associated with an index. + * * @param index The index must be between 0 and length() - 1. + * * @return A string value. + * * @throws JSONException If there is no string value for the index. */ public String getString(int index) throws JSONException { @@ -317,7 +318,9 @@ public class JSONArray { /** * Determine if the value is null. + * * @param index The index must be between 0 and length() - 1. + * * @return true if the value at the index is null, or if there is no value. */ public boolean isNull(int index) { @@ -325,11 +328,13 @@ public class JSONArray { } /** - * Make a string from the contents of this JSONArray. The - * separator string is inserted between each element. - * Warning: This method assumes that the data structure is acyclical. + * Make a string from the contents of this JSONArray. The separator string is inserted between each + * element. Warning: This method assumes that the data structure is acyclical. + * * @param separator A string that will be inserted between the elements. + * * @return a string. + * * @throws JSONException If the array contains an invalid number. */ public String join(String separator) throws JSONException { @@ -356,9 +361,10 @@ public class JSONArray { /** * Get the optional object value associated with an index. + * * @param index The index must be between 0 and length() - 1. - * @return An object value, or null if there is no - * object at that index. + * + * @return An object value, or null if there is no object at that index. */ public Object opt(int index) { return (index < 0 || index >= this.length()) @@ -367,11 +373,11 @@ public class JSONArray { } /** - * Get the optional boolean value associated with an index. - * It returns false if there is no value at that index, - * or if the value is not Boolean.TRUE or the String "true". + * Get the optional boolean value associated with an index. It returns false if there is no value at that index, or + * if the value is not Boolean.TRUE or the String "true". * * @param index The index must be between 0 and length() - 1. + * * @return The truth. */ public boolean optBoolean(int index) { @@ -379,12 +385,12 @@ public class JSONArray { } /** - * Get the optional boolean value associated with an index. - * It returns the defaultValue if there is no value at that index or if - * it is not a Boolean or the String "true" or "false" (case insensitive). + * Get the optional boolean value associated with an index. It returns the defaultValue if there is no value at that + * index or if it is not a Boolean or the String "true" or "false" (case insensitive). * * @param index The index must be between 0 and length() - 1. - * @param defaultValue A boolean default. + * @param defaultValue A boolean default. + * * @return The truth. */ public boolean optBoolean(int index, boolean defaultValue) { @@ -396,11 +402,11 @@ public class JSONArray { } /** - * Get the optional double value associated with an index. - * NaN is returned if there is no value for the index, - * or if the value is not a number and cannot be converted to a number. + * Get the optional double value associated with an index. NaN is returned if there is no value for the index, or if + * the value is not a number and cannot be converted to a number. * * @param index The index must be between 0 and length() - 1. + * * @return The value. */ public double optDouble(int index) { @@ -408,12 +414,12 @@ public class JSONArray { } /** - * Get the optional double value associated with an index. - * The defaultValue is returned if there is no value for the index, - * or if the value is not a number and cannot be converted to a number. + * Get the optional double value associated with an index. The defaultValue is returned if there is no value for the + * index, or if the value is not a number and cannot be converted to a number. * * @param index subscript - * @param defaultValue The default value. + * @param defaultValue The default value. + * * @return The value. */ public double optDouble(int index, double defaultValue) { @@ -425,11 +431,11 @@ public class JSONArray { } /** - * Get the optional int value associated with an index. - * Zero is returned if there is no value for the index, - * or if the value is not a number and cannot be converted to a number. + * Get the optional int value associated with an index. Zero is returned if there is no value for the index, or if + * the value is not a number and cannot be converted to a number. * * @param index The index must be between 0 and length() - 1. + * * @return The value. */ public int optInt(int index) { @@ -437,11 +443,12 @@ public class JSONArray { } /** - * Get the optional int value associated with an index. - * The defaultValue is returned if there is no value for the index, - * or if the value is not a number and cannot be converted to a number. + * Get the optional int value associated with an index. The defaultValue is returned if there is no value for the + * index, or if the value is not a number and cannot be converted to a number. + * * @param index The index must be between 0 and length() - 1. - * @param defaultValue The default value. + * @param defaultValue The default value. + * * @return The value. */ public int optInt(int index, int defaultValue) { @@ -454,9 +461,10 @@ public class JSONArray { /** * Get the optional JSONArray associated with an index. + * * @param index subscript - * @return A JSONArray value, or null if the index has no value, - * or if the value is not a JSONArray. + * + * @return A JSONArray value, or null if the index has no value, or if the value is not a JSONArray. */ public JSONArray optJSONArray(int index) { Object o = this.opt(index); @@ -464,11 +472,11 @@ public class JSONArray { } /** - * Get the optional JSONObject associated with an index. - * Null is returned if the key is not found, or null if the index has - * no value, or if the value is not a JSONObject. + * Get the optional JSONObject associated with an index. Null is returned if the key is not found, or null if the + * index has no value, or if the value is not a JSONObject. * * @param index The index must be between 0 and length() - 1. + * * @return A JSONObject value. */ public JSONObject optJSONObject(int index) { @@ -477,11 +485,11 @@ public class JSONArray { } /** - * Get the optional long value associated with an index. - * Zero is returned if there is no value for the index, - * or if the value is not a number and cannot be converted to a number. + * Get the optional long value associated with an index. Zero is returned if there is no value for the index, or if + * the value is not a number and cannot be converted to a number. * * @param index The index must be between 0 and length() - 1. + * * @return The value. */ public long optLong(int index) { @@ -489,11 +497,12 @@ public class JSONArray { } /** - * Get the optional long value associated with an index. - * The defaultValue is returned if there is no value for the index, - * or if the value is not a number and cannot be converted to a number. + * Get the optional long value associated with an index. The defaultValue is returned if there is no value for the + * index, or if the value is not a number and cannot be converted to a number. + * * @param index The index must be between 0 and length() - 1. - * @param defaultValue The default value. + * @param defaultValue The default value. + * * @return The value. */ public long optLong(int index, long defaultValue) { @@ -505,11 +514,11 @@ public class JSONArray { } /** - * Get the optional string value associated with an index. It returns an - * empty string if there is no value at that index. If the value - * is not a string and is not null, then it is coverted to a string. + * Get the optional string value associated with an index. It returns an empty string if there is no value at that + * index. If the value is not a string and is not null, then it is coverted to a string. * * @param index The index must be between 0 and length() - 1. + * * @return A String value. */ public String optString(int index) { @@ -517,11 +526,11 @@ public class JSONArray { } /** - * Get the optional string associated with an index. - * The defaultValue is returned if the key is not found. + * Get the optional string associated with an index. The defaultValue is returned if the key is not found. * * @param index The index must be between 0 and length() - 1. - * @param defaultValue The default value. + * @param defaultValue The default value. + * * @return A String value. */ public String optString(int index, String defaultValue) { @@ -535,6 +544,7 @@ public class JSONArray { * Append a boolean value. This increases the array's length by one. * * @param value A boolean value. + * * @return this. */ public JSONArray put(boolean value) { @@ -543,9 +553,10 @@ public class JSONArray { } /** - * Put a value in the JSONArray, where the value will be a - * JSONArray which is produced from a Collection. + * Put a value in the JSONArray, where the value will be a JSONArray which is produced from a Collection. + * * @param value A Collection value. + * * @return this. */ public JSONArray put(Collection value) { @@ -557,8 +568,10 @@ public class JSONArray { * Append a double value. This increases the array's length by one. * * @param value A double value. - * @throws JSONException if the value is not finite. + * * @return this. + * + * @throws JSONException if the value is not finite. */ public JSONArray put(double value) throws JSONException { Double d = new Double(value); @@ -571,6 +584,7 @@ public class JSONArray { * Append an int value. This increases the array's length by one. * * @param value An int value. + * * @return this. */ public JSONArray put(int value) { @@ -582,6 +596,7 @@ public class JSONArray { * Append an long value. This increases the array's length by one. * * @param value A long value. + * * @return this. */ public JSONArray put(long value) { @@ -590,9 +605,10 @@ public class JSONArray { } /** - * Put a value in the JSONArray, where the value will be a - * JSONObject which is produced from a Map. + * Put a value in the JSONArray, where the value will be a JSONObject which is produced from a Map. + * * @param value A Map value. + * * @return this. */ public JSONArray put(Map value) { @@ -602,9 +618,10 @@ public class JSONArray { /** * Append an object value. This increases the array's length by one. - * @param value An object value. The value should be a - * Boolean, Double, Integer, JSONArray, JSONObject, Long, or String, or the - * JSONObject.NULL object. + * + * @param value An object value. The value should be a Boolean, Double, Integer, JSONArray, JSONObject, Long, or + * String, or the JSONObject.NULL object. + * * @return this. */ public JSONArray put(Object value) { @@ -613,12 +630,14 @@ public class JSONArray { } /** - * Put or replace a boolean value in the JSONArray. If the index is greater - * than the length of the JSONArray, then null elements will be added as - * necessary to pad it out. + * Put or replace a boolean value in the JSONArray. If the index is greater than the length of the JSONArray, then + * null elements will be added as necessary to pad it out. + * * @param index The subscript. * @param value A boolean value. + * * @return this. + * * @throws JSONException If the index is negative. */ public JSONArray put(int index, boolean value) throws JSONException { @@ -627,13 +646,14 @@ public class JSONArray { } /** - * Put a value in the JSONArray, where the value will be a - * JSONArray which is produced from a Collection. + * Put a value in the JSONArray, where the value will be a JSONArray which is produced from a Collection. + * * @param index The subscript. * @param value A Collection value. + * * @return this. - * @throws JSONException If the index is negative or if the value is - * not finite. + * + * @throws JSONException If the index is negative or if the value is not finite. */ public JSONArray put(int index, Collection value) throws JSONException { this.put(index, new JSONArray(value)); @@ -641,14 +661,15 @@ public class JSONArray { } /** - * Put or replace a double value. If the index is greater than the length of - * the JSONArray, then null elements will be added as necessary to pad - * it out. + * Put or replace a double value. If the index is greater than the length of the JSONArray, then null elements will + * be added as necessary to pad it out. + * * @param index The subscript. * @param value A double value. + * * @return this. - * @throws JSONException If the index is negative or if the value is - * not finite. + * + * @throws JSONException If the index is negative or if the value is not finite. */ public JSONArray put(int index, double value) throws JSONException { this.put(index, new Double(value)); @@ -656,12 +677,14 @@ public class JSONArray { } /** - * Put or replace an int value. If the index is greater than the length of - * the JSONArray, then null elements will be added as necessary to pad - * it out. + * Put or replace an int value. If the index is greater than the length of the JSONArray, then null elements will be + * added as necessary to pad it out. + * * @param index The subscript. * @param value An int value. + * * @return this. + * * @throws JSONException If the index is negative. */ public JSONArray put(int index, int value) throws JSONException { @@ -670,12 +693,14 @@ public class JSONArray { } /** - * Put or replace a long value. If the index is greater than the length of - * the JSONArray, then null elements will be added as necessary to pad - * it out. + * Put or replace a long value. If the index is greater than the length of the JSONArray, then null elements will be + * added as necessary to pad it out. + * * @param index The subscript. * @param value A long value. + * * @return this. + * * @throws JSONException If the index is negative. */ public JSONArray put(int index, long value) throws JSONException { @@ -684,13 +709,14 @@ public class JSONArray { } /** - * Put a value in the JSONArray, where the value will be a - * JSONObject that is produced from a Map. + * Put a value in the JSONArray, where the value will be a JSONObject that is produced from a Map. + * * @param index The subscript. * @param value The Map value. + * * @return this. - * @throws JSONException If the index is negative or if the the value is - * an invalid number. + * + * @throws JSONException If the index is negative or if the the value is an invalid number. */ public JSONArray put(int index, Map value) throws JSONException { this.put(index, new JSONObject(value)); @@ -698,16 +724,16 @@ public class JSONArray { } /** - * Put or replace an object value in the JSONArray. If the index is greater - * than the length of the JSONArray, then null elements will be added as - * necessary to pad it out. + * Put or replace an object value in the JSONArray. If the index is greater than the length of the JSONArray, then + * null elements will be added as necessary to pad it out. + * * @param index The subscript. - * @param value The value to put into the array. The value should be a - * Boolean, Double, Integer, JSONArray, JSONObject, Long, or String, or the - * JSONObject.NULL object. + * @param value The value to put into the array. The value should be a Boolean, Double, Integer, JSONArray, + * JSONObject, Long, or String, or the JSONObject.NULL object. + * * @return this. - * @throws JSONException If the index is negative or if the the value is - * an invalid number. + * + * @throws JSONException If the index is negative or if the the value is an invalid number. */ public JSONArray put(int index, Object value) throws JSONException { JSONObject.testValidity(value); @@ -727,9 +753,10 @@ public class JSONArray { /** * Remove an index and close the hole. + * * @param index The index of the element to be removed. - * @return The value that was associated with the index, - * or null if there was no value. + * + * @return The value that was associated with the index, or null if there was no value. */ public Object remove(int index) { Object o = this.opt(index); @@ -738,12 +765,12 @@ public class JSONArray { } /** - * Produce a JSONObject by combining a JSONArray of names with the values - * of this JSONArray. - * @param names A JSONArray containing a list of key strings. These will be - * paired with the values. - * @return A JSONObject, or null if there are no names or if this JSONArray - * has no values. + * Produce a JSONObject by combining a JSONArray of names with the values of this JSONArray. + * + * @param names A JSONArray containing a list of key strings. These will be paired with the values. + * + * @return A JSONObject, or null if there are no names or if this JSONArray has no values. + * * @throws JSONException If any of the names are null. */ public JSONObject toJSONObject(JSONArray names) throws JSONException { @@ -758,15 +785,13 @@ public class JSONArray { } /** - * Make a JSON text of this JSONArray. For compactness, no - * unnecessary whitespace is added. If it is not possible to produce a - * syntactically correct JSON text then null will be returned instead. This - * could occur if the array contains an invalid number. - *

+ * Make a JSON text of this JSONArray. For compactness, no unnecessary whitespace is added. If it is not possible to + * produce a syntactically correct JSON text then null will be returned instead. This could occur if the array + * contains an invalid number. + *

* Warning: This method assumes that the data structure is acyclical. * - * @return a printable, displayable, transmittable - * representation of the array. + * @return a printable, displayable, transmittable representation of the array. */ public String toString() { try { @@ -777,14 +802,15 @@ public class JSONArray { } /** - * Make a prettyprinted JSON text of this JSONArray. - * Warning: This method assumes that the data structure is acyclical. - * @param indentFactor The number of spaces to add to each level of - * indentation. - * @return a printable, displayable, transmittable - * representation of the object, beginning - * with [ (left bracket) and ending - * with ] (right bracket). + * Make a prettyprinted JSON text of this JSONArray. Warning: This method assumes that the data structure is + * acyclical. + * + * @param indentFactor The number of spaces to add to each level of indentation. + * + * @return a printable, displayable, transmittable representation of the object, beginning with + * [ (left bracket) and ending with ] (right + * bracket). + * * @throws JSONException */ public String toString(int indentFactor) throws JSONException { @@ -795,12 +821,12 @@ public class JSONArray { } /** - * Write the contents of the JSONArray as JSON text to a writer. For - * compactness, no whitespace is added. - *

+ * Write the contents of the JSONArray as JSON text to a writer. For compactness, no whitespace is added. + *

* Warning: This method assumes that the data structure is acyclical. * * @return The writer. + * * @throws JSONException */ public Writer write(Writer writer) throws JSONException { @@ -808,16 +834,15 @@ public class JSONArray { } /** - * Write the contents of the JSONArray as JSON text to a writer. For - * compactness, no whitespace is added. - *

+ * Write the contents of the JSONArray as JSON text to a writer. For compactness, no whitespace is added. + *

* Warning: This method assumes that the data structure is acyclical. * - * @param indentFactor - * The number of spaces to add to each level of indentation. - * @param indent - * The indention of the top level. + * @param indentFactor The number of spaces to add to each level of indentation. + * @param indent The indention of the top level. + * * @return The writer. + * * @throws JSONException */ Writer write(Writer writer, int indentFactor, int indent) diff --git a/src/main/java/org/json/JSONException.java b/src/main/java/org/json/JSONException.java index 2998332..35b72b0 100644 --- a/src/main/java/org/json/JSONException.java +++ b/src/main/java/org/json/JSONException.java @@ -2,6 +2,7 @@ package org.json; /** * The JSONException is thrown by the JSON.org classes when things are amiss. + * * @author JSON.org * @version 2010-12-24 */ @@ -12,6 +13,7 @@ public class JSONException extends Exception { /** * Constructs a JSONException with an explanatory message. + * * @param message Detail about the reason for the exception. */ public JSONException(String message) { diff --git a/src/main/java/org/json/JSONObject.java b/src/main/java/org/json/JSONObject.java index e47e710..4e06b38 100644 --- a/src/main/java/org/json/JSONObject.java +++ b/src/main/java/org/json/JSONObject.java @@ -30,65 +30,42 @@ import java.io.Writer; import java.lang.reflect.Field; import java.lang.reflect.Method; import java.lang.reflect.Modifier; -import java.util.Collection; -import java.util.Enumeration; -import java.util.HashMap; -import java.util.Iterator; -import java.util.Locale; -import java.util.Map; -import java.util.ResourceBundle; -import java.util.Set; +import java.util.*; /** - * A JSONObject is an unordered collection of name/value pairs. Its external - * form is a string wrapped in curly braces with colons between the names and - * values, and commas between the values and names. The internal form is an - * object having get and opt methods for accessing the - * values by name, and put methods for adding or replacing values - * by name. The values can be any of these types: Boolean, - * JSONArray, JSONObject, Number, - * String, or the JSONObject.NULL object. A JSONObject - * constructor can be used to convert an external form JSON text into an - * internal form whose values can be retrieved with the get and - * opt methods, or to convert values into a JSON text using the - * put and toString methods. A get method - * returns a value if one can be found, and throws an exception if one cannot be - * found. An opt method returns a default value instead of throwing - * an exception, and so is useful for obtaining optional values. - *

- * The generic get() and opt() methods return an - * object, which you can cast or query for type. There are also typed - * get and opt methods that do type checking and type - * coercion for you. The opt methods differ from the get methods in that they do - * not throw. Instead, they return a specified value, such as null. - *

+ * A JSONObject is an unordered collection of name/value pairs. Its external form is a string wrapped in curly braces + * with colons between the names and values, and commas between the values and names. The internal form is an object + * having get and opt methods for accessing the values by name, and put methods + * for adding or replacing values by name. The values can be any of these types: Boolean, + * JSONArray, JSONObject, Number, String, or the + * JSONObject.NULL object. A JSONObject constructor can be used to convert an external form JSON text into + * an internal form whose values can be retrieved with the get and opt methods, or to convert + * values into a JSON text using the put and toString methods. A get method + * returns a value if one can be found, and throws an exception if one cannot be found. An opt method + * returns a default value instead of throwing an exception, and so is useful for obtaining optional values. + *

+ * The generic get() and opt() methods return an object, which you can cast or query for type. + * There are also typed get and opt methods that do type checking and type coercion for you. + * The opt methods differ from the get methods in that they do not throw. Instead, they return a specified value, such + * as null. + *

* The put methods add or replace values in an object. For example, - * + *

* 

  * myString = new JSONObject().put("JSON", "Hello, World!").toString();
  *
- * + *

* produces the string {"JSON": "Hello, World"}. - *

- * The texts produced by the toString methods strictly conform to - * the JSON syntax rules. The constructors are more forgiving in the texts they - * will accept: - *

+ *

+ * The texts produced by the toString methods strictly conform to the JSON syntax rules. The constructors + * are more forgiving in the texts they will accept:

* * @author JSON.org * @version 2012-12-01 @@ -101,23 +78,21 @@ public class JSONObject { private static final int keyPoolSize = 100; /** - * Key pooling is like string interning, but without permanently tying up - * memory. To help conserve memory, storage of duplicated key strings in - * JSONObjects will be avoided by using a key pool to manage unique key - * string objects. This is used by JSONObject.put(string, object). + * Key pooling is like string interning, but without permanently tying up memory. To help conserve memory, storage + * of duplicated key strings in JSONObjects will be avoided by using a key pool to manage unique key string objects. + * This is used by JSONObject.put(string, object). */ private static HashMap keyPool = new HashMap(keyPoolSize); /** - * JSONObject.NULL is equivalent to the value that JavaScript calls null, - * whilst Java's null is equivalent to the value that JavaScript calls - * undefined. + * JSONObject.NULL is equivalent to the value that JavaScript calls null, whilst Java's null is equivalent to the + * value that JavaScript calls undefined. */ private static final class Null { /** - * There is only intended to be a single instance of the NULL object, - * so the clone method returns itself. + * There is only intended to be a single instance of the NULL object, so the clone method returns itself. + * * @return NULL. */ protected final Object clone() { @@ -126,9 +101,10 @@ public class JSONObject { /** * A Null object is equal to the null value and to itself. - * @param object An object to test for nullness. - * @return true if the object parameter is the JSONObject.NULL object - * or null. + * + * @param object An object to test for nullness. + * + * @return true if the object parameter is the JSONObject.NULL object or null. */ public boolean equals(Object object) { return object == null || object == this; @@ -136,6 +112,7 @@ public class JSONObject { /** * Get the "null" string value. + * * @return The string "null". */ public String toString() { @@ -149,9 +126,8 @@ public class JSONObject { private final Map map; /** - * It is sometimes more convenient and less ambiguous to have a - * NULL object than to use Java's null value. - * JSONObject.NULL.equals(null) returns true. + * It is sometimes more convenient and less ambiguous to have a NULL object than to use Java's + * null value. JSONObject.NULL.equals(null) returns true. * JSONObject.NULL.toString() returns "null". */ public static final Object NULL = new Null(); @@ -164,13 +140,14 @@ public class JSONObject { } /** - * Construct a JSONObject from a subset of another JSONObject. - * An array of strings is used to identify the keys that should be copied. - * Missing keys are ignored. + * Construct a JSONObject from a subset of another JSONObject. An array of strings is used to identify the keys that + * should be copied. Missing keys are ignored. + * * @param jo A JSONObject. * @param names An array of strings. + * * @throws JSONException - * @exception JSONException If a value is a non-finite number or if a name is duplicated. + * @throws JSONException If a value is a non-finite number or if a name is duplicated. */ public JSONObject(JSONObject jo, String[] names) { this(); @@ -184,9 +161,10 @@ public class JSONObject { /** * Construct a JSONObject from a JSONTokener. + * * @param x A JSONTokener object containing the source string. - * @throws JSONException If there is a syntax error in the source string - * or a duplicated key. + * + * @throws JSONException If there is a syntax error in the source string or a duplicated key. */ public JSONObject(JSONTokener x) throws JSONException { this(); @@ -241,8 +219,8 @@ public class JSONObject { /** * Construct a JSONObject from a Map. * - * @param map A map object that can be used to initialize the contents of - * the JSONObject. + * @param map A map object that can be used to initialize the contents of the JSONObject. + * * @throws JSONException */ public JSONObject(Map map) { @@ -260,23 +238,19 @@ public class JSONObject { } /** - * Construct a JSONObject from an Object using bean getters. - * It reflects on all of the public methods of the object. - * For each of the methods with no parameters and a name starting - * with "get" or "is" followed by an uppercase letter, - * the method is invoked, and a key and the value returned from the getter method + * Construct a JSONObject from an Object using bean getters. It reflects on all of the public methods of the object. + * For each of the methods with no parameters and a name starting with "get" or "is" + * followed by an uppercase letter, the method is invoked, and a key and the value returned from the getter method * are put into the new JSONObject. + *

+ * The key is formed by removing the "get" or "is" prefix. If the second remaining + * character is not upper case, then the first character is converted to lower case. + *

+ * For example, if an object has a method named "getName", and if the result of calling + * object.getName() is "Larry Fine", then the JSONObject will contain "name": "Larry + * Fine". * - * The key is formed by removing the "get" or "is" prefix. - * If the second remaining character is not upper case, then the first - * character is converted to lower case. - * - * For example, if an object has a method named "getName", and - * if the result of calling object.getName() is "Larry Fine", - * then the JSONObject will contain "name": "Larry Fine". - * - * @param bean An object that has getter methods that should be used - * to make a JSONObject. + * @param bean An object that has getter methods that should be used to make a JSONObject. */ public JSONObject(Object bean) { this(); @@ -284,15 +258,12 @@ public class JSONObject { } /** - * Construct a JSONObject from an Object, using reflection to find the - * public members. The resulting JSONObject's keys will be the strings - * from the names array, and the values will be the field values associated - * with those keys in the object. If a key is not found or not visible, - * then it will not be copied into the new JSONObject. - * @param object An object that has fields that should be used to make a - * JSONObject. - * @param names An array of strings, the names of the fields to be obtained - * from the object. + * Construct a JSONObject from an Object, using reflection to find the public members. The resulting JSONObject's + * keys will be the strings from the names array, and the values will be the field values associated with those keys + * in the object. If a key is not found or not visible, then it will not be copied into the new JSONObject. + * + * @param object An object that has fields that should be used to make a JSONObject. + * @param names An array of strings, the names of the fields to be obtained from the object. */ public JSONObject(Object object, String names[]) { this(); @@ -307,13 +278,12 @@ public class JSONObject { } /** - * Construct a JSONObject from a source JSON text string. - * This is the most commonly used JSONObject constructor. - * @param source A string beginning - * with { (left brace) and ending - * with } (right brace). - * @exception JSONException If there is a syntax error in the source - * string or a duplicated key. + * Construct a JSONObject from a source JSON text string. This is the most commonly used JSONObject constructor. + * + * @param source A string beginning with { (left brace) and ending with + * } (right brace). + * + * @throws JSONException If there is a syntax error in the source string or a duplicated key. */ public JSONObject(String source) throws JSONException { this(new JSONTokener(source)); @@ -321,8 +291,10 @@ public class JSONObject { /** * Construct a JSONObject from a ResourceBundle. + * * @param baseName The ResourceBundle base name. * @param locale The Locale to load the ResourceBundle for. + * * @throws JSONException If any JSONExceptions are detected. */ public JSONObject(String baseName, Locale locale) throws JSONException { @@ -359,20 +331,19 @@ public class JSONObject { } /** - * Accumulate values under a key. It is similar to the put method except - * that if there is already an object stored under the key then a - * JSONArray is stored under the key to hold all of the accumulated values. - * If there is already a JSONArray, then the new value is appended to it. - * In contrast, the put method replaces the previous value. + * Accumulate values under a key. It is similar to the put method except that if there is already an object stored + * under the key then a JSONArray is stored under the key to hold all of the accumulated values. If there is already + * a JSONArray, then the new value is appended to it. In contrast, the put method replaces the previous value. + *

+ * If only one value is accumulated that is not a JSONArray, then the result will be the same as using put. But if + * multiple values are accumulated, then the result will be like append. * - * If only one value is accumulated that is not a JSONArray, then the - * result will be the same as using put. But if multiple values are - * accumulated, then the result will be like append. - * @param key A key string. + * @param key A key string. * @param value An object to be accumulated under the key. + * * @return this. - * @throws JSONException If the value is an invalid number - * or if the key is null. + * + * @throws JSONException If the value is an invalid number or if the key is null. */ public JSONObject accumulate( String key, @@ -393,15 +364,16 @@ public class JSONObject { } /** - * Append values to the array under a key. If the key does not exist in the - * JSONObject, then the key is put in the JSONObject with its value being a - * JSONArray containing the value parameter. If the key was already - * associated with a JSONArray, then the value parameter is appended to it. - * @param key A key string. + * Append values to the array under a key. If the key does not exist in the JSONObject, then the key is put in the + * JSONObject with its value being a JSONArray containing the value parameter. If the key was already associated + * with a JSONArray, then the value parameter is appended to it. + * + * @param key A key string. * @param value An object to be accumulated under the key. + * * @return this. - * @throws JSONException If the key is null or if the current value - * associated with the key is not a JSONArray. + * + * @throws JSONException If the key is null or if the current value associated with the key is not a JSONArray. */ public JSONObject append(String key, Object value) throws JSONException { testValidity(value); @@ -418,9 +390,10 @@ public class JSONObject { } /** - * Produce a string from a double. The string "null" will be returned if - * the number is not finite. - * @param d A double. + * Produce a string from a double. The string "null" will be returned if the number is not finite. + * + * @param d A double. + * * @return A String. */ public static String doubleToString(double d) { @@ -446,8 +419,10 @@ public class JSONObject { /** * Get the value object associated with a key. * - * @param key A key string. + * @param key A key string. + * * @return The object associated with the key. + * * @throws JSONException if the key is not found. */ public Object get(String key) throws JSONException { @@ -465,10 +440,11 @@ public class JSONObject { /** * Get the boolean value associated with a key. * - * @param key A key string. + * @param key A key string. + * * @return The truth. - * @throws JSONException - * if the value is not a Boolean or the String "true" or "false". + * + * @throws JSONException if the value is not a Boolean or the String "true" or "false". */ public boolean getBoolean(String key) throws JSONException { Object object = this.get(key); @@ -487,10 +463,13 @@ public class JSONObject { /** * Get the double value associated with a key. - * @param key A key string. + * + * @param key A key string. + * * @return The numeric value. - * @throws JSONException if the key is not found or - * if the value is not a Number object and cannot be converted to a number. + * + * @throws JSONException if the key is not found or if the value is not a Number object and cannot be converted to a + * number. */ public double getDouble(String key) throws JSONException { Object object = this.get(key); @@ -507,10 +486,11 @@ public class JSONObject { /** * Get the int value associated with a key. * - * @param key A key string. + * @param key A key string. + * * @return The integer value. - * @throws JSONException if the key is not found or if the value cannot - * be converted to an integer. + * + * @throws JSONException if the key is not found or if the value cannot be converted to an integer. */ public int getInt(String key) throws JSONException { Object object = this.get(key); @@ -527,10 +507,11 @@ public class JSONObject { /** * Get the JSONArray value associated with a key. * - * @param key A key string. + * @param key A key string. + * * @return A JSONArray which is the value. - * @throws JSONException if the key is not found or - * if the value is not a JSONArray. + * + * @throws JSONException if the key is not found or if the value is not a JSONArray. */ public JSONArray getJSONArray(String key) throws JSONException { Object object = this.get(key); @@ -544,10 +525,11 @@ public class JSONObject { /** * Get the JSONObject value associated with a key. * - * @param key A key string. + * @param key A key string. + * * @return A JSONObject which is the value. - * @throws JSONException if the key is not found or - * if the value is not a JSONObject. + * + * @throws JSONException if the key is not found or if the value is not a JSONObject. */ public JSONObject getJSONObject(String key) throws JSONException { Object object = this.get(key); @@ -561,10 +543,11 @@ public class JSONObject { /** * Get the long value associated with a key. * - * @param key A key string. + * @param key A key string. + * * @return The long value. - * @throws JSONException if the key is not found or if the value cannot - * be converted to a long. + * + * @throws JSONException if the key is not found or if the value cannot be converted to a long. */ public long getLong(String key) throws JSONException { Object object = this.get(key); @@ -623,8 +606,10 @@ public class JSONObject { /** * Get the string associated with a key. * - * @param key A key string. + * @param key A key string. + * * @return A string which is the value. + * * @throws JSONException if there is no string value for the key. */ public String getString(String key) throws JSONException { @@ -638,7 +623,9 @@ public class JSONObject { /** * Determine if the JSONObject contains a specific key. - * @param key A key string. + * + * @param key A key string. + * * @return true if the key exists in the JSONObject. */ public boolean has(String key) { @@ -646,13 +633,15 @@ public class JSONObject { } /** - * Increment a property of a JSONObject. If there is no such property, - * create one with a value of 1. If there is such a property, and if - * it is an Integer, Long, Double, or Float, then add one to it. - * @param key A key string. + * Increment a property of a JSONObject. If there is no such property, create one with a value of 1. If there is + * such a property, and if it is an Integer, Long, Double, or Float, then add one to it. + * + * @param key A key string. + * * @return this. - * @throws JSONException If there is already a property with this name - * that is not an Integer, Long, Double, or Float. + * + * @throws JSONException If there is already a property with this name that is not an Integer, Long, Double, or + * Float. */ public JSONObject increment(String key) throws JSONException { Object value = this.opt(key); @@ -673,11 +662,11 @@ public class JSONObject { } /** - * Determine if the value associated with the key is null or if there is - * no value. - * @param key A key string. - * @return true if there is no value associated with the key or if - * the value is the JSONObject.NULL object. + * Determine if the value associated with the key is null or if there is no value. + * + * @param key A key string. + * + * @return true if there is no value associated with the key or if the value is the JSONObject.NULL object. */ public boolean isNull(String key) { return JSONObject.NULL.equals(this.opt(key)); @@ -711,10 +700,9 @@ public class JSONObject { } /** - * Produce a JSONArray containing the names of the elements of this - * JSONObject. - * @return A JSONArray containing the key strings, or null if the JSONObject - * is empty. + * Produce a JSONArray containing the names of the elements of this JSONObject. + * + * @return A JSONArray containing the key strings, or null if the JSONObject is empty. */ public JSONArray names() { JSONArray ja = new JSONArray(); @@ -727,8 +715,11 @@ public class JSONObject { /** * Produce a string from a Number. - * @param number A Number + * + * @param number A Number + * * @return A String. + * * @throws JSONException If n is a non-finite number. */ public static String numberToString(Number number) @@ -755,7 +746,9 @@ public class JSONObject { /** * Get an optional value associated with a key. - * @param key A key string. + * + * @param key A key string. + * * @return An object which is the value, or null if there is no value. */ public Object opt(String key) { @@ -763,11 +756,11 @@ public class JSONObject { } /** - * Get an optional boolean associated with a key. - * It returns false if there is no such key, or if the value is not + * Get an optional boolean associated with a key. It returns false if there is no such key, or if the value is not * Boolean.TRUE or the String "true". * - * @param key A key string. + * @param key A key string. + * * @return The truth. */ public boolean optBoolean(String key) { @@ -775,12 +768,12 @@ public class JSONObject { } /** - * Get an optional boolean associated with a key. - * It returns the defaultValue if there is no such key, or if it is not - * a Boolean or the String "true" or "false" (case insensitive). + * Get an optional boolean associated with a key. It returns the defaultValue if there is no such key, or if it is + * not a Boolean or the String "true" or "false" (case insensitive). + * + * @param key A key string. + * @param defaultValue The default. * - * @param key A key string. - * @param defaultValue The default. * @return The truth. */ public boolean optBoolean(String key, boolean defaultValue) { @@ -792,12 +785,11 @@ public class JSONObject { } /** - * Get an optional double associated with a key, - * or NaN if there is no such key or if its value is not a number. - * If the value is a string, an attempt will be made to evaluate it as - * a number. + * Get an optional double associated with a key, or NaN if there is no such key or if its value is not a number. If + * the value is a string, an attempt will be made to evaluate it as a number. + * + * @param key A string which is the key. * - * @param key A string which is the key. * @return An object which is the value. */ public double optDouble(String key) { @@ -805,13 +797,12 @@ public class JSONObject { } /** - * Get an optional double associated with a key, or the - * defaultValue if there is no such key or if its value is not a number. - * If the value is a string, an attempt will be made to evaluate it as - * a number. + * Get an optional double associated with a key, or the defaultValue if there is no such key or if its value is not + * a number. If the value is a string, an attempt will be made to evaluate it as a number. + * + * @param key A key string. + * @param defaultValue The default. * - * @param key A key string. - * @param defaultValue The default. * @return An object which is the value. */ public double optDouble(String key, double defaultValue) { @@ -823,12 +814,11 @@ public class JSONObject { } /** - * Get an optional int value associated with a key, - * or zero if there is no such key or if the value is not a number. - * If the value is a string, an attempt will be made to evaluate it as - * a number. + * Get an optional int value associated with a key, or zero if there is no such key or if the value is not a number. + * If the value is a string, an attempt will be made to evaluate it as a number. + * + * @param key A key string. * - * @param key A key string. * @return An object which is the value. */ public int optInt(String key) { @@ -836,13 +826,12 @@ public class JSONObject { } /** - * Get an optional int value associated with a key, - * or the default if there is no such key or if the value is not a number. - * If the value is a string, an attempt will be made to evaluate it as - * a number. + * Get an optional int value associated with a key, or the default if there is no such key or if the value is not a + * number. If the value is a string, an attempt will be made to evaluate it as a number. + * + * @param key A key string. + * @param defaultValue The default. * - * @param key A key string. - * @param defaultValue The default. * @return An object which is the value. */ public int optInt(String key, int defaultValue) { @@ -854,11 +843,11 @@ public class JSONObject { } /** - * Get an optional JSONArray associated with a key. - * It returns null if there is no such key, or if its value is not a - * JSONArray. + * Get an optional JSONArray associated with a key. It returns null if there is no such key, or if its value is not + * a JSONArray. + * + * @param key A key string. * - * @param key A key string. * @return A JSONArray which is the value. */ public JSONArray optJSONArray(String key) { @@ -867,11 +856,11 @@ public class JSONObject { } /** - * Get an optional JSONObject associated with a key. - * It returns null if there is no such key, or if its value is not a - * JSONObject. + * Get an optional JSONObject associated with a key. It returns null if there is no such key, or if its value is not + * a JSONObject. + * + * @param key A key string. * - * @param key A key string. * @return A JSONObject which is the value. */ public JSONObject optJSONObject(String key) { @@ -880,12 +869,11 @@ public class JSONObject { } /** - * Get an optional long value associated with a key, - * or zero if there is no such key or if the value is not a number. - * If the value is a string, an attempt will be made to evaluate it as - * a number. + * Get an optional long value associated with a key, or zero if there is no such key or if the value is not a + * number. If the value is a string, an attempt will be made to evaluate it as a number. + * + * @param key A key string. * - * @param key A key string. * @return An object which is the value. */ public long optLong(String key) { @@ -893,13 +881,12 @@ public class JSONObject { } /** - * Get an optional long value associated with a key, - * or the default if there is no such key or if the value is not a number. - * If the value is a string, an attempt will be made to evaluate it as - * a number. + * Get an optional long value associated with a key, or the default if there is no such key or if the value is not a + * number. If the value is a string, an attempt will be made to evaluate it as a number. * - * @param key A key string. + * @param key A key string. * @param defaultValue The default. + * * @return An object which is the value. */ public long optLong(String key, long defaultValue) { @@ -911,11 +898,11 @@ public class JSONObject { } /** - * Get an optional string associated with a key. - * It returns an empty string if there is no such key. If the value is not - * a string and is not null, then it is converted to a string. + * Get an optional string associated with a key. It returns an empty string if there is no such key. If the value is + * not a string and is not null, then it is converted to a string. + * + * @param key A key string. * - * @param key A key string. * @return A string which is the value. */ public String optString(String key) { @@ -923,11 +910,11 @@ public class JSONObject { } /** - * Get an optional string associated with a key. - * It returns the defaultValue if there is no such key. + * Get an optional string associated with a key. It returns the defaultValue if there is no such key. + * + * @param key A key string. + * @param defaultValue The default. * - * @param key A key string. - * @param defaultValue The default. * @return A string which is the value. */ public String optString(String key, String defaultValue) { @@ -985,9 +972,11 @@ public class JSONObject { /** * Put a key/boolean pair in the JSONObject. * - * @param key A key string. + * @param key A key string. * @param value A boolean which is the value. + * * @return this. + * * @throws JSONException If the key is null. */ public JSONObject put(String key, boolean value) throws JSONException { @@ -996,11 +985,13 @@ public class JSONObject { } /** - * Put a key/value pair in the JSONObject, where the value will be a - * JSONArray which is produced from a Collection. - * @param key A key string. + * Put a key/value pair in the JSONObject, where the value will be a JSONArray which is produced from a Collection. + * + * @param key A key string. * @param value A Collection value. + * * @return this. + * * @throws JSONException */ public JSONObject put(String key, Collection value) throws JSONException { @@ -1011,9 +1002,11 @@ public class JSONObject { /** * Put a key/double pair in the JSONObject. * - * @param key A key string. + * @param key A key string. * @param value A double which is the value. + * * @return this. + * * @throws JSONException If the key is null or if the number is invalid. */ public JSONObject put(String key, double value) throws JSONException { @@ -1024,9 +1017,11 @@ public class JSONObject { /** * Put a key/int pair in the JSONObject. * - * @param key A key string. + * @param key A key string. * @param value An int which is the value. + * * @return this. + * * @throws JSONException If the key is null. */ public JSONObject put(String key, int value) throws JSONException { @@ -1037,9 +1032,11 @@ public class JSONObject { /** * Put a key/long pair in the JSONObject. * - * @param key A key string. + * @param key A key string. * @param value A long which is the value. + * * @return this. + * * @throws JSONException If the key is null. */ public JSONObject put(String key, long value) throws JSONException { @@ -1048,11 +1045,13 @@ public class JSONObject { } /** - * Put a key/value pair in the JSONObject, where the value will be a - * JSONObject which is produced from a Map. - * @param key A key string. + * Put a key/value pair in the JSONObject, where the value will be a JSONObject which is produced from a Map. + * + * @param key A key string. * @param value A Map value. + * * @return this. + * * @throws JSONException */ public JSONObject put(String key, Map value) throws JSONException { @@ -1061,15 +1060,16 @@ public class JSONObject { } /** - * Put a key/value pair in the JSONObject. If the value is null, - * then the key will be removed from the JSONObject if it is present. - * @param key A key string. - * @param value An object which is the value. It should be of one of these - * types: Boolean, Double, Integer, JSONArray, JSONObject, Long, String, - * or the JSONObject.NULL object. + * Put a key/value pair in the JSONObject. If the value is null, then the key will be removed from the JSONObject if + * it is present. + * + * @param key A key string. + * @param value An object which is the value. It should be of one of these types: Boolean, Double, Integer, + * JSONArray, JSONObject, Long, String, or the JSONObject.NULL object. + * * @return this. - * @throws JSONException If the value is non-finite number - * or if the key is null. + * + * @throws JSONException If the value is non-finite number or if the key is null. */ public JSONObject put(String key, Object value) throws JSONException { String pooled; @@ -1095,12 +1095,14 @@ public class JSONObject { } /** - * Put a key/value pair in the JSONObject, but only if the key and the - * value are both non-null, and only if there is not already a member - * with that name. + * Put a key/value pair in the JSONObject, but only if the key and the value are both non-null, and only if there is + * not already a member with that name. + * * @param key * @param value + * * @return his. + * * @throws JSONException if the key is a duplicate */ public JSONObject putOnce(String key, Object value) throws JSONException { @@ -1114,13 +1116,14 @@ public class JSONObject { } /** - * Put a key/value pair in the JSONObject, but only if the - * key and the value are both non-null. - * @param key A key string. - * @param value An object which is the value. It should be of one of these - * types: Boolean, Double, Integer, JSONArray, JSONObject, Long, String, - * or the JSONObject.NULL object. + * Put a key/value pair in the JSONObject, but only if the key and the value are both non-null. + * + * @param key A key string. + * @param value An object which is the value. It should be of one of these types: Boolean, Double, Integer, + * JSONArray, JSONObject, Long, String, or the JSONObject.NULL object. + * * @return this. + * * @throws JSONException If the value is a non-finite number. */ public JSONObject putOpt(String key, Object value) throws JSONException { @@ -1131,11 +1134,12 @@ public class JSONObject { } /** - * Produce a string in double quotes with backslash sequences in all the - * right places. A backslash will be inserted within + * Make a JSON text of this JSONObject. For compactness, no whitespace is added. If this would not result in a + * syntactically correct JSON text, then null will be returned instead. + *

* Warning: This method assumes that the data structure is acyclical. * - * @return a printable, displayable, portable, transmittable - * representation of the object, beginning - * with { (left brace) and ending - * with } (right brace). + * @return a printable, displayable, portable, transmittable representation of the object, beginning with + * { (left brace) and ending with } (right + * brace). */ public String toString() { try { @@ -1333,14 +1341,15 @@ public class JSONObject { /** * Make a prettyprinted JSON text of this JSONObject. - *

+ *

* Warning: This method assumes that the data structure is acyclical. - * @param indentFactor The number of spaces to add to each level of - * indentation. - * @return a printable, displayable, portable, transmittable - * representation of the object, beginning - * with { (left brace) and ending - * with } (right brace). + * + * @param indentFactor The number of spaces to add to each level of indentation. + * + * @return a printable, displayable, portable, transmittable representation of the object, beginning with + * { (left brace) and ending with } (right + * brace). + * * @throws JSONException If the object contains an invalid number. */ public String toString(int indentFactor) throws JSONException { @@ -1351,24 +1360,22 @@ public class JSONObject { } /** - * Make a JSON text of an Object value. If the object has an - * value.toJSONString() method, then that method will be used to produce - * the JSON text. The method is required to produce a strictly - * conforming text. If the object does not contain a toJSONString - * method (which is the most common case), then a text will be - * produced by other means. If the value is an array or Collection, - * then a JSONArray will be made from it and its toJSONString method - * will be called. If the value is a MAP, then a JSONObject will be made - * from it and its toJSONString method will be called. Otherwise, the - * value's toString method will be called, and the result will be quoted. - * - *

+ * Make a JSON text of an Object value. If the object has an value.toJSONString() method, then that method will be + * used to produce the JSON text. The method is required to produce a strictly conforming text. If the object does + * not contain a toJSONString method (which is the most common case), then a text will be produced by other means. + * If the value is an array or Collection, then a JSONArray will be made from it and its toJSONString method will be + * called. If the value is a MAP, then a JSONObject will be made from it and its toJSONString method will be called. + * Otherwise, the value's toString method will be called, and the result will be quoted. + *

+ *

* Warning: This method assumes that the data structure is acyclical. + * * @param value The value to be serialized. - * @return a printable, displayable, transmittable - * representation of the object, beginning - * with { (left brace) and ending - * with } (right brace). + * + * @return a printable, displayable, transmittable representation of the object, beginning with + * { (left brace) and ending with } (right + * brace). + * * @throws JSONException If the value is or contains an invalid number. */ public static String valueToString(Object value) throws JSONException { @@ -1407,15 +1414,13 @@ public class JSONObject { } /** - * Wrap an object, if necessary. If the object is null, return the NULL - * object. If it is an array or collection, wrap it in a JSONArray. If - * it is a map, wrap it in a JSONObject. If it is a standard property - * (Double, String, et al) then it is already wrapped. Otherwise, if it - * comes from one of the java packages, turn it into a string. And if - * it doesn't, try to wrap it in a JSONObject. If the wrapping fails, - * then null is returned. + * Wrap an object, if necessary. If the object is null, return the NULL object. If it is an array or collection, + * wrap it in a JSONArray. If it is a map, wrap it in a JSONObject. If it is a standard property (Double, String, et + * al) then it is already wrapped. Otherwise, if it comes from one of the java packages, turn it into a string. And + * if it doesn't, try to wrap it in a JSONObject. If the wrapping fails, then null is returned. * * @param object The object to wrap + * * @return The wrapped value */ public static Object wrap(Object object) { @@ -1458,12 +1463,12 @@ public class JSONObject { } /** - * Write the contents of the JSONObject as JSON text to a writer. - * For compactness, no whitespace is added. - *

+ * Write the contents of the JSONObject as JSON text to a writer. For compactness, no whitespace is added. + *

* Warning: This method assumes that the data structure is acyclical. * * @return The writer. + * * @throws JSONException */ public Writer write(Writer writer) throws JSONException { @@ -1510,12 +1515,12 @@ public class JSONObject { } /** - * Write the contents of the JSONObject as JSON text to a writer. For - * compactness, no whitespace is added. - *

+ * Write the contents of the JSONObject as JSON text to a writer. For compactness, no whitespace is added. + *

* Warning: This method assumes that the data structure is acyclical. * * @return The writer. + * * @throws JSONException */ Writer write(Writer writer, int indentFactor, int indent) diff --git a/src/main/java/org/json/JSONString.java b/src/main/java/org/json/JSONString.java index aa1e21b..150f164 100644 --- a/src/main/java/org/json/JSONString.java +++ b/src/main/java/org/json/JSONString.java @@ -1,18 +1,15 @@ package org.json; /** - * The JSONString interface allows a toJSONString() - * method so that a class can change the behavior of - * JSONObject.toString(), JSONArray.toString(), - * and JSONWriter.value(Object). The - * toJSONString method will be used instead of the default behavior - * of using the Object's toString() method and quoting the result. + * The JSONString interface allows a toJSONString() method so that a class can change the + * behavior of JSONObject.toString(), JSONArray.toString(), and + * JSONWriter.value(Object). The toJSONString method will be used instead of the + * default behavior of using the Object's toString() method and quoting the result. */ public interface JSONString { /** - * The toJSONString method allows a class to produce its own JSON - * serialization. + * The toJSONString method allows a class to produce its own JSON serialization. * * @return A strictly syntactically correct JSON text. */ diff --git a/src/main/java/org/json/JSONTokener.java b/src/main/java/org/json/JSONTokener.java index bfe3daf..85d5445 100644 --- a/src/main/java/org/json/JSONTokener.java +++ b/src/main/java/org/json/JSONTokener.java @@ -1,11 +1,6 @@ package org.json; -import java.io.BufferedReader; -import java.io.IOException; -import java.io.InputStream; -import java.io.InputStreamReader; -import java.io.Reader; -import java.io.StringReader; +import java.io.*; /* * Copyright (c) 2002 JSON.org @@ -32,9 +27,9 @@ import java.io.StringReader; */ /** - * A JSONTokener takes a source string and extracts characters and tokens from - * it. It is used by the JSONObject and JSONArray constructors to parse - * JSON source strings. + * A JSONTokener takes a source string and extracts characters and tokens from it. It is used by the JSONObject and + * JSONArray constructors to parse JSON source strings. + * * @author JSON.org * @version 2012-02-16 */ @@ -51,7 +46,7 @@ public class JSONTokener { /** * Construct a JSONTokener from a Reader. * - * @param reader A reader. + * @param reader A reader. */ public JSONTokener(Reader reader) { this.reader = reader.markSupported() @@ -75,16 +70,15 @@ public class JSONTokener { /** * Construct a JSONTokener from a string. * - * @param s A source string. + * @param s A source string. */ public JSONTokener(String s) { this(new StringReader(s)); } /** - * Back up one character. This provides a sort of lookahead capability, - * so that you can test for a digit or letter before attempting to parse - * the next number or identifier. + * Back up one character. This provides a sort of lookahead capability, so that you can test for a digit or letter + * before attempting to parse the next number or identifier. */ public void back() throws JSONException { if (this.usePrevious || this.index <= 0) { @@ -98,8 +92,9 @@ public class JSONTokener { /** * Get the hex value of a character (base16). - * @param c A character between '0' and '9' or between 'A' and 'F' or - * between 'a' and 'f'. + * + * @param c A character between '0' and '9' or between 'A' and 'F' or between 'a' and 'f'. + * * @return An int between 0 and 15, or -1 if c was not a hex digit. */ public static int dehexchar(char c) { @@ -120,8 +115,8 @@ public class JSONTokener { } /** - * Determine if the source string still contains characters that next() - * can consume. + * Determine if the source string still contains characters that next() can consume. + * * @return true if not yet at the end of the source. */ public boolean more() throws JSONException { @@ -170,10 +165,12 @@ public class JSONTokener { } /** - * Consume the next character, and check that it matches a specified - * character. + * Consume the next character, and check that it matches a specified character. + * * @param c The character to match. + * * @return The character. + * * @throws JSONException if the character does not match. */ public char next(char c) throws JSONException { @@ -188,11 +185,11 @@ public class JSONTokener { /** * Get the next n characters. * - * @param n The number of characters to take. + * @param n The number of characters to take. + * * @return A string of n characters. - * @throws JSONException - * Substring bounds error if there are not - * n characters remaining in the source string. + * + * @throws JSONException Substring bounds error if there are not n characters remaining in the source string. */ public String next(int n) throws JSONException { if (n == 0) { @@ -214,8 +211,10 @@ public class JSONTokener { /** * Get the next char in the string, skipping whitespace. - * @throws JSONException + * * @return A character, or 0 if there are no more characters. + * + * @throws JSONException */ public char nextClean() throws JSONException { for (; ; ) { @@ -227,14 +226,14 @@ public class JSONTokener { } /** - * Return the characters up to the next close quote character. - * Backslash processing is done. The formal JSON format does not - * allow strings in single quotes, but an implementation is allowed to - * accept them. - * @param quote The quoting character, either - * " (double quote) or - * ' (single quote). + * Return the characters up to the next close quote character. Backslash processing is done. The formal JSON format + * does not allow strings in single quotes, but an implementation is allowed to accept them. + * + * @param quote The quoting character, either " (double quote) or + * ' (single quote). + * * @return A String. + * * @throws JSONException Unterminated string. */ public String nextString(char quote) throws JSONException { @@ -288,9 +287,10 @@ public class JSONTokener { } /** - * Get the text up but not including the specified character or the - * end of line, whichever comes first. - * @param delimiter A delimiter character. + * Get the text up but not including the specified character or the end of line, whichever comes first. + * + * @param delimiter A delimiter character. + * * @return A string. */ public String nextTo(char delimiter) throws JSONException { @@ -308,9 +308,11 @@ public class JSONTokener { } /** - * Get the text up but not including one of the specified delimiter - * characters or the end of line, whichever comes first. + * Get the text up but not including one of the specified delimiter characters or the end of line, whichever comes + * first. + * * @param delimiters A set of delimiter characters. + * * @return A string, trimmed. */ public String nextTo(String delimiters) throws JSONException { @@ -330,11 +332,12 @@ public class JSONTokener { } /** - * Get the next value. The value can be a Boolean, Double, Integer, - * JSONArray, JSONObject, Long, or String, or the JSONObject.NULL object. - * @throws JSONException If syntax error. + * Get the next value. The value can be a Boolean, Double, Integer, JSONArray, JSONObject, Long, or String, or the + * JSONObject.NULL object. * * @return An object. + * + * @throws JSONException If syntax error. */ public Object nextValue() throws JSONException { char c = this.nextClean(); @@ -376,11 +379,12 @@ public class JSONTokener { } /** - * Skip characters until the next character is the requested character. - * If the requested character is not found, no characters are skipped. + * Skip characters until the next character is the requested character. If the requested character is not found, no + * characters are skipped. + * * @param to A character to skip to. - * @return The requested character, or zero if the requested character - * is not found. + * + * @return The requested character, or zero if the requested character is not found. */ public char skipTo(char to) throws JSONException { char c; @@ -411,6 +415,7 @@ public class JSONTokener { * Make a JSONException to signal a syntax error. * * @param message The error message. + * * @return A JSONException object, suitable for throwing */ public JSONException syntaxError(String message) {