org.schwering.irc.lib
Class IRCConnection

java.lang.Object
  java.lang.Thread
      org.schwering.irc.lib.IRCConnection

All Implemented Interfaces:

Runnable

Direct Known Subclasses:

SSLIRCConnection, SSLIRCConnection

public class IRCConnection
extends Thread

Creates a new connection to an IRC server. It's the main class of the IRClib, the point everything starts.

The following sample code tries to establish an IRC connection to an IRC server:

 /* 
  * The following code of a class which imports org.schwering.irc.lib.*
  * prepares an IRC connection and then tries to establish the connection.
  * The server is "irc.somenetwork.com", the default portrange (6667 and 
  * 6669) is set, no password is used (null). The nickname is "Foo" and 
  * the realname is "Mr. Foobar". The username "foobar".
  * Because of setDaemon(true), the JVM exits even if this thread is 
  * running.
  * An instance of the class MyListener which must implement 
  * IRCActionListener is added as only event-listener for the connection. 
  * The connection is told to parse out mIRC color codes and to enable
  * automatic PING? PONG! replies.
  */
 IRCConnection conn = new IRCConnection(
                            "irc.somenetwork.com", 
                            6667, 
                            6669, 
                            null, 
                            "Foo", 
                            "Mr. Foobar", 
                            "foo@bar.com" 
                          ); 
 
 conn.addIRCEventListener(new MyListener()); 
 conn.setDaemon(true);
 conn.setColors(false); 
 conn.setPong(true); 
 
 try {
   conn.connect(); // Try to connect!!! Don't forget this!!!
 } catch (IOException ioexc) {
   ioexc.printStackTrace(); 
 }
 

The serverpassword isn't needed in most cases. You can give null or "" instead as done in this example.

See Also:

IRCEventListener, IRCParser, IRCUtil, SSLIRCConnection

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

Thread.State, Thread.UncaughtExceptionHandler

Field Summary

protected String	encoding The String contains the name of the character encoding used to talk to the server.
protected String	host The host of the IRC server.
protected byte	level This is like a UNIX-runlevel.
protected int[]	ports The int[] contains all ports to which we are going to try to connect.

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

IRCConnection(String host, int[] ports, String pass, String nick, String username, String realname)
Creates a new IRC connection.

IRCConnection(String host, int portMin, int portMax, String pass, String nick, String username, String realname)
Creates a new IRC connection.

Method Summary

void	addIRCEventListener(IRCEventListener l) Adds a new IRCEventListener which listens for actions coming from the IRC server.
void	close() Close down the connection brutally.
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.
boolean	getColors() Indicates whether colors are stripped out or not.
String	getEncoding() Returns the encoding of the socket.
String	getHost() Returns the server of this instance.
String	getNick() Returns the nickname of this instance.
String	getPassword() Returns the password of this instance.
boolean	getPong() Indicates whether automatic PING? PONG! is enabled or not.
int	getPort() Returns the port to which the IRCConnection connected, or 0 if the connection failed or wasn't tried yet.
int[]	getPorts() Returns all ports to which the IRCConnection is going to try or has tried to connect to.
String	getRealname() Returns the realname of this instance.
int	getTimeout() Returns the timeout of the socket.
String	getUsername() Returns the username of this instance.
boolean	isConnected() Tells whether there's a connection to the IRC network or not.
protected void	prepare(Socket s) Invoked by the connect method, this method prepares the connection.
boolean	removeIRCEventListener(IRCEventListener l) Removes the first occurence of the given IRCEventListener from the listener-vector.
void	run() The Thread is started by the connect method.
void	send(String line) Sends a String to the server.
void	setColors(boolean colors) Enables or disables the mIRC colorcodes.
void	setEncoding(String encoding) Changes the character encoding used to talk to the server.
void	setPong(boolean pong) Enables or disables the automatic PING? PONG! support.
void	setTimeout(int millis) Sets the connection's timeout in milliseconds.
String	toString() Generates a String with some information about the instance of IRCConnection.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, yield

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

level

protected byte level

This is like a UNIX-runlevel. Its value indicates the level of the IRCConnection object. 0 means that the object has not yet been connected, 1 means that it's connected but not registered, 2 means that it's connected and registered but still waiting to receive the nickname the first time, 3 means that it's connected and registered, and -1 means that it was connected but is disconnected. Therefore the defaultvalue is 0.

host

protected String host

The host of the IRC server.

ports

protected int[] ports

The int[] contains all ports to which we are going to try to connect. This can be a portrange from port 6667 to 6669, for example.

encoding

protected String encoding

The String contains the name of the character encoding used to talk to the server. This can be ISO-8859-1 or UTF-8 for example. The default is ISO-8859-1.

Constructor Detail

IRCConnection

public IRCConnection(String host,
                     int[] ports,
                     String pass,
                     String nick,
                     String username,
                     String realname)

Creates a new IRC connection.
The difference to the other constructor is, that it transmits the ports in an int[]. Thus, also ports like 1024, 2048, 6667 and 6669 can be selected.

The constructor prepares a new IRC connection which can be really started by invoking the connect method. Before invoking it, you should set the IRCEventListener and other settings.
Note that you do not need to set a password to connect to the large public IRC networks like QuakeNet, EFNet etc. To use no password in your IRC connection, use "" or null for the password argument in the constructor.

Parameters:

host - The hostname of the server we want to connect to.

ports - The portrange to which we want to connect.

pass - The password of the IRC server. If your server isn't secured by a password (that's normal), use null or "".

nick - The nickname for the connection. Is used to register the connection.

username - The username. Is used to register the connection.

realname - The realname. Is used to register the connection.

Throws:

IllegalArgumentException - If the host or ports is null or ports' length is 0.

See Also:

connect()

IRCConnection

public IRCConnection(String host,
                     int portMin,
                     int portMax,
                     String pass,
                     String nick,
                     String username,
                     String realname)

Creates a new IRC connection.
The difference to the other constructor is, that it transmits the ports as two ints. Thus, only a portrange from port x to port y like from port 6667 to 6669 can be selected.

The constructor prepares a new IRC connection which can be really started by invoking the connect method. Before invoking it, you should set the IRCEventListener and other settings.
Note that you do not need to set a password to connect to the large public IRC networks like QuakeNet, EFNet etc. To use no password in your IRC connection, use "" or null for the password argument in the constructor.

Parameters:

host - The hostname of the server we want to connect to.

portMin - The beginning of the port range we are going to connect to.

portMax - The ending of the port range we are going to connect to.

pass - The password of the IRC server. If your server isn't secured by a password (that's normal), use null or "".

nick - The nickname for the connection. Is used to register the connection.

username - The username. Is used to register the connection.

realname - The realname. Is used to register the connection.

Throws:

IllegalArgumentException - If the host is null.

See Also:

connect()

Method Detail

connect

public void connect()
             throws IOException

Establish a connection to the server.
This method must be invoked to start a connection; the constructor doesn't do that!
It tries all set ports until one is open. If all ports fail it throws an IOException.
You can invoke connect only one time.

Throws:

IOException - If an I/O error occurs.

SocketException - If the connect method was already invoked.

See Also:

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

prepare

protected void prepare(Socket s)
                throws IOException

Invoked by the connect method, this method prepares the connection.
It initializes the class-vars for the inputstream and the outputstream of the socket, starts the registration of at the IRC server by calling register() and starts the receiving of lines from the server by starting the thread with the start method.

This method must be protected, because it is used by extending classes, which override the connect method.

Parameters:

s - The socket which is used for the connection.

Throws:

IOException - If an I/O error occurs.

See Also:

connect(), run()

run

public void run()

The Thread is started by the connect method. It's task is to receive strings from the IRC server and hand them over to the get method.

Specified by:

run in interface Runnable

Overrides:

run in class Thread

send

public 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).

close

public void close()

Close down the connection brutally.
It does *NOT* send the proper IRC command QUIT. You should always use the doQuit methods or send("QUIT") instead of this method.
You should use this method to close down the connection only when the IRC server doesn't react to the QUIT command.

See Also:

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

addIRCEventListener

public 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.

removeIRCEventListener

public 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.

setColors

public void setColors(boolean colors)

Enables or disables the mIRC colorcodes.

Parameters:

colors - true to enable, false to disable colors.

setPong

public void setPong(boolean pong)

Enables or disables the automatic PING? PONG! support.

Parameters:

pong - true to enable automatic PONG reply, false makes the class fire onPing events.

setEncoding

public void setEncoding(String encoding)

Changes the character encoding used to talk to the server. This can be ISO-8859-1 or UTF-8 for example. This property must be set before a call to the connect() method.

Parameters:

encoding -

setTimeout

public void setTimeout(int millis)

Sets the connection's timeout in milliseconds.
The default is 1000 * 60 15 millis which are 15 minutes.

isConnected

public 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()

getNick

public String getNick()

Returns the nickname of this instance.

Returns:

The nickname.

getRealname

public String getRealname()

Returns the realname of this instance.

Returns:

The realname.

getUsername

public String getUsername()

Returns the username of this instance.

Returns:

The username.

getHost

public String getHost()

Returns the server of this instance.

Returns:

The server's hostname.

getPassword

public String getPassword()

Returns the password of this instance. If no password is set, null is returned.

Returns:

The password. If no password is set, null is returned.

getPorts

public int[] getPorts()

Returns all ports to which the IRCConnection is going to try or has tried to connect to.

Returns:

The ports in an int[] array.

getPort

public 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.

getColors

public boolean getColors()

Indicates whether colors are stripped out or not.

Returns:

true if colors are disabled.

getPong

public boolean getPong()

Indicates whether automatic PING? PONG! is enabled or not.

Returns:

true if PING? PONG! is done automatically.

getEncoding

public String getEncoding()

Returns the encoding of the socket.

Returns:

The socket's encoding.

getTimeout

public int getTimeout()

Returns the timeout of the socket.
If an error occurs, which is never the case, -1 is returned.

Returns:

The timeout.

toString

public String toString()

Generates a String with some information about the instance of IRCConnection. Its format is: classname[host,portMin,portMax,username,nick,realname,pass,connected] .

Overrides:

toString in class Thread

Returns:

A String with information about the instance.

doAway

public void doAway()

Removes away message.

doAway

public void doAway(String msg)

Sets away message.

Parameters:

msg - The away message.

doInvite

public 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

public 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

public void doJoin(String chan)

Joins a channel without a key.

Parameters:

chan - The channel which is to join.

doJoin

public 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

public 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

public 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

public void doList()

Lists all channels with their topic and status.

doList

public void doList(String chan)

Lists channel(s) with their topic and status.

Parameters:

chan - The channel the LIST refers to.

doNames

public void doNames()

Lists all visible users.

doNames

public void doNames(String chan)

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

Parameters:

chan - The channel the NAMES command is refering to.

doPrivmsg

public 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.

doMode

public 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

public 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.

doNick

public void doNick(String nick)

Changes the nickname.

Parameters:

nick - The new nickname.

doNotice

public 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

public void doPart(String chan)

Parts from a given channel.

Parameters:

chan - The channel you want to part from.

doPart

public 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

public 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.

doQuit

public void doQuit()

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

See Also:

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

doQuit

public 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

public 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

public void doTopic(String chan,
                    String topic)

Changes the topic of a chan.

Parameters:

chan - The channel which topic is changed.

topic - The new topic.

doWho

public 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

public void doWhois(String nick)

Requires information about an existing user.

Parameters:

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

doWhowas

public 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.

doUserhost

public 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.