org.schwering.irc.lib

Interface IRCConnection

All Known Implementing Classes:

DefaultIRCConnection

public interface IRCConnection

A connection to an IRC server.

Typical usage:

 IRCConfig config = IRCConfigBuilder.newBuilder()
          .host("irc.freenode.net")
          .port(6667)
          .username(System.getProperty("user.name"))
          .password("secret")
          .realname(System.getProperty("user.name"));
 IRCConnection connection = IRCConnectionFactory.newConnection(config);
 connection.addIRCEventListener(new IRCEventAdapter() {
     /* implement whatever you need */
 });
 connection.connect();
 connection.doJoin("#test");
 connection.doPrivmsg("#test", "Hello World!");
 connection.close();
 

Author:

Peter Palaga

Field Summary

Fields

Modifier and Type	Field and Description
static int	INVALID_TIMEOUT Value returned when there is no timeout to deliver.

Method Summary

Modifier and Type	Method and Description
void	addIRCEventListener(IRCEventListener l) Adds a new IRCEventListener which listens for actions coming from the IRC server.
void	close() Close the connection forcefully.
void	connect() Establish a connection to the server.
void	doAway() Removes away message.
void	doAway(String msg) Sets away message.
void	doInvite(String nick, String chan) Invites a user to a channel.
void	doIson(String nick) Checks if one or more nicks are used on the server.
void	doJoin(String chan) Joins a channel without a key.
void	doJoin(String chan, String key) Joins a channel with a key.
void	doKick(String chan, String nick) Kicks a user from a channel.
void	doKick(String chan, String nick, String msg) Kicks a user from a channel with a comment.
void	doList() Lists all channels with their topic and status.
void	doList(String chan) Lists channel(s) with their topic and status.
void	doMode(String chan) Requests a Reply 324 for the modes of a given channel.
void	doMode(String target, String mode) Sends a mode to the server.
void	doNames() Lists all visible users.
void	doNames(String chan) Lists all visible users of (a) channel(s).
void	doNick(String nick) Changes the nickname.
void	doNotice(String target, String msg) Notices a message to a person or a channel.
void	doPart(String chan) Parts from a given channel.
void	doPart(String chan, String msg) Parts from a given channel with a given parg-msg.
void	doPong(String ping) Quits from the IRC server with a quit-msg.
void	doPrivmsg(String target, String msg) Sends a message to a person or a channel.
void	doQuit() Quits from the IRC server.
void	doQuit(String msg) Quits from the IRC server with a quit-msg.
void	doTopic(String chan) Requests the topic of a chan.
void	doTopic(String chan, String topic) Changes the topic of a chan.
void	doUserhost(String nick) Requires host-information about up to 5 users which must be listed and divided by spaces.
void	doWho(String criteric) Requests information about users matching the given criteric, for example a channel they are on.
void	doWhois(String nick) Requires information about an existing user.
void	doWhowas(String nick) Requires host-information about a user, who is not connected anymore.
InetAddress	getLocalAddress() Returns the local address of the connection socket.
String	getNick() Returns the nickname of this instance.
int	getPort() Returns the port to which the IRCConnection connected, or 0 if the connection failed or wasn't tried yet.
int	getTimeout() Returns the timeout of the socket.
boolean	isConnected() Tells whether there's a connection to the IRC network or not.
boolean	isSSL()
boolean	removeIRCEventListener(IRCEventListener l) Removes the first occurence of the given IRCEventListener from the listener-vector.
void	send(String line) Sends a String to the server.

Field Detail

INVALID_TIMEOUT

static final int INVALID_TIMEOUT

Value returned when there is no timeout to deliver.

See Also:

Constant Field Values

Method Detail

addIRCEventListener

void addIRCEventListener(IRCEventListener l)

Adds a new IRCEventListener which listens for actions coming from the IRC server.

Parameters:

l - An instance of the IRCEventListener interface.

Throws:

IllegalArgumentException - If listener is null.

close

void close()

Close the connection forcefully.

This method does not send QUIT IRC command. Consider using doQuit() or doQuit(String) to send the proper QUIT command to the server.

This method should be used only when there is a good reason for that, e.g. that the IRC server does not react to QUIT command.

Possibly occuring IOExceptions are handled according to the set exception handling.

See Also:

connect(), doQuit(), doQuit(String)

connect

void connect()
      throws IOException,
             KeyManagementException,
             NoSuchAlgorithmException

Establish a connection to the server. This method must be invoked to start a connection as the constructor does not do that.

It tries all ports from IRCServerConfig.getPorts() until the connecting succeeds. If all ports fail an IOException is thrown.

This method can be invokde once only.

Throws:

IOException - If an I/O error occurs.

NoSuchAlgorithmException - rethrown from the SSL layer

KeyManagementException - rethrown from the SSL layer

SocketException - If the connect method was already invoked.

See Also:

isConnected(), doQuit(), doQuit(String), close()

doAway

void doAway()

Removes away message.

doAway

void doAway(String msg)

Sets away message.

Parameters:

msg - The away message.

doInvite

void doInvite(String nick,
              String chan)

Invites a user to a channel.

Parameters:

nick - The nickname of the user who should be invited.

chan - The channel the user should be invited to.

doIson

void doIson(String nick)

Checks if one or more nicks are used on the server.

Parameters:

nick - The nickname of the user we search for.

doJoin

void doJoin(String chan)

Joins a channel without a key.

Parameters:

chan - The channel which is to join.

doJoin

void doJoin(String chan,
            String key)

Joins a channel with a key.

Parameters:

chan - The channel which is to join.

key - The key of the channel.

doKick

void doKick(String chan,
            String nick)

Kicks a user from a channel.

Parameters:

chan - The channel somebody should be kicked from.

nick - The nickname of the user who should be kicked.

doKick

void doKick(String chan,
            String nick,
            String msg)

Kicks a user from a channel with a comment.

Parameters:

chan - The channel somebody should be kicked from.

nick - The nickname of the user who should be kicked.

msg - The optional kickmessage.

doList

void doList()

Lists all channels with their topic and status.

doList

void doList(String chan)

Lists channel(s) with their topic and status.

Parameters:

chan - The channel the LIST refers to.

doMode

void doMode(String chan)

Requests a Reply 324 for the modes of a given channel.

Parameters:

chan - The channel the MODE request is refering to.

doMode

void doMode(String target,
            String mode)

Sends a mode to the server. The first argument is a nickname (user-mode) or a channel (channel-mode). String mode must contain the operators (+/-), the modes (o/v/i/k/l/p/s/w) and the possibly values (nicks/banmask/limit/key).

Parameters:

target - The nickname or channel of the user whose modes will be changed.

mode - The new modes.

doNames

void doNames()

Lists all visible users.

doNames

void doNames(String chan)

Lists all visible users of (a) channel(s).

Parameters:

chan - The channel the NAMES command is refering to.

doNick

void doNick(String nick)

Changes the nickname.

Parameters:

nick - The new nickname.

doNotice

void doNotice(String target,
              String msg)

Notices a message to a person or a channel.

Parameters:

target - The nickname or channel (group) the message should be sent to.

msg - The message which should be transmitted.

doPart

void doPart(String chan)

Parts from a given channel.

Parameters:

chan - The channel you want to part from.

doPart

void doPart(String chan,
            String msg)

Parts from a given channel with a given parg-msg.

Parameters:

chan - The channel you want to part from.

msg - The optional partmessage.

doPong

void doPong(String ping)

Quits from the IRC server with a quit-msg.

Parameters:

ping - The ping which was received in onPing. It's a String, because sometimes on some networks the server-hostname (for example splatterworld.quakenet.org) is given as parameter which would throw an Exception if we gave the ping as long.

doPrivmsg

void doPrivmsg(String target,
               String msg)

Sends a message to a person or a channel.

Parameters:

target - The nickname or channel the message should be sent to.

msg - The message which should be transmitted.

doQuit

void doQuit()

Quits from the IRC server. Calls the disconnect-method which does the work actually.

See Also:

isConnected(), connect(), doQuit(String), close()

doQuit

void doQuit(String msg)

Quits from the IRC server with a quit-msg. Calls the disconnect-method which does the work actually.

Parameters:

msg - The optional quitmessage.

See Also:

isConnected(), connect(), doQuit(), close()

doTopic

void doTopic(String chan)

Requests the topic of a chan. The topic is given in a numeric reply.

Parameters:

chan - The channel which topic should be requested.

doTopic

void doTopic(String chan,
             String topic)

Changes the topic of a chan.

Parameters:

chan - The channel which topic is changed.

topic - The new topic.

doUserhost

void doUserhost(String nick)

Requires host-information about up to 5 users which must be listed and divided by spaces.

Parameters:

nick - The nickname of the user the query is refering to.

doWho

void doWho(String criteric)

Requests information about users matching the given criteric, for example a channel they are on.

Parameters:

criteric - The criterics of the WHO query.

doWhois

void doWhois(String nick)

Requires information about an existing user.

Parameters:

nick - The nickname of the user the query is refering to.

doWhowas

void doWhowas(String nick)

Requires host-information about a user, who is not connected anymore.

Parameters:

nick - The nickname of the user the query is refering to.

getLocalAddress

InetAddress getLocalAddress()

Returns the local address of the connection socket. If the connection is not yet connected, null is returned.

Returns:

the local address

getNick

String getNick()

Returns the nickname of this instance.

Returns:

The nickname.

getPort

int getPort()

Returns the port to which the IRCConnection connected, or 0 if the connection failed or wasn't tried yet.

Returns:

The port to which the IRCConnection, or 0 if the connection failed or wasn't tried yet.

getTimeout

int getTimeout()

Returns the timeout of the socket. If an error occurs, which is never the case, -1 is returned. The possibly occuring IOException are handled according to the set exception handling.

Returns:

The timeout.

isConnected

boolean isConnected()

Tells whether there's a connection to the IRC network or not. If connect wasn't called yet, it returns false.

Returns:

The status of the connection; true if it's connected.

See Also:

connect(), doQuit(), doQuit(String), close()

isSSL

boolean isSSL()

Returns:

true if the connection is using SSL

removeIRCEventListener

boolean removeIRCEventListener(IRCEventListener l)

Removes the first occurence of the given IRCEventListener from the listener-vector.

Parameters:

l - An instance of the IRCEventListener interface.

Returns:

true if the listener was successfully removed; false if it was not found.

send

void send(String line)

Sends a String to the server. You should use this method only, if you must do it. For most purposes, there are do* methods (like doJoin). A carriage return line feed (\r\n) is appended automatically.

Parameters:

line - The line which should be send to the server without the trailing carriage return line feed (\r\n).