Kitteh IRC Client Library Documentation

The Kitteh IRC Client Library (KICL) is a powerful, modern Java IRC library built with NIO using the Netty library to maximize performance and scalability. KICL is built with Java 8 and utilizes Java 8's Optional to avoid returning null in the API.

Some niceties about KICL include:

• Full SSL support
• WEBIRC authentication
• Fully featured CTCP support
• IRCv3.1 and IRCv3.2 support
  • CAP negotiation
  • SASL authentication
  • Account tracking with account-notify, extended-join, and WHOX
  • Away status tracking with away-notify
  • More accurate mode tracking with multi-prefix
• Flexible authentication
  • SASL, NickServ, and GameSurge's AuthServ supported out-of-the-box
  • Custom authentication protocols can be easily written and registered
• Events model for handling information from the server.

Getting started

KICL is designed with a simple and intuitive API. A hello world is as simple as:

Client client = Client.builder().nick("KittehBot").serverHost("127.0.0.1").build();

client.addChannel("#kitteh.org");
client.sendMessage("#kitteh.org", "Hello World!");

Note: By default KICL connects over SSL, which requires additional setup on certain networks.

Debugging

It can be useful to see input, output, and exceptions thrown while developing.

Use the ClientBuilder methods listenInput, listenOutput, and listenException to catch these little surprises. Here is a simple example, printing all of the info to the console:

SimpleDateFormat sdf = new SimpleDateFormat("mm:ss");
builder.listenInput(line -> System.out.println(sdf.format(new Date()) + ' ' + "[I] " + line));
builder.listenOutput(line -> System.out.println(sdf.format(new Date()) + ' ' + "[O] " + line));
builder.listenException(Throwable::printStackTrace);

Using KICL in your Maven project

KICL is built and deployed using Maven. Releases are available on Maven Central. Adding it as a dependency is simple as adding the lines below to your pom.xml file:

<dependency>
    <groupId>org.kitteh.irc</groupId>
    <artifactId>client-lib</artifactId>
    <version>3.2.0</version>
    <scope>...</scope>
</dependency>

Events

KICL uses a simple event system driven by @Handler annotations. A simple event listener example is shown below. For more information on events, see the Events documentation.

public class FriendlyBot {
    private Client client;

    public void connect() {
        ...; // Setting up this.client

        this.client.getEventManager().registerEventListener(this);
    }

    @Handler
    public void onJoin(ChannelJoinEvent event) {
        Channel channel = event.getChannel();
        channel.sendMessage("Hi " + event.getUser().getNick() + "!");
    }
}

More information

Consult the JavaDocs to answer most questions.

Visit us in #kitteh.org on irc.esper.net for a chat (click here to join), or check out the Issue Tracker if you have trouble.