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

All Implemented Interfaces:: java.lang.Runnable

Direct Known Subclasses:: SSLIRCConnection, SSLIRCConnection

public class IRCConnection
extends java.lang.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
  java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler

Field Summary

Fields
Modifier and Type	Field	Description
`protected java.lang.String`	`encoding`	The `String` contains the name of the character encoding used to talk to the server.
`protected java.lang.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

Constructors
Constructor	Description
`IRCConnection(java.lang.String host, int[] ports, java.lang.String pass, java.lang.String nick, java.lang.String username, java.lang.String realname)`	Creates a new IRC connection.
`IRCConnection(java.lang.String host, int portMin, int portMax, java.lang.String pass, java.lang.String nick, java.lang.String username, java.lang.String realname)`	Creates a new IRC connection.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`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(java.lang.String msg)`	Sets away message.
`void`	`doInvite(java.lang.String nick, java.lang.String chan)`	Invites a user to a channel.
`void`	`doIson(java.lang.String nick)`	Checks if one or more nicks are used on the server.
`void`	`doJoin(java.lang.String chan)`	Joins a channel without a key.
`void`	`doJoin(java.lang.String chan, java.lang.String key)`	Joins a channel with a key.
`void`	`doKick(java.lang.String chan, java.lang.String nick)`	Kicks a user from a channel.
`void`	`doKick(java.lang.String chan, java.lang.String nick, java.lang.String msg)`	Kicks a user from a channel with a comment.
`void`	`doList()`	Lists all channels with their topic and status.
`void`	`doList(java.lang.String chan)`	Lists channel(s) with their topic and status.
`void`	`doMode(java.lang.String chan)`	Requests a Reply 324 for the modes of a given channel.
`void`	`doMode(java.lang.String target, java.lang.String mode)`	Sends a mode to the server.
`void`	`doNames()`	Lists all visible users.
`void`	`doNames(java.lang.String chan)`	Lists all visible users of (a) channel(s).
`void`	`doNick(java.lang.String nick)`	Changes the nickname.
`void`	`doNotice(java.lang.String target, java.lang.String msg)`	Notices a message to a person or a channel.
`void`	`doPart(java.lang.String chan)`	Parts from a given channel.
`void`	`doPart(java.lang.String chan, java.lang.String msg)`	Parts from a given channel with a given parg-msg.
`void`	`doPong(java.lang.String ping)`	Quits from the IRC server with a quit-msg.
`void`	`doPrivmsg(java.lang.String target, java.lang.String msg)`	Sends a message to a person or a channel.
`void`	`doQuit()`	Quits from the IRC server.
`void`	`doQuit(java.lang.String msg)`	Quits from the IRC server with a quit-msg.
`void`	`doTopic(java.lang.String chan)`	Requests the topic of a chan.
`void`	`doTopic(java.lang.String chan, java.lang.String topic)`	Changes the topic of a chan.
`void`	`doUserhost(java.lang.String nick)`	Requires host-information about up to 5 users which must be listed and divided by spaces.
`void`	`doWho(java.lang.String criteric)`	Requests information about users matching the given criteric, for example a channel they are on.
`void`	`doWhois(java.lang.String nick)`	Requires information about an existing user.
`void`	`doWhowas(java.lang.String nick)`	Requires host-information about a user, who is not connected anymore.
`boolean`	`getColors()`	Indicates whether colors are stripped out or not.
`java.lang.String`	`getEncoding()`	Returns the encoding of the socket.
`java.lang.String`	`getHost()`	Returns the server of this instance.
`java.lang.String`	`getNick()`	Returns the nickname of this instance.
`java.lang.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.
`java.lang.String`	`getRealname()`	Returns the realname of this instance.
`int`	`getTimeout()`	Returns the timeout of the socket.
`java.lang.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(java.net.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(java.lang.String line)`	Sends a String to the server.
`void`	`setColors(boolean colors)`	Enables or disables the mIRC colorcodes.
`void`	`setEncoding(java.lang.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.
`java.lang.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, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, onSpinWait, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, 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 java.lang.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 java.lang.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(java.lang.String host,
                     int[] ports,
                     java.lang.String pass,
                     java.lang.String nick,
                     java.lang.String username,
                     java.lang.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:
    
    java.lang.IllegalArgumentException - If the host or ports is null or ports' length is 0.
    
    See Also:
    
    connect()
  - IRCConnection
```
public IRCConnection(java.lang.String host,
                     int portMin,
                     int portMax,
                     java.lang.String pass,
                     java.lang.String nick,
                     java.lang.String username,
                     java.lang.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:
    
    java.lang.IllegalArgumentException - If the host is null.
    
    See Also:
    
    connect()
- Method Detail
  - connect
```
public void connect()
             throws java.io.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:
    
    java.io.IOException - If an I/O error occurs.
    
    java.net.SocketException - If the connect method was already invoked.
    
    See Also:
    
    isConnected(), doQuit(), doQuit(String), close()
  - prepare
```
protected void prepare(java.net.Socket s)
                throws java.io.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:
    
    java.io.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 java.lang.Runnable
    
    Overrides:
    
    run in class java.lang.Thread
  - send
```
public void send(java.lang.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:
    
    java.lang.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(java.lang.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 java.lang.String getNick()
```
    Returns the nickname of this instance.
    
    Returns:
    
    The nickname.
  - getRealname
```
public java.lang.String getRealname()
```
    Returns the realname of this instance.
    
    Returns:
    
    The realname.
  - getUsername
```
public java.lang.String getUsername()
```
    Returns the username of this instance.
    
    Returns:
    
    The username.
  - getHost
```
public java.lang.String getHost()
```
    Returns the server of this instance.
    
    Returns:
    
    The server's hostname.
  - getPassword
```
public java.lang.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 java.lang.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 java.lang.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 java.lang.Thread
    
    Returns:
    
    A String with information about the instance.
  - doAway
```
public void doAway()
```
    Removes away message.
  - doAway
```
public void doAway(java.lang.String msg)
```
    Sets away message.
    
    Parameters:
    
    msg - The away message.
  - doInvite
```
public void doInvite(java.lang.String nick,
                     java.lang.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(java.lang.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(java.lang.String chan)
```
    Joins a channel without a key.
    
    Parameters:
    
    chan - The channel which is to join.
  - doJoin
```
public void doJoin(java.lang.String chan,
                   java.lang.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(java.lang.String chan,
                   java.lang.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(java.lang.String chan,
                   java.lang.String nick,
                   java.lang.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(java.lang.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(java.lang.String chan)
```
    Lists all visible users of (a) channel(s).
    
    Parameters:
    
    chan - The channel the NAMES command is refering to.
  - doPrivmsg
```
public void doPrivmsg(java.lang.String target,
                      java.lang.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(java.lang.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(java.lang.String target,
                   java.lang.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(java.lang.String nick)
```
    Changes the nickname.
    
    Parameters:
    
    nick - The new nickname.
  - doNotice
```
public void doNotice(java.lang.String target,
                     java.lang.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(java.lang.String chan)
```
    Parts from a given channel.
    
    Parameters:
    
    chan - The channel you want to part from.
  - doPart
```
public void doPart(java.lang.String chan,
                   java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.String chan,
                    java.lang.String topic)
```
    Changes the topic of a chan.
    
    Parameters:
    
    chan - The channel which topic is changed.
    
    topic - The new topic.
  - doWho
```
public void doWho(java.lang.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(java.lang.String nick)
```
    Requires information about an existing user.
    
    Parameters:
    
    nick - The nickname of the user the query is refering to.
  - doWhowas
```
public void doWhowas(java.lang.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(java.lang.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.

Class IRCConnection

Nested Class Summary

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

Field Summary

Fields inherited from class java.lang.Thread

Constructor Summary

Method Summary

Methods inherited from class java.lang.Thread

Methods inherited from class java.lang.Object

Field Detail

level

host

ports

encoding

Constructor Detail

IRCConnection

IRCConnection

Method Detail

connect

prepare

run

send

close

addIRCEventListener

removeIRCEventListener

setColors

setPong

setEncoding

setTimeout

isConnected

getNick

getRealname

getUsername

getHost

getPassword

getPorts

getPort

getColors

getPong

getEncoding

getTimeout

toString

doAway

doAway

doInvite

doIson

doJoin

doJoin

doKick

doKick

doList

doList

doNames

doNames

doPrivmsg

doMode

doMode

doNick

doNotice

doPart

doPart

doPong

doQuit

doQuit

doTopic

doTopic

doWho

doWhois

doWhowas

doUserhost