Package org.schwering.irc.lib
Class IRCConnection
- 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
-
-
Field Summary
Fields Modifier and Type Field Description protected java.lang.String
encoding
TheString
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
Theint[]
contains all ports to which we are going to try to connect.
-
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 newIRCEventListener
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 theIRCConnection
connected, or0
if the connection failed or wasn't tried yet.int[]
getPorts()
Returns all ports to which theIRCConnection
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 theconnect
method, this method prepares the connection.boolean
removeIRCEventListener(IRCEventListener l)
Removes the first occurence of the givenIRCEventListener
from the listener-vector.void
run()
TheThread
is started by theconnect
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 aString
with some information about the instance ofIRCConnection
.-
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
-
-
-
-
Field Detail
-
level
protected byte level
This is like a UNIX-runlevel. Its value indicates the level of theIRCConnection
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 is0
.
-
host
protected java.lang.String host
The host of the IRC server.
-
ports
protected int[] ports
Theint[]
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
TheString
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 anint[]
. 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 theconnect
method. Before invoking it, you should set theIRCEventListener
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""
ornull
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), usenull
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 thehost
orports
isnull
orports
' length is0
.- 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 twoint
s. Thus, only a portrange from portx
to porty
like from port 6667 to 6669 can be selected.
The constructor prepares a new IRC connection which can be really started by invoking theconnect
method. Before invoking it, you should set theIRCEventListener
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""
ornull
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), usenull
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 thehost
isnull
.- 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 anIOException
.
You can invokeconnect
only one time.- Throws:
java.io.IOException
- If an I/O error occurs.java.net.SocketException
- If theconnect
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 theconnect
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 callingregister()
and starts the receiving of lines from the server by starting the thread with thestart
method.
This method must be protected, because it is used by extending classes, which override theconnect
method.
-
run
public void run()
TheThread
is started by theconnect
method. It's task is to receive strings from the IRC server and hand them over to theget
method.- Specified by:
run
in interfacejava.lang.Runnable
- Overrides:
run
in classjava.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 aredo*
methods (likedoJoin
). 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 commandQUIT
. You should always use thedoQuit
methods orsend("QUIT")
instead of this method.
You should use this method to close down the connection only when the IRC server doesn't react to theQUIT
command.- See Also:
connect()
,doQuit()
,doQuit(String)
-
addIRCEventListener
public void addIRCEventListener(IRCEventListener l)
Adds a newIRCEventListener
which listens for actions coming from the IRC server.- Parameters:
l
- An instance of theIRCEventListener
interface.- Throws:
java.lang.IllegalArgumentException
- Iflistener
isnull
.
-
removeIRCEventListener
public boolean removeIRCEventListener(IRCEventListener l)
Removes the first occurence of the givenIRCEventListener
from the listener-vector.- Parameters:
l
- An instance of theIRCEventListener
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 automaticPONG
reply,false
makes the class fireonPing
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 theconnect()
method.- Parameters:
encoding
-
-
setTimeout
public void setTimeout(int millis)
Sets the connection's timeout in milliseconds.
The default is1000 * 60 15
millis which are 15 minutes.
-
isConnected
public boolean isConnected()
Tells whether there's a connection to the IRC network or not.
Ifconnect
wasn't called yet, it returnsfalse
.- 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 theIRCConnection
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 theIRCConnection
connected, or0
if the connection failed or wasn't tried yet.- Returns:
- The port to which the
IRCConnection
, or0
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 aString
with some information about the instance ofIRCConnection
. Its format is:classname[host,portMin,portMax,username,nick,realname,pass,connected]
.- Overrides:
toString
in classjava.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 theLIST
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 theNAMES
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 theMODE
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 inonPing
. It's aString
, 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 thedisconnect
-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 thedisconnect
-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 theWHO
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.
-
-