Providing an API

I'm working on a plugin that I'd like to provide an API with (for myself and other developers to use)... However I've never done this before.

How can I provide methods for other plugins for use? Does anyone know of a simple example of how this is done?

Just make the methods public and you should be fine

How would another plugin grab those methods?

Plugin p = getServer().getPluginManager().getPlugin("YourPluginName");
if (p == null)
return;
YourPlugin pl = (YourPlugin) p;

They would have to add your plugin as a JAR to their build path

Gotcha, thanks!

Also, really helpful to create some forum of Documentation (preferably Java Docs) to provide for use with your API.

I was looking into that, however honestly I'm not familiar with how to create Java Docs. Any pointers?

Eclipse handles some of the basic setting it up, such as auto generating params and returns tags when the method uses it.

So of course I'm using NetBeans, heh.

Anyway I'll do some Googling.

Netbeans might do it too, I only use eclipse so that's my experience, just look up Java Doc tagging and you should be good.

In eclipse, before a method you want to javadoc, you just have type /**, press enter and It'll place the @ tags... however, if your editor doesn't automatically make those, you can add them yourself... look at a example generated java doc for a method of mine:

Code:

	/**
	 * 
	 * @param item
	 * @param ingredient
	 * @return
	 */
	protected static List<Recipe> getRecipesForItem(final Item item, final boolean ingredient)

It's easy to replicate manually The rest needs to be completed manually either way, like description and stuff...

Code:

	/**
	 * Just a method :}
	 * Test.
	 * <br>
	 * bla bla bla
	 * 
	 * @param item - the item
	 * @param ingredient - if it should search in ingredients or in results
	 * @return the list of found recipes
	 */
	protected static List<Recipe> getRecipesForItem(final Item item, final boolean ingredient)

Makes this:


But ofc you shouldn't use private or protected for API xD

Thanks I'll have to get to work on that!

As a side note this is what I've been working on:
http://dev.bukkit.org/server-mods/urlmanager/

To truly provide an API for other plugin developers, It is better to use the ServicesManager and register a service provided by your plugin.

Do you know of any examples of this being implemented? Sorry I'm not familiar with the ServicesManager.

I believe Vault provides a service through this.

Yah... I was hoping to find something a little simpler, but I'll dig through it, thanks!

You'll have to forgive some ignorance... So to set this up I need one of these:

(main file)

Code:

        if (packageExists("com.platymuus.bukkit.permissions.PermissionsPlugin")) {
            Permission pPerms = new Permission_PermissionsBukkit(this);
            sm.register(Permission.class, pPerms, this, ServicePriority.Highest);
            log.info(String.format("[%s][Permission] PermissionsBukkit found: %s", getDescription().getName(), pPerms.isEnabled() ? "Loaded" : "Waiting"));
        }

and one of these?

(SomeDefinition.java ?)

Code:

package net.milkbowl.vault.permission;
 
import java.util.logging.Logger;
 
import net.milkbowl.vault.Vault;
 
import org.bukkit.World;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;
import org.bukkit.permissions.PermissionAttachment;
import org.bukkit.permissions.PermissionAttachmentInfo;
 
/**
 * The main Permission API - allows for group and player based permission tests
 *
 */
public abstract class Permission {
 
protected static final Logger log = Logger.getLogger("Minecraft");
    protected Vault plugin = null;
 
    /**
     * Gets name of permission method
     * @return Name of Permission Method
     */
    abstract public String getName();
 
    /**
     * Checks if permission method is enabled.
     * @return Success or Failure
     */
    abstract public boolean isEnabled();
    
    /**
     * Returns if the permission system is or attempts to be compatible with super-perms.
     * @return True if this permission implementation works with super-perms
     */
    abstract public boolean hasSuperPermsCompat();
    
    /**
     * Checks if player has a permission node. (Short for playerHas(...)
     * @param world World name
     * @param player Player name
     * @param permission Permission node
     * @return Success or Failure
     */
    public boolean has(String world, String player, String permission) {
        if (world == null) {
            return playerHas((String) null, player, permission);
        }
        return playerHas(world, player, permission);
    }
 
    /**
     * Checks if player has a permission node. (Short for playerHas(...)
     * @param world World Object
     * @param player Player name
     * @param permission Permission node
     * @return Success or Failure
     */
    public boolean has(World world, String player, String permission) {
        if (world == null) {
            return playerHas((String) null, player, permission);
        }
        return playerHas(world.getName(), player, permission);
    }
 
    /**
     * Checks if a CommandSender has a permission node.
     * For easy checking of a commandsender
     * @param sender
     * @param permission
     * @return true if the sender has the permission
     */
    public boolean has(CommandSender sender, String permission) {
        return sender.hasPermission(permission);
    }
    
    /**
     * Checks if player has a permission node. (Short for playerHas(...)
     * @param player Player Object
     * @param permission Permission node
     * @return Success or Failure
     */
    public boolean has(Player player, String permission) {
        return player.hasPermission(permission);
    }
 
    /**
     * Checks if player has a permission node.
     * @param world World name
     * @param player Player name
     * @param permission Permission node
     * @return Success or Failure
     */
    abstract public boolean playerHas(String world, String player, String permission);
 
    /**
     * Checks if player has a permission node.
     * @param world World Object
     * @param player Player name
     * @param permission Permission node
     * @return Success or Failure
     */
    public boolean playerHas(World world, String player, String permission) {
        if (world == null) {
            return playerHas((String) null, player, permission);
        }
        return playerHas(world.getName(), player, permission);
    }
 
    /**
     * Checks if player has a permission node.
     * @param player Player Object
     * @param permission Permission node
     * @return Success or Failure
     */
    public boolean playerHas(Player player, String permission) {
        return has(player, permission);
    }
 
    /**
     * Add permission to a player.
     * @param world World name
     * @param player Player name
     * @param permission Permission node
     * @return Success or Failure
     */
    abstract public boolean playerAdd(String world, String player, String permission);
 
    /**
     * Add permission to a player.
     * @param world World Object
     * @param player Player name
     * @param permission Permission node
     * @return Success or Failure
     */
    public boolean playerAdd(World world, String player, String permission) {
        if (world == null) {
            return playerAdd((String) null, player, permission);
        }
        return playerAdd(world.getName(), player, permission);
    }
 
    /**
     * Add permission to a player.
     * @param player Player Object
     * @param permission Permission node
     * @return Success or Failure
     */
    public boolean playerAdd(Player player, String permission) {
        return playerAdd(player.getWorld().getName(), player.getName(), permission);
    }
    
    /**
     * Add transient permission to a player.
     * This implementation can be used by any subclass which implements a "pure" superperms plugin, i.e. 
     * one that only needs the built-in Bukkit API to add transient permissions to a player.  Any subclass
     * implementing a plugin which provides its own API for this needs to override this method. 
     * @param world World name
     * @param player Player name
     * @param permission Permission node
     * @return Success or Failure
     */
    public boolean playerAddTransient(String player, String permission) {
Player p = plugin.getServer().getPlayer(player);
if (p == null) {
throw new UnsupportedOperationException(getName() + " does not support offline player transient permissions!");
}
return playerAddTransient(p, permission);
}
 
    /**
     * Add transient permission to a player.
     * @param player Player Object
     * @param permission Permission node
     * @return Success or Failure
     */
    public boolean playerAddTransient(Player player, String permission) {
for (PermissionAttachmentInfo paInfo : player.getEffectivePermissions()) {
if (paInfo.getAttachment() != null && paInfo.getAttachment().getPlugin().equals(plugin)) {
paInfo.getAttachment().setPermission(permission, true);
return true;
}
}
 
PermissionAttachment attach = player.addAttachment(plugin);
attach.setPermission(permission, true);
 
return true;
    }
 
    /**
     * Adds a world specific transient permission to the player - ONLY WORKS IN PEX/P3 - otherwise it defaults to GLOBAL!
     * @param world
     * @param player
     * @param permission
     * @return
     */
    public boolean playerAddTransient(String worldName, Player player, String permission) {
   return playerAddTransient(player, permission);
    }
    
    /**
     * Adds a world specific transient permission to the player - ONLY WORKS IN PEX/P3 - otherwise it defaults to GLOBAL!
     * @param world
     * @param player
     * @param permission
     * @return
     */
    public boolean playerAddTransient(String worldName, String player, String permission) {
Player p = plugin.getServer().getPlayer(player);
if (p == null) {
throw new UnsupportedOperationException(getName() + " does not support offline player transient permissions!");
}
return playerAddTransient(p, permission);
    }
    
    /**
     * Removes a world specific transient permission from the player - Only works in PEX/P3 - otherwise it defaults to Global!
     * @param world
     * @param player
     * @param permission
     * @return
     */
public boolean playerRemoveTransient(String worldName, String player, String permission) {
Player p = plugin.getServer().getPlayer(player);
if (p == null)
return false;
 
return playerRemoveTransient(p, permission);
}
 
    /**
     * Removes a world specific transient permission from the player - Only works in PEX/P3 - otherwise it defaults to Global!
     * @param worldName
     * @param player
     * @param permission
     * @return
     */
    public boolean playerRemoveTransient(String worldName, Player player, String permission) {
   return playerRemoveTransient(player, permission);
    }
    
    /**
     * Remove permission from a player.
     * @param world World name
     * @param player Name of Player
     * @param permission Permission node
     * @return Success or Failure
     */
    abstract public boolean playerRemove(String world, String player, String permission);
 
    /**
     * Remove permission from a player.
     * @param world World name
     * @param player Player name
     * @param permission Permission node
     * @return Success or Failure
     */
    public boolean playerRemove(World world, String player, String permission) {
        if (world == null) {
            return playerRemove((String) null, player, permission);
        }
        return playerRemove(world.getName(), player, permission);
    }
 
    /**
     * Remove permission from a player.
     * @param player Player Object
     * @param permission Permission node
     * @return Success or Failure
     */
    public boolean playerRemove(Player player, String permission) {
        return playerRemove(player.getWorld().getName(), player.getName(), permission);
    }
    
    /**
     * Remove transient permission from a player.
     * This implementation can be used by any subclass which implements a "pure" superperms plugin, i.e. 
     * one that only needs the built-in Bukkit API to remove transient permissions from a player.  Any subclass
     * implementing a plugin which provides its own API for this needs to override this method.
     * @param world World name
     * @param player Player name
     * @param permission Permission node
     * @return Success or Failure
     */
public boolean playerRemoveTransient(String player, String permission) {
Player p = plugin.getServer().getPlayer(player);
if (p == null)
return false;
 
return playerRemoveTransient(p, permission);
}
 
    /**
     * Remove transient permission from a player.
     * @param player Player Object
     * @param permission Permission node
     * @return Success or Failure
     */
    public boolean playerRemoveTransient(Player player, String permission) {
for (PermissionAttachmentInfo paInfo : player.getEffectivePermissions()) {
if (paInfo.getAttachment() != null && paInfo.getAttachment().getPlugin().equals(plugin)) {
paInfo.getAttachment().unsetPermission(permission);
return true;
}
}
return false;
    }
    
    /**
     * Checks if group has a permission node.
     * @param world World name
     * @param group Group name
     * @param permission Permission node
     * @return Success or Failure
     */
    abstract public boolean groupHas(String world, String group, String permission);
 
    /**
     * Checks if group has a permission node.
     * @param world World Object
     * @param group Group name
     * @param permission Permission node
     * @return Success or Failure
     */
    public boolean groupHas(World world, String group, String permission) {
        if (world == null) {
            return groupHas((String) null, group, permission);
        }
        return groupHas(world.getName(), group, permission);
    }
 
    /**
     * Add permission to a group.
     * @param world World name
     * @param group Group name
     * @param permission Permission node
     * @return Success or Failure
     */
    abstract public boolean groupAdd(String world, String group, String permission);
 
    /**
     * Add permission to a group.
     * @param world World Object
     * @param group Group name
     * @param permission Permission node
     * @return Success or Failure
     */
    public boolean groupAdd(World world, String group, String permission) {
        if (world == null) {
            return groupAdd((String) null, group, permission);
        }
        return groupAdd(world.getName(), group, permission);
    }
 
    /**
     * Remove permission from a group.
     * @param world World name
     * @param group Group name
     * @param permission Permission node
     * @return Success or Failure
     */
    abstract public boolean groupRemove(String world, String group, String permission);
 
    /**
     * Remove permission from a group.
     * @param world World Object
     * @param group Group name
     * @param permission Permission node
     * @return Success or Failure
     */
    public boolean groupRemove(World world, String group, String permission) {
        if (world == null) {
            return groupRemove((String) null, group, permission);
        }
        return groupRemove(world.getName(), group, permission);
    }
 
    /**
     * Check if player is member of a group.
     * @param world World name
     * @param player Player name
     * @param group Group name
     * @return Success or Failure
     */
    abstract public boolean playerInGroup(String world, String player, String group);
 
    /**
     * Check if player is member of a group.
     * @param world World Object
     * @param player Player name
     * @param group Group name
     * @return Success or Failure
     */
    public boolean playerInGroup(World world, String player, String group) {
        if (world == null) {
            return playerInGroup((String) null, player, group);
        }
        return playerInGroup(world.getName(), player, group);
    }
 
    /**
     * Check if player is member of a group.
     * @param player Player Object
     * @param group Group name
     * @return Success or Failure
     */
    public boolean playerInGroup(Player player, String group) {
        return playerInGroup(player.getWorld().getName(), player.getName(), group);
    }
 
    /**
     * Add player to a group.
     * @param world World name
     * @param player Player name
     * @param group Group name
     * @return Success or Failure
     */
    abstract public boolean playerAddGroup(String world, String player, String group);
 
    /**
     * Add player to a group.
     * @param world World Object
     * @param player Player name
     * @param group Group name
     * @return Success or Failure
     */
    public boolean playerAddGroup(World world, String player, String group) {
        if (world == null) {
            return playerAddGroup((String) null, player, group);
        }
        return playerAddGroup(world.getName(), player, group);
    }
 
    /**
     * Add player to a group.
     * @param player Player Object
     * @param group Group name
     * @return Success or Failure
     */
    public boolean playerAddGroup(Player player, String group) {
        return playerAddGroup(player.getWorld().getName(), player.getName(), group);
    }
 
    /**
     * Remove player from a group.
     * @param world World name
     * @param player Player name
     * @param group Group name
     * @return Success or Failure
     */
    abstract public boolean playerRemoveGroup(String world, String player, String group);
 
    /**
     * Remove player from a group.
     * @param world World Object
     * @param player Player name
     * @param group Group name
     * @return Success or Failure
     */
    public boolean playerRemoveGroup(World world, String player, String group) {
        if (world == null) {
            return playerRemoveGroup((String) null, player, group);
        }
        return playerRemoveGroup(world.getName(), player, group);
    }
 
    /**
     * Remove player from a group.
     * @param player Player Object
     * @param group Group name
     * @return Success or Failure
     */
    public boolean playerRemoveGroup(Player player, String group) {
        return playerRemoveGroup(player.getWorld().getName(), player.getName(), group);
    }
 
    /**
     * Gets the list of groups that this player has
     * @param world World name
     * @param player Player name
     * @return Array of groups
     */
    abstract public String[] getPlayerGroups(String world, String player);
 
    /**
     * Gets the list of groups that this player has
     * @param world World Object
     * @param player Player name
     * @return Array of groups
     */
    public String[] getPlayerGroups(World world, String player) {
        if (world == null) {
            return getPlayerGroups((String) null, player);
        }
        return getPlayerGroups(world.getName(), player);
    }
 
    /**
     * Gets the list of groups that this player has
     * @param player Player Object
     * @return Array of groups
     */
    public String[] getPlayerGroups(Player player) {
        return getPlayerGroups(player.getWorld().getName(), player.getName());
    }
 
    /**
     * Gets players primary group
     * @param world World name
     * @param player Player name
     * @return Players primary group
     */
    abstract public String getPrimaryGroup(String world, String player);
 
    /**
     * Gets players primary group
     * @param world World Object
     * @param player Player name
     * @return Players primary group
     */
    public String getPrimaryGroup(World world, String player) {
        if (world == null) {
            return getPrimaryGroup((String) null, player);
        }
        return getPrimaryGroup(world.getName(), player);
    }
 
    /**
     * Get players primary group
     * @param player Player Object
     * @return Players primary group
     */
    public String getPrimaryGroup(Player player) {
        return getPrimaryGroup(player.getWorld().getName(), player.getName());
    }
    
    /**
     * Returns a list of all known groups
     * @return an Array of String of all groups
     */
    abstract public String[] getGroups();
}

Is there anything I'm missing? Sorry I wasn't able to find a tutorial/example on how this beast works.