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

	* java/nio/channels/Channels.java:
	Reindented, documentation added.
	(newInputStream): Documentation added.
	(newOutputStream): Documentation added.
	(newChannel): Documentation added.
	(newReader): JDK 1.4 conform implementation, documentation added.
	(newWriter: JDK 1.4 conform implementation, documentation added.

5 files changed, 264 insertions, 112 deletions

diff --git a/java/nio/channels/Channels.java b/java/nio/channels/Channels.java
index 437a1f8ff..4d2ccc0d1 100644
--- a/java/nio/channels/Channels.java
+++ b/java/nio/channels/Channels.java
@@ -37,50 +37,94 @@ exception statement from your version. */
 
 package java.nio.channels;
 
-import java.io.*;
-import java.nio.*;
-import java.nio.charset.*;
-
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.io.Reader;
+import java.io.Writer;
+import java.nio.channels.WritableByteChannel;
+import java.nio.charset.Charset;
+import java.nio.charset.CharsetDecoder;
+import java.nio.charset.CharsetEncoder;
 
+/**
+ * @since 1.4
+ */
 public final class Channels 
 {
-    public static InputStream newInputStream(ReadableByteChannel ch)
-    {
-	return null;
-    }
-    public static OutputStream newOutputStream(final WritableByteChannel ch) 
-    {
-	return null;
-    }
-    public static ReadableByteChannel newChannel(final InputStream in)
-    {
-	return null;
-    }
-    public static WritableByteChannel newChannel(final OutputStream out)
-    {
+  /**
+   * Constructs a stream that reads bytes from the given channel.
+   */
+  public static InputStream newInputStream (ReadableByteChannel ch)
+  {
+    return null;
+  }
+  
+  /**
+   * Constructs a stream that writes bytes to the given channel.
+   */
+  public static OutputStream newOutputStream (WritableByteChannel ch) 
+  {
+    return null;
+  }
+  
+  /**
+   * Constructs a channel that reads bytes from the given stream.
+   */
+  public static ReadableByteChannel newChannel (InputStream in)
+  {
+    return null;
+  }
+  
+  /**
+   * Constructs a channel that writes bytes to the given stream.
+   */
+  public static WritableByteChannel newChannel (OutputStream out)
+  {
+    return null;	
+  }
+
+  /**
+   * Constructs a reader that decodes bytes from the given channel using the
+   * given decoder.
+   */
+  public static Reader newReader (ReadableByteChannel ch, CharsetDecoder dec,
+                                  int minBufferCap)
+  {
+    return null;
+  }
+
+  /**
+   * Constructs a reader that decodes bytes from the given channel according to
+   * the named charset.
+   *
+   * @exception UnsupportedCharsetException If no support for the named charset
+   * is available in this instance of the Java virtual machine.
+   */
+  public static Reader newReader (ReadableByteChannel ch, String csName)
+  {
+    return newReader (ch, Charset.forName (csName).newDecoder (), -1);
+  }
+
+  /**
+   * Constructs a writer that encodes characters using the given encoder and
+   * writes the resulting bytes to the given channel.
+   */
+  public static Writer newWriter (WritableByteChannel ch, CharsetEncoder enc,
+                                  int minBufferCap)
+  {
+    return null;
+  }
 
-	return null;	
-    }
-    public static Reader newReader(ReadableByteChannel ch,
-                                   CharsetDecoder dec,
-                                   int minBufferCap)
-    {
-	return null;
-    }
-    public static Reader newReader(ReadableByteChannel ch,
-                                   String csName)
-    {
-	return newReader(ch, null, 0);
-    }
-    public static Writer newWriter(final WritableByteChannel ch,
-                                   final CharsetEncoder enc,
-                                   final int minBufferCap)
-    {
-	return null;
-    }
-    public static Writer newWriter(WritableByteChannel ch,
-                                   String csName)
-    {
-	return newWriter(ch, null, 0);
-    }
+  /**
+   * Constructs a writer that encodes characters according to the named charset
+   * and writes the resulting bytes to the given channel.
+   *
+   * @exception UnsupportedCharsetException If no support for the named charset
+   * is available in this instance of the Java virtual machine.
+   */
+  public static Writer newWriter (WritableByteChannel ch,
+                                  String csName)
+  {
+    return newWriter (ch, Charset.forName (csName).newEncoder (), -1);
+  }
 }
diff --git a/java/nio/channels/DatagramChannel.java b/java/nio/channels/DatagramChannel.java
index eefa443cb..973e7ce70 100644
--- a/java/nio/channels/DatagramChannel.java
+++ b/java/nio/channels/DatagramChannel.java
@@ -61,6 +61,8 @@ public abstract class DatagramChannel
 
   /**
    * Opens a datagram channel.
+   *
+   * @exception IOException If an error occurs
    */
   public static DatagramChannel open () throws IOException
   {
@@ -82,6 +84,9 @@ public abstract class DatagramChannel
   
   /**
    * Writes data to this channel.
+   *
+   * @exception IOException If an error occurs
+   * @exception NotYetConnectedException The channel's socket is not connected.
    */
   public final long write (ByteBuffer[] srcs)
   {
@@ -95,16 +100,23 @@ public abstract class DatagramChannel
     
   /**
    * Connects this channel's socket.
+   *
+   * @exception IOException If an error occurs
    */
   public abstract DatagramChannel connect (SocketAddress remote);
 
   /**
    * Disonnects this channel's socket.
+   *
+   * @exception IOException If an error occurs
    */
   public abstract DatagramChannel disconnect ();
 
   /**
    * Tells whether or not this channel's socket is connected.
+   *
+   * @exception IOException If an error occurs.
+   * @exception NotYetConnectedException The channel's socket is not connected.
    */
   public abstract boolean isConnected ();
   
@@ -115,16 +127,23 @@ public abstract class DatagramChannel
   
   /**
    * Reads data from this channel.
+   *
+   * @exception IOException If an error occurs.
+   * @exception NotYetConnectedException The channel's socket is not connected.
    */
   public abstract long read (ByteBuffer[] dsts, int offset, int length);
  
   /**
    * Receives a datagram via this channel.
+   *
+   * @exception IOException If an error occurs
    */
   public abstract SocketAddress receive (ByteBuffer dst);
  
   /**
    * Sends a datagram via this channel.
+   *
+   * @exception IOException If an error occurs
    */
   public abstract int send (ByteBuffer src, SocketAddress target);
  
@@ -135,16 +154,25 @@ public abstract class DatagramChannel
   
   /**
    * Writes data to this channel.
+   *
+   * @exception IOException If an error occurs.
+   * @exception NotYetConnectedException The channel's socket is not connected.
    */
   public abstract int write (ByteBuffer src);
   
   /**
    * Writes data to this channel.
+   *
+   * @exception IOException If an error occurs.
+   * @exception NotYetConnectedException The channel's socket is not connected.
    */
   public abstract long write (ByteBuffer[] srcs, int offset, int length);
 
   /**
    * Retrieves the valid operations for this channel.
+   *
+   * @exception IOException If an error occurs.
+   * @exception NotYetConnectedException The channel's socket is not connected.
    */
   public final int validOps ()
   {
diff --git a/java/nio/channels/FileLock.java b/java/nio/channels/FileLock.java
index 65a53cc90..883c17cf0 100644
--- a/java/nio/channels/FileLock.java
+++ b/java/nio/channels/FileLock.java
@@ -37,62 +37,99 @@ exception statement from your version. */
 
 package java.nio.channels;
 
-
+/**
+ * @since 1.4
+ */
 public abstract class FileLock
 {
-    FileChannel channel;
-    long position;
-    long size;
-    boolean shared;
-    
-    protected FileLock(FileChannel channel, 
-		       long position, 
-		       long size,
-		       boolean shared)
-    {
-	this.channel = channel;
-	this.position = position;
-	this.size = size;
-	this.shared = shared;
-    }
+  FileChannel channel;
+  long position;
+  long size;
+  boolean shared;
+  
+  /**
+   * Initializes the file lock.
+   *
+   * @exception IllegalArgumentException If the preconditions on the parameters do not hold
+   */
+  protected FileLock (FileChannel channel, long position, long size,
+                      boolean shared)
+  {
+    if (position < 0 ||
+        size < 0)
+      throw new IllegalArgumentException ();
+
+    this.channel = channel;
+    this.position = position;
+    this.size = size;
+    this.shared = shared;
+  }
  
-    public abstract  boolean isValid();
-    public abstract  void release();
-
-
-    public FileChannel channel()
-    {
-	return channel;
-    }
-
-    public boolean isShared()
-    {
-	return shared;
-    }    
-
-    public boolean overlaps(long position, long size)
-    {
-	if (position > this.position+this.size)
-	    return false;
-
-	if (position+size < this.position)
-	    return false;
-
-	return true;
-    }
-
-    public long position()
-    {
-	return position;
-    }
+  /**
+   * Tells whether or not this lock is valid.
+   */
+  public abstract boolean isValid();
+ 
+  /**
+   * Releases this lock.
+   *
+   * @exception IOException If an error occurs
+   * @exception ClosedChannelException If the locked channel is no longer open.
+   */
+  public abstract void release ();
+  
+  /**
+   * Returns the file channel upon whose file this lock is held.
+   */
+  public final FileChannel channel ()
+  {
+    return channel;
+  }
+
+  /**
+   * Tells whether this lock is shared.
+   */
+  public final boolean isShared ()
+  {
+    return shared;
+  }    
+
+  /**
+   * Tells whether or not this lock overlaps the given lock range.
+   */
+  public final boolean overlaps (long position, long size)
+  {
+    if (position > this.position +this.size)
+      return false;
+
+    if (position + size < this.position)
+      return false;
+
+    return true;
+  }
+
+  /**
+   * Returns the position within the file of the first byte of the
+   * locked region.
+   */
+  public final long position ()
+  {
+    return position;
+  }
     
-    public long size()
-    {
-	return size;
-    }
-
-    public String toString()
-    {
-	return "file-lock:pos="+position+"size="+size;
-    }
+  /**
+   * Returns the size of the locked region in bytes.
+   */
+  public final long size ()
+  {
+    return size;
+  }
+
+  /**
+   * Returns a string describing the range, type, and validity of this lock.
+   */
+  public final String toString ()
+  {
+    return "file-lock:pos=" + position + "size=" + size;
+  }
 }
diff --git a/java/nio/channels/SocketChannel.java b/java/nio/channels/SocketChannel.java
index 1d9343094..a71cf837e 100644
--- a/java/nio/channels/SocketChannel.java
+++ b/java/nio/channels/SocketChannel.java
@@ -60,6 +60,8 @@ abstract public class SocketChannel extends AbstractSelectableChannel
  
   /**
    * Opens a socket channel.
+   *
+   * @exception IOException If an error occurs
    */
   public static SocketChannel open () throws IOException
   {
@@ -68,6 +70,8 @@ abstract public class SocketChannel extends AbstractSelectableChannel
   
   /**
    * Opens a channel and connects it to a remote address.
+   *
+   * @exception IOException If an error occurs
    */
   public static SocketChannel open (SocketAddress remote) throws IOException
   {
@@ -82,6 +86,8 @@ abstract public class SocketChannel extends AbstractSelectableChannel
     
   /**
    * Reads data from the channel.
+   *
+   * @exception IOException If an error occurs
    */
   public final long read (ByteBuffer[] dsts)
   {
@@ -97,6 +103,8 @@ abstract public class SocketChannel extends AbstractSelectableChannel
     
   /**
    * Writes data to the channel.
+   *
+   * @exception IOException If an error occurs
    */
   public final long write (ByteBuffer[] dsts)
   {
@@ -120,16 +128,22 @@ abstract public class SocketChannel extends AbstractSelectableChannel
 
   /**
    * Reads data from the channel.
+   *
+   * @exception IOException If an error occurs
    */
   public abstract int read (ByteBuffer dst);
 
   /**
    * Connects the channel's socket to the remote address.
+   *
+   * @exception IOException If an error occurs
    */
   public abstract boolean connect (SocketAddress remote) throws IOException;
   
   /**
    * Finishes the process of connecting a socket channel.
+   *
+   * @exception IOException If an error occurs
    */
   public abstract boolean finishConnect ();
  
@@ -145,6 +159,8 @@ abstract public class SocketChannel extends AbstractSelectableChannel
   
   /**
    * Reads data from the channel.
+   *
+   * @exception IOException If an error occurs
    */
   public abstract long read (ByteBuffer[] dsts, int offset, int length);
  
@@ -155,11 +171,15 @@ abstract public class SocketChannel extends AbstractSelectableChannel
   
   /**
    * Writes data to the channel.
+   *
+   * @exception IOException If an error occurs
    */
   public abstract int write (ByteBuffer src);
   
   /**
    * Writes data to the channel.
+   *
+   * @exception IOException If an error occurs
    */
   public abstract long write (ByteBuffer[] srcs, int offset, int length);
 }
diff --git a/java/nio/charset/Charset.java b/java/nio/charset/Charset.java
index 7dd400972..cc60c99b9 100644
--- a/java/nio/charset/Charset.java
+++ b/java/nio/charset/Charset.java
@@ -57,7 +57,16 @@ public abstract class Charset implements Comparable
 {
   private static CharsetEncoder cachedEncoder;
   private static CharsetDecoder cachedDecoder;
-  
+ 
+  static
+  {
+    synchronized (Charset.class)
+      {
+        cachedEncoder = null;
+        cachedDecoder = null;
+      }
+  }
+
   private final String canonicalName;
   private final String[] aliases;
   
@@ -198,14 +207,21 @@ public abstract class Charset implements Comparable
   {
     try
       {
-	if (cachedEncoder == null)
+        // NB: This implementation serializes different threads calling
+        // Charset.encode(), a potential performance problem.  It might
+        // be better to remove the cache, or use ThreadLocal to cache on
+        // a per-thread basis.
+        synchronized (Charset.class)
           {
-            cachedEncoder = newEncoder ()
-              .onMalformedInput (CodingErrorAction.REPLACE)
-              .onUnmappableCharacter (CodingErrorAction.REPLACE);
-	  }
-		  
-        return cachedEncoder.encode (cb);
+            if (cachedEncoder == null)
+              {
+                cachedEncoder = newEncoder ()
+                  .onMalformedInput (CodingErrorAction.REPLACE)
+                  .onUnmappableCharacter (CodingErrorAction.REPLACE);
+              }
+
+            return cachedEncoder.encode (cb);
+          }
       }
     catch (CharacterCodingException e)
       {
@@ -221,15 +237,22 @@ public abstract class Charset implements Comparable
   public CharBuffer decode (ByteBuffer bb)
   {
     try
-     {
-        if (cachedDecoder == null)
+      {
+        // NB: This implementation serializes different threads calling
+        // Charset.decode(), a potential performance problem.  It might
+        // be better to remove the cache, or use ThreadLocal to cache on
+        // a per-thread basis.
+        synchronized (Charset.class)
           {
-	    cachedDecoder = newDecoder ()
-              .onMalformedInput (CodingErrorAction.REPLACE)
-              .onUnmappableCharacter (CodingErrorAction.REPLACE);
-	  }
-	
-        return cachedDecoder.decode (bb);
+            if (cachedDecoder == null)
+              {
+                cachedDecoder = newDecoder ()
+                  .onMalformedInput (CodingErrorAction.REPLACE)
+                  .onUnmappableCharacter (CodingErrorAction.REPLACE);
+              }
+
+            return cachedDecoder.decode (bb);
+          }
       }
     catch (CharacterCodingException e)
       {