LagMeter API

Short message for developers

LagMeter has an API available for developers to use. I, TheLunarFrog, have created and added to this API upon request, in hopes that to some developers, it will be useful. If you'd like to see a method, listener, or object added, or made public, let me know either by commenting on the main page of the plugin or by PMing me.

The API

Listeners

LagMeter, as of 1.14.0, offers listeners for the memory and tps of the server. Currently, LagMeter will only notify its observers (see the Observer Model if you don't know what I'm talking about) when the server's memory or lag, repsective of whichever you're using, or both, reaches a certain point, configured into the plugin. This will eventually change to accept a threshold passed by the method invocation. Also, the watcher will only check once every (insert user-configured value here), so it may be activated somewhat in a delay. This will eventually change to check more often than the default 5 minutes, or lowest value a user can configure, 1 minute.

The listeners are obviously threaded, and not only that, but when an observer's notification method is invoked, that is also threaded, meaning that your methods will NOT block LagMeter's execution, and your methods will NOT block other observers' notifications. What you choose to do with the notification is up to you, and you will be provided some information in the form of a class instance, passed to the notification method. Other than that, you can still always use LagMeter.getInstance() to access LagMeter, or the instance passed to your method's method, getLagMeter(), or use anything else, like Bukkit or your own code.

Lag Listeners

To create a Lag listener, it's pretty simple. First, create a class, and let it implement LagListener, importing such class:

/** File: ExampleLagListener.java */
import main.java.com.webkonsept.minecraft.lagmeter.listeners.LagListener;

class ExampleLagListener implements LagListener{
}

Then, implement the notification method and add your handling code to it (remember, this will be a notification of high lag/low tps) - a null method body is shown here:

@Override
public void onHighLagEvent(HighLagEvent event){
}

This will require that you import HighLagEvent, like so:

import main.java.com.webkonsept.minecraft.lagmeter.events.HighLagEvent;

Finally, you must register your listener with LagMeter, calling LagMeter's registerSyncLagListener(LagListener) (for synchronous execution) method or registerAsyncLagListener(LagListener) (for asynchronous execution), passing a new instance of the class you just made for the listener:

/** File: ExamplePlugin.java */
import org.bukkit.plugin.java.JavaPlugin;
import main.java.com.webkonsept.minecraft.lagmeter.LagMeter;

public class ExamplePlugin extends JavaPlugin{
    private int lagListenerID;
    @Override
    public void onEnable(){
        this.lagListenerID = LagMeter.getInstance().registerSyncLagListener(new ExampleLagListener());
    }
}

You should assign a variable of type int to the return of the registration method, as it is used to cancel your registration of that listener at any given time, should you ever wish to.

So maybe, my classes have been populated with code, and now look like this:

/** File: ExamplePlugin.java */
import main.java.com.webkonsept.minecraft.lagmeter.LagMeter;
import org.bukkit.plugin.java.JavaPlugin;

public class ExamplePlugin extends JavaPlugin{
	private int lagListenerID;

	@Override
	public void onEnable(){
		this.lagListenerID = LagMeter.getInstance().registerSyncLagListener(new ExampleLagListener());
	}
	@Override
	public void onDisable(){
		LagMeter.getInstance().cancelSyncLagListener(this.lagListenerID);
	}
}

/** File: ExampleLagListener.java */
import main.java.com.webkonsept.minecraft.lagmeter.events.HighLagEvent;
import main.java.com.webkonsept.minecraft.lagmeter.listeners.LagListener;

import org.bukkit.Bukkit;

class ExampleLagListener implements LagListener{
	@Override
	public void onHighLagEvent(HighLagEvent event){
		System.out.println(String.valueOf(Bukkit.getServer().getOnlinePlayers().length)+" players online.");
		System.out.println("TPS at the time of event: "+event.getCurrentTPS());
		System.out.println("TPS now: "+event.getLagMeter().getTPS());
	}
}

Please note that it is not really necessary to cancel your listeners when your plugin is unloaded. LagMeter will do this for you if you don't do it. That method is really only intended for just removing it early from LagMeter's execution if you wish to do so.

That's all there is to know. The method body can obviously be replaced for the notification method. The source code for this example is available in file form in a zip here, if you so need it: https://dl.dropboxusercontent.com/u/96899792/lag%20listener%20example.zip

Memory Listeners

Creating a memory listener is as simple as making a lag listener.

First, create a class and let it implement MemoryListener, then implement the notification method, a void called onLowMemoryEvent with a LowMemoryEvent parameter. This will require you to import main.java.com.webkonsept.minecraft.lagmeter.events.LowMemoryEvent and main.java.com.webkonsept.minecraft.lagmeter.listeners.MemoryListener. The class should look something like this:

import main.java.com.webkonsept.minecraft.lagmeter.events.LowMemoryEvent;
import main.java.com.webkonsept.minecraft.lagmeter.listeners.MemoryListener;

/** File: ExampleMemoryListener.java */
public class ExampleMemoryListener implements MemoryListener{
	@Override
	public void onLowMemoryEvent(LowMemoryEvent evt){
	}
}

Now, somewhere in another class, which is already instantiated, and probably would be your plugin's main class, in the enable method, you must call one of LagMeter's methods, namely, registerSyncMemoryListener(MemoryListener) (synchronous execution) or registerAsyncMemoryListener(MemoryListener) (asynchronous execution). The method's only argument is a MemoryListener - which you've just made. This also method requires an instance of LagMeter to access, so you can use, for example, LagMeter.getInstance().registerSyncMemoryListener(new ExampleMemoryListener());. This method returns an int, which will be the ID of your listener in LagMeter's allocated memory. You should keep this in a variable.

If there comes a time at which you wish that your listener be destroyed and LagMeter no longer notify it of events, you may remove it from LagMeter's registry by using the value which was returned by the registration method.

Both of these concepts are illustrated below.

/** File: ExamplePlugin.java */
import main.java.com.webkonsept.minecraft.lagmeter.LagMeter;
import org.bukkit.plugin.java.JavaPlugin;

public class ExamplePlugin extends JavaPlugin{
	private int memoryWatcherID;
	@Override
	public void onEnable(){
		this.memoryWatcherID = LagMeter.getInstance().registerSyncMemoryListener(new ExampleMemoryListener());
	}
	@Override
	public void onDisable(){
		LagMeter.getInstance().cancelSyncMemoryListener(this.memoryWatcherID);
	}
}

So now, if the method body is populated for the notification method so that it actually does something, my two classes should look like this:

/** File: ExamplePlugin.java */
import main.java.com.webkonsept.minecraft.lagmeter.LagMeter;
import org.bukkit.plugin.java.JavaPlugin;

public class ExamplePlugin extends JavaPlugin{
	private int memoryWatcherID;
	@Override
	public void onEnable(){
		this.memoryWatcherID = LagMeter.getInstance().registerSyncMemoryListener(new ExampleMemoryListener());
	}
	@Override
	public void onDisable(){
		LagMeter.getInstance().cancelSyncMemoryListener(this.memoryWatcherID);
	}
}

/** File: ExampleMemoryListener.java */
import main.java.com.webkonsept.minecraft.lagmeter.events.LowMemoryEvent;
import main.java.com.webkonsept.minecraft.lagmeter.listeners.MemoryListener;
import org.bukkit.Bukkit;

public class ExampleMemoryListener implements MemoryListener{
	@Override
	public void onLowMemoryEvent(LowMemoryEvent evt){
		final int[] uptime = evt.getLagMeter().getCurrentServerUptime();
		System.out.println("Memory used: "+evt.getUsedMemory()+" MB/"+evt.getMaximumMemory()+" MB ("+(100-evt.getMemoryFreePercentage())+"% used).");
		System.out.println("Server has been up for "+String.valueOf(uptime[3])+" day(s), "+String.valueOf(uptime[2])+" hour(s), "+String.valueOf(uptime[1])+" minute(s), and "+String.valueOf(uptime[0])+" second(s).");
		System.out.println(String.valueOf(Bukkit.getServer().getOnlinePlayers().length)+" players are online.");
	}
}

That's all there is to know. The method body can obviously be replaced for the notification method. The source code for this example is available in file form in a zip here, if you so need it: https://dl.dropboxusercontent.com/u/96899792/memory%20listener%20example.zip