Class 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​(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.