Bukkit

API Guide

Important

This page will soon be out of date and the JavaDocs link does NOT work. If you want help, please open a ticket about it.

In this guide, i will be showing you basics and some examples of using jail API. There are many possibilities, for full reference see javadocs.

Getting access to Jail API

First we need to get an access to Jail, so we can use it later. This step is needed before doing anything

1. Add Jail.jar to the build path of your project. For eclipse, right click on your project -> Build Path -> Add external archives... and search for Jail.jar

2. Create variable that you will use to access Jail. I recommend using global variable (define it right after Class line).

    JailAPI jail;

3. Put following code to onEnable event of your plugin:

    Plugin plugin = getServer().getPluginManager().getPlugin("Jail");
    if (plugin != null)
    {
        jail = ((Jail) plugin).API;
    }
    else
    {
        //Code here will run if player don't have Jail installed.
        //Use that to disable features of your plugin that include Jail to prevent errors.
    }

Now you are connected to the Jail and ready to do some actions.

Example #1: Jailing somebody

    String playerName = "Player";
    int time = 0;
    String reason = "Griefing";

    jail.jailPlayer(playerName, time, null, reason);

This code will simply jail a player. We define player data and then jail him. Notice, that jailName is null. If we don't want to specify our own jail name, we just set it to null and plugin will automatically pick nearest one. Same can be done for reason.

Example #2: Reading prisoner data

    String playerName = "Player";
    JailPrisoner prisoner = jail.getPrisoner(playerName);

    double remainingTime = prisoner.getRemainingTimeMinutes();

This code will read, how many minutes does prisoner still have. First we retrieve JailPrisoner class for our prisoner. JailPrisoner class is used to read and change prisoner's data. After that, It's really simple to retrieve remaining time.

Example #3: Reading and Writing prisoner data

	Collection<JailPrisoner> allPrisoners = jail.getAllPrisoners();
	for (JailPrisoner prisoner : allPrisoners)
	{
	    double remainingTime = prisoner.getRemainingTimeMinutes();
	    if (remainingTime > 40)
	    {
	        prisoner.setRemainingTimeMinutes(40);
	        prisoner.update();
	    }
	}

This piece of code will make sure, that no prisoner is jailed for more than 40 minutes. First we retrieve Collection of all prisoners. Then we loop through all prisoners. For each prisoner we retrieve his remaining time and check if Is above 40. If is, we change his remaining time to 40 and then execute update method. This method will update prisoner's data into database. It's necessary to do that in order to prevent data loss on server restart.

Example #4: Modifying Jail data

	String zoneName = "jail";
	int x = 1;
	int y = 2;
	int z = 3;
	Location corner = new Location(null, x, y, z);
	
	JailZone zone = jail.getJailZone(zoneName);
	zone.setFirstCorner(corner);
	zone.update();

This piece of code will modify first corner of cuboid of our jail named "jail" to 1,2,3. First we define our coordinates and then Location. There is no need to define world when setting corners, so we can just set it to null. After that, we retrieve our jail zone and modify data. Notice that there is also update method for jail zone.

This quick tutorial just showed some ways to mess around with jail plugin. There are lot of possibilities, take a look and see if your plugin could use some of these!