Wiki/API
If you are interested in developing a plugin that relies on Statistics for data collection and processing, you have the Statistics API available for you to use.
Table of Contents
Getting Started with Statistics
As with any plugin dependency, you will need to include the depend: [Statistics] in your plugin's plugin.yml. After that, you will need to ensure that Statistics is present and enabled. Usually, this is done in the onEnable().
Plugin plugin = Bukkit.getServer().getPluginManager().getPlugin("Statistics");
if (plugin == null || !(plugin instanceof Statistics)) {
this.setEnable(false); // Disable the plugin
return;
}
You are ready to use the StatisticsAPI.
Fetching the global server statistics
Statistics stores a variety of server-related variables, all of which are accessible through com.wolvencraft.yasp.StatisticsAPI. Here are a few examples:
// Getting the server startup time
long lastStartup = (Long) StatisticsAPI.getValue(ServerVariable.LAST_STARTUP);
// Getting the total number of deaths on the server
int deaths = (Integer) StatisticsAPI.getValue(ServerVariable.DEATHS);
// Getting the current tick rate
int ticksPerSecond = (Integer) StatisticsAPI.getValue(ServerVariable.TICKS_PER_SECOND);
Getting the player statistics
Fetching a player session
Statistics stores player data in sessions, of which there are two kinds available to you: com.wolvencraft.yasp.session.OnlineSession and com.wolvencraft.yasp.session.OfflineSession. The difference is obvious: OnlineSession is for players that are currently online, while OfflineSession is used to pull the data from the database when the player in question is offline.
Getting a hold of a player session is really easy. This is how you do it:
// Getting an online session (where player is an instance of Player)
OnlineSession onlineSession = StatisticsAPI.getSession(player);
// Getting an offline session (where username is a String with a player name
OfflineSession offlineSession = StatisticsAPI.getSession(username);
All sessions are cached. This means that once you used getSession() to get an instance of a player session, its data will be synchronized with the database automatically. If you want an uncached session (for whatever reason), you can use the following method:
// Getting an offline session (where username is a String with a player name
OfflineSession offlineSession = StatisticsAPI.getSession(username, false);
Note that fetching player from the database is a taxing process; if you run it in the main server thread, it will likely cause server lag. Player sessions are thread-safe; feel free to use them in asynchronous tasks.
Some servers might disable data tracking for some users. If a player is not tracked, attempting to get his or her OnlineSession will return a null.
Retrieving player data
Getting player statistics from a session is very similar to getting server statistics. Here are a few examples:
// Getting the number of blocks a player broke
int blocksBroken = (Integer) session.getPlayerTotals().getValue(PlayerVariable.BLOCKS_BROKEN);
// Getting player's playtime
long playtime = (Long) session.getPlayerTotals().getValue(PlayerVariable.TOTAL_PLAYTIME_RAW);
// Getting the kill-to-death ratio
double kdr = (Double) session.getPlayerTotals().getValue(PlayerVariable.KILL_DEATH_RATIO);
As far as variable types go, use common sense. Number of blocks is an integer, distance traveled is a double, time is a timestamp, etc.
Hooking into Statistics configuration
Sometimes, you might want to get a value from the main plugin's configuration. For example, you might want to check if the plugin is running in the debug mode, check if Statistics has hooked into some plugin, look up the database synchronization schedule, etc.
Please, note that yes, you can get the server owner's personal information using this method, including, but not limited to the database hostname and port, database username and password, database table and prefix. However, you do NOT need this information, at all; moreover, attempting to take a hold of this data may be considered to be malicious code by the BukkitDev administration.
There are several enums that you can access, namely com.wolvencraft.yasp.settings.LocalConfiguration, com.wolvencraft.yasp.settings.RemoteConfiguration, and com.wolvencraft.yasp.settings.Modules. All data is cached to prevent server lag; you do not need to worry about this.
LocalConfiguration
LocalConfiguration contains data from config.yml created by Statistics. For example,
// Checking if the plugin is running in the debug mode
boolean debug = LocalConfiguration.Debug.asBoolean();
RemoteConfiguration
RemoteConfiguration contains data stored in the settings table in the database. Not all entries in the settings table are present in the RemoteConfiguration; module entries are located in the Module enum, while some portal-specific values (like admin's email) are not present at all. Here are a few examples:
// Getting the synchronization period
long ping = RemoteConfiguration.Ping.asLong();
// Getting the database version
int version = RemoteConfiguration.DatabaseVersion.asInteger();
Module
Module enum represents the different plugin hooks and modules of the Statistics plugins. This section is unimportant, unless you plan to use Statistics's hook to another plugin for whatever reason (please, don't do that, it is ridiculously inefficient and unnecessary). Here are a few examples:
// Check if the plugin collects players' inventory data
boolean active = Module.Inventory.isActive();
// Check if the plugin hooks into WorldGuard
boolean worldGuard = Module.WorldGuard.isActive();
You might notice that there are actually two similar methods in the Module - isEnabled() and isActive(). Short version: always use isActive(). Long version: isEnabled() means that the module has been turned on in the web portal's admin panel, while isActive() means that Statistics was also able to hook into that module.
Patches and Database Access
Statistics provides functionality to safely and securely access the database and execute patches.