Pages

API

API

Overview

The API can be used to extend the V10parser, which parses .v10 files for the V10 scripting language. It is designed to be simple.

The main use: Extend the API

To use the API you have to create a new class which implements de.V10lator.BukkitHTTPD.Function - like this:

import de.V10lator.BukkitHTTPD.Function;

public class MyCustomFunction implements Function
{
  //...
}

The class have to have two functions: The void onBukkitExecute() and the onHTTPDExecute which has to return a String.

This two functions are guaranteed to be never executed for the same time! If you still wonder why, well, it's easy:

The function onBukkitExecute() will be called within the bukkit main loop, so you can access all bukkit API calls and fill their returns into buffer variables, like this:

import de.V10lator.BukkitHTTPD.Function;

public class MyCustomFunction implements Function
{
  private final MyAwesomePlugin plugin;
  private String world = null;

  public MyCustomFunction(new MyAwesomePlugin plugin)
  {
    this.plugin = plugin;
  }
  private String world = null;
  public void onBukkitExecute()
  {
    world = plugin.getServer().getWorld("world").getName();
  }
  //...
}

All fine, now you can access the variable later in onHTTPDExecute(Params parms, String[] args, String ip). Later means whenever a client requests a page with your function included, as BukkitHTTPD is multi threaded it's not allowed to talk to the Bukkit API, but as it's guaranteed that onBukkitExecute() won't run while we do, we can acces our pre-stored variable, like this:

import de.V10lator.BukkitHTTPD.Function;

public class MyCustomFunction implements Function
{
  private final MyAwesomePlugin plugin;
  private String world = null;

  public MyCustomFunction(new MyAwesomePlugin plugin)
  {
    this.plugin = plugin;
  }
  private String world = null;
  public void onBukkitExecute()
  {
    world = plugin.getServer().getWorld("world").getName();
  }
  public void onHTTPDExecute()
  {
    return("\"world\"");
  }
}

Okay, but what's the String? Well, it will be written between

myAwesomeFunction = new Array(

and

);

in the HTML (JavaScript) code. :)

Of course BukkitHTTPD has to be informed about you function, so register it, it's simple:

import org.bukkit.plugin.java.JavaPlugin;

public MyAwesomePlugin extends JavaPlugin
{
  public void onEnable()
  {
    //...
    de.V10lator.BukkitHTTPD.API api = ((BukkitHTTPD)pm.getPlugin("BukkitHTTPD")).getAPI();
    if(!api.isReady())
    {
      //There's something wrong, did you forget to make BukkitHTTPD a dependencie in your plugin.yml?
      return;
    }
    //There's a function to get the versions number of the API: api.getVersion(). It will return a Double where the first number only changes if there are breakages and the second whenever there are bugfixes and/or new functions. You should check at least the first number before you do:
    api.addFunction("myAwesomeFunction", new MyAwesomeFunction(this))
    //...
  }
  //...
}

You can also unregister or replace your function. to do this:

api.removeFunction("myAwesomeFunction");

api.replaceFunction("myAwesomeFunction");


Now that you read that much, here are the arguments of onBukkitHTTPDExecute(Params parms, String[] args, String ip):

parms: The HTTP GET and POST arguments.
args: The arguments given to myAwesomeFunction() in the .v10 file.
ip: The web clients IP.

And if you're asking how often onBukkitExecute() get's called, well, around every second, which is the refresh cycle for all of BukkitHTTPDs buffers.

Another use: Write to BukkitHTTPDs chat

This is the sourcecode from HeroChat-BukkitHTTPD v0.3 - it is licensed under the terms of the GPLv3:

package de.V10lator.HeroChat;

import java.io.File;
import java.util.ArrayList;
import java.util.List;

import org.bukkit.Server;
import org.bukkit.configuration.Configuration;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerChatEvent;
import org.bukkit.plugin.PluginManager;
import org.bukkit.plugin.java.JavaPlugin;

import com.dthielke.herochat.ChannelChatEvent;

import de.V10lator.BukkitHTTPD.BukkitHTTPD;

public class HTTPDPlugin extends JavaPlugin
{
  private List<String> channelList;
  private de.V10lator.BukkitHTTPD.API bAPI;
  
  public void onEnable()
  {
	Server s = getServer();
	PluginManager pm = s.getPluginManager();
	bAPI = ((BukkitHTTPD)pm.getPlugin("BukkitHTTPD")).getAPI();
	if(!bAPI.isReady())
	{
	  s.getLogger().info("["+getName()+"] BukkitHTTPDs API not ready!");
	  s.getPluginManager().disablePlugin(this);
	  return;
	}
	double bv = bAPI.getVersion();
	if(bv < 3.0D)
	{
	  s.getLogger().info("["+getName()+"] BukkitHTTPD API outdated (>=3.0 needed, "+bv+" found!");
	  s.getPluginManager().disablePlugin(this);
	  return;
	}
	if(bv >= 4.0D)
	{
	  s.getLogger().info("["+getName()+"] BukkitHTTPD API breakage detected (<4.0 needed, "+bv+" found!");
	  s.getPluginManager().disablePlugin(this);
	  return;
	}
	File cfg = new File(getDataFolder(), "config.yml");
	if(!cfg.exists())
	{
	  Configuration config = getConfig();
	  ArrayList<String> tmp = new ArrayList<String>();
	  tmp.add("Global");
	  config.set("ChannelList", tmp);
	  saveConfig();
	}
	Configuration config = getConfig();
	channelList = config.getStringList("ChannelList");
	getServer().getPluginManager().registerEvents(new HeroListener(), this);
  }
  
  private class HeroListener implements Listener
  {
	@SuppressWarnings("unused")
	@EventHandler(priority = EventPriority.MONITOR)
	public void heroChat(ChannelChatEvent event)
	{
	  String channel = event.getChannel().getName();
	  if(event.getResult() == com.dthielke.herochat.Chatter.Result.ALLOWED && channelList.contains(channel))
	  {
		PlayerChatEvent pce = event.getBukkitEvent();
		bAPI.addToChat(channel+"| "+pce.getPlayer().getDisplayName() + ": " +
						 pce.getMessage());
	  }
	}
  }
}

Get the www dir

Simple: api.getWwwDir();


Happy hacking! :)

Comments

Posts Quoted:
Reply
Clear All Quotes