src/main/java/net/pterodactylus/irc/Connection.java

   1 package net.pterodactylus.irc;
   2
   3 import java.io.IOException;
   4
   5 /**
   6  * A connection to an IRC server.
   7  *
   8  * @author <a href="mailto:bombe@pterodactylus.net">David ‘Bombe’ Roden</a>
   9  */
  10 public interface Connection {
  11
  12         /**
  13          * Returns the hostname of the remote end of the connection.
  14          *
  15          * @return The remote’s hostname
  16          */
  17         String hostname();
  18
  19         /**
  20          * Returns the port number of the remote end of the connection.
  21          *
  22          * @return The remote’s port number
  23          */
  24         int port();
  25
  26         /**
  27          * Returns whether this connection has already been established.
  28          *
  29          * @return {@code true} as long as this connection is established, {@code
  30          * false} otherwise
  31          */
  32         boolean established();
  33
  34         /**
  35          * Returns the nickname that is currently in use by this connection. The
  36          * nickname is only available once the connection has been {@link #start()}ed.
  37          *
  38          * @return The current nickname
  39          */
  40         String nickname();
  41
  42         /**
  43          * Sets the username to use.
  44          *
  45          * @param username
  46          *              The username to use
  47          * @return This connection
  48          */
  49         Connection username(String username);
  50
  51         /**
  52          * Sets the real name to use.
  53          *
  54          * @param realName
  55          *              The real name to use
  56          * @return This connection
  57          */
  58         Connection realName(String realName);
  59
  60         /**
  61          * Sets the optional password for the connection.
  62          *
  63          * @param password
  64          *              The password for the connection
  65          * @return This connection
  66          */
  67         Connection password(String password);
  68
  69         /**
  70          * Returns the current rate of the connection’s incoming side.
  71          *
  72          * @return The current input rate (in bytes per second)
  73          */
  74         long getInputRate();
  75
  76         /**
  77          * Returns the current rate of the connection’s outgoing side.
  78          *
  79          * @return The current output rate (in bytes per second)
  80          */
  81         long getOutputRate();
  82
  83         /**
  84          * Checks whether the given source is the client represented by this
  85          * connection.
  86          *
  87          * @param source
  88          *              The source to check
  89          * @return {@code true} if this connection represents the given source, {@code
  90          * false} otherwise
  91          */
  92         boolean isSource(Source source);
  93
  94         /**
  95          * Joins the given channel.
  96          *
  97          * @param channel
  98          *              The channel to join
  99          * @throws IOException
 100          *              if an I/O error occurs
 101          */
 102         void joinChannel(String channel) throws IOException;
 103
 104         /**
 105          * Sends a message to the given recipient, which may be a channel or another
 106          * nickname.
 107          *
 108          * @param recipient
 109          *              The recipient of the message
 110          * @param message
 111          *              The message
 112          * @throws IOException
 113          *              if an I/O error occurs
 114          */
 115         void sendMessage(String recipient, String message) throws IOException;
 116
 117         /**
 118          * Sends a DCC RESUME request to the given recipient.
 119          *
 120          * @param recipient
 121          *              The recipient of the request
 122          * @param filename
 123          *              The name of the file to resume
 124          * @param port
 125          *              The port number from the original DCC SEND request
 126          * @param position
 127          *              The position at which to resume the transfer
 128          * @throws IOException
 129          *              if an I/O error occurs
 130          */
 131         void sendDccResume(String recipient, String filename, int port, long position)
 132                         throws IOException;
 133
 134         /**
 135          * Opens the connection and starts processing messages from the other side.
 136          */
 137         void open();
 138
 139         /**
 140          * Closes this connection.
 141          *
 142          * @throws IOException
 143          *              if an I/O error occurs
 144          */
 145         void close() throws IOException;
 146
 147 }