Development Using the Connect API in your plugins and projects

Concept
The Connect API allows for the creation of rich plugins which enable your server to be more than a simple inter-server. The API is ever expanding, and will cover most of your needs from the beginning.

Download
You can download the latest Connect API build by clicking here. If you need an older Connect API build, you can view an archive of them by clicking here.

If you would like to use this project with maven, you can add this repository:

Code (xml):

<repository>
    <id>lilypad</id>
    <url>http://ci.lilypadmc.org/plugin/repository/everything</url>
</repository>
 

Along with adding this dependency:

Code (xml):

<dependency>
    <groupId>lilypad.client.connect</groupId>
    <artifactId>api</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>
 

Javadocs
If you would like to have a reference to look to, or you are one of the more advanced folk, you can view the Javadocs made for the Connect API at http://jd.lilypadmc.org.

Getting Started
You can retrieve the Connect object (in a Bukkit-Connect environment) by using:

Code (java):

import lilypad.client.connect.api.Connect;
...
Plugin plugin = ...
Connect connect = plugin.getServer().getServicesManager().getRegistration(Connect.class).getProvider();
 

Using the Settings
The settings are useful in scenarios where you are required to know Connect's username, password, or outbound address. In this case, you can retrieve the settings by using:

Code (java):

import lilypad.client.connect.api.Connect;
import lilypad.client.connect.api.ConnectSettings;
import java.net.InetSocketAddress;
...
Connect connect = ...
ConnectSettings settings = connect.getSettings();
String username = settings.getUsername();
String password = settings.getPassword();
String outboundAddress = settings.getOutboundAddress();
 

Requests and Results
In the Connect API, requests and results are to be entirely asynchronous to ensure the performance within the game. You can execute an example request by using:

Code (java):

import lilypad.client.connect.api.Connect;
import lilypad.client.connect.api.request.Request;
import lilypad.client.connect.api.result.FutureResult;
...
Connect connect = ...
Request<T> request = ...
FutureResult<T> futureResult = connect.request(request);
 

And to retrieve the result, you can use any of the variants:

Code (java):

try {
    T result = futureResult.await();
} catch(InterruptedException exception) {
    //ignore
}
 

Code (java):

long timeout = 10000L;
try {
    T result = futureResult.await(timeout);
} catch(InterruptedException exception) {
    //ignore
}
 

Code (java):

T result = futureResult.awaitUninterruptibly();
 

Code (java):

long timeout = 10000L;
T result = futureResult.awaitUninterruptibly(timeout);
 

Code (java):

import lilypad.client.connect.api.result.FutureResultListener;
...
futureResult.addListener(new FutureResultListener<T>() {
    public void onResult(T result) {
    }
});
 

Please note that the Connect API will return null if the connection to the Connect Server has broken, and your request has expired.

For all of the requests and their corresponding responses, you can refer to the GitHub repository by clicking here.

Listening for Message Events
Other servers can send you messages that will have a sender, channel and the actual message. To respond to these correctly, you will need to listen for them. You can do this by using:

Code (java):

import lilypad.client.connect.api.Connect;
import lilypad.client.connect.api.event.MessageEvent;
import lilypad.client.connect.api.MessageEventListener;
import java.io.UnsupportedEncodingException;
...
MessageListener messageListener = new MessageListener();
public void onEnable() {
    Connect connect = ...
    connect.registerEvents(messageListener);
}
public void onDisable() {
    Connect connect = ...
    connect.unregisterEvents(messageListener);
}
...
public class MessageListener {
    @EventListener
    public void onMessage(MessageEvent messageEvent) {
        String sender = messageEvent.getSender();
        String channel = messageEvent.getChannel();
        byte[] message = messageEvent.getMessage();
        try {
          String messageAsString = messageEvent.getMessageAsString();
        } catch(UnsupportedEncodingException exception) {
            //ignore
        }
    }
}
 

Please note that when sending a message to ensure you use a unique channel name, and to abbreviate to use the smallest amount of data on the network. "lp*" channel names are reserved for LilyPad internal and example plugins.

Be sure to look at: http://www.lilypadmc.org/threads/event-api-change.221/

What's next?
The sky is the limit. You can use the API to create something unique and never before seen, and request feature additions as you need them.

Have fun!