Troubleshooter API

Suppose there's a problem with the data in your module. Currently, the user would have to open an issue, send you his files, then you fix them and send them back, and that process takes an eternity. Wouldn't it be great if Prison could fix that itself? That's what the Troubleshooter does.

To explain this, we'll use ranks as an example. On our server, the ranks are all out of order because the index file doesn't match the rank files (this is a made up example, the ranks module doesn't even have an index file!). The user can type /prison troubleshoot fix_rank_order and it will attempt to fix it itself. Isn't that cool? Let's see how to use it.

Creating a Troubleshooter

To create a Troubleshooter, you extend the tech.mcprison.prison.troubleshooter.Troubleshooter class.

import tech.mcprison.prison.internal.CommandSender;

public class TestTroubleshooter extends Troubleshooter {
    
    public TestTroubleshooter() {
        super("test-api", "Test the Troubleshooter API.");
    }
    
    @Override public TroubleshootResult invoke(CommandSender invoker) {
        return null;
    }
}

Notice that there are two arguments to pass into the super constructor. The first one is the name, which the user will use to invoke the troubleshooter. It should be all lowercase, and it should contain hyphens for spaces. The next one is the description, which is shown to the user in the /prison troubleshoot list menu. This is what lets the user know whether they should run that troubleshooter, so ensure that you make it concise yet descriptive.

Now, let's take a look at that invoke(CommandSender) method. This method is called when the troubleshooter is invoked by the user. This is where you should perform your tasks. You'll notice that it returns a TroubleshootResult object. This provides information to Prison about the results of your troubleshooting operation. Here is an example of how to use it.

    @Override public TroubleshootResult invoke(CommandSender invoker) {
        // Do your fixing here

        TroubleshootResult result = new TroubleshootResult(TroubleshootResult.Result.SUCCESS,
            "We scanned the Troubleshooter API and found corruption in the files. We fixed it.");
        TroubleshootResult result2 = new TroubleshootResult(TroubleshootResult.Result.USER_ACTION,
            "We scanned the Troubleshooter API and found corruption in the files. We fixed it, but it will require you to restart your server.");
        TroubleshootResult result3 = new TroubleshootResult(TroubleshootResult.Result.FAILURE,
            "We scanned the Troubleshooter API and found corruption in the files. We could not fix it ourselves. Please open a support ticket.");
        return result; // or result2 or result3
    }

It's very straightforward. You pass in a TroubleshootResult.Result enum value, and a description of the process. For the description, be sure to include what you did during the operation. Let's take a look at when to use each Result enum value.

• SUCCESS - When the operation succeeds and there is no further action required.
• USER_ACTION - When the operation succeeds, but the user must do something to finish the process. You should instruct the user on what to do very thoroughly.
• FAILURE - When the operation fails, and the user should seek developer help.

Registering the Troubleshooter

To register a Troubleshooter, you simply register it with the TroubleshootManager.

// ...
TestTroubleshooter testTroubleshooter = new TestTroubleshooter();
PrisonAPI.getTroubleshootManager().registerTroubleshooter(testTroubleshooter);
// ...

If a Troubleshooter with the same name as yours has already been registered, an IllegalArgumentException will be thrown. You may also use the TroubleshootManager to invoke or get another troubleshooter (or all of them).

Using a Troubleshooter

To run a troubleshooter, the user simply needs to run /prison troubleshoot <name>. Ensure that you instruct users to do this in your module's documentation, or even during runtime if you can detect when the troubleshooting process should be run. You should always wait for the user to run the troubleshooter. Never run a troubleshooter yourself. The user can also list all the troubleshooters with the /prison troubleshoot list command.

That's it! You're ready to start developing with this powerful API.