Comet IRC API

An Internet Relay Chat API for Java.

Setup

1. Either build the JAR or download it from the latest release

2. Create a folder, "lib", in the directory of a new/existing project

3. Move or copy the JAR file into the lib folder

4. Add the JAR file to the build path

   IDEA: From the Project window, select and right-click the lib folder, then click Add as Library...

   Eclipse: From the Package Explorer, select and right-click the JAR file, then select Build and click Add to Build Path

Usage

1. In a Java source file, import the IRC client API

import comets.irc.IrcClientApi;

2. Instantiate a new client

IrcServiceApi client = new IrcServiceApi();

3. Initialize client

client.initialize();

4. Set server, port, channel, and nickname

client.setServer("irc.freenode.net");
client.setPort(6667);
client.setChannel("#irchacks");
client.setNick("my_nickname");

5. Connect, login/join, and idle

client.connect();
client.login();
client.join();
client.idle(); // just for listening on a channel; see below

Use Your Own Idle Method

Example:

    public static void idle(IrcClientApi client) {
        String line = null;
        while(client.isConnected()) {
            line = client.read();
            if (line != null) {
                client.print(line);
                if (line.contains("ping")) {
                    client.post("pong");
                }
            }
        }
    }

Result:

...
[07:59] <remote_user> a
[08:00] <remote_user> ping
[08:00] <comet_irc_api> pong

A Simple Full Example

import comets.irc.IrcClientApi;

public class Main {

    public static void main(String[] args) {
        startIrcClient();
    }

    private static void startIrcClient() {
        IrcClientApi client = new IrcClientApi();
        client.initialize()
                .connect("irc.freenode.net", 6667)
                .login("my_nickname")
                .join("#irchacks");
        idle(client);
    }

    private static void idle(IrcClientApi client) {
        String line = null;
        while(client.isConnected()) {
            line = client.read();
            if(line != null) {
                client.print(line);
                if(line.contains("ping")) {
                    client.post("pong");
                }
            }
            client.updateUserList();
        }
    }

}

API Reference

connect()

    Connects with server and port information set previously using setServer(String) and setPort(int)

connect(String server, int port)

    Connects with new server and port information

disconnect()

    Disconnects from server

getLine()

    Returns the current line

getPostHistory()

    Returns an ArrayList object with all recorded outgoing posts

getState()

    Returns the connection state

    States:

• not connected
• connecting
• connected
• disconnected
• not logged in
• logging in
• logged in
• logged out
• not joined channel
• joining channel
• joined channel
• left channel

getUserList()

    Returns an ArrayList object containing the names of users present on the current channel

    In order to receive an updated and accurate userlist, the updateUserList() method must be invoked upon reading each incoming line

idle()

    Listens to channel and prints processed lines to standard output

    To receive each line elsewhere, build a custom idle() method, then use the read() and post(String) methods

ignore(String user)

    Sends request to ignore a specified user

isConnected()

    Returns a boolean value that indicates the connection status

    At this time, this method returns true for both connected and connecting states

join()

    Joins previously specified channel

join(String channel)

    Joins a new channel

leave()

    Parts from the current channel

login()

    Logs in using nick and password information set previously

login(String nick)

    Logs in using new nick

login(String channel, String nick, String pass)

    Logs in using new channel, nick, and pass

login(String nick, String pass, String realName, String login, int mode)

    Logs in using new nick, pass, real name, login, and mode

logout()

    Logs nickname out

ping()

    Sends a 'ping' message

    This message is not saved in the post history

pong()

    Sends a 'pong' message

    This message is not saved in the post history and it is not the same as sending a pong back to a ping request from the server. Ping responses are handled silently in the background

post(String message)

    Adds the post to history, then reshapes it into an IRC message line and sends it to the connected channel

print(String line)

    Takes a string, adds a time-stamp to the beginning of it, using the [HR:MN] format, then prints it to standard output

    [08:00] <remote_user> hi

printLine()

    Prints the current line

    Same as: print(line)

process(String line)

    Takes a raw line and reshapes it into a more human-readable format

    <remote_user> hi

quit()

    Disconnects and drops current connection information (server, port, channel, nick, user list)

read()

    Returns the read line after processing it

    Same as: processLine(receive())

    <remote_user> hi

receive()

    Returns the raw line (no processing or reshaping)

    :remote_user!4dd17b5c@gateway/web/freenode/ip.##.###.###.### PRIVMSG #irchacks :hi

send(String rawLine)

    Takes an IRC-formatted line and sends it to the connected channel

    Does not record the line in post history

setChannel(String channel)

    Sets channel information so that it won't have to be done later

setNick(String nick)

    Sets nickname with which to login

setPort(int port)

    Sets port number for future connection

setServer(String server)

    Sets server address for future connection

setSession(String server, int port, String channel, String nick)

    Sets server, port, channel, and nick for future connection

unignore(String user)

    Sends request to unignore a specified user

updateUserList()

    Keeps track of the users logged into the current channel by reading the lines for user activity

    This method is meant to be independent of the NAMES command, which requests the usernames from the server

whois(String user)

    Sends a whois request for a specified user

    Note: must read lines to receive response

Contributing

All pull requests are welcome.