2002-11-07 Michael Koch <konqueror@gmx.de>

	* java/net/DatagramSocketImpl.java: Added documentation.
	* java/net/Inet4Address.java: Made final again.
	* java/net/MulticastSocket.java: Reindented.
	* java/net/ServerSocket.java: Added documentation.
	* java/net/Socket.java: Added documentation.
	(Socket): Must be public now.
	* java/net/SocketImpl.java: Added documentation.
	* java/nio/channels/IllegalBlockingModeException.java: New file.
	* java/nio/channels/Makefile.am:
	Added IllegalBlockingModeException.java.

8 files changed, 226 insertions, 123 deletions

diff --git a/java/net/DatagramSocketImpl.java b/java/net/DatagramSocketImpl.java
index 260088dfe..fd51ed76f 100644
--- a/java/net/DatagramSocketImpl.java
+++ b/java/net/DatagramSocketImpl.java
@@ -108,6 +108,9 @@ public abstract class DatagramSocketImpl implements SocketOptions
    * @return The port number of the sender of the packet
    *
    * @exception IOException If an error occurs
+   * @exception PortUnreachableException May be thrown if the socket is
+   * connected to a currently unreachable destination. Note, there is no
+   * guarantee that the exception will be thrown.
    */
   protected abstract int peek(InetAddress i) throws IOException;
 
@@ -118,6 +121,9 @@ public abstract class DatagramSocketImpl implements SocketOptions
    * @param p The packet to send
    *
    * @exception IOException If an error occurs
+   * @exception PortUnreachableException May be thrown if the socket is
+   * connected to a currently unreachable destination. Note, there is no
+   * guarantee that the exception will be thrown.
    */
   protected abstract void send(DatagramPacket p) throws IOException;
 
@@ -129,6 +135,9 @@ public abstract class DatagramSocketImpl implements SocketOptions
    * @param p A place to store the incoming packet.
    *
    * @exception IOException If an error occurs
+   * @exception PortUnreachableException May be thrown if the socket is
+   * connected to a currently unreachable destination. Note, there is no
+   * guarantee that the exception will be thrown.
    */
   protected abstract void receive(DatagramPacket p) throws IOException;
 
@@ -208,7 +217,7 @@ public abstract class DatagramSocketImpl implements SocketOptions
    * Sets the specified option on a socket to the passed in object.  For
    * options that take an integer argument, the passed in object is an
    * <code>Integer</code>.  For options that are set to on or off, the
-   * value passed will be a <code>Boolean</code>.   The <code>option_id</code> 
+   * value passed will be a <code>Boolean</code>.   The <code>option_id</code>
    * parameter is one of the defined constants in the superinterface.
    *
    * @param option_id The identifier of the option
diff --git a/java/net/Inet4Address.java b/java/net/Inet4Address.java
index 2c19abcfe..c635c671d 100644
--- a/java/net/Inet4Address.java
+++ b/java/net/Inet4Address.java
@@ -53,7 +53,7 @@ import java.io.ObjectStreamException;
  * Status: Believed complete and correct.
  */
 
-public class Inet4Address extends InetAddress
+public final class Inet4Address extends InetAddress
 {
   static final long serialVersionUID = 7615067291688066509L;
 
diff --git a/java/net/MulticastSocket.java b/java/net/MulticastSocket.java
index 7381a866d..f5e495811 100644
--- a/java/net/MulticastSocket.java
+++ b/java/net/MulticastSocket.java
@@ -39,82 +39,82 @@ package java.net;
 
 import java.io.IOException;
 
-/*
+/**
  * Written using on-line Java Platform 1.2 API Specification, as well
  * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
  * Status:  Believed complete and correct.
  */
 
 /**
-  * This class models a multicast UDP socket.  A multicast address is a
-  * class D internet address (one whose most significant bits are 1110).  
-  * A multicast group consists of a multicast address and a well known
-  * port number.  All members of the group listening on that address and
-  * port will receive all the broadcasts to the group.
-  * <p>
-  * Please note that applets are not allowed to use multicast sockets 
-  * 
-  * Written using on-line Java Platform 1.2 API Specification, as well
-  * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
-  * Status:  Believed complete and correct.
-  *
-  * @author Warren Levy <warrenl@cygnus.com>
-  * @author Aaron M. Renn (arenn@urbanophile.com) (Documentation comments)
-  * @since 1.1
-  * @date May 18, 1999.
-  */
+ * This class models a multicast UDP socket.  A multicast address is a
+ * class D internet address (one whose most significant bits are 1110).  
+ * A multicast group consists of a multicast address and a well known
+ * port number.  All members of the group listening on that address and
+ * port will receive all the broadcasts to the group.
+ * <p>
+ * Please note that applets are not allowed to use multicast sockets 
+ * 
+ * Written using on-line Java Platform 1.2 API Specification, as well
+ * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
+ * Status:  Believed complete and correct.
+ *
+ * @author Warren Levy <warrenl@cygnus.com>
+ * @author Aaron M. Renn (arenn@urbanophile.com) (Documentation comments)
+ * @since 1.1
+ * @date May 18, 1999.
+ */
 public class MulticastSocket extends DatagramSocket
 {
   // FIXME: the local addr bound to the multicast socket can be reused;
   // unlike unicast sockets.  It binds to any available network interface.
   // See p.1159 JCL book.
 
-/**
-  * Create a MulticastSocket that this not bound to any address
-  *
-  * @exception IOException If an error occurs
-  */
+  /**
+   * Create a MulticastSocket that this not bound to any address
+   *
+   * @exception IOException If an error occurs
+   */
   public MulticastSocket() throws IOException
   {
     super(0, null);
   }
 
-/**
-  * Create a multicast socket bound to the specified port
-  *
-  * @param The port to bind to
-  *
-  * @exception IOException If an error occurs
-  */
+  /**
+   * Create a multicast socket bound to the specified port
+   *
+   * @param The port to bind to
+   *
+   * @exception IOException If an error occurs
+   */
   public MulticastSocket(int port) throws IOException
   {
     super(port, null);
   }
 
-/**
-  * Returns the interface being used for multicast packets
-  * 
-  * @return The multicast interface
-  *
-  * @exception SocketException If an error occurs
-  */
+  /**
+   * Returns the interface being used for multicast packets
+   * 
+   * @return The multicast interface
+   *
+   * @exception SocketException If an error occurs
+   */
   public InetAddress getInterface() throws SocketException
   {
     // FIXME: Is it possible that an InetAddress wasn't returned from getOption?
     return (InetAddress) impl.getOption(SocketOptions.IP_MULTICAST_IF);
   }
 
-/**
-  * Returns the current value of the "Time to Live" option.  This is the
-  * number of hops a packet can make before it "expires".   This method id
-  * deprecated.  Use <code>getTimeToLive</code> instead.
-  * 
-  * @return The TTL value
-  *
-  * @exception IOException If an error occurs
-  *
-  * @deprecated Replaced by getTimeToLive() in Java 1.2
-  */
+  /**
+   * Returns the current value of the "Time to Live" option.  This is the
+   * number of hops a packet can make before it "expires".   This method id
+   * deprecated.  Use <code>getTimeToLive</code> instead.
+   * 
+   * @return The TTL value
+   *
+   * @exception IOException If an error occurs
+   *
+   * @deprecated Replaced by getTimeToLive() in Java 1.2
+   */
   public byte getTTL() throws IOException
   {
     // Use getTTL here rather than getTimeToLive in case we're using an impl
@@ -123,43 +123,43 @@ public class MulticastSocket extends DatagramSocket
     return impl.getTTL();
   }
 
-/**
-  * Returns the current value of the "Time to Live" option.  This is the
-  * number of hops a packet can make before it "expires". 
-  * 
-  * @return The TTL value
-  *
-  * @exception IOException If an error occurs
-  *
-  * @since Java 1.2
-  */
+  /**
+   * Returns the current value of the "Time to Live" option.  This is the
+   * number of hops a packet can make before it "expires". 
+   * 
+   * @return The TTL value
+   *
+   * @exception IOException If an error occurs
+   *
+   * @since Java 1.2
+   */
   public int getTimeToLive() throws IOException
   {
     return impl.getTimeToLive();
   }
 
-/**
-  * Sets the interface to use for multicast packets.
-  *
-  * @param addr The new interface to use
-  *
-  * @exception SocketException If an error occurs
-  */
+ /**
+   * Sets the interface to use for multicast packets.
+   *
+   * @param addr The new interface to use
+   *
+   * @exception SocketException If an error occurs
+   */
   public void setInterface(InetAddress inf) throws SocketException
   {
     impl.setOption(SocketOptions.IP_MULTICAST_IF, inf);
   }
 
-/**
-  * Sets the "Time to Live" value for a socket.  The value must be between
-  * 1 and 255.
-  *
-  * @param ttl The new TTL value
-  *
-  * @exception IOException If an error occurs
-  *
-  * @deprecated Replaced by <code>setTimeToLive</code> in Java 1.2
-  */
+  /**
+   * Sets the "Time to Live" value for a socket.  The value must be between
+   * 1 and 255.
+   *
+   * @param ttl The new TTL value
+   *
+   * @exception IOException If an error occurs
+   *
+   * @deprecated Replaced by <code>setTimeToLive</code> in Java 1.2
+   */
   public void setTTL(byte ttl) throws IOException
   {
     // Use setTTL here rather than setTimeToLive in case we're using an impl
@@ -168,16 +168,16 @@ public class MulticastSocket extends DatagramSocket
     impl.setTTL(ttl);
   }
 
-/**
-  * Sets the "Time to Live" value for a socket.  The value must be between
-  * 1 and 255.  
-  *
-  * @param ttl The new TTL value
-  *
-  * @exception IOException If an error occurs
-  * 
-  * @since Java 1.2
-  */
+  /**
+   * Sets the "Time to Live" value for a socket.  The value must be between
+   * 1 and 255.  
+   *
+   * @param ttl The new TTL value
+   *
+   * @exception IOException If an error occurs
+   * 
+   * @since Java 1.2
+   */
   public void setTimeToLive(int ttl) throws IOException
   {
     if (ttl <= 0 || ttl > 255)
@@ -186,13 +186,13 @@ public class MulticastSocket extends DatagramSocket
     impl.setTimeToLive(ttl);
   }
 
-/**
-  * Joins the specified mulitcast group.
-  *
-  * @param addr The address of the group to join
-  * 
-  * @exception IOException If an error occurs
-  */
+  /**
+   * Joins the specified mulitcast group.
+   *
+   * @param addr The address of the group to join
+   * 
+   * @exception IOException If an error occurs
+   */
   public void joinGroup(InetAddress mcastaddr) throws IOException
   {
     if (! mcastaddr.isMulticastAddress())
@@ -205,13 +205,13 @@ public class MulticastSocket extends DatagramSocket
     impl.join(mcastaddr);
   }
 
-/**
-  * Leaves the specified multicast group
-  *
-  * @param addr The address of the group to leave
-  *
-  * @exception IOException If an error occurs
-  */
+  /**
+   * Leaves the specified multicast group
+   *
+   * @param addr The address of the group to leave
+   *
+   * @exception IOException If an error occurs
+   */
   public void leaveGroup(InetAddress mcastaddr) throws IOException
   {
     if (! mcastaddr.isMulticastAddress())
@@ -224,16 +224,16 @@ public class MulticastSocket extends DatagramSocket
     impl.leave(mcastaddr);
   }
 
-/**
-  * Sends a packet of data to a multicast address with a TTL that is
-  * different from the default TTL on this socket.  The default TTL for
-  * the socket is not changed.
-  *
-  * @param packet The packet of data to send
-  * @param ttl The TTL for this packet
-  *
-  * @exception IOException If an error occurs
-  */
+  /**
+   * Sends a packet of data to a multicast address with a TTL that is
+   * different from the default TTL on this socket.  The default TTL for
+   * the socket is not changed.
+   *
+   * @param packet The packet of data to send
+   * @param ttl The TTL for this packet
+   *
+   * @exception IOException If an error occurs
+   */
   public synchronized void send(DatagramPacket p, byte ttl) throws IOException
   {
     SecurityManager s = System.getSecurityManager();
diff --git a/java/net/ServerSocket.java b/java/net/ServerSocket.java
index 788057d13..33c36d32f 100644
--- a/java/net/ServerSocket.java
+++ b/java/net/ServerSocket.java
@@ -38,6 +38,8 @@ exception statement from your version. */
 package java.net;
 
 import java.io.IOException;
+import java.nio.channels.IllegalBlockingModeException;
+import java.nio.channels.ServerSocketChannel;
 
 /* Written using on-line Java Platform 1.2 API Specification.
  * Status:  I believe all methods are implemented.
@@ -49,7 +51,7 @@ import java.io.IOException;
  * listens for and accepts connections.  At that point the client and
  * server sockets are ready to communicate with one another utilizing
  * whatever application layer protocol they desire.
- * <p>
+ *
  * As with the <code>Socket</code> class, most instance methods of this class 
  * simply redirect their calls to an implementation class.
  *
@@ -75,9 +77,13 @@ public class ServerSocket
   private SocketImpl impl;
 
   /**
-   * Private constructor that simply sets the implementation.
+   * Constructor that simply sets the implementation.
+   * 
+   * @exception IOException If an error occurs
+   *
+   * @specnote This constructor is public since JDK 1.4
    */
-  private ServerSocket()
+  public ServerSocket() throws IOException
   {
     if (factory != null)
       impl = factory.createSocketImpl();
@@ -93,9 +99,11 @@ public class ServerSocket
    * @param port The port number to bind to
    * 
    * @exception IOException If an error occurs
+   * @exception SecurityException If a security manager exists and its
+   * checkListen method doesn't allow the operation
    */
   public ServerSocket (int port)
-    throws java.io.IOException
+    throws IOException
   {
     this(port, 50);
   }
diff --git a/java/net/Socket.java b/java/net/Socket.java
index ee95e0526..5a67288c0 100644
--- a/java/net/Socket.java
+++ b/java/net/Socket.java
@@ -38,7 +38,8 @@ exception statement from your version. */
 package java.net;
 
 import java.io.*;
-import java.nio.channels.*;
+import java.nio.channels.SocketChannel;
+import java.nio.channels.IllegalBlockingModeException;
 
 /* Written using on-line Java Platform 1.2 API Specification.
  * Status:  I believe all methods are implemented.
@@ -79,14 +80,18 @@ public class Socket
    */
   SocketImpl impl;
 
+  SocketChannel ch; // this field must have been set if created by SocketChannel
+
   // Constructors
 
   /**
    * Initializes a new instance of <code>Socket</code> object without 
    * connecting to a remote host.  This useful for subclasses of socket that 
    * might want this behavior.
+   *
+   * @specnote This constructor is public since JDK 1.4
    */
-  protected Socket ()
+  public Socket ()
   {
     if (factory != null)
       impl = factory.createSocketImpl();
@@ -125,6 +130,8 @@ public class Socket
    * @exception UnknownHostException If the hostname cannot be resolved to a
    * network address.
    * @exception IOException If an error occurs
+   * @exception SecurityException If a security manager exists and its
+   * checkConnect method doesn't allow the operation
    */
   public Socket (String host, int port)
     throws UnknownHostException, IOException
@@ -140,6 +147,8 @@ public class Socket
    * @param port The port number to connect to
    *
    * @exception IOException If an error occurs
+   * @exception SecurityException If a security manager exists and its
+   * checkConnect method doesn't allow the operation
    */
   public Socket (InetAddress address, int port)
     throws IOException 
@@ -179,6 +188,8 @@ public class Socket
    * @param localPort The local port to connect to
    *
    * @exception IOException If an error occurs
+   * @exception SecurityException If a security manager exists and its
+   * checkConnect method doesn't allow the operation
    */
   public Socket (InetAddress address, int port,
 		 InetAddress localAddr, int localPort) throws IOException
@@ -198,6 +209,8 @@ public class Socket
    * for a datagram socket
    *
    * @exception IOException If an error occurs
+   * @exception SecurityException If a security manager exists and its
+   * checkConnect method doesn't allow the operation
    *
    * @deprecated Use the <code>DatagramSocket</code> class to create
    * datagram oriented sockets.
@@ -219,6 +232,8 @@ public class Socket
    * <code>false</code> to create a datagram socket.
    *
    * @exception IOException If an error occurs
+   * @exception SecurityException If a security manager exists and its
+   * checkConnect method doesn't allow the operation
    *
    * @deprecated Use the <code>DatagramSocket</code> class to create
    * datagram oriented sockets.
@@ -242,6 +257,8 @@ public class Socket
    * @param stream true for a stream socket, false for a datagram socket
    *
    * @exception IOException If an error occurs
+   * @exception SecurityException If a security manager exists and its
+   * checkConnect method doesn't allow the operation
    */
   private Socket(InetAddress raddr, int rport, InetAddress laddr, int lport,
                  boolean stream) throws IOException
@@ -425,6 +442,7 @@ public class Socket
    * SO_LINGER not set.
    *
    * @exception SocketException If an error occurs or Socket not connected
+   * @exception IllegalArgumentException If linger is negative
    */
   public void setSoLinger(boolean on, int linger) throws SocketException
   {
@@ -534,6 +552,7 @@ public class Socket
    * @param size The new send buffer size.
    *
    * @exception SocketException If an error occurs or Socket not connected
+   * @exception IllegalArgumentException If size is 0 or negative
    *
    * @since 1.2
    */
@@ -580,6 +599,7 @@ public class Socket
    * @param size The new receive buffer size.
    *
    * @exception SocketException If an error occurs or Socket is not connected
+   * @exception IllegalArgumentException If size is 0 or negative
    *
    * @since 1.2
    */
@@ -669,25 +689,32 @@ public class Socket
     factory = fac;
   }
 
+  /**
+   * Closes the input side of the socket stream.
+   *
+   * @exception IOException If an error occurs.
+   */
   public void shutdownInput() throws IOException
   {
     // impl.shutdownInput();
   }
 
+  /**
+   * Closes the output side of the socket stream.
+   *
+   * @exception IOException If an error occurs.
+   */
   public void shutdownOutput() throws IOException
   {
     // impl.shutdownOutput();
   }
 
-  SocketChannel ch; // this field must have been set if created by SocketChannel
-
   /**
-   * Returns the socket channel associated with 
-   * this socket.
-   * 
+   * Returns the socket channel associated with this socket.
+   *
    * It returns null if no associated socket exists.
    */
-  public SocketChannel getChannel() 
+  public SocketChannel getChannel()
   {
     return ch;
   }
diff --git a/java/net/SocketImpl.java b/java/net/SocketImpl.java
index fb5a60ca5..ecdaa1532 100644
--- a/java/net/SocketImpl.java
+++ b/java/net/SocketImpl.java
@@ -95,6 +95,8 @@ public abstract class SocketImpl implements SocketOptions
    * if the stream parameter is false.
    *
    * @param stream true for a stream socket, false for a datagram socket
+   *
+   * @exception IOException If an error occurs
    */
   protected abstract void create(boolean stream) throws IOException;
 
diff --git a/java/nio/channels/IllegalBlockingModeException.java b/java/nio/channels/IllegalBlockingModeException.java
new file mode 100644
index 000000000..dca811005
--- /dev/null
+++ b/java/nio/channels/IllegalBlockingModeException.java
@@ -0,0 +1,56 @@
+/* IllegalBlockingModeException.java -- 
+   Copyright (C) 2002 Free Software Foundation, Inc.
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
+
+package java.nio.channels;
+
+/**
+ * @author Michael Koch <konqueror@gmx.de>
+ * @since 1.4
+ *
+ * Written using JDK 1.4.1 Online API from Sun
+ * Status: JDK 1.4 complete
+ */
+public class IllegalBlockingModeException extends IllegalStateException
+{
+  /**
+   * Creates the exception
+   */
+  public IllegalBlockingModeException()
+  {
+    super();
+  }
+}
diff --git a/java/nio/channels/Makefile.am b/java/nio/channels/Makefile.am
index c6ed5ea88..8542eb2f0 100644
--- a/java/nio/channels/Makefile.am
+++ b/java/nio/channels/Makefile.am
@@ -9,6 +9,7 @@ DatagramChannel.java \
 FileChannel.java \
 FileLock.java \
 GatheringByteChannel.java \
+IllegalBlockingModeException.java \
 InterruptibleChannel.java \
 Pipe.java \
 ReadableByteChannel.java \