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

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