Bukkit

EV Modules

The Environment Variable Module API method is the simplest way to hook into Commander and the way to use if you want to provide values to a Commander Script.

The EVM Interface

EVMs are simple enough to program: there's one interface to implement in a class. I recommend keeping the EVM class separate from the rest of your code, but you can make a main class implement it if you like! There's two methods to implement in your EVM:

public String getNamespace()

This method should return the name of your plugin, or the name of the plugin you are providing values from, case sensitive. This method is called once during registration, and optionally called once during unregistration (if you are unregistering by passing the EVM and not just this string). If your plugin is providing multiple EVMs (if, for example, your plugin has the sole purpose of providing EVMs for other plugins that you may or may not own), then this method should return the name of the respective plugin the EVM represents.

public Object getEVValue(String varname, CommandSender sender) 
    throws BadEVPathException

This method is what does all the heavy lifting. You are provided with a path called "varname" and the sender of the command (echo controlled). The path does not contain the "plugin.<namespace>." segments of the path; those have been cut out for you.

You should look at the path provided for you and return a String, Integer, Boolean, or List<String>, depending on what that path represents. If you return an object that is not one of these, then Commander will throw an exception and return null to the script. See the examples below for ways to parse out the path and provide values.

If the path does not mean anything to you, or if it is malformatted or incorrect, then you should throw a BadEVPathException. Commander will catch this and print the exception's message the server console, and return null to the script. You should avoid throwing other types of exceptions if possible. If the value is unavailable but the path is correct, return a valid, if inconsequential, value instead of throwing an exception. You may also return null, but that is discouraged over returning a valid value.

Registering

You need to register your EVM if you want scripts to be able to use it; Commander knows nothing about it until you do so. You may register or unregister your EVM at any time, but onEnable() and onDisable(), respectfully, are the most common time to do so.

You register your EVM, call the following method:

CommanderAPI.registerEVM(evm); //passing a class instance

To unregister your EVM, call one of the following two methods:

CommanderAPI.unregisterEVM(evm.getNamespace()); //passing a string
CommanderAPI.unregisterEVM(evm); //passing the class instance

Once registered, any scripts that call an for an environment variable with your namespace ("plugin.<YourPluginName>") will be directed to your EVM and the getEVValue() method.

Examples

Required Example

<coming soon!>

And don't forget to include Commander in your plugin.yml as a hard dependency. If you don't your plugin may be loaded before Commander, or loaded when Commander isn't even installed, and will throw exceptions!

depend: [Commander]

Non-Required Example

For an example of how to use a Commander EVM optionally, check out my other (new!) plugin, ServerSleeper. This plugin only supplies an EVM if Commander is available and enabled. Note that in order to do this, you're going to have to use java's reflection API. Here's how ServerSleeper does it!

Commander's EVM is an interface, so just make a new class that implements the interface. Here's ServerSleeper's EVM.

Note that the reflection I'm doing in ServerSleeper's main plugin class is getting ServerSleeper's EVM and not the CommanderAPI class. I found it easier to do this way. You can use reflection to get the CommanderAPI class, but you'll also have to use reflection to get the EVM class as well. If you don't use reflection, and Commander isn't loaded (because they don't have it installed), simply loading your class (not even instantiating it, just loading it) will load your EVM class, which will load Commander's EVM interface class, which it won't be able to do and throw an exception. The point of using reflection is to ensure Java doesn't try and load the classes until we are sure it is possible to do so. If Commander isn't available, the EVM implementation shouldn't be loaded at all.

And don't forget to include Commander in your plugin.yml as a soft dependency. If you don't your plugin may be loaded before Commander, and therefore won't be able to connect to Commander!

softdepend: [Commander]