libjava/java/nio/channels/SocketChannel.java

   1 /* SocketChannel.java --
   2    Copyright (C) 2002, 2004  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.nio.channels;
  40
  41 import java.io.IOException;
  42 import java.net.Socket;
  43 import java.net.SocketAddress;
  44 import java.nio.ByteBuffer;
  45 import java.nio.channels.spi.AbstractSelectableChannel;
  46 import java.nio.channels.spi.SelectorProvider;
  47
  48 /**
  49  * @author Michael Koch (konqueror@gmx.de)
  50  * @since 1.4
  51  */
  52 public abstract class SocketChannel extends AbstractSelectableChannel
  53   implements ByteChannel, ScatteringByteChannel, GatheringByteChannel
  54 {
  55   /**
  56    * Initializes this socket channel.
  57    */
  58   protected SocketChannel(SelectorProvider provider)
  59   {
  60     super(provider);
  61   }
  62
  63   /**
  64    * Opens a socket channel.
  65    *
  66    * @return the new <code>SocketChannel</code> object
  67    *
  68    * @exception IOException If an error occurs
  69    */
  70   public static SocketChannel open() throws IOException
  71   {
  72     return SelectorProvider.provider().openSocketChannel();
  73   }
  74
  75   /**
  76    * Opens a channel and connects it to a remote address.
  77    *
  78    * @return the new <code>SocketChannel</code> object
  79    *
  80    * @exception AsynchronousCloseException If this channel is already connected.
  81    * @exception ClosedByInterruptException If another thread interrupts the
  82    * current thread while the connect operation is in progress, thereby closing
  83    * the channel and setting the current thread's interrupt status.
  84    * @exception IOException If an error occurs
  85    * @exception SecurityException If a security manager has been installed and
  86    * it does not permit access to the given remote endpoint.
  87    * @exception UnresolvedAddressException If the given remote address is not
  88    * fully resolved.
  89    * @exception UnsupportedAddressTypeException If the type of the given remote
  90    * address is not supported.
  91    */
  92   public static SocketChannel open(SocketAddress remote)
  93     throws IOException
  94   {
  95     SocketChannel ch = open();
  96     ch.connect(remote);
  97     return ch;
  98   }
  99
 100   /**
 101    * Reads data from the channel.
 102    *
 103    * @return the number of bytes read, zero is valid too, -1 if end of stream
 104    * is reached
 105    *
 106    * @exception IOException If an error occurs
 107    * @exception NotYetConnectedException If this channel is not yet connected.
 108    */
 109   public final long read(ByteBuffer[] dsts) throws IOException
 110   {
 111     long b = 0;
 112
 113     for (int i = 0; i < dsts.length; i++)
 114       b += read(dsts[i]);
 115
 116     return b;
 117   }
 118
 119   /**
 120    * Writes data to the channel.
 121    *
 122    * @return the number of bytes written, zero is valid too
 123    *
 124    * @exception IOException If an error occurs
 125    * @exception NotYetConnectedException If this channel is not yet connected.
 126    */
 127   public final long write(ByteBuffer[] dsts) throws IOException
 128   {
 129     long b = 0;
 130
 131     for (int i = 0; i < dsts.length; i++)
 132       b += write(dsts[i]);
 133
 134     return b;
 135   }
 136
 137   /**
 138    * Retrieves the valid operations for this channel.
 139    *
 140    * @return the valid operations
 141    */
 142   public final int validOps()
 143   {
 144     return SelectionKey.OP_CONNECT | SelectionKey.OP_READ
 145            | SelectionKey.OP_WRITE;
 146   }
 147
 148   /**
 149    * Reads data from the channel.
 150    *
 151    * @return the number of bytes read, zero is valid too, -1 if end of stream
 152    * is reached
 153    *
 154    * @exception IOException If an error occurs
 155    * @exception NotYetConnectedException If this channel is not yet connected.
 156    */
 157   public abstract int read(ByteBuffer dst) throws IOException;
 158
 159   /**
 160    * Connects the channel's socket to the remote address.
 161    *
 162    * @return <code>true</code> if the channel got successfully connected,
 163    * <code>false</code> if the channel is in non-blocking mode and connection
 164    * operation is still in progress.
 165    *
 166    * @exception AlreadyConnectedException If this channel is already connected.
 167    * @exception AsynchronousCloseException If this channel is already connected.
 168    * @exception ClosedByInterruptException If another thread interrupts the
 169    * current thread while the connect operation is in progress, thereby closing
 170    * the channel and setting the current thread's interrupt status.
 171    * @exception ClosedChannelException If this channel is closed.
 172    * @exception ConnectionPendingException If a non-blocking connection
 173    * operation is already in progress on this channel.
 174    * @exception IOException If an error occurs
 175    * @exception SecurityException If a security manager has been installed and
 176    * it does not permit access to the given remote endpoint.
 177    * @exception UnresolvedAddressException If the given remote address is not
 178    * fully resolved.
 179    * @exception UnsupportedAddressTypeException If the type of the given remote
 180    * address is not supported.
 181    */
 182   public abstract boolean connect(SocketAddress remote)
 183     throws IOException;
 184
 185   /**
 186    * Finishes the process of connecting a socket channel.
 187    *
 188    * @exception AsynchronousCloseException If this channel is already connected.
 189    * @exception ClosedByInterruptException If another thread interrupts the
 190    * current thread while the connect operation is in progress, thereby closing
 191    * the channel and setting the current thread's interrupt status.
 192    * @exception ClosedChannelException If this channel is closed.
 193    * @exception IOException If an error occurs
 194    * @exception NoConnectionPendingException If this channel is not connected
 195    * and a connection operation has not been initiated.
 196    */
 197   public abstract boolean finishConnect() throws IOException;
 198
 199   /**
 200    * Tells whether or not the channel's socket is connected.
 201    */
 202   public abstract boolean isConnected();
 203
 204   /**
 205    * Tells whether or not a connection operation is in progress on this channel.
 206    */
 207   public abstract boolean isConnectionPending();
 208
 209   /**
 210    * Reads data from the channel.
 211    *
 212    * @return the number of bytes read, zero is valid too, -1 if end of stream
 213    * is reached
 214    *
 215    * @exception IOException If an error occurs
 216    * @exception NotYetConnectedException If this channel is not yet connected.
 217    */
 218   public abstract long read(ByteBuffer[] dsts, int offset, int length)
 219     throws IOException;
 220
 221   /**
 222    * Retrieves the channel's socket.
 223    *
 224    * @return the socket
 225    */
 226   public abstract Socket socket();
 227
 228   /**
 229    * Writes data to the channel.
 230    *
 231    * @return the number of bytes written, zero is valid too
 232    *
 233    * @exception IOException If an error occurs
 234    * @exception NotYetConnectedException If this channel is not yet connected.
 235    */
 236   public abstract int write(ByteBuffer src) throws IOException;
 237
 238   /**
 239    * Writes data to the channel.
 240    *
 241    * @return the number of bytes written, zero is valid too
 242    *
 243    * @exception IOException If an error occurs
 244    * @exception NotYetConnectedException If this channel is not yet connected.
 245    */
 246   public abstract long write(ByteBuffer[] srcs, int offset, int length)
 247     throws IOException;
 248 }