Dev builds

Development builds of this project can be acquired at the provided continuous integration server.
These builds have not been approved by the BukkitDev staff. Use them at your own risk.

Dev Builds

1.2.9 Description

As because the API on the PHP side has grown so big, I will move the description to Git WIki soon.

Java API

Description

This plugin will allow plugin developers to create a simple integration with websites.

Server owners to use this plugin properly and without making a Security hole needs to set the pass node in the config file. This password will be used later on the PHP side to allow only valid requests form your website.

pass: 'Password'

All connections are done using sockets, so there i no MySQL database between or any other server like service. This plugin is a small server itself, so you just need this API some supported plugins, and you can show plugin data on your website, or even create a small Application that will allow you to manage some plugin things from the web :)

How it works for each group is written below.

API

This plugin has two API's, one is for Plugin Developers and the other one is for Web Developers (PHP devs).

Each API is simple and does not need much to make it working :)

Java

As a plugin dev you can just allow users to get data and display it on the web, or you can also allow users from the web to change values in your plugin.
For each of this possibilities you got 2 Interfaces and and Annotation.

The @Stat annotation

This annotation can be added to methods which will be used to send data to the web, or to update a requested stat using a value parsed from the web.

This annotation has a "name" property that must be set, this name will be used by web-devs to get the required stat value, or to update the chosen stat with a value set. The @Stat name also is used as a stat path, so you can using this name add more complicated paths, handle additional arguments.

A second optional attribute the @Stat annotation has is the requestType attribute. It's by default set to AUTO so it depends if it's in a Listener or in a Updater class, where it will be listed for Web requests.This is useful when you got an Updater and Listener for the same class, because this allows to set a Stat method only for one request type. If not done this one method can be listed for both Update and Get requests. (Better description soon)

Example:

@Stat(name = "number")
public int someNumber()
{
    return 123;
}

An example with a path, and a argument.

@Stat(name = "number/{format}")
public int someNumber(String format)
{
    return String.format(format, 123);
}

This argument is easily added on the webpage API, allowing you to set the formation already on the Web!

@Stat for classes

You can also add the @Stat annotation to a class with the Listener or Updater interface. Doing this will apply the name for that Stat to each method beginning.

Example:

@Stat(name="clazz/{name}")
class Test implements Updater
{
    @Stat(name="test")
    public void test(String name, String value)
    {
        System.out.println(name + " " + value);
    }
}

So ass you see the class got a path like "clazz/{name}". From up now to use this update Stat you need to call on the website a method like this

Stat::update('clazz/myName/test', 'myValue');

So as you see the whole path to the method is not "test" as normally, but it changed to "clazz/{name}/test".

Paths

When using paths and path arguments always remember, that you need to set the exact number of arguments to a Listener method. And 1 more argument to an Updater method. So when a path looks like this "first/second/{third}", a Listener method needs 1 String argument defined, and a Updater method needs 2 arguments defined.

The Listener interface

This interface holds all methods that are used to get information from the plugin.

Example:

class StatListener implements Listener 
{
    @Stat(name = "number")
    public int someNumber()
    {
        return 123;
    }
}

The Updater interface

I know this Interface name is stupid, but for now i didn't got a better one.
This interface holds all methods that are used to update some values in the plugin.

Example:

class StatUpdater implements Updater
{
    @Stat(name = "message")
    public void sendMessage(String value)
    {
        Bukkit.broadcastMessage(value);
    }
}

Who says you can't send a message with this from the website.

Register Updater and listener

After you have created your listener and/or updater you just need to register it this way, first argument is your PluginName, second is the listener/updater class or object. As because Both updater and Listener are Inferfaces you can set one class to be both of them.

Manager.registerListener("dtlStats", new SampleClass());
Manager.registerUpdater("dtlStats", SampleClass.class);

php

PHP developers doesn't need to know much, the only thing they need is to include one file that can be downloaded from the Repo.
With this file you got five basic methods to use.

First you need to open a connection to a server that has dtlStats running. All you need to do is to call the static method connect() from the Stat class, with two arguments. First of them is the server address or the servers domain, the second one is the port that you have set in the config file. (default 4447)

Stat::connect("a.server.com", 4447);

After connection your password needs to be given so this connection will be validated. This password is the same that you set in the config file of this plugin.

Stat::pass("password");

After this is done you need to set the plugin from witch you want to request statistics, this plugin needs to support this plugin to make it work. Also you need to know what are the statistic names you can request from the plugin. You can always change the plugin from which you want request statistics.

Stat::plugin("pluginName");

Now you can use the Stat::get and Stat::update methods, both of them needs as the first argument the statistic name that will be acquired or updated, where the update method has a second argument that is the new value that will be set for the updated statistic.

Stat::get("number"); //without a format, will return 123
Stat::get("number/%.2f"); //with a format, will return 123.00
Stat::update("message", "Hello world!");

After all is done you need to disconnect the connection with the following method. After its disconnected you can still reconnect it after with Stat::connect.

Stat::disconnect();

Supported CMS projects

PyroCMS thanks to boozaa!

Supported plugins

Almost nothing so far, just two examples from this plugin :P Help me to get plugins supported :D You can always be sure your plugin will be linked here :)

• dtlStats
  
  • Listener statistics:
    
    • listenerCount - returns the number of listeners registered by plugins
      
  • Updater statistics:
    
    • v1.0 - message - allows to broadcast a message on the server
      
    • v1.1 - {action} - allows to evaluate a command or broadcast a message on the server