StaleAPIWhat is it?
Making it easy to keep servers clean and running fast!
Not just for developers!
Tested and works on:
Untested on any earlier releases
StaleAPI is a plugin that on its own removes player data files from the world directory after a period of inactivity. By default if a player hasn't been on for 30 days their player file is wiped. Their file contains their inventory, current gamemode, current world and other bits of information.
When combined with plugins that support StaleAPI's integration all plugins with support will be notified both when a players data is about to expire (So it can be cancelled if needed, Great for plugins that have their own form of authorities) and when the players data has actually expired, Plugins can use this information to clear their own data for that player.
Integrating StaleAPI with as many plugins as possible will help toward a cleaner and faster future for all Spigot/Bukkit Servers!
How will it benefit my server?
Servers start to slow down after a while due to the enormous amount of data they keep hold of, even if a player hasn't been online in a long time. A practical example being a server I'm developer on. Running /invsee on a player that's not online or doesn't exist causes Spigot to freeze then crash. The reason? Between Essentials and Spigot there are 70,289 files stored when the daily average of players is 30-40. The server has only been running for less than a year.
A lot of plugins now days have a bad habit of storing user data and not bothering to remove it when it may be useless. Some plugins may even load every piece of data when your server starts. The server I'm developer on uses 20GB of RAM to run because of this. Its not a large and busy server either. It's an average server.
Adding StaleAPI will remove old data and tell plugins to remove data for old players. Assuming plugins you use support StaleAPI.
This will help avoid your server becoming highly unstable, eating diskspace, CPU and RAM and ensure your server doesn't lag for no particular reason in game.
How will it benefit my plugin?
Adding StaleAPI support to your plugin will add useful functionality for removing stale user data without having to track when the player was last online and help you avoid having to implement config options and more methods to remove old data. StaleAPI is more than ideal for simple plugins that shouldn't be over complex.
Adding StaleAPI to your plugin will not only make your own life easier it will make your users lives easier, They can edit one config to tweak when stale data is removed. Rather than editing configs for every plugin that deals with data removal on its own.
You don't need to depend on StaleAPI or force users to use StaleAPI and can simply add the support for it. StaleAPI simply adds an extra event which you can listen to like any normal event. Nothing over complicated!
What does StaleAPI add for Developers?
StaleAPI adds two methods and an event.
The event added is PlayerExpireEvent, the event is called every time a players data is about to expire and carrys a list of players whom are going to expire. You can use this to remove data for those players yourself as well as cancel the Expire event if required.
Two methods added allow your plugins to manually expire a players data. Such as an ability to delete players from your plugin. Calling the methods expirePlayer or expirePlayers will trigger the PlayerExpireEvent alerting all other plugins to this. The event can always be cancelled.
What about donors or admins?
If you don't want specific players to ever expire. Either they're a donor or staff, you can add the permission stale.exempt to them. When StaleAPI checks for expired players it will skip players with this permission.
Operators are automatically exempt from expiry.
Currently there are no planned features other than in game commands which will occupy /stale
Feel free to suggest features!
There are no known bugs right now, please let me know if you encounter them.
Yes please! All feedback is appreciated. Feel free to be blunt about any doubts you have too.
How do I use StaleAPI?
If you're a Server Owner, Put it in your plugins directory!
If you're a developer, Add it as a dependency, you'll want to download the provided Jar.
StaleAPI v1.1.0-Alpha Maven:
Add the following to your pom.xml to use StaleAPI v1.1.0 with your project.
Although the latest is v1.1.1-Alpha this dependency will work fine with v1.1.1 due to StaleAPI not changing at all.
For more indepth information please see the JavaDoc at the bottom of this description.
- isCancelled - Returns boolean.
- setCancelled - Accepts boolean.
- getPlayers - Returns List<OfflinePlayer>
- skipPlayer - Accepts OfflinePlayer
Ideal for knowing when data is actually expiring.
- getPlayers - Returns List<OfflinePlayer>
All methods are void. This returning nothing.
ExpirePlayer - Accepts OfflinePlayer, Runs PlayerExpireEvent for that player.
ExpirePlayers - Accepts List<OfflinePlayer>, Runs PlayerExpireEvent for all listed players.
reloadConfig - Accepts and returns nothing, Reloads the StaleAPI config.
Want to contribute fixes or continue the project when I die from eating too much cake?
StaleAPI can be found on GitHub and can be compiled using Maven!
You can also find the JavaDocs here:
A favor if you will?
StaleAPI is at its first stages. Few or no plugins support the features added by StaleAPI. If you like StaleAPI and find it useful and would like it to get better. Please encourage authors of your favourite plugins to consider implementing StaleAPI, It will help server owners as well as developers with basic plugins. The more StaleAPI is implemented the more useful it becomes for everyone! Thanks!
Plugins that Support StaleAPI:
NicknameRequest by TMFKSOFT
Let me know on the discussion page if your plugin supports StaleAPI for nifty data tracking!
Improve Performance - Remove stale data for users that haven't been online in a while!
- Fixed issue in the expirePlayers method and removed a lot of warnings Jul 4, 2015
- Fixed Permissions + Vault Support + New Event Jun 2, 2015
- Permissions Code Fix Jun 1, 2015