DataStore ($.inidb) API


#1

INIDB Interface

This serves as a guide for those developers that are wishing to interface with the INIDB class which provides an abstract class for interfacing with IniDB, SQLite, or MySQL.

Introduction

Data is stored in PhantomBot using a key and value pair, there is also an additional higher level key, referred to as a section, which is not often used, but provides for the ability to store duplicate keys that can be retrieved.

That said, data is represented in PhantomBot in the following manner:

Section Key Value
Typically unused, but can group together keys. A unique key for accessing a value. A value which is related to a key.

All data is represented as Strings within the database. This allows for a generic representation of all data. All data may of course be converted between different data types with different Java and JavaScript methods. There are also JavaScript API calls that are provided which will provide conversion as well that are described later on this page.

All data is stored within a single database within tables that are named phantombot_tablespace. For example, the points data is stored in the phantombot_points table.

API Calls

Note that for all calls that require a section that a blank String may be passed if a section is not used.

String[] $.inidb.GetFileList()

Returns a list object that contains a list of all of the tables within the database.

String[] $.inidb.GetCategoryList(String table_name)

Returns a list object that contains a list of all sections stored within a table.

String[] $.inidb.GetKeyList(String table_name, String section)

Returns a list of all of the keys stored within a table.

String $.inidb.GetString(String table_name, String section, String key)

Returns a value related to the section and key from the table_name.

String $.inidb.get(String table_name,String key)

Returns a value related to a key from the table_name.

void $.inidb.SetString(String table_name, String section, String key, String value)

Stores, or updates, a value in the table_name related to section and key.

void $.inidb.set(String table_name, String key, String value)

Stores, or updates, a value in the table_name related to key.

long $.inidb.GetLong(String table_name, String section, String key)

Retrieves data like GetString() casting the return value as a long.

void $.inidb.SetLong(String table_name, String section, String key, long value)

Stores data like SetString casting the value to a String before storing the data.

int $.inidb.GetInteger(String table_name, String section, string key)

Retrieves data like GetString() casting the return value as an int.

void $.inidb.SetInteger(String table_name, String section, String key, int value)

Stores data like SetString casting the value to a String before storing the data.

float $.inidb.GetFloat(String table_name, String section, string key)

Retrieves data like GetString() casting the return value as a float.

void $.inidb.SetFloat(String table_name, String section, String key, float value)

Stores data like SetString casting the value to a String before storing the data.

double $.inidb.GetDouble(String table_name, String section, string key)

Retrieves data like GetString() casting the return value as a double.

void $.inidb.SetDouble(String table_name, String section, String key, double value)

Stores data like SetString casting the value to a String before storing the data.

Boolean $.inidb.GetBoolean(String table_name, String section, string key)

Retrieves data like GetString() casting the return value as a Boolean.

void $.inidb.SetBoolean(String table_name, String section, String key, Boolean value)

Stores data like SetString casting the value to a String before storing the data.

void $.inidb.RemoveKey(String table_name, String section, String key)

Removes data from the table_name that is referenced by section and key.

void $.inidb.RemoveSection(String table_name, String section)

Removes an entire section of related keys from table_name.

void $.inidb.AddFile(String table_name)

Create a blank database table. Not required as this is performed automatically by the various set functions.

void $.inidb.RemoveFile(String table_name)

Removes the table_name from the database.

boolean $.inidb.FileExists(String table_name)

Returns true if the table_name exists.

boolean $.inidb.HasKey(String table_name, String section, String key)

Returns true if the key and section combination exists in table_name.

boolean $.inidb.exists(String table_name, String key)

Returns true is the key exists in table_name.

String $.inidb.get(String table_name, String key)

Returns a value associated with the key in table_name.

void $.inidb.set(String table_name, String key, String value)

Sets a value in table_name associated to key.

void $.inidb.setbatch(String table_name, String[] keys, String[] values)

Performs a bulk set operation.

void $.inidb.del(String table_name, String key)

Deletes a key from table_name.

void $.inidb.incr(String table_name, String key, int amount)

Increments a value related to key in table_name. Ensure that this is only used on data that is stored as a whole number in the database.

void $.inidb.decr(String table_name, String key, int amount)

Decrements a value related to key in table_name. Ensure that this is only used on data that is stored as a whole number in the database.

void $.inidb.setAutoCommit(boolean mode)

Enable/disable auto-commit mode for the database. This is applicable for MySQL and SQLite databases. It has no effect on an IniDB. Caller must ensure that auto-commit is enabled again after disabling. This is recommended for intense updates to the database such as those performed within large loops.

void $.inidb.RenameFile(String source_table_name, String dest_table_name)  // 2.3.5 Release

Rename the source_table_name to dest_table_name. If dest_table_name exists, it is removed and replaced.

String[] $.inidb.searchByValue(String table_name, String value_search)     // 2.3.5 Release

Performs a search in table_name for any values that match value_search using a substring match method, and returns the list of related keys as a String[] object. In IniStore, this uses the Java String.contains() method. In the SQLite and MySQL this uses the LIKE %value_search% SQL statement.

String[] $.inidb.SearchByKey(String table_name, String key_search)        // 2.3.5 Release

Performs a search in table_name for any keys that match key_search using a substring match method, and returns the list of related keys as a String[] object. In IniStore, this uses the Java String.contains() method. In the SQLite and MySQL this uses the LIKE %key_search% SQL statement.

String $.inidb.GetKeyByValue(String table_name, String section, String value_search)    // 2.3.7 Release

Performs a search in table_name for a key that matches value_search. Note that this does not return multiple keys, it will only return the first key that is found. Use $.inidb.searchByValue() to return a list of keys.

String $.inidb.GetKeyByValue(String table_name, String section, String value_search)    // 2.3.7 Release

Performs a search in table_name for a key that matches value_search. Note that this does not return multiple keys, and will only return the first key that is found. If section is not needed, pass an empty string.

JavaScript Helper API Calls

The following are provided as wrappers around the core API to aid the developer in accessing the database.

boolean $.getIniDbBoolean(String table_name, String key, [boolean defaultValue])
String $.getIniDbString(String table_name, String key, [String defaultValue])
int $.getIniDbNumber(String table_name, String key, [int defaultValue])
float $.getIniDbFloat(String table_name, String key, [float defaultValue])

Performs a get operation from table_name querying for key. Optionally, a defaultValue may be provided which is returned if no data is found. This is useful for querying the database and being provided with an optional default value if no data exists in the database. It is suggested that defaultValue is always used but it is not required, depending upon the use case.

boolean $.getSetIniDbBoolean(String table_name, String key, boolean defaultValue)
String $.getSetIniDbString(String table_name, String key, String defaultValue)
int $.getSetIniDbNumber(String table_name, String key, int defaultValue)
float $.getSetIniDbFloat(String table_name, String key, float defaultValue)

Performs a get operation from table_name querying for key. If data does not exist, then defaultValue is stored in the database and returned. This is useful for setting default values in the database and either retrieving a previously stored value or the new default value.

void $.setIniDbBoolean(String table_name, String key, boolean value)
void $.setIniDbString(String table_name, String key, String value)  // 2.3.5 Release
void $.setIniDbNumber(String table_name, String key, int value)     // 2.3.5 Release
void $.setIniDbFloat(String table_name, String key, float value)    // 2.3.5 Release

Performs a set operation on table_name associating value to key.


User Specific Values... kinda like points
How to make your own Script
Warning System Script
Greeting Enabled issues